doc: add documents of some modules

Documentation all modules is complete, enable missing_doc check in CI

.github/workflows/build.yml

@@ -16,10 +16,10 @@ jobs:
         components: rust-src, clippy, rustfmt
     - name: Clippy for the default target
       run: cargo clippy --all-features
-    - name: Clippy for other targets
-      run: |
-        make clippy ARCH=riscv64
-        make clippy ARCH=aarch64
+    - name: Clippy for riscv64
+      run: make clippy ARCH=riscv64
+    - name: Clippy for aarch64
+      run: make clippy ARCH=aarch64
     - name: Check code format
       run: cargo fmt --all -- --check
 

.github/workflows/docs.yml

@@ -18,7 +18,7 @@ jobs:
         profile: minimal
         toolchain: nightly
     - name: Build docs
-      run: make doc
+      run: make doc_check_missing
     - name: Deploy to Github Pages
       uses: JamesIves/github-pages-deploy-action@v4
       with:

doc/arceos-arch.md

@@ -1,52 +1,56 @@
 # ArceOS Architecture
 
 ## ArceOS Modules
-* [axruntime](../modules/axruntime/): Bootstraping from the bare-metal environment, and initialization.
-* [axhal](../modules/axhal/): Hardware abstraction layer, provides unified APIs for cross-platform.
-* [axconfig](../modules/axconfig/): Platform constants and kernel parameters, such as physical memory base, kernel load addresses, stack size, etc.
-* [axlog](../modules/axlog/): Multi-level log definition and printing.
-* [axalloc](../modules/axalloc/): Dynamic memory allocation.
-* [axdriver](../modules/axdriver/): Device driver framework.
-* [axdisplay](../modules/axdisplay/): Graphic display framework.
-* [axfs](../modules/axfs/): File system framework with low/high level filesystem manipulation operations.
-* [axnet](../modules/axnet/): Network stack.
-* [axsync](../modules/axsync/): Synchronization primitives.
-* [axtask](../modules/axtask/): Task management.
+
+* [axalloc](../modules/axalloc): ArceOS global memory allocator.
+* [axconfig](../modules/axconfig): Platform-specific constants and parameters for ArceOS.
+* [axdisplay](../modules/axdisplay): ArceOS graphics module.
+* [axdriver](../modules/axdriver): ArceOS device drivers.
+* [axfs](../modules/axfs): ArceOS filesystem module.
+* [axhal](../modules/axhal): ArceOS hardware abstraction layer, provides unified APIs for platform-specific operations.
+* [axlog](../modules/axlog): Macros for multi-level formatted logging used by ArceOS.
+* [axnet](../modules/axnet): ArceOS network module.
+* [axruntime](../modules/axruntime): Runtime library of ArceOS.
+* [axsync](../modules/axsync): ArceOS synchronization primitives.
+* [axtask](../modules/axtask): ArceOS task management module.
 
 ## Crates
