Docs and CI actions

.github/workflows/clippy.yml

@@ -0,0 +1,40 @@
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+  merge_group:
+
+name: Lints compliance check
+
+env:
+  CLIPPY_PARAMS: -W clippy::all -W clippy::pedantic -W clippy::nursery -W clippy::cargo
+
+jobs:
+  clippy:
+    strategy:
+      matrix:
+        toolchain: [ stable, nightly ]
+        cargo_flags: [ ]
+        include:
+          # Nightly is only for reference and allowed to fail
+          - toolchain: nightly
+            experimental: true
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.experimental || false }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.toolchain }}
+          components: clippy
+      - name: Run clippy
+        run: cargo clippy --all ${{ matrix.cargo_flags }} -- -D warnings
+
+   # Job to check that all the lint checks succeeded
+  clippy-check:
+    needs:
+    - clippy
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - run: jq --exit-status 'all(.result == "success")' <<< '${{ toJson(needs) }}'

.github/workflows/rustfmt.yml

@@ -0,0 +1,18 @@
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+  merge_group:
+
+name: Code formatting check
+
+jobs:
+  rustfmt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - name: Run Rustfmt
+        run: cargo fmt --all -- --check --verbose

README.md

@@ -1,6 +1,6 @@
 # `riscv-peripheral`
 
-> Standard RISC-V targets for embedded systems written in Rust
+> Standard RISC-V peripherals for embedded systems written in Rust
 
 ## Minimum Supported Rust Version (MSRV)
 

src/aclint.rs

@@ -41,6 +41,7 @@ pub unsafe trait HartIdNumber: Copy {
 /// * This trait must only be implemented on a PAC of a target with a CLINT peripheral.
 /// * The CLINT peripheral base address `BASE` must be valid for the target device.
 pub unsafe trait Clint: Copy {
+    /// Base address of the CLINT peripheral.
     const BASE: usize;
 }
 
@@ -64,6 +65,38 @@ impl<C: Clint> CLINT<C> {
 
     const MTIME_OFFSET: usize = 0xBFF8;
 
+    /// Enables machine software interrupts to let the `MSWI` peripheral trigger interrupts.
+    ///
+    /// # Safety
+    ///
+    /// Enabling the `MSWI` may break mask-based critical sections.
+    #[inline]
+    pub unsafe fn enable_mswi() {
+        mswi::MSWI::enable();
+    }
+
+    /// Disables machine software interrupts to prevent the `MSWI` peripheral from triggering interrupts.
+    #[inline]
+    pub fn disable_mswi() {
+        mswi::MSWI::disable();
+    }
+
+    /// Enables machine timer interrupts to let the `MTIMER` peripheral trigger interrupts.
+    ///
+    /// # Safety
+    ///
+    /// Enabling the `MTIMER` may break mask-based critical sections.
+    #[inline]
+    pub unsafe fn enable_mtimer() {
+        mtimer::MTIMER::enable();
+    }
+
+    /// Disables machine timer interrupts to prevent the `MTIMER` peripheral from triggering interrupts.
+    #[inline]
+    pub fn disable_mtimer() {
+        mtimer::MTIMER::disable();
+    }
+
     /// Returns the `MSWI` peripheral.
     #[inline]
     pub const fn mswi() -> mswi::MSWI {
@@ -128,6 +161,7 @@ pub(crate) mod test {
         assert_eq!(HartId::from_number(3), Err(3));
     }
 
+    #[allow(dead_code)]
     #[test]
     fn check_clint() {
         // Call CLINT macro with a base address and a list of mtimecmps for easing access to per-HART mtimecmp regs.

src/aclint/mswi.rs

@@ -1,7 +1,9 @@
+//! Machine-level Software Interrupt Device.
+
 pub use super::HartIdNumber;
 use crate::common::unsafe_peripheral;
 
-/// Machine-level Software Interrupt Device.
+/// MSWI peripheral.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[repr(transparent)]
 pub struct MSWI {

src/aclint/mtimer.rs

@@ -1,7 +1,9 @@
+//! Machine-level Timer Device.
+
 pub use super::HartIdNumber;
 use crate::common::safe_peripheral;
 
-/// Machine-level Timer Device.
+/// MTIMER peripheral.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub struct MTIMER {
     /// `MTIMECMP` register for HART ID 0.  In multi-HART architectures,

src/aclint/sswi.rs

@@ -1,7 +1,9 @@
+//! Supervisor-level Software Interrupt Device.
+
 pub use super::HartIdNumber;
 use crate::common::unsafe_peripheral;
 
-/// Supervisor-level Software Interrupt Device.
+/// SSWI peripheral.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[repr(transparent)]
 pub struct SSWI {

src/lib.rs

@@ -1,3 +1,6 @@
+//! Standard RISC-V peripherals for embedded systems written in Rust
+
+#![deny(missing_docs)]
 #![no_std]
 
 pub use riscv; // re-export riscv crate to allow users to use it without importing it

src/macros.rs

@@ -1,3 +1,5 @@
+//! Utility macros for generating standard peripherals-related code in RISC-V PACs.
+
 /// Macro to create interfaces to CLINT peripherals in PACs.
 /// The resulting struct will be named `CLINT`, and will provide safe access to the CLINT registers.
 ///
@@ -73,6 +75,38 @@ macro_rules! clint_codegen {
         }
 
         impl CLINT {
+            /// Enables the `MSWI` peripheral.
+            ///
+            /// # Safety
+            ///
+            /// Enabling the `MSWI` may break mask-based critical sections.
+            #[inline]
+            pub unsafe fn enable_mswi() {
+                $crate::aclint::CLINT::<CLINT>::enable_mswi();
+            }
+
+            /// Disables the `MSWI` peripheral.
+            #[inline]
+            pub fn disable_mswi() {
+                $crate::aclint::CLINT::<CLINT>::disable_mswi();
+            }
+
+            /// Enables the `MTIMER` peripheral.
+            ///
+            /// # Safety
+            ///
+            /// Enabling the `MTIMER` may break mask-based critical sections.
+            #[inline]
+            pub unsafe fn enable_mtimer() {
+                $crate::aclint::CLINT::<CLINT>::enable_mtimer();
+            }
+
+            /// Disables the `MTIMER` peripheral.
+            #[inline]
+            pub fn disable_mtimer() {
+                $crate::aclint::CLINT::<CLINT>::disable_mtimer();
+            }
+
             /// Returns the `MSWI` peripheral.
             #[inline]
             pub const fn mswi() -> $crate::aclint::mswi::MSWI {
@@ -103,6 +137,7 @@ macro_rules! clint_codegen {
     };
 }
 
+/// Macro to create interfaces to PLIC peripherals in PACs.
 #[macro_export]
 macro_rules! plic_codegen {
     () => {

src/plic/pendings.rs

@@ -5,6 +5,7 @@ use crate::{
     plic::InterruptNumber,
 };
 
+/// Interrupts pending bits register.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[repr(transparent)]
 pub struct PENDINGS {

src/plic/priorities.rs

@@ -5,6 +5,7 @@ use crate::{
     plic::{InterruptNumber, PriorityNumber},
 };
 
+/// Interrupts priorities register.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[repr(transparent)]
 pub struct PRIORITIES {