New riscv-pac

Author: romancardenas

riscv-pac/CHANGELOG.md

@@ -10,6 +10,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 
 - Add `result` module for `Error` and `Result` types
+- Add `ExceptionNumber` trait.
+- Classify interrupt numbers in `CoreInterruptNumber` and `ExternalInterruptNumber`.
+- Added simple tests to illustrate how to implement all the provided traits.
+
+### Changed 
+
+- `InterruptNumber` trait now expects `usize`
 
 ## [v0.1.1] - 2024-02-15
 

riscv-pac/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "riscv-pac"
-version = "0.1.1"
+version = "0.2.0"
 edition = "2021"
-rust-version = "1.60"
+rust-version = "1.61"
 repository = "https://github.com/rust-embedded/riscv"
 authors = ["The RISC-V Team <risc-v@teams.rust-embedded.org>"]
 categories = ["embedded", "hardware-support", "no-std"]

riscv-pac/src/lib.rs

@@ -4,37 +4,86 @@ pub mod result;
 
 use result::Result;
 
-/// Trait for enums of target-specific external interrupt numbers.
+/// Trait for enums of target-specific exception numbers.
 ///
-/// This trait should be implemented by a peripheral access crate (PAC)
-/// on its enum of available external interrupts for a specific device.
-/// Each variant must convert to a `u16` of its interrupt number.
+/// This trait should be implemented by a peripheral access crate (PAC) on its enum of available
+/// exceptions for a specific device. Alternatively, the `riscv` crate provides a default
+/// implementation for the RISC-V ISA. Each variant must convert to a `usize` of its exception number.
 ///
 /// # Safety
 ///
-/// * This trait must only be implemented on a PAC of a RISC-V target.
-/// * This trait must only be implemented on enums of external interrupts.
+/// * This trait must only be implemented on the `riscv` crate or on a PAC of a RISC-V target.
+/// * This trait must only be implemented on enums of exceptions.
+/// * Each enum variant must represent a distinct value (no duplicates are permitted),
+/// * Each enum variant must always return the same value (do not change at runtime).
+/// * All the exception numbers must be less than or equal to `MAX_EXCEPTION_NUMBER`.
+/// * `MAX_EXCEPTION_NUMBER` must coincide with the highest allowed exception number.
+pub unsafe trait ExceptionNumber: Copy {
+    /// Highest number assigned to an exception.
+    const MAX_EXCEPTION_NUMBER: usize;
+
+    /// Converts an exception to its corresponding number.
+    fn number(self) -> usize;
+
+    /// Tries to convert a number to a valid exception.
+    /// If the conversion fails, it returns an error with the number back.
+    fn from_number(value: usize) -> Result<Self>;
+}
+
+/// Trait for enums of target-specific interrupt numbers.
+///
+/// This trait should be implemented by a peripheral access crate (PAC) on its enum of available
+/// interrupts for a specific device. Alternatively, the `riscv` crate provides a default
+/// implementation for the RISC-V ISA. Each variant must convert to a `usize` of its interrupt number.
+///
+/// # Safety
+///
+/// * This trait must only be implemented on the `riscv` crate or on a PAC of a RISC-V target.
+/// * This trait must only be implemented on enums of interrupts.
 /// * Each enum variant must represent a distinct value (no duplicates are permitted),
 /// * Each enum variant must always return the same value (do not change at runtime).
 /// * All the interrupt numbers must be less than or equal to `MAX_INTERRUPT_NUMBER`.
 /// * `MAX_INTERRUPT_NUMBER` must coincide with the highest allowed interrupt number.
 pub unsafe trait InterruptNumber: Copy {
     /// Highest number assigned to an interrupt source.
-    const MAX_INTERRUPT_NUMBER: u16;
+    const MAX_INTERRUPT_NUMBER: usize;
 
     /// Converts an interrupt source to its corresponding number.
-    fn number(self) -> u16;
+    fn number(self) -> usize;
 
     /// Tries to convert a number to a valid interrupt source.
     /// If the conversion fails, it returns an error with the number back.
-    fn from_number(value: u16) -> Result<Self>;
+    fn from_number(value: usize) -> Result<Self>;
 }
 
+/// Marker trait for enums of target-specific core interrupt numbers.
+///
+/// Core interrupts are interrupts are retrieved from the `mcause` CSR. Usually, vectored mode is
+/// only available for core interrupts. The `riscv` crate provides a default implementation for
+/// the RISC-V ISA. However, a PAC may override the default implementation if the target has a
+/// different interrupt numbering scheme (e.g., ESP32C3).
+///
+/// # Safety
+///
+/// Each enum variant must represent a valid core interrupt number read from the `mcause` CSR.
+pub unsafe trait CoreInterruptNumber: InterruptNumber {}
+
+/// Marker trait for enums of target-specific external interrupt numbers.
+///
+/// External interrupts are interrupts caused by external sources (e.g., GPIO, UART, SPI).
+/// External interrupts are **not** retrieved from the `mcause` CSR.
+/// Instead, RISC-V processors have a single core interrupt for all external interrupts.
+/// An additional peripheral (e.g., PLIC) is used to multiplex the external interrupts.
+///
+/// # Safety
+///
+/// Each enum variant must represent a valid external interrupt number.
+pub unsafe trait ExternalInterruptNumber: InterruptNumber {}
+
 /// Trait for enums of priority levels.
 ///
