doc: add more docs to libax

And enable all features for cargo clippy

.github/workflows/build.yml

@@ -7,17 +7,19 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
-      matrix:
-        arch: [riscv64, aarch64]
     steps:
     - uses: actions/checkout@v3
     - uses: actions-rs/toolchain@v1
       with:
         profile: minimal
         toolchain: nightly
         components: rust-src, clippy, rustfmt
-    - name: Clippy
-      run: make clippy ARCH=${{ matrix.arch }}
+    - 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: Check code format
       run: cargo fmt --all -- --check
 

Makefile

@@ -85,7 +85,7 @@ debug: build
 	$(GDB) $(OUT_ELF) -ex 'target remote localhost:1234'
 
 clippy:
-	cargo clippy --target $(TARGET)
+	$(call cargo_clippy)
 
 doc:
 	$(call cargo_doc)

crates/kernel_guard/src/lib.rs

@@ -47,6 +47,10 @@ impl NoOp {
     }
 }
 
+impl Drop for NoOp {
+    fn drop(&mut self) {}
+}
+
 #[cfg(any(target_os = "none", doc))]
 mod imp {
     use super::*;

crates/spinlock/src/base.rs

@@ -347,7 +347,7 @@ mod tests {
     fn test_mutex_arc_access_in_unwind() {
         let arc = Arc::new(SpinMutex::<_>::new(1));
         let arc2 = arc.clone();
-        let _ = thread::spawn(move || -> () {
+        let _ = thread::spawn(move || {
             struct Unwinder {
                 i: Arc<SpinMutex<i32>>,
             }

modules/axsync/src/mutex.rs

@@ -200,7 +200,7 @@ mod tests {
 
     #[test]
     fn lots_and_lots() {
-        INIT.call_once(|| axtask::init_scheduler());
+        INIT.call_once(axtask::init_scheduler);
 
         const NUM_TASKS: u32 = 10;
         const NUM_ITERS: u32 = 10_000;

modules/axtask/src/tests.rs

@@ -9,7 +9,7 @@ static SERIAL: Mutex<()> = Mutex::new(());
 #[test]
 fn test_sched_fifo() {
     let _lock = SERIAL.lock();
-    INIT.call_once(|| axtask::init_scheduler());
+    INIT.call_once(axtask::init_scheduler);
 
     const NUM_TASKS: usize = 10;
     static FINISHED_TASKS: AtomicUsize = AtomicUsize::new(0);
@@ -30,7 +30,7 @@ fn test_sched_fifo() {
 #[test]
 fn test_fp_state_switch() {
     let _lock = SERIAL.lock();
-    INIT.call_once(|| axtask::init_scheduler());
+    INIT.call_once(axtask::init_scheduler);
 
     const NUM_TASKS: usize = 5;
     const FLOATS: [f64; NUM_TASKS] = [
@@ -42,14 +42,14 @@ fn test_fp_state_switch() {
     ];
     static FINISHED_TASKS: AtomicUsize = AtomicUsize::new(0);
 
-    for i in 0..NUM_TASKS {
+    for (i, float) in FLOATS.iter().enumerate() {
         axtask::spawn(move || {
-            let mut value = FLOATS[i] + i as f64;
+            let mut value = float + i as f64;
             axtask::yield_now();
             value -= i as f64;
 
             println!("Float {} = {}", i, value);
-            assert!((value - FLOATS[i]).abs() < 1e-9);
+            assert!((value - float).abs() < 1e-9);
             FINISHED_TASKS.fetch_add(1, Ordering::Relaxed);
         });
     }
@@ -61,7 +61,7 @@ fn test_fp_state_switch() {
 #[test]
 fn test_wait_queue() {
     let _lock = SERIAL.lock();
-    INIT.call_once(|| axtask::init_scheduler());
+    INIT.call_once(axtask::init_scheduler);
 
     const NUM_TASKS: usize = 10;
 

scripts/make/cargo.mk

@@ -54,6 +54,11 @@ define cargo_build
   cargo rustc $(build_args) $(1) -- $(rustc_flags)
 endef
 
+define cargo_clippy
+  cargo clippy --target $(TARGET) --all-features --workspace --exclude axlog
+  cargo clippy --target $(TARGET) -p axlog -p percpu -p percpu_macros
+endef
+
 all_packages := \
   $(shell ls $(CURDIR)/crates) \
   $(shell ls $(CURDIR)/modules) \

ulib/libax/Cargo.toml

@@ -2,9 +2,17 @@
 name = "libax"
 version = "0.1.0"
 edition = "2021"
-authors = ["Yuekai Jia <[email protected]>"]
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+authors = [
+    "Yuekai Jia <[email protected]>",
+    "yfblock <[email protected]>",
+    "scPointer <[email protected]>",
+    "Shiping Yuan <[email protected]>",
+]
+description = "ArceOS user library with an interface similar to rust std"
+license = "GPL-3.0-or-later OR Apache-2.0"
+homepage = "https://github.com/rcore-os/arceos"
+repository = "https://github.com/rcore-os/arceos"
+documentation = "https://rcore-os.github.io/arceos/libax/index.html"
 
 [features]
 # Generate bindings for C code

ulib/libax/src/cbindings/fs.rs

@@ -60,10 +60,16 @@ fn flags_to_options(flags: c_int, _mode: ctypes::mode_t) -> OpenOptions {
     options
 }
 
-/// Open a file by `filename` and insert it into `FD_TABLE`, and return its
-/// `FD_TABLE` index. Return `ENFILE` if file table overflow.
+/// Open a file by `filename` and insert it into the file descriptor table.
+///
+/// Return its index in the file table (`fd`). Return `ENFILE` if the file
+/// table overflows.
 #[no_mangle]
-pub extern "C" fn ax_open(filename: *const c_char, flags: c_int, mode: ctypes::mode_t) -> c_int {
+pub unsafe extern "C" fn ax_open(
+    filename: *const c_char,
+    flags: c_int,
+    mode: ctypes::mode_t,
+) -> c_int {
     let filename = char_ptr_to_str(filename);
     debug!("ax_open <= {:?} {:#o} {:#o}", filename, flags, mode);
     ax_call_body!(ax_open, {
@@ -75,7 +81,7 @@ pub extern "C" fn ax_open(filename: *const c_char, flags: c_int, mode: ctypes::m
 
 /// Close a file by `fd`.
 #[no_mangle]
-pub extern "C" fn ax_close(fd: c_int) -> c_int {
+pub unsafe extern "C" fn ax_close(fd: c_int) -> c_int {
     debug!("ax_close <= {}", fd);
     if (0..2).contains(&fd) {
         return 0; // stdin, stdout, stderr
@@ -90,9 +96,15 @@ pub extern "C" fn ax_close(fd: c_int) -> c_int {
     })
 }
 
-/// Seek the position of the file, return its position after seek.
+/// Set the position of the file indicated by `fd`.
+///
+/// Return its position after seek.
 #[no_mangle]
-pub extern "C" fn ax_lseek(fd: c_int, offset: ctypes::off_t, whence: c_int) -> ctypes::off_t {
+pub unsafe extern "C" fn ax_lseek(
+    fd: c_int,
+    offset: ctypes::off_t,
+    whence: c_int,
+) -> ctypes::off_t {
     debug!("ax_lseek <= {} {} {}", fd, offset, whence);
     ax_call_body!(ax_lseek, {
         let pos = match whence {
@@ -107,9 +119,11 @@ pub extern "C" fn ax_lseek(fd: c_int, offset: ctypes::off_t, whence: c_int) -> c
     })
 }
 
-/// Read data from file by `fd`, return read size if success.
+/// Read data from the file indicated by `fd`.
+///
+/// Return the read size if success.
 #[no_mangle]
-pub extern "C" fn ax_read(fd: c_int, buf: *mut c_void, count: usize) -> ctypes::ssize_t {
+pub unsafe extern "C" fn ax_read(fd: c_int, buf: *mut c_void, count: usize) -> ctypes::ssize_t {
     debug!("ax_read <= {} {:#x} {}", fd, buf as usize, count);
     ax_call_body!(ax_read, {
         if buf.is_null() {
@@ -122,9 +136,11 @@ pub extern "C" fn ax_read(fd: c_int, buf: *mut c_void, count: usize) -> ctypes::
     })
 }
 
-/// Write data through `fd`, return written size if success.
+/// Write data to the file indicated by `fd`.
+///
+/// Return the written size if success.
 #[no_mangle]
-pub extern "C" fn ax_write(fd: c_int, buf: *const c_void, count: usize) -> ctypes::ssize_t {
+pub unsafe extern "C" fn ax_write(fd: c_int, buf: *const c_void, count: usize) -> ctypes::ssize_t {
     debug!("ax_write <= {} {:#x} {}", fd, buf as usize, count);
     ax_call_body!(ax_write, {
         if buf.is_null() {
@@ -156,9 +172,11 @@ fn stat_file(file: &File) -> io::Result<ctypes::stat> {
     })
 }
 
-/// Get file info by `path` and write to `buf`, return 0 if success.
+/// Get the file metadata by `path` and write into `buf`.
+///
+/// Return 0 if success.
 #[no_mangle]
-pub extern "C" fn ax_stat(path: *const c_char, buf: *mut ctypes::stat) -> ctypes::ssize_t {
+pub unsafe extern "C" fn ax_stat(path: *const c_char, buf: *mut ctypes::stat) -> ctypes::ssize_t {
     let path = char_ptr_to_str(path);
     debug!("ax_stat <= {:?} {:#x}", path, buf as usize);
     ax_call_body!(ax_stat, {
@@ -173,9 +191,11 @@ pub extern "C" fn ax_stat(path: *const c_char, buf: *mut ctypes::stat) -> ctypes
     })
 }
 
-/// Get symbolic link info and write to `buf`, return 0 if success.
+/// Get the metadata of the symbolic link and write into `buf`.
+///
+/// Return 0 if success.
 #[no_mangle]
-pub extern "C" fn ax_lstat(path: *const c_char, buf: *mut ctypes::stat) -> ctypes::ssize_t {
+pub unsafe extern "C" fn ax_lstat(path: *const c_char, buf: *mut ctypes::stat) -> ctypes::ssize_t {
     let path = char_ptr_to_str(path);
     debug!("ax_lstat <= {:?} {:#x}", path, buf as usize);
     ax_call_body!(ax_lstat, {
@@ -187,9 +207,11 @@ pub extern "C" fn ax_lstat(path: *const c_char, buf: *mut ctypes::stat) -> ctype
     })
 }
 
-/// Get file info by `fd` and write to `buf`, return 0 if success.
+/// Get file metadata by `fd` and write into `buf`.
+///
+/// Return 0 if success.
 #[no_mangle]
-pub extern "C" fn ax_fstat(fd: c_int, buf: *mut ctypes::stat) -> ctypes::ssize_t {
+pub unsafe extern "C" fn ax_fstat(fd: c_int, buf: *mut ctypes::stat) -> ctypes::ssize_t {
     debug!("ax_fstat <= {} {:#x}", fd, buf as usize);
     ax_call_body!(ax_fstat, {
         if buf.is_null() {
@@ -202,9 +224,9 @@ pub extern "C" fn ax_fstat(fd: c_int, buf: *mut ctypes::stat) -> ctypes::ssize_t
     })
 }
 
-/// get the path of the current directory
+/// Get the path of the current directory.
 #[no_mangle]
-pub extern "C" fn ax_getcwd(buf: *mut c_char, size: usize) -> *mut c_char {
+pub unsafe extern "C" fn ax_getcwd(buf: *mut c_char, size: usize) -> *mut c_char {
     debug!("ax_getcwd <= {:#x} {}", buf as usize, size);
     ax_call_body!(ax_getcwd, {
         if buf.is_null() {

ulib/libax/src/cbindings/malloc.rs

@@ -19,7 +19,7 @@ struct MemoryControlBlock {
 ///
 /// Returns 0 on failure (the current implementation does not trigger an exception)
 #[no_mangle]
-pub extern "C" fn ax_malloc(size: usize) -> *mut c_void {
+pub unsafe extern "C" fn ax_malloc(size: usize) -> *mut c_void {
     // Allocate `(actual length) + 8`. The lowest 8 Bytes are stored in the actual allocated space size.
     // This is because free(uintptr_t) has only one parameter representing the address,
     // So we need to save in advance to know the size of the memory space that needs to be released
@@ -30,17 +30,17 @@ pub extern "C" fn ax_malloc(size: usize) -> *mut c_void {
             control_block.size = size;
             (addr + 8) as *mut c_void
         }
-        Err(_) => 0 as *mut c_void,
+        Err(_) => core::ptr::null_mut(),
     }
 }
 
-/// Release memory.
+/// Deallocate memory.
 ///
 /// (WARNING) If the address to be released does not match the allocated address, an error should
 /// occur, but it will NOT be checked out. This is due to the global allocator `Buddy_system`
 /// (currently used) does not check the validity of address to be released.
 #[no_mangle]
-pub extern "C" fn ax_free(addr: *mut c_void) {
+pub unsafe extern "C" fn ax_free(addr: *mut c_void) {
     let size = {
         let control_block = unsafe {
             &mut *((addr as usize - size_of::<MemoryControlBlock>()) as *mut MemoryControlBlock)

ulib/libax/src/cbindings/mod.rs

@@ -1,3 +1,7 @@
+// Exported C bindings, to call ArceOS funtions from C code.
+
+#![allow(clippy::missing_safety_doc)]
+
 #[macro_use]
 mod utils;
 
@@ -15,27 +19,31 @@ mod ctypes;
 use crate::io::Write;
 use core::ffi::{c_char, c_int};
 
+/// Sets the seed for the random number generator.
 #[no_mangle]
-pub extern "C" fn ax_srand(seed: u32) {
+pub unsafe extern "C" fn ax_srand(seed: u32) {
     crate::rand::srand(seed);
 }
 
+/// Returns a 32-bit unsigned pseudo random interger.
 #[no_mangle]
-pub extern "C" fn ax_rand_u32() -> u32 {
+pub unsafe extern "C" fn ax_rand_u32() -> u32 {
     crate::rand::rand_u32()
 }
 
+/// Print a string to the global standard output stream.
 #[no_mangle]
-pub extern "C" fn ax_print_str(buf: *const c_char, count: usize) -> c_int {
+pub unsafe extern "C" fn ax_print_str(buf: *const c_char, count: usize) -> c_int {
     if buf.is_null() {
         return -axerrno::LinuxError::EFAULT.code();
     }
     let bytes = unsafe { core::slice::from_raw_parts(buf as *const u8, count as _) };
     crate::io::stdout().write(bytes).unwrap() as _
 }
 
+/// Abort the current process.
 #[no_mangle]
-pub extern "C" fn ax_panic() -> ! {
+pub unsafe extern "C" fn ax_panic() -> ! {
     panic!()
 }
 

ulib/libax/src/display/mod.rs

@@ -1,11 +1,15 @@
+//! Graphics manipulation operations.
+
 use axdisplay;
 
 pub use axdisplay::DisplayInfo;
 
+/// Returns the framebuffer information.
 pub fn framebuffer_info() -> DisplayInfo {
     axdisplay::framebuffer_info()
 }
 
+/// Flushes the framebuffer.
 pub fn framebuffer_flush() -> isize {
     axdisplay::framebuffer_flush()
 }

ulib/libax/src/env.rs

@@ -1,2 +1,4 @@
+//! Inspection and manipulation of the process’s environment.
+
 #[cfg(feature = "fs")]
 pub use axfs::api::{current_dir, set_current_dir};

ulib/libax/src/fs.rs

@@ -1,3 +1,5 @@
+//! Filesystem manipulation operations.
+
 pub use axfs::api::{canonicalize, metadata, read, read_to_string, remove_file, write};
 pub use axfs::api::{create_dir, create_dir_all, read_dir, remove_dir};
 pub use axfs::api::{DirEntry, File, FileType, Metadata, OpenOptions, Permissions, ReadDir};

ulib/libax/src/io/mod.rs

@@ -1,3 +1,5 @@
+//! Traits, helpers, and type definitions for core I/O functionality.
+
 mod stdio;
 
 pub use axio::prelude;