-* [allocator](../crates/allocator): Memory allocation: bitmap&buddy allocator in page size,  slab allocator in byte size.
-* [arm_gic](../crates/arm_gic): ARM GIC(Generic Interrupt Controller) registers & ops.
-* [axerrno](../crates/axerrno): Error number in linux.
-* [axio](../crates/axio): `std`-like traits, helpers, and type definitions for core I/O functionality.
-* [axfs_devfs](../crates/axfs_devfs): Device file system.
-* [axfs_vfs](../crates/axfs_vfs): Virtual filesystem interfaces.
-* [crate_interface](../crates/crate_interface): crate interface macros for OPs between crates.
-* [driver_block](../crates/driver_block): trait(read_block/write_block/flush) of BlockDriver.
-* [driver_common](../crates/driver_common): trait(device_name/device_type) of BaseDriver, types of drivers.
-* [driver_display](../crates/driver_display):  FrameBuffer, DisplayInfo, trait of DisplayDriver on virtio-gpu.
-* [driver_net](../crates/driver_net): trait of NetBuffer & NetDriver.
-* [driver_virtio](../crates/driver_virtio): config & probe for VirtioDevice(Block/Net/GPU).
-* [handler_table](../crates/handler_table): Exception/Interrupt Handler Table for Hardware abstraction layer -- [axhal](../modules/axhal/).
-* [kernel_guard](../crates/kernel_guard): IRQ OPs.
-* [lazy_init](../crates/lazy_init): Global static variable instance OPs.
-* [linked_list](../crates/linked_list): Based on linux/rust/kernel/linked_list.rs, but use [`unsafe_list::List`](../crates/linked_list/src/unsafe_list.rs) as the inner implementation..
-* [memory_addr](../crates/memory_addr): PhyAddr/VirtAddr related OPs.
-* [page_table](../crates/page_table): Generic page table. 
-* [page_table_entry](../crates/page_table_entry): Generic page table entry.
-* [percpu](../crates/percpu): Framework for per-cpu data.
-* [percpu_macros](../crates/percpu_macros): Macros for per-cpu data.
-* [ratio](../crates/ratio): Convert `numerator / denominator` to `mult / (1 << shift)` to avoid `u128` division.
-* [scheduler](../crates/scheduler): FIFO/RR schedulers.
-* [slab_allocator](../crates/slab_allocator): Memory: slab allocator.
-* [spinlock](../crates/spinlock): Sync: spin lock. 
-* [timer_list](../crates/timer_list): Timer event/list & OPs. 
-* [tuple_for_each](../crates/tuple_for_each): tuple_for_each to traverse devices. 
+
+* [allocator](../crates/allocator): Various allocator algorithms in a unified interface.
+* [arm_gic](../crates/arm_gic): ARM Generic Interrupt Controller (GIC) register definitions and basic operations.
+* [axerrno](../crates/axerrno): Error code definition used by ArceOS.
+* [axfs_devfs](../crates/axfs_devfs): Device filesystem used by ArceOS.
+* [axfs_vfs](../crates/axfs_vfs): Virtual filesystem interfaces used by ArceOS.
+* [axio](../crates/axio): `std::io`-like I/O traits for `no_std` environment.
+* [capability](../crates/capability): Provide basic capability-based security.
+* [crate_interface](../crates/crate_interface): Provides a way to define an interface (trait) in a crate, but can implement or use it in any crate.
+* [driver_block](../crates/driver_block): Common traits and types for block storage drivers.
+* [driver_common](../crates/driver_common): Device driver interfaces used by ArceOS.
+* [driver_display](../crates/driver_display): Common traits and types for graphics device drivers.
+* [driver_net](../crates/driver_net): Common traits and types for network device (NIC) drivers.
+* [driver_virtio](../crates/driver_virtio): Wrappers of some devices in the `virtio-drivers` crate, that implement traits in the `driver_common` series crates.
+* [handler_table](../crates/handler_table): A lock-free table of event handlers.
+* [kernel_guard](../crates/kernel_guard): RAII wrappers to create a critical section with local IRQs or preemption disabled.
+* [lazy_init](../crates/lazy_init): A wrapper for lazy initialized values without concurrency safety but more efficient.
+* [linked_list](../crates/linked_list): Linked lists that supports arbitrary removal in constant time.
+* [memory_addr](../crates/memory_addr): Wrappers and helper functions for physical and virtual addresses.
+* [page_table](../crates/page_table): Generic page table structures for various hardware architectures.
+* [page_table_entry](../crates/page_table_entry): Page table entry definition for various hardware architectures.
+* [percpu](../crates/percpu): Define and access per-CPU data structures.
+* [percpu_macros](../crates/percpu_macros): Macros to define and access a per-CPU data structure.
+* [ratio](../crates/ratio): The type of ratios and related operations.
+* [scheduler](../crates/scheduler): Various scheduler algorithms in a unified interface.
+* [slab_allocator](../crates/slab_allocator): Slab allocator for `no_std` systems. Uses multiple slabs with blocks of different sizes and a linked list for blocks larger than 4096 bytes.
+* [spinlock](../crates/spinlock): `no_std` spin lock implementation that can disable kernel local IRQs or preemption while locking.
+* [timer_list](../crates/timer_list): A list of timed events that will be triggered sequentially when the timer expires.
+* [tuple_for_each](../crates/tuple_for_each): Provides macros and methods to iterate over the fields of a tuple struct.
+
 ## Dependencies
 
 ```mermaid
 graph TD;
 subgraph "User Apps"
-A["Rust App"] 
+A["Rust App"]
 C["C App"]
 end
 subgraph "ArceOS ulib"
@@ -224,4 +228,4 @@ IN9 --> IN3;
 F3 --> IN13;
 F2 --> IN13;
 F1 --> F2;
-```
+```

doc/init.md

@@ -5,7 +5,7 @@ graph TD;
     A --> P[platform_init];
     A --> B[axruntime::rust_main];
     P --> P1["axhal::mem::clear_bss()"];
-    P --> P2["axhal::arch::riscv::set_tap_vector_base()"];
+    P --> P2["axhal::arch::riscv::set_trap_vector_base()"];
     P --> P3["axhal::cpu::init_percpu()"];
     P --> P4["axhal::platform::qemu_virt_riscv::irq.rs::init()"];
     P --> P5["axhal::platform::qemu_virt_riscv::time.rs::init()"];

modules/axconfig/src/lib.rs

@@ -1,10 +1,15 @@
-//! Platform-specific constants and parameters for
-//! [ArceOS](https://github.com/rcore-os/arceos).
+//! Platform-specific constants and parameters for [ArceOS].
 //!
-//! Currently supported platforms (corresponding cargo features):
+//! Currently supported platforms (specify by cargo features):
 //!
 //! - `platform-qemu-virt-riscv`: QEMU virt machine with RISC-V ISA.
 //! - `platform-qemu-virt-aarch64`: QEMU virt machine with AArch64 ISA.
+//! - `dummy`: If none of the above platform is selected, the dummy platform
+//!    will be used. In this platform, most of the constants are dummy values.
+//!    This platform is mainly used for [cargo test].
+//!
+//! [ArceOS]: https://github.com/rcore-os/arceos
+//! [cargo test]: https://doc.rust-lang.org/cargo/guide/tests.html
 
 #![no_std]
 

modules/axhal/Cargo.toml

@@ -3,18 +3,21 @@ name = "axhal"
 version = "0.1.0"
 edition = "2021"
 authors = ["Yuekai Jia <equation618@gmail.com>"]
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+description = "ArceOS hardware abstraction layer, provides unified APIs for platform-specific operations"
+license = "GPL-3.0-or-later OR Apache-2.0"
+homepage = "https://github.com/rcore-os/arceos"
+repository = "https://github.com/rcore-os/arceos/tree/main/modules/axhal"
+documentation = "https://rcore-os.github.io/arceos/axhal/index.html"
 
 [features]
 smp = []
 fp_simd = []
+paging = ["axalloc", "page_table"]
 platform-qemu-virt-riscv = ["axconfig/platform-qemu-virt-riscv"]
 platform-qemu-virt-aarch64 = [
     "axconfig/platform-qemu-virt-aarch64",
     "dep:page_table_entry", "dep:ratio",
 ]
-paging = ["axalloc", "page_table"]
 default = []
 
 [dependencies]

modules/axhal/src/arch/aarch64/context.rs

@@ -1,6 +1,7 @@
 use core::arch::asm;
 use memory_addr::VirtAddr;
 
+/// Saved registers when a trap (exception) occurs.
 #[repr(C)]
 #[derive(Debug, Default, Clone, Copy)]
 pub struct TrapFrame {
@@ -14,11 +15,15 @@ pub struct TrapFrame {
     pub spsr: u64,
 }
 
+/// FP & SIMD registers.
 #[repr(C, align(16))]
 #[derive(Debug, Default)]
 pub struct FpState {
+    /// 128-bit SIMD & FP registers (V0..V31)
     pub regs: [u128; 32],
+    /// Floating-point Control Register (FPCR)
     pub fpcr: u32,
+    /// Floating-point Status Register (FPSR)
     pub fpsr: u32,
 }
 
@@ -29,6 +34,18 @@ impl FpState {
     }
 }
 
+/// Saved hardware states of a task.
+///
+/// The context usually includes:
+///
+/// - Callee-saved registers
+/// - Stack pointer register
+/// - Thread pointer register (for thread-local storage, currently unsupported)
+/// - FP/SIMD registers
+///
+/// On context switch, current task saves its context from CPU to memory,
+/// and the next task restores its context from memory to CPU.
+#[allow(missing_docs)]
 #[repr(C)]
 #[derive(Debug)]
 pub struct TaskContext {
@@ -51,15 +68,22 @@ pub struct TaskContext {
 }
 
 impl TaskContext {
+    /// Creates a new default context for a new task.
     pub const fn new() -> Self {
         unsafe { core::mem::MaybeUninit::zeroed().assume_init() }
     }
 
+    /// Initializes the context for a new task, with the given entry point and
+    /// kernel stack.
     pub fn init(&mut self, entry: usize, kstack_top: VirtAddr) {
         self.sp = kstack_top.as_usize() as u64;
         self.lr = entry as u64;
     }
 
+    /// Switches to another task.
+    ///
+    /// It first saves the current task's context from CPU to this place, and then
+    /// restores the next task's context from `next_ctx` to CPU.
     pub fn switch_to(&mut self, next_ctx: &Self) {
         #[cfg(feature = "fp_simd")]
         self.fp_state.switch_to(&next_ctx.fp_state);

modules/axhal/src/arch/aarch64/mod.rs

@@ -7,34 +7,43 @@ use aarch64_cpu::registers::{DAIF, TTBR1_EL1, VBAR_EL1};
 use memory_addr::{PhysAddr, VirtAddr};
 use tock_registers::interfaces::{Readable, Writeable};
 
-pub use self::context::{TaskContext, TrapFrame};
+pub use self::context::{FpState, TaskContext, TrapFrame};
 
+/// Allows the current CPU to respond to interrupts.
 #[inline]
 pub fn enable_irqs() {
     unsafe { asm!("msr daifclr, #2") };
 }
 
+/// Makes the current CPU to ignore interrupts.
 #[inline]
 pub fn disable_irqs() {
     unsafe { asm!("msr daifset, #2") };
 }
 
+/// Returns whether the current CPU is allowed to respond to interrupts.
 #[inline]
 pub fn irqs_enabled() -> bool {
     !DAIF.matches_all(DAIF::I::Masked)
 }
 
+/// Relaxes the current CPU and waits for interrupts.
 #[inline]
 pub fn wait_for_irqs() {
     aarch64_cpu::asm::wfi();
 }
 
+/// Reads the register that stores the current page table root.
+///
+/// Returns the physical address of the page table root.
 #[inline]
 pub fn read_page_table_root() -> PhysAddr {
     let root = TTBR1_EL1.get();
     PhysAddr::from(root as usize)
 }
 
+/// Writes the register to update the current page table root.
+///
 /// # Safety
 ///
 /// This function is unsafe as it changes the virtual memory address space.
@@ -48,6 +57,10 @@ pub unsafe fn write_page_table_root(root_paddr: PhysAddr) {
     }
 }
 
+/// Flushes the TLB.
+///
+/// If `vaddr` is [`None`], flushes the entire TLB. Otherwise, flushes the TLB
+/// entry that maps the given virtual address.
 #[inline]
 pub fn flush_tlb(vaddr: Option<VirtAddr>) {
     unsafe {
@@ -60,11 +73,13 @@ pub fn flush_tlb(vaddr: Option<VirtAddr>) {
     }
 }
 
+/// Flushes the entire instruction cache.
 #[inline]
 pub fn flush_icache_all() {
     unsafe { asm!("ic iallu; dsb sy; isb") };
 }
 
+/// Sets the base address of the exception vector (writes `VBAR_EL1`).
 #[inline]
 pub fn set_exception_vector_base(vbar_el1: usize) {
     VBAR_EL1.set(vbar_el1 as _);

modules/axhal/src/arch/mod.rs

@@ -1,3 +1,5 @@
+//! Architecture-specific types and operations.
+
 cfg_if::cfg_if! {
     if #[cfg(target_arch = "x86_64")] {
         mod x86_64;

modules/axhal/src/arch/riscv/context.rs

@@ -3,6 +3,8 @@ use memory_addr::VirtAddr;
 
 include_asm_marcos!();
 
+/// General registers of RISC-V.
+#[allow(missing_docs)]
 #[repr(C)]
 #[derive(Debug, Default, Clone)]
 pub struct GeneralRegisters {
@@ -39,14 +41,30 @@ pub struct GeneralRegisters {
     pub t6: usize,
 }
 
+/// Saved registers when a trap (interrupt or exception) occurs.
 #[repr(C)]
 #[derive(Debug, Default, Clone)]
 pub struct TrapFrame {
+    /// All general registers.
     pub regs: GeneralRegisters,
+    /// Supervisor Exception Program Counter.
     pub sepc: usize,
+    /// Supervisor Status Register.
     pub sstatus: usize,
 }
 
+/// Saved hardware states of a task.
+///
+/// The context usually includes:
+///
+/// - Callee-saved registers
+/// - Stack pointer register
+/// - Thread pointer register (for thread-local storage, currently unsupported)
+/// - FP/SIMD registers
+///
+/// On context switch, current task saves its context from CPU to memory,
+/// and the next task restores its context from memory to CPU.
+#[allow(missing_docs)]
 #[repr(C)]
 #[derive(Debug, Default)]
 pub struct TaskContext {
@@ -70,15 +88,22 @@ pub struct TaskContext {
 }
 
 impl TaskContext {
+    /// Creates a new default context for a new task.
     pub const fn new() -> Self {
         unsafe { core::mem::MaybeUninit::zeroed().assume_init() }
     }
 
+    /// Initializes the context for a new task, with the given entry point and
+    /// kernel stack.
     pub fn init(&mut self, entry: usize, kstack_top: VirtAddr) {
         self.sp = kstack_top.as_usize();
         self.ra = entry;
     }
 
+    /// Switches to another task.
+    ///
+    /// It first saves the current task's context from CPU to this place, and then
+    /// restores the next task's context from `next_ctx` to CPU.
     pub fn switch_to(&mut self, next_ctx: &Self) {
         unsafe {
             // TODO: switch TLS