From d1104a2226e302d209e4d53b180933307e3ab9f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=94=B0=E5=87=AF=E5=A4=AB?= Date: Mon, 14 Mar 2022 16:37:10 +0800 Subject: [PATCH] Update docs --- os/src/loader.rs | 5 +++++ os/src/sbi.rs | 3 +++ os/src/syscall/mod.rs | 1 + os/src/syscall/process.rs | 2 ++ os/src/task/mod.rs | 15 +++++++++++++++ os/src/trap/mod.rs | 6 ++++-- 6 files changed, 30 insertions(+), 2 deletions(-) diff --git a/os/src/loader.rs b/os/src/loader.rs index 0f08a174..f2ed4f04 100644 --- a/os/src/loader.rs +++ b/os/src/loader.rs @@ -41,10 +41,12 @@ impl UserStack { } } +/// Get base address of app i. fn get_base_i(app_id: usize) -> usize { APP_BASE_ADDRESS + app_id * APP_SIZE_LIMIT } +/// Get the total number of applications. pub fn get_num_app() -> usize { extern "C" { fn _num_app(); @@ -52,6 +54,8 @@ pub fn get_num_app() -> usize { unsafe { (_num_app as usize as *const usize).read_volatile() } } +/// Load nth user app at +/// [APP_BASE_ADDRESS + n * APP_SIZE_LIMIT, APP_BASE_ADDRESS + (n+1) * APP_SIZE_LIMIT). pub fn load_apps() { extern "C" { fn _num_app(); @@ -78,6 +82,7 @@ pub fn load_apps() { } } +/// get app info with entry and sp and save `TrapContext` in kernel stack pub fn init_app_cx(app_id: usize) -> usize { KERNEL_STACK[app_id].push_context(TrapContext::app_init_context( get_base_i(app_id), diff --git a/os/src/sbi.rs b/os/src/sbi.rs index 90ba2c2a..f66d9751 100644 --- a/os/src/sbi.rs +++ b/os/src/sbi.rs @@ -27,14 +27,17 @@ fn sbi_call(which: usize, arg0: usize, arg1: usize, arg2: usize) -> usize { ret } +/// use sbi call to putchar in console (qemu uart handler) pub fn console_putchar(c: usize) { sbi_call(SBI_CONSOLE_PUTCHAR, c, 0, 0); } +/// use sbi call to getchar from console (qemu uart handler) pub fn console_getchar() -> usize { sbi_call(SBI_CONSOLE_GETCHAR, 0, 0, 0) } +/// use sbi call to shutdown the kernel pub fn shutdown() -> ! { sbi_call(SBI_SHUTDOWN, 0, 0, 0); panic!("It should shutdown!"); diff --git a/os/src/syscall/mod.rs b/os/src/syscall/mod.rs index 804c94b4..0fe4e215 100644 --- a/os/src/syscall/mod.rs +++ b/os/src/syscall/mod.rs @@ -9,6 +9,7 @@ mod process; use fs::*; use process::*; +/// handle syscall exception with `syscall_id` and other arguments pub fn syscall(syscall_id: usize, args: [usize; 3]) -> isize { match syscall_id { SYSCALL_WRITE => sys_write(args[0], args[1] as *const u8, args[2]), diff --git a/os/src/syscall/process.rs b/os/src/syscall/process.rs index 55912373..3349b630 100644 --- a/os/src/syscall/process.rs +++ b/os/src/syscall/process.rs @@ -1,11 +1,13 @@ use crate::task::{exit_current_and_run_next, suspend_current_and_run_next}; +/// task exits and submit an exit code pub fn sys_exit(exit_code: i32) -> ! { println!("[kernel] Application exited with code {}", exit_code); exit_current_and_run_next(); panic!("Unreachable in sys_exit!"); } +/// current task gives up resources for other tasks pub fn sys_yield() -> isize { suspend_current_and_run_next(); 0 diff --git a/os/src/task/mod.rs b/os/src/task/mod.rs index 6f6b54cf..e9ecd47b 100644 --- a/os/src/task/mod.rs +++ b/os/src/task/mod.rs @@ -14,12 +14,16 @@ use task::{TaskControlBlock, TaskStatus}; pub use context::TaskContext; pub struct TaskManager { + /// total number of tasks num_app: usize, + /// use inner value to get mutable access inner: UPSafeCell, } struct TaskManagerInner { + /// task list tasks: [TaskControlBlock; MAX_APP_NUM], + /// id of current `Running` task current_task: usize, } @@ -47,6 +51,10 @@ lazy_static! { } impl TaskManager { + /// Run the first task in task list. + /// + /// Generally, the first task in task list is an idle task (we call it zero process later). + /// But in ch3, we load apps statically, so the first task is a real app. fn run_first_task(&self) -> ! { let mut inner = self.inner.exclusive_access(); let task0 = &mut inner.tasks[0]; @@ -61,18 +69,23 @@ impl TaskManager { panic!("unreachable in run_first_task!"); } + /// Change the status of current `Running` task into `Ready`. fn mark_current_suspended(&self) { let mut inner = self.inner.exclusive_access(); let current = inner.current_task; inner.tasks[current].task_status = TaskStatus::Ready; } + /// Change the status of current `Running` task into `Exited`. fn mark_current_exited(&self) { let mut inner = self.inner.exclusive_access(); let current = inner.current_task; inner.tasks[current].task_status = TaskStatus::Exited; } + /// Find next task to run and return app id. + /// + /// In this case, we only return the first `Ready` task in task list. fn find_next_task(&self) -> Option { let inner = self.inner.exclusive_access(); let current = inner.current_task; @@ -81,6 +94,8 @@ impl TaskManager { .find(|id| inner.tasks[*id].task_status == TaskStatus::Ready) } + /// Switch current `Running` task to the task we have found, + /// or there is no `Ready` task and we can exit with all applications completed fn run_next_task(&self) { if let Some(next) = self.find_next_task() { let mut inner = self.inner.exclusive_access(); diff --git a/os/src/trap/mod.rs b/os/src/trap/mod.rs index db33a18a..b199500f 100644 --- a/os/src/trap/mod.rs +++ b/os/src/trap/mod.rs @@ -10,6 +10,7 @@ use riscv::register::{ global_asm!(include_str!("trap.S")); +/// initialize CSR `stvec` as the entry of `__alltraps` pub fn init() { extern "C" { fn __alltraps(); @@ -20,9 +21,10 @@ pub fn init() { } #[no_mangle] +/// handle an interrupt, exception, or system call from user space pub fn trap_handler(cx: &mut TrapContext) -> &mut TrapContext { - let scause = scause::read(); - let stval = stval::read(); + let scause = scause::read(); // get trap cause + let stval = stval::read(); // get extra value match scause.cause() { Trap::Exception(Exception::UserEnvCall) => { cx.sepc += 4;