update comments

os/src/main.rs

@@ -30,14 +30,13 @@ mod lang_items;
 mod loader;
 mod sbi;
 mod sync;
-mod syscall;
-mod task;
-mod trap;
+pub mod syscall;
+pub mod task;
+pub mod trap;
 
 global_asm!(include_str!("entry.asm"));
 global_asm!(include_str!("link_app.S"));
 
-
 /// clear BSS segment
 fn clear_bss() {
     extern "C" {

os/src/task/context.rs

@@ -1,14 +1,19 @@
 //! Implementation of [`TaskContext`]
 
+/// Task Context
 #[derive(Copy, Clone)]
 #[repr(C)]
 pub struct TaskContext {
+    /// return address ( e.g. __restore ) of __switch ASM function
     ra: usize,
+    /// kernel stack pointer of app
     sp: usize,
+    /// callee saved registers:  s 0..11
     s: [usize; 12],
 }
 
 impl TaskContext {
+    /// init task context
     pub fn zero_init() -> Self {
         Self {
             ra: 0,
@@ -16,6 +21,8 @@ impl TaskContext {
             s: [0; 12],
         }
     }
+
+    /// set task context {__restore ASM funciton, kernel stack, s_0..12 }
     pub fn goto_restore(kstack_ptr: usize) -> Self {
         extern "C" {
             fn __restore();

os/src/task/mod.rs

@@ -6,7 +6,7 @@
 //! A single global instance of [`TaskManager`] called `TASK_MANAGER` controls
 //! all the tasks in the operating system.
 //!
-//! Be careful when you see [`__switch`]. Control flow around this function
+//! Be careful when you see `__switch` ASM function in `switch.S`. Control flow around this function
 //! might not be what you expect.
 
 mod context;
@@ -40,7 +40,8 @@ pub struct TaskManager {
     inner: UPSafeCell<TaskManagerInner>,
 }
 
-struct TaskManagerInner {
+/// Inner of Task Manager
+pub struct TaskManagerInner {
     /// task list
     tasks: [TaskControlBlock; MAX_APP_NUM],
     /// id of current `Running` task
@@ -48,6 +49,7 @@ struct TaskManagerInner {
 }
 
 lazy_static! {
+    /// Global variable: TASK_MANAGER
     pub static ref TASK_MANAGER: TaskManager = {
         let num_app = get_num_app();
         let mut tasks = [TaskControlBlock {
@@ -136,27 +138,33 @@ impl TaskManager {
     }
 }
 
+/// run first task
 pub fn run_first_task() {
     TASK_MANAGER.run_first_task();
 }
 
+/// rust next task
 fn run_next_task() {
     TASK_MANAGER.run_next_task();
 }
 
+/// suspend current task
 fn mark_current_suspended() {
     TASK_MANAGER.mark_current_suspended();
 }
 
+/// exit current task
 fn mark_current_exited() {
     TASK_MANAGER.mark_current_exited();
 }
 
+/// suspend current task, then run next task
 pub fn suspend_current_and_run_next() {
     mark_current_suspended();
     run_next_task();
 }
 
+/// exit current task,  then run next task
 pub fn exit_current_and_run_next() {
     mark_current_exited();
     run_next_task();

os/src/trap/context.rs

@@ -1,25 +1,30 @@
 use riscv::register::sstatus::{self, Sstatus, SPP};
-
+/// Trap Context
 #[repr(C)]
 pub struct TrapContext {
+    /// general regs[0..31]
     pub x: [usize; 32],
+    /// CSR sstatus      
     pub sstatus: Sstatus,
+    /// CSR sepc
     pub sepc: usize,
 }
 
 impl TrapContext {
+    /// set stack pointer to x_2 reg (sp)
     pub fn set_sp(&mut self, sp: usize) {
         self.x[2] = sp;
     }
+    /// init app context
     pub fn app_init_context(entry: usize, sp: usize) -> Self {
-        let mut sstatus = sstatus::read();
-        sstatus.set_spp(SPP::User);
+        let mut sstatus = sstatus::read(); // CSR sstatus
+        sstatus.set_spp(SPP::User); //previous privilege mode: user mode
         let mut cx = Self {
             x: [0; 32],
             sstatus,
-            sepc: entry,
+            sepc: entry, // entry point of app
         };
-        cx.set_sp(sp);
-        cx
+        cx.set_sp(sp); // app's user stack pointer
+        cx // return initial Trap Context of app
     }
 }