From 2157e4bbcfa97fa61d5be67c0a2e01956b07007b Mon Sep 17 00:00:00 2001
From: lcy1996 <992195697@qq.com>
Date: Sat, 6 Oct 2018 01:45:56 +0800
Subject: [PATCH] Add comment for interrutp and trap code

---
 docs/OSTrain2018docs-g4/expr1/report-lcy.md |  6 +--
 kernel/src/arch/riscv32/context.rs          |  2 +-
 kernel/src/arch/riscv32/interrupt.rs        | 52 ++++++++++++++++++++-
 kernel/src/trap.rs                          | 10 ++++
 4 files changed, 65 insertions(+), 5 deletions(-)
 mode change 100755 => 100644 docs/OSTrain2018docs-g4/expr1/report-lcy.md

diff --git a/docs/OSTrain2018docs-g4/expr1/report-lcy.md b/docs/OSTrain2018docs-g4/expr1/report-lcy.md
old mode 100755
new mode 100644
index 52aea10..7d5d8dc
--- a/docs/OSTrain2018docs-g4/expr1/report-lcy.md
+++ b/docs/OSTrain2018docs-g4/expr1/report-lcy.md
@@ -16,11 +16,11 @@
 | spin | 通过 |  |
 | sh | 未通过 | unknown syscall id: 0x66, args: [0, 7000ff97, 1, 7000ff70, 25, 73] <br> 可能是由于尚未实现sh这一系统调用 |
 | forktest | 通过 |  |
-| faultread | 未通过 | [INFO] open: path: "stdin:", flags: 0 <br>[INFO] open: path: "stdout:", flags: 1 <br>[ERROR] Process 2 error <br> 推测是标准输入输出的错误？ |
+| faultread | 通过 | [INFO] open: path: "stdin:", flags: 0 <br>[INFO] open: path: "stdout:", flags: 1 <br>[ERROR] Process 2 error <br> 系统似乎成功处理了该异常并正确结束该进程？ |
 | forktree | 未通过 | PANIC in src/lang.rs at line 22 <br>out of memory<br>似乎是由于“目前所有没被wait过的进程退出后，内存不会被回收”导致的问题|
 | divzero | 通过 | |
 | yield | 通过 | |
-| faultreadkernel | 未通过| 原因同faultread |
+| faultreadkernel | 通过 | 原因同faultread |
 | exit | 通过 | |
 | softint | 未实现? | |
 | badsegment | 通过 | |
