Rework of PLIC

romancardenas · romancardenas · commit 9d6a40382acd · 2025-05-21T20:01:41.000+02:00
diff --git a/riscv-peripheral/CHANGELOG.md b/riscv-peripheral/CHANGELOG.md
@@ -11,7 +11,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - Rework of CLINT peripheral to use methods instead of associated functions.
   This change follows the `svd2rust` pattern, making the ecosystem more consistent.
-- Simplify `clint!` macro using the `Deref` trait.
+- Simplify `clint_codegen!` macro using the `Deref` trait.
+- Rework of PLIC peripherals to use methods instead of associated functions.
+  This change follows the `svd2rust` pattern, making the ecosystem more consistent.
+- Simplify `plic_codegen!` macro using the `Deref` trait.
 
 ### Removed
 
diff --git a/riscv-peripheral/examples/e310x.rs b/riscv-peripheral/examples/e310x.rs
@@ -147,7 +147,7 @@ riscv_peripheral::clint_codegen!(
 
 riscv_peripheral::plic_codegen!(
     base 0x0C00_0000,
-    ctxs [ctx0=(HartId::H0,"`H0`")],
+    harts [HartId::H0 => 0],
 );
 
 fn main() {}
diff --git a/riscv-peripheral/src/macros.rs b/riscv-peripheral/src/macros.rs
@@ -140,7 +140,7 @@ macro_rules! clint_codegen {
 /// This macro expects 2 different argument types:
 ///
 /// - Base address (**MANDATORY**): base address of the PLIC peripheral of the target.
-/// - Per-HART contexts (**OPTIONAL**): a list of `ctx` contexts for easing access to per-HART PLIC contexts.
+/// - HART map (**OPTIONAL**): a list of HART IDs and their corresponding numbers.
 ///
 /// Check the examples below for more details about the usage and syntax of this macro.
 ///
@@ -153,8 +153,48 @@ macro_rules! clint_codegen {
 ///
 /// riscv_peripheral::plic_codegen!(base 0x0C00_0000,); // do not forget the ending comma!
 ///
-/// let priorities = PLIC::priorities(); // Priorities registers
-/// let pendings = PLIC::pendings();     // Pendings registers
+/// let plic = PLIC::new(); // Create a new PLIC peripheral
+/// let priorities = plic.priorities(); // Priorities registers
+/// let pendings = plic.pendings();     // Pendings registers
+/// ```
+///
+///
+/// ## Base address and per-HART context proxies
+///
+/// ```
+/// use riscv_pac::result::{Error, Result};
+///
+/// /// HART IDs for the target CLINT peripheral
+/// #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+/// pub enum HartId { H0 = 0, H1 = 1, H2 = 2 }
+///
+/// // Implement `HartIdNumber` for `HartId`
+/// unsafe impl riscv_peripheral::aclint::HartIdNumber for HartId {
+///   const MAX_HART_ID_NUMBER: usize = Self::H2 as usize;
+///   fn number(self) -> usize { self as _ }
+///   fn from_number(number: usize) -> Result<Self> {
+///     match number {
+///      0 => Ok(HartId::H0),
+///      1 => Ok(HartId::H1),
+///      2 => Ok(HartId::H2),
+///      _ => Err(Error::InvalidVariant(number)),
+///     }
+///   }
+/// }
+///
+/// riscv_peripheral::plic_codegen!(
+///     base 0x0C00_0000,
+///     harts [HartId::H0 => 0, HartId::H1 => 1, HartId::H2 => 2], // do not forget the ending comma!
+/// );
+///
+/// let plic = PLIC::new(); // Create a new PLIC peripheral
+/// let ctx0 = plic.ctx0(); // Context proxy for HART 0
+/// let ctx1 = plic.ctx1(); // Context proxy for HART 1
+/// let ctx2 = plic.ctx2(); // Context proxy for HART 2
+///
+/// assert_eq!(ctx0, plic.ctx(HartId::H0));
+/// assert_eq!(ctx1, plic.ctx(HartId::H1));
+/// assert_eq!(ctx2, plic.ctx(HartId::H2));
 /// ```
 #[macro_export]
 macro_rules! plic_codegen {
@@ -166,84 +206,51 @@ macro_rules! plic_codegen {
         /// PLIC peripheral
         #[allow(clippy::upper_case_acronyms)]
         #[derive(Clone, Copy, Debug, Eq, PartialEq)]
-        pub struct PLIC;
-
-        unsafe impl $crate::plic::Plic for PLIC {
-            const BASE: usize = $addr;
-        }
+        pub struct PLIC($crate::plic::PLIC<Self>);
 
         impl PLIC {
-            /// Returns `true` if a machine external interrupt is pending.
-            #[inline]
-            pub fn is_interrupting() -> bool {
-                $crate::riscv::register::mip::read().mext()
-            }
-
-            /// Returns true if Machine External Interrupts are enabled.
-            #[inline]
-            pub fn is_enabled() -> bool {
-                $crate::riscv::register::mie::read().mext()
-            }
-
-            /// Enables machine external interrupts to allow the PLIC to trigger interrupts.
-            ///
-            /// # Safety
-            ///
-            /// Enabling the `PLIC` may break mask-based critical sections.
-            #[inline]
-            pub unsafe fn enable() {
-                $crate::riscv::register::mie::set_mext();
-            }
-
-            /// Disables machine external interrupts to prevent the PLIC from triggering interrupts.
+            /// Creates a new `CLINT` peripheral.
             #[inline]
-            pub fn disable() {
-                // SAFETY: it is safe to disable interrupts
-                unsafe { $crate::riscv::register::mie::clear_mext() };
+            pub const fn new() -> Self {
+                Self($crate::plic::PLIC::new())
             }
+        }
 
-            /// Returns the priorities register of the PLIC.
-            #[inline]
-            pub fn priorities() -> $crate::plic::priorities::PRIORITIES {
-                $crate::plic::PLIC::<PLIC>::priorities()
-            }
+        unsafe impl $crate::plic::Plic for PLIC {
+            const BASE: usize = $addr;
+        }
 
-            /// Returns the pendings register of the PLIC.
-            #[inline]
-            pub fn pendings() -> $crate::plic::pendings::PENDINGS {
-                $crate::plic::PLIC::<PLIC>::pendings()
-            }
+        impl core::ops::Deref for PLIC {
+            type Target = $crate::plic::PLIC<Self>;
 
-            /// Returns the context proxy of a given PLIC HART context.
             #[inline]
-            pub fn ctx<H: $crate::plic::HartIdNumber>(hart_id: H) -> $crate::plic::CTX<Self> {
-                $crate::plic::PLIC::<PLIC>::ctx(hart_id)
+            fn deref(&self) -> &Self::Target {
+                &self.0
             }
+        }
 
-            /// Returns the PLIC HART context for the current HART.
-            ///
-            /// # Note
-            ///
-            /// This function determines the current HART ID by reading the [`riscv::register::mhartid`] CSR.
-            /// Thus, it can only be used in M-mode. For S-mode, use [`PLIC::ctx`] instead.
+        impl core::ops::DerefMut for PLIC {
             #[inline]
-            pub fn ctx_mhartid() -> $crate::plic::CTX<Self> {
-                $crate::plic::PLIC::<PLIC>::ctx_mhartid()
+            fn deref_mut(&mut self) -> &mut Self::Target {
+                &mut self.0
             }
         }
+
         $crate::plic_codegen!($($tail)*);
     };
-    (ctxs [$($fn:ident = ($ctx:expr , $sctx:expr)),+], $($tail:tt)*) => {
-        impl PLIC {
-            $(
-                #[doc = "Returns a PLIC context proxy for context of HART "]
-                #[doc = $sctx]
-                #[doc = "."]
-                #[inline]
-                pub fn $fn() -> $crate::plic::CTX<Self> {
-                    Self::ctx($ctx)
-                }
-            )*
+    (harts [$($hart:expr => $num:literal),+], $($tail:tt)*) => {
+        $crate::macros::paste! {
+            impl PLIC {
+                $(
+                    #[doc = "Returns a PLIC context proxy for context of HART "]
+                    #[doc = stringify!($hart)]
+                    #[doc = "`]."]
+                    #[inline]
+                    pub fn [<ctx $num>](&self) -> $crate::plic::CTX<Self> {
+                        self.ctx($hart)
+                    }
+                )*
+            }
         }
         $crate::plic_codegen!($($tail)*);
     };
diff --git a/riscv-peripheral/src/plic.rs b/riscv-peripheral/src/plic.rs
@@ -11,6 +11,8 @@ pub mod threshold;
 // re-export useful riscv-pac traits
 pub use riscv_pac::{HartIdNumber, InterruptNumber, PriorityNumber};
 
+use riscv::register::{mhartid, mie, mip};
+
 /// Trait for a PLIC peripheral.
 ///
 /// # Safety
@@ -43,26 +45,65 @@ impl<P: Plic> PLIC<P> {
 
     const PENDINGS_OFFSET: usize = 0x1000;
 
-    /// Returns the priorities register of the PLIC.
+    /// Creates a new `PLIC` peripheral.
+    #[inline]
+    pub const fn new() -> Self {
+        Self {
+            _marker: core::marker::PhantomData,
+        }
+    }
+
+    /// Returns `true` if a machine external interrupt is pending.
+    #[inline]
+    pub fn is_interrupting(&self) -> bool {
+        mip::read().mext()
+    }
+
+    /// Returns true if machine external interrupts are enabled.
+    #[inline]
+    pub fn is_enabled(&self) -> bool {
+        mie::read().mext()
+    }
+
+    /// Enables machine external interrupts to allow the PLIC to trigger interrupts.
+    ///
+    /// # Safety
+    ///
+    /// Enabling the `PLIC` may break mask-based critical sections.
+    #[inline]
+    pub unsafe fn enable(&self) {
+        mie::set_mext();
+    }
+
+    /// Disables machine external interrupts to prevent the PLIC from triggering interrupts.
+    #[inline]
+    pub fn disable(&self) {
+        // SAFETY: it is safe to disable interrupts
+        unsafe { mie::clear_mext() };
+    }
+
+    /// Returns the [`PRIORITIES`](priorities::PRIORITIES) register of the PLIC.
+    ///
     /// This register allows to set the priority level of each interrupt source.
     /// The priority level of each interrupt source is shared among all the contexts.
     #[inline]
-    pub fn priorities() -> priorities::PRIORITIES {
+    pub const fn priorities(&self) -> priorities::PRIORITIES {
         // SAFETY: valid address
         unsafe { priorities::PRIORITIES::new(P::BASE + Self::PRIORITIES_OFFSET) }
     }
 
-    /// Returns the pendings register of the PLIC.
+    /// Returns the [`PENDINGS`](pendings::PENDINGS) register of the PLIC.
+    ///
     /// This register allows to check if a particular interrupt source is pending.
     #[inline]
-    pub fn pendings() -> pendings::PENDINGS {
+    pub const fn pendings(&self) -> pendings::PENDINGS {
         // SAFETY: valid address
         unsafe { pendings::PENDINGS::new(P::BASE + Self::PENDINGS_OFFSET) }
     }
 
     /// Returns a proxy to access to all the PLIC registers of a given HART context.
     #[inline]
-    pub fn ctx<H: HartIdNumber>(hart_id: H) -> CTX<P> {
+    pub fn ctx<H: HartIdNumber>(&self, hart_id: H) -> CTX<P> {
         // SAFETY: valid context number
         unsafe { CTX::new(hart_id.number() as _) }
     }
@@ -71,11 +112,11 @@ impl<P: Plic> PLIC<P> {
     ///
     /// # Note
     ///
-    /// This function determines the current HART ID by reading the [`riscv::register::mhartid`] CSR.
+    /// This function determines the current HART ID by reading the [`mhartid`] CSR.
     /// Thus, it can only be used in M-mode. For S-mode, use [`PLIC::ctx`] instead.
     #[inline]
-    pub fn ctx_mhartid() -> CTX<P> {
-        let hart_id = riscv::register::mhartid::read();
+    pub fn ctx_mhartid(&self) -> CTX<P> {
+        let hart_id = mhartid::read();
         // SAFETY: `hart_id` is valid for the target and is the current hart
         unsafe { CTX::new(hart_id as _) }
     }
@@ -281,19 +322,20 @@ pub(crate) mod test {
     fn check_plic() {
         crate::plic_codegen!(
             base 0x0C00_0000,
-            ctxs [ctx0 = (Context::C0, "`C0`"), ctx1 = (Context::C1, "`C1`"), ctx2 = (Context::C2, "`C2`")],
+            harts [Context::C0 => 0, Context::C1 => 1, Context::C2 => 2],
         );
 
-        let priorities = PLIC::priorities();
-        let pendings = PLIC::pendings();
+        let plic = PLIC::new();
+        let priorities = plic.priorities();
+        let pendings = plic.pendings();
 
         assert_eq!(priorities.address(), 0x0C00_0000);
         assert_eq!(pendings.address(), 0x0C00_1000);
 
         for i in 0..=Context::MAX_HART_ID_NUMBER {
             let context = Context::from_number(i).unwrap();
 
-            let ctx = PLIC::ctx(context);
+            let ctx = plic.ctx(context);
 
             assert_eq!(ctx.enables().address(), 0x0C00_0000 + 0x2000 + i * 0x80);
             assert_eq!(
@@ -306,8 +348,8 @@ pub(crate) mod test {
             );
         }
 
-        assert_eq!(PLIC::ctx0(), PLIC::ctx(Context::C0));
-        assert_eq!(PLIC::ctx1(), PLIC::ctx(Context::C1));
-        assert_eq!(PLIC::ctx2(), PLIC::ctx(Context::C2));
+        assert_eq!(plic.ctx0(), plic.ctx(Context::C0));
+        assert_eq!(plic.ctx1(), plic.ctx(Context::C1));
+        assert_eq!(plic.ctx2(), plic.ctx(Context::C2));
     }
 }