-/// This trait should be implemented by a peripheral access crate (PAC)
-/// on its enum of available priority numbers for a specific device.
-/// Each variant must convert to a `u8` of its priority level.
+/// This trait should be implemented by a peripheral access crate (PAC) on its enum of available
+/// priority numbers for a specific device. Each variant must convert to a `u8` of its priority level.
 ///
 /// # Safety
 ///
@@ -58,9 +107,8 @@ pub unsafe trait PriorityNumber: Copy {
 
 /// Trait for enums of HART identifiers.
 ///
-/// This trait should be implemented by a peripheral access crate (PAC)
-/// on its enum of available HARTs for a specific device.
-/// Each variant must convert to a `u16` of its HART ID number.
+/// This trait should be implemented by a peripheral access crate (PAC) on its enum of available
+/// HARTs for a specific device. Each variant must convert to a `u16` of its HART ID number.
 ///
 /// # Safety
 ///
@@ -81,3 +129,165 @@ pub unsafe trait HartIdNumber: Copy {
     /// If the conversion fails, it returns an error with the number back.
     fn from_number(value: u16) -> Result<Self>;
 }
+
+#[cfg(test)]
+mod test {
+    use super::*;
+    use crate::result::Error;
+
+    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+    enum Exception {
+        E1 = 1,
+        E3 = 3,
+    }
+
+    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+    enum Interrupt {
+        I1 = 1,
+        I2 = 2,
+        I4 = 4,
+    }
+
+    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+    enum Priority {
+        P0 = 0,
+        P1 = 1,
+        P2 = 2,
+        P3 = 3,
+    }
+
+    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+    enum HartId {
+        H0 = 0,
+        H1 = 1,
+        H2 = 2,
+    }
+
+    unsafe impl ExceptionNumber for Exception {
+        const MAX_EXCEPTION_NUMBER: usize = Self::E3 as usize;
+
+        #[inline]
+        fn number(self) -> usize {
+            self as _
+        }
+
+        #[inline]
+        fn from_number(number: usize) -> Result<Self> {
+            match number {
+                1 => Ok(Exception::E1),
+                3 => Ok(Exception::E3),
+                _ => Err(Error::InvalidVariant(number)),
+            }
+        }
+    }
+
+    unsafe impl InterruptNumber for Interrupt {
+        const MAX_INTERRUPT_NUMBER: usize = Self::I4 as usize;
+
+        #[inline]
+        fn number(self) -> usize {
+            self as _
+        }
+
+        #[inline]
+        fn from_number(number: usize) -> Result<Self> {
+            match number {
+                1 => Ok(Interrupt::I1),
+                2 => Ok(Interrupt::I2),
+                4 => Ok(Interrupt::I4),
+                _ => Err(Error::InvalidVariant(number)),
+            }
+        }
+    }
+
+    unsafe impl PriorityNumber for Priority {
+        const MAX_PRIORITY_NUMBER: u8 = Self::P3 as u8;
+
+        #[inline]
+        fn number(self) -> u8 {
+            self as _
+        }
+
+        #[inline]
+        fn from_number(number: u8) -> Result<Self> {
+            match number {
+                0 => Ok(Priority::P0),
+                1 => Ok(Priority::P1),
+                2 => Ok(Priority::P2),
+                3 => Ok(Priority::P3),
+                _ => Err(Error::InvalidVariant(number as _)),
+            }
+        }
+    }
+
+    unsafe impl HartIdNumber for HartId {
+        const MAX_HART_ID_NUMBER: u16 = Self::H2 as u16;
+
+        #[inline]
+        fn number(self) -> u16 {
+            self as _
+        }
+
+        #[inline]
+        fn from_number(number: u16) -> Result<Self> {
+            match number {
+                0 => Ok(HartId::H0),
+                1 => Ok(HartId::H1),
+                2 => Ok(HartId::H2),
+                _ => Err(Error::InvalidVariant(number as _)),
+            }
+        }
+    }
+
+    #[test]
+    fn check_exception_enum() {
+        assert_eq!(Exception::E1.number(), 1);
+        assert_eq!(Exception::E3.number(), 3);
+
+        assert_eq!(Exception::from_number(0), Err(Error::InvalidVariant(0)));
+        assert_eq!(Exception::from_number(1), Ok(Exception::E1));
+        assert_eq!(Exception::from_number(2), Err(Error::InvalidVariant(2)));
+        assert_eq!(Exception::from_number(3), Ok(Exception::E3));
+        assert_eq!(Exception::from_number(4), Err(Error::InvalidVariant(4)));
+    }
+
+    #[test]
+    fn check_interrupt_enum() {
+        assert_eq!(Interrupt::I1.number(), 1);
+        assert_eq!(Interrupt::I2.number(), 2);
+        assert_eq!(Interrupt::I4.number(), 4);
+
+        assert_eq!(Interrupt::from_number(0), Err(Error::InvalidVariant(0)));
+        assert_eq!(Interrupt::from_number(1), Ok(Interrupt::I1));
+        assert_eq!(Interrupt::from_number(2), Ok(Interrupt::I2));
+        assert_eq!(Interrupt::from_number(3), Err(Error::InvalidVariant(3)));
+        assert_eq!(Interrupt::from_number(4), Ok(Interrupt::I4));
+        assert_eq!(Interrupt::from_number(5), Err(Error::InvalidVariant(5)));
+    }
+
+    #[test]
+    fn check_priority_enum() {
+        assert_eq!(Priority::P0.number(), 0);
+        assert_eq!(Priority::P1.number(), 1);
+        assert_eq!(Priority::P2.number(), 2);
+        assert_eq!(Priority::P3.number(), 3);
+
+        assert_eq!(Priority::from_number(0), Ok(Priority::P0));
+        assert_eq!(Priority::from_number(1), Ok(Priority::P1));
+        assert_eq!(Priority::from_number(2), Ok(Priority::P2));
+        assert_eq!(Priority::from_number(3), Ok(Priority::P3));
+        assert_eq!(Priority::from_number(4), Err(Error::InvalidVariant(4)));
+    }
+
+    #[test]
+    fn check_hart_id_enum() {
+        assert_eq!(HartId::H0.number(), 0);
+        assert_eq!(HartId::H1.number(), 1);
+        assert_eq!(HartId::H2.number(), 2);
+
+        assert_eq!(HartId::from_number(0), Ok(HartId::H0));
+        assert_eq!(HartId::from_number(1), Ok(HartId::H1));
+        assert_eq!(HartId::from_number(2), Ok(HartId::H2));
+        assert_eq!(HartId::from_number(3), Err(Error::InvalidVariant(3)));
+    }
+}

riscv-peripheral/CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - use `riscv-pac` result types for trait implementations
 
+### Changed
+
+- Bump `riscv-pac` version
+
 ### Fixed
 
 - `clippy` fixes

riscv-peripheral/Cargo.toml

@@ -17,7 +17,7 @@ license = "ISC"
 embedded-hal = "1.0.0"
 embedded-hal-async = { version = "1.0.0", optional =  true }
 riscv = { path = "../riscv", version = "0.11.1" }
-riscv-pac = { path = "../riscv-pac", version = "0.1.1" }
+riscv-pac = { path = "../riscv-pac", version = "0.2.0" }
 
 [dev-dependencies]
 heapless = "0.8.0"

riscv-peripheral/examples/e310x.rs

@@ -21,17 +21,15 @@ unsafe impl HartIdNumber for HartId {
 
     #[inline]
     fn from_number(number: u16) -> Result<Self> {
-        if number > Self::MAX_HART_ID_NUMBER {
-            Err(Error::InvalidVariant(number as usize))
-        } else {
-            // SAFETY: valid context number
-            Ok(unsafe { core::mem::transmute(number) })
+        match number {
+            0 => Ok(Self::H0),
+            _ => Err(Error::InvalidVariant(number as usize)),
         }
     }
 }
 
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
-#[repr(u16)]
+#[repr(usize)]
 pub enum Interrupt {
     WATCHDOG = 1,
     RTC = 2,
@@ -88,20 +86,20 @@ pub enum Interrupt {
 }
 
 unsafe impl InterruptNumber for Interrupt {
-    const MAX_INTERRUPT_NUMBER: u16 = 52;
+    const MAX_INTERRUPT_NUMBER: usize = 52;
 
     #[inline]
-    fn number(self) -> u16 {
+    fn number(self) -> usize {
         self as _
     }
 
     #[inline]
-    fn from_number(number: u16) -> Result<Self> {
+    fn from_number(number: usize) -> Result<Self> {
         if number == 0 || number > Self::MAX_INTERRUPT_NUMBER {
-            Err(Error::InvalidVariant(number as usize))
+            Err(Error::InvalidVariant(number))
         } else {
             // SAFETY: valid interrupt number
-            Ok(unsafe { core::mem::transmute(number) })
+            Ok(unsafe { core::mem::transmute::<usize, Interrupt>(number) })
         }
     }
 }
@@ -133,7 +131,7 @@ unsafe impl PriorityNumber for Priority {
             Err(Error::InvalidVariant(number as usize))
         } else {
             // SAFETY: valid priority number
-            Ok(unsafe { core::mem::transmute(number) })
+            Ok(unsafe { core::mem::transmute::<u8, Priority>(number) })
         }
     }
 }