@@ -29,7 +29,7 @@
 | priority | 通过 | |
 | badarg | 未通过 | PANIC in /home/lcy1996/.rustup/toolchains/nightly-2018-09-18-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/src/libcore/option.rs at line 345 <br> called \`Option::unwrap()\` on a \`None\` value <br> 内核bug?错误原因需要进一步探索|
 | testbss | 未通过 | PANIC in /home/lcy1996/.rustup/toolchains/nightly-2018-09-18-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/src/libcore/option.rs at line 1000<br>failed to allocate frame <br>内核bug?错误原因需要进一步探索|
-| pgdir | 未通过 | [ERROR] unknown syscall id: 0x1f, args: [a, ffff6ad9, 2, 0, 15, ffffffff] <br> 推测原因是尚未实现0x1f这个系统调用 |
+| pgdir | 未通过 | [ERROR] unknown syscall id: 0x1f, args: [a, ffff6ad9, 2, 0, 15, ffffffff] <br> 阅读syscall.rs推测原因是尚未实现0x1f(PGDIR)这个系统调用 |
 | matrix | 通过 | |
 | sleepkill | 未通过 | PANIC in /home/lcy1996/Documents/OSTrain/RustOS/crate/process/src/event_hub.rs at line 55 <br>    attempt to add with overflow <br> 推测与forktree出错原因相同|
 
diff --git a/kernel/src/arch/riscv32/context.rs b/kernel/src/arch/riscv32/context.rs
index 2a61cf4..0dc73e8 100644
--- a/kernel/src/arch/riscv32/context.rs
+++ b/kernel/src/arch/riscv32/context.rs
@@ -5,7 +5,7 @@ use super::super::riscv::register::*;
 pub struct TrapFrame {
     pub x: [usize; 32], // general registers
     pub sstatus: sstatus::Sstatus, // Supervisor Status Register
-    pub sepc: usize, // Supervisor exception program counter (here is used to save the process program entry addr?)
+    pub sepc: usize, // Supervisor exception program counter, save the trap virtual address (here is used to save the process program entry addr?)
     pub sbadaddr: usize, // Supervisor bad address
     pub scause: scause::Scause, // scause register: record the cause of exception/interrupt/trap
 }
diff --git a/kernel/src/arch/riscv32/interrupt.rs b/kernel/src/arch/riscv32/interrupt.rs
index 58ed672..a3784c5 100644
--- a/kernel/src/arch/riscv32/interrupt.rs
+++ b/kernel/src/arch/riscv32/interrupt.rs
@@ -4,6 +4,10 @@ pub use self::context::*;
 #[path = "context.rs"]
 mod context;
 
+/*
+* @brief: 
+*   initialize the interrupt status
+*/
 pub fn init() {
     extern {
         fn __alltraps();
@@ -18,11 +22,21 @@ pub fn init() {
     info!("interrupt: init end");
 }
 
+/*
+* @brief: 
+*   enable interrupt
+*/
 #[inline(always)]
 pub unsafe fn enable() {
     sstatus::set_sie();
 }
 
+/*
+* @brief: 
+*   store and disable interrupt
+* @retbal:
+*   a usize value store the origin sie
+*/
 #[inline(always)]
 pub unsafe fn disable_and_store() -> usize {
     let e = sstatus::read().sie() as usize;
@@ -30,6 +44,12 @@ pub unsafe fn disable_and_store() -> usize {
     e
 }
 
+/*
+* @param:
+*   flags: input flag
+* @brief: 
+*   enable interrupt if flags != 0
+*/
 #[inline(always)]
 pub unsafe fn restore(flags: usize) {
     if flags != 0 {
@@ -37,6 +57,12 @@ pub unsafe fn restore(flags: usize) {
     }
 }
 
+/*
+* @param:
+*   TrapFrame: the trapFrame of the Interrupt/Exception/Trap to be processed
+* @brief: 
+*   process the Interrupt/Exception/Trap
+*/
 #[no_mangle]
 pub extern fn rust_trap(tf: &mut TrapFrame) {
     use super::riscv::register::scause::{Trap, Interrupt as I, Exception as E};
@@ -51,17 +77,33 @@ pub extern fn rust_trap(tf: &mut TrapFrame) {
     trace!("Interrupt end");
 }
 
+/*
+* @brief: 
+*   process timer interrupt
+*/
 fn timer() {
     ::trap::timer();
     super::timer::set_next();
 }
 
+/*
+* @param:
+*   TrapFrame: the Trapframe for the syscall
+* @brief: 
+*   process syscall
+*/
 fn syscall(tf: &mut TrapFrame) {
     tf.sepc += 4;   // Must before syscall, because of fork.
     let ret = ::syscall::syscall(tf.x[10], [tf.x[11], tf.x[12], tf.x[13], tf.x[14], tf.x[15], tf.x[16]], tf);
     tf.x[10] = ret as usize;
 }
 
+/*
+* @param:
+*   TrapFrame: the Trapframe for the illegal inst exception
+* @brief: 
+*   process IllegalInstruction exception
+*/
 fn illegal_inst(tf: &mut TrapFrame) {
     if !emulate_mul_div(tf) {
         ::trap::error(tf);
@@ -69,6 +111,14 @@ fn illegal_inst(tf: &mut TrapFrame) {
 }
 
 /// Migrate from riscv-pk
+/*
+* @param:
+*   TrapFrame: the Trapframe for the illegal inst exception
+* @brief: 
+*   emulate the multiply and divide operation (if not this kind of operation return false)
+* @retval: 
+*   a bool indicates whether emulate the multiply and divide operation successfully
+*/
 fn emulate_mul_div(tf: &mut TrapFrame) -> bool {
     let insn = unsafe { *(tf.sepc as *const usize) };
     let rs1 = tf.x[get_reg(insn, RS1)];
@@ -94,7 +144,7 @@ fn emulate_mul_div(tf: &mut TrapFrame) -> bool {
         return false;
     };
     tf.x[get_reg(insn, RD)] = rd;
-    tf.sepc += 4;
+    tf.sepc += 4; // jump to next instruction
     return true;
 
     fn get_reg(inst: usize, offset: usize) -> usize {
diff --git a/kernel/src/trap.rs b/kernel/src/trap.rs
index 42c7abc..5430e43 100644
--- a/kernel/src/trap.rs
+++ b/kernel/src/trap.rs
@@ -1,6 +1,10 @@
 use process::*;
 use arch::interrupt::TrapFrame;
 
+/*
+* @brief:
+*   process timer interrupt
+*/
 pub fn timer() {
     let mut processor = processor();
     processor.tick();
@@ -12,6 +16,12 @@ pub fn before_return() {
     }
 }
 
+/*
+* @param: 
+*   TrapFrame: the error's trapframe
+* @brief: 
+*   process the error trap, if processor inited then exit else panic!
+*/
 pub fn error(tf: &TrapFrame) -> ! {
     if let Some(processor) = PROCESSOR.try() {
         let mut processor = processor.lock();