convert all C-style comments to Rust-style docs

kernel/src/arch/aarch64/memory.rs

@@ -25,15 +25,7 @@ fn init_frame_allocator() {
     ba.insert(to_range(start, end));
     info!("FrameAllocator init end");
 
-    /*
+    /// Transform memory area `[start, end)` to integer range for `FrameAllocator`
-     * @param:
-     *   start: start address
-     *   end: end address
-     * @brief:
-     *   transform the memory address to the page number
-     * @retval:
-     *   the page number range from start address to end address
-     */
     fn to_range(start: usize, end: usize) -> Range<usize> {
         let page_start = (start - MEMORY_OFFSET) / PAGE_SIZE;
         let page_end = (end - MEMORY_OFFSET - 1) / PAGE_SIZE + 1;

kernel/src/arch/riscv32/interrupt.rs

@@ -6,10 +6,7 @@ use log::*;
 #[path = "context.rs"]
 mod context;
 
-/*
+/// Initialize interrupt
-* @brief:
-*   initialize the interrupt status
-*/
 pub fn init() {
     extern {
         fn trap_entry();
@@ -30,15 +27,13 @@ pub fn init() {
     info!("interrupt: init end");
 }
 
-/*
+/// Enable interrupt
-* @brief:
-*   enable interrupt
-*/
 #[inline]
 pub unsafe fn enable() {
     sstatus::set_sie();
 }
 
+/// Disable interrupt and return current interrupt status
 #[inline]
 pub unsafe fn disable_and_store() -> usize {
     let e = sstatus::read().sie() as usize;
@@ -46,12 +41,7 @@ pub unsafe fn disable_and_store() -> usize {
     e
 }
 
-/*
+/// Enable interrupt if `flags` != 0
-* @param:
-*   flags: input flag
-* @brief:
-*   enable interrupt if flags != 0
-*/
 #[inline]
 pub unsafe fn restore(flags: usize) {
     if flags != 0 {
@@ -59,12 +49,9 @@ pub unsafe fn restore(flags: usize) {
     }
 }
 
-/*
+/// Dispatch and handle interrupt.
-* @param:
+///
-*   TrapFrame: the trapFrame of the Interrupt/Exception/Trap to be processed
+/// This function is called from `trap.asm`.
-* @brief:
-*   process the Interrupt/Exception/Trap
-*/
 #[no_mangle]
 pub extern fn rust_trap(tf: &mut TrapFrame) {
     use self::scause::{Trap, Interrupt as I, Exception as E};
@@ -119,33 +106,17 @@ fn ipi() {
     super::sbi::clear_ipi();
 }
 
-/*
-* @brief:
-*   process timer interrupt
-*/
 fn timer() {
     super::timer::set_next();
     crate::trap::timer();
 }
 
-/*
-* @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 = crate::syscall::syscall(tf.x[17], [tf.x[10], tf.x[11], tf.x[12], tf.x[13], tf.x[14], tf.x[15]], tf);
     tf.x[10] = ret as usize;
 }
 
-/*
-* @param:
-*   TrapFrame: the Trapframe for the page fault exception
-* @brief:
-*   process page fault exception
-*/
 fn page_fault(tf: &mut TrapFrame) {
     let addr = tf.stval;
     trace!("\nEXCEPTION: Page Fault @ {:#x}", addr);

kernel/src/arch/riscv32/memory.rs

@@ -6,10 +6,7 @@ use crate::memory::{FRAME_ALLOCATOR, init_heap, MemoryAttr, MemorySet, Linear};
 use crate::consts::{MEMORY_OFFSET, MEMORY_END, KERNEL_OFFSET};
 use riscv::register::satp;
 
-/*
+/// Initialize the memory management module
-* @brief:
-*   Init the mermory management module, allow memory access and set up page table and init heap and frame allocator
-*/
 pub fn init(dtb: usize) {
     unsafe { sstatus::set_sum(); }  // Allow user memory access
     // initialize heap and Frame allocator
@@ -26,10 +23,6 @@ pub fn init_other() {
     }
 }
 
-/*
-* @brief:
-*   Init frame allocator, here use a BitAlloc implemented by segment tree.
-*/
 fn init_frame_allocator() {
     use bit_allocator::BitAlloc;
     use core::ops::Range;
@@ -40,15 +33,7 @@ fn init_frame_allocator() {
 
     info!("frame allocator: init end");
 
-    /*
+    /// Transform memory area `[start, end)` to integer range for `FrameAllocator`
-    * @param:
-    *   start: start address
-    *   end: end address
-    * @brief:
-    *   transform the memory address to the page number
-    * @retval:
-    *   the page number range from start address to end address
-    */
     fn to_range(start: usize, end: usize) -> Range<usize> {
         let page_start = (start - MEMORY_OFFSET) / PAGE_SIZE;
         let page_end = (end - MEMORY_OFFSET - 1) / PAGE_SIZE + 1;

kernel/src/arch/riscv32/paging.rs

@@ -53,7 +53,7 @@ impl PageTable for ActivePageTable {
 
 impl PageTableExt for ActivePageTable {}
 
-// define the ROOT_PAGE_TABLE, and the virtual address of it?
+/// The virtual address of root page table
 #[cfg(target_arch = "riscv32")]
 const ROOT_PAGE_TABLE: *mut RvPageTable =
     ((RECURSIVE_INDEX     << 12 << 10) |
@@ -149,10 +149,6 @@ impl InactivePageTable for InactivePageTable0 {
         InactivePageTable0 { root_frame: frame }
     }
 
-    /*
-    * @brief:
-    *   map the kernel code memory address (p2 page table) in the new inactive page table according the current active page table
-    */
     #[cfg(target_arch = "riscv32")]
     fn map_kernel(&mut self) {
         let table = unsafe { &mut *ROOT_PAGE_TABLE };
@@ -215,13 +211,6 @@ impl InactivePageTable for InactivePageTable0 {
         unsafe { sfence_vma_all(); }
     }
 
-    /*
-    * @param:
-    *   f: a function to do something with the temporary modified activate page table
-    * @brief:
-    *   temporarily make current `active_table`'s recursive entry point to
-    *    `this` inactive table, so we can modify this inactive page table.
-    */
     fn edit<T>(&mut self, f: impl FnOnce(&mut Self::Active) -> T) -> T {
         let target = satp::read().frame().start_address().as_usize();
         active_table().with_temporary_map(target, |active_table, root_table: &mut RvPageTable| {

kernel/src/arch/riscv32/timer.rs

@@ -2,19 +2,11 @@ use riscv::register::*;
 use super::sbi;
 use log::*;
 
-/*
-* @brief: 
-*   get timer cycle for 64 bit cpu
-*/ 
 #[cfg(target_pointer_width = "64")]
 pub fn get_cycle() -> u64 {
     time::read() as u64
 }
 
-/*
-* @brief: 
-*   get timer cycle for 32 bit cpu
-*/ 
 #[cfg(target_pointer_width = "32")]
 pub fn get_cycle() -> u64 {
     loop {
@@ -32,10 +24,7 @@ pub fn read_epoch() -> u64 {
     0
 }
 
-/*
+/// Enable timer interrupt
-* @brief: 
-*   enable supervisor timer interrupt and set next timer interrupt
-*/
 pub fn init() {
     // Enable supervisor timer interrupt
     unsafe { sie::set_stimer(); }
@@ -43,10 +32,7 @@ pub fn init() {
     info!("timer: init end");
 }
 
-/*
+/// Set the next timer interrupt
-* @brief: 
-*   set the next timer interrupt
-*/
 pub fn set_next() {
     // 100Hz @ QEMU
     let timebase = 250000;