Initial commit

.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        rust-toolchain: [nightly]
+        targets: [x86_64-unknown-linux-gnu, x86_64-unknown-none, riscv64gc-unknown-none-elf, aarch64-unknown-none-softfloat]
+    steps:
+    - uses: actions/checkout@v4
+    - uses: dtolnay/rust-toolchain@nightly
+      with:
+        toolchain: ${{ matrix.rust-toolchain }}
+        components: rust-src, clippy, rustfmt
+        targets: ${{ matrix.targets }}
+    - name: Check rust version
+      run: rustc --version --verbose
+    - name: Check code format
+      run: cargo fmt --all -- --check
+    - name: Clippy
+      run: cargo clippy --target ${{ matrix.targets }} --all-features -- -A clippy::new_without_default
+    - name: Build
+      run: cargo build --target ${{ matrix.targets }} --all-features
+    - name: Unit test
+      if: ${{ matrix.targets == 'x86_64-unknown-linux-gnu' }}
+      run: cargo test --target ${{ matrix.targets }} -- --nocapture
+
+  doc:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    permissions:
+      contents: write
+    env:
+      default-branch: ${{ format('refs/heads/{0}', github.event.repository.default_branch) }}
+      RUSTDOCFLAGS: -D rustdoc::broken_intra_doc_links -D missing-docs
+    steps:
+    - uses: actions/checkout@v4
+    - uses: dtolnay/rust-toolchain@nightly
+    - name: Build docs
+      continue-on-error: ${{ github.ref != env.default-branch && github.event_name != 'pull_request' }}
+      run: |
+        cargo doc --no-deps --all-features
+        printf '<meta http-equiv="refresh" content="0;url=%s/index.html">' $(cargo tree | head -1 | cut -d' ' -f1) > target/doc/index.html
+    - name: Deploy to Github Pages
+      if: ${{ github.ref == env.default-branch }}
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        single-commit: true
+        branch: gh-pages
+        folder: target/doc

.gitignore

@@ -0,0 +1,3 @@
+/target
+/.vscode
+.DS_Store

Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "kernel_guard"
+version = "0.1.0"
+edition = "2021"
+authors = ["Yuekai Jia <[email protected]>"]
+description = "RAII wrappers to create a critical section with local IRQs or preemption disabled"
+license = "GPL-3.0-or-later OR Apache-2.0 OR MulanPSL-2.0"
+homepage = "https://github.com/arceos-org/arceos"
+repository = "https://github.com/arceos-org/arceos/tree/main/crates/kernel_guard"
+documentation = "https://docs.rs/kernel_guard"
+keywords = ["arceos", "synchronization", "preemption"]
+categories = ["os", "no-std"]
+
+[features]
+preempt = []
+default = []
+
+[dependencies]
+cfg-if = "1.0"
+crate_interface = "0.1"

README.md

@@ -0,0 +1,56 @@
+# kernel_guard
+
+[![Crates.io](https://img.shields.io/crates/v/kernel_guard)](https://crates.io/crates/kernel_guard)
+
+RAII wrappers to create a critical section with local IRQs or preemption
+disabled, used to implement spin locks in kernel.
+
+The critical section is created after the guard struct is created, and is
+ended when the guard falls out of scope.
+
+The crate user must implement the `KernelGuardIf` trait using
+[`crate_interface::impl_interface`](https://crates.io/crates/crate_interface) to provide the low-level implementantion
+of how to enable/disable kernel preemption, if the feature `preempt` is
+enabled.
+
+Available guards:
+
+- `NoOp`: Does nothing around the critical section.
+- `IrqSave`: Disables/enables local IRQs around the critical section.
+- `NoPreempt`: Disables/enables kernel preemption around the critical
+section.
+- `NoPreemptIrqSave`: Disables/enables both kernel preemption and local
+IRQs around the critical section.
+
+## Crate features
+
+- `preempt`: Use in the preemptive system. If this feature is enabled, you
+need to implement the `KernelGuardIf` trait in other crates. Otherwise
+the preemption enable/disable operations will be no-ops. This feature is
+disabled by default.
+
+## Examples
+
+```rust
+use kernel_guard::{KernelGuardIf, NoPreempt};
+
+struct KernelGuardIfImpl;
+
+#[crate_interface::impl_interface]
+impl KernelGuardIf for KernelGuardIfImpl {
+    fn enable_preempt() {
+        // Your implementation here
+    }
+    fn disable_preempt() {
+        // Your implementation here
+    }
+}
+
+let guard = NoPreempt::new();
+/* The critical section starts here
+
+Do something that requires preemption to be disabled
+
+The critical section ends here */
+drop(guard);
+```

src/arch/aarch64.rs

@@ -0,0 +1,14 @@
+use core::arch::asm;
+
+#[inline]
+pub fn local_irq_save_and_disable() -> usize {
+    let flags: usize;
+    // save `DAIF` flags, mask `I` bit (disable IRQs)
+    unsafe { asm!("mrs {}, daif; msr daifset, #2", out(reg) flags) };
+    flags
+}
+
+#[inline]
+pub fn local_irq_restore(flags: usize) {
+    unsafe { asm!("msr daif, {}", in(reg) flags) };
+}

src/arch/mod.rs

@@ -0,0 +1,14 @@
+#![cfg_attr(not(target_os = "none"), allow(dead_code, unused_imports))]
+
+cfg_if::cfg_if! {
+    if #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] {
+        mod x86;
+        pub use self::x86::*;
+    } else if #[cfg(any(target_arch = "riscv32", target_arch = "riscv64"))] {
+        mod riscv;
+        pub use self::riscv::*;
+    } else if #[cfg(target_arch = "aarch64")] {
+        mod aarch64;
+        pub use self::aarch64::*;
+    }
+}

src/arch/riscv.rs

@@ -0,0 +1,18 @@
+use core::arch::asm;
+
+/// Bit 1: Supervisor Interrupt Enable
+const SIE_BIT: usize = 1 << 1;
+
+#[inline]
+pub fn local_irq_save_and_disable() -> usize {
+    let flags: usize;
+    // clear the `SIE` bit, and return the old CSR
+    unsafe { asm!("csrrc {}, sstatus, {}", out(reg) flags, const SIE_BIT) };
+    flags & SIE_BIT
+}
+
+#[inline]
+pub fn local_irq_restore(flags: usize) {
+    // restore the `SIE` bit
+    unsafe { asm!("csrrs x0, sstatus, {}", in(reg) flags) };
+}

src/arch/x86.rs

@@ -0,0 +1,20 @@
+use core::arch::asm;
+
+/// Interrupt Enable Flag (IF)
+const IF_BIT: usize = 1 << 9;
+
+#[inline]
+pub fn local_irq_save_and_disable() -> usize {
+    let flags: usize;
+    unsafe { asm!("pushf; pop {}; cli", out(reg) flags) };
+    flags & IF_BIT
+}
+
+#[inline]
+pub fn local_irq_restore(flags: usize) {
+    if flags != 0 {
+        unsafe { asm!("sti") };
+    } else {
+        unsafe { asm!("cli") };
+    }
+}