Macro to implement riscv-pac traits

Author: romancardenas

riscv-pac/Cargo.toml

@@ -19,4 +19,10 @@ targets = [
 ]
 
 [dependencies]
-riscv-pac-macros = { path = "macros", version = "0.1.0" }
+riscv-pac-macros = { path = "macros", version = "0.1.0", optional = true }
+
+[features]
+default = ["riscv-pac-macros"]
+
+[dev-dependencies]
+trybuild = "1.0"

riscv-pac/macros/Cargo.toml

@@ -17,4 +17,4 @@ proc-macro = true
 [dependencies]
 proc-macro2 = "1.0"
 quote = "1.0"
-syn = { version = "2.0", default-features = false, features = ["derive", "parsing", "proc-macro"]}
+syn = { version = "2.0" }

riscv-pac/macros/src/lib.rs

@@ -6,15 +6,66 @@ extern crate syn;
 use proc_macro::TokenStream;
 use proc_macro2::TokenStream as TokenStream2;
 use quote::quote;
-use std::{collections::HashMap, convert::TryFrom, ops::Range, str::FromStr};
-use syn::{parse_macro_input, Data, DeriveInput, Error, Ident};
+use std::{collections::HashMap, ops::Range, str::FromStr};
+use syn::{parse_macro_input, Data, DeriveInput, Ident};
 
 struct PacNumberEnum {
     name: Ident,
     valid_ranges: Vec<Range<usize>>,
 }
 
 impl PacNumberEnum {
+    fn new(input: &DeriveInput) -> Self {
+        let variants = match &input.data {
+            Data::Enum(data) => &data.variants,
+            _ => panic!("Input is not an enum"),
+        };
+
+        // Collect the variants and their associated number discriminants
+        let mut var_map = HashMap::new();
+        let mut numbers = Vec::new();
+        for variant in variants {
+            let ident = &variant.ident;
+            let value = match &variant.discriminant {
+                Some(d) => match &d.1 {
+                    syn::Expr::Lit(expr_lit) => match &expr_lit.lit {
+                        syn::Lit::Int(lit_int) => match lit_int.base10_parse::<usize>() {
+                            Ok(num) => num,
+                            Err(_) => panic!("All variant discriminants must be unsigned integers"),
+                        },
+                        _ => panic!("All variant discriminants must be unsigned integers"),
+                    },
+                    _ => panic!("All variant discriminants must be unsigned integers"),
+                },
+                _ => panic!("Variant must have a discriminant"),
+            };
+            // check for duplicate discriminant values
+            var_map.insert(value, ident);
+            numbers.push(value);
+        }
+
+        // sort the number discriminants and generate a list of valid ranges
+        numbers.sort_unstable();
+        let mut valid_ranges = Vec::new();
+        let mut start = numbers[0];
+        let mut end = start;
+        for &number in &numbers[1..] {
+            if number == end + 1 {
+                end = number;
+            } else {
+                valid_ranges.push(start..end + 1);
+                start = number;
+                end = start;
+            }
+        }
+        valid_ranges.push(start..end + 1);
+
+        Self {
+            name: input.ident.clone(),
+            valid_ranges,
+        }
+    }
+
     fn valid_condition(&self) -> TokenStream2 {
         let mut arms = Vec::new();
         for range in &self.valid_ranges {
@@ -45,7 +96,7 @@ impl PacNumberEnum {
         let const_name = TokenStream2::from_str(const_name).unwrap();
 
         quote! {
-            unsafe impl #trait_name for #name {
+            unsafe impl riscv_pac::#trait_name for #name {
                 const #const_name: #num_type = #max_discriminant;
 
                 #[inline]
@@ -67,93 +118,88 @@ impl PacNumberEnum {
     }
 }
 
-impl TryFrom<DeriveInput> for PacNumberEnum {
-    type Error = Error;
-
-    fn try_from(input: DeriveInput) -> Result<Self, Self::Error> {
-        let variants = match &input.data {
-            Data::Enum(data) => &data.variants,
-            _ => panic!("Input is not an enum"),
-        };
-
-        // Collect the variants and their associated number discriminants
-        let mut var_map = HashMap::new();
-        let mut numbers = Vec::new();
-        for variant in variants {
-            let ident = &variant.ident;
-            let value = match &variant.discriminant {
-                Some(d) => match &d.1 {
-                    syn::Expr::Lit(expr_lit) => match &expr_lit.lit {
-                        syn::Lit::Int(lit_int) => match lit_int.base10_parse::<usize>() {
-                            Ok(num) => num,
-                            Err(_) => panic!("All variant discriminants must be unsigned integers"),
-                        },
-                        _ => panic!("All variant discriminants must be unsigned integers"),
-                    },
-                    _ => panic!("All variant discriminants must be unsigned integers"),
-                },
-                _ => panic!("Variant must have a discriminant"),
-            };
-            // check for duplicate discriminant values
-            var_map.insert(value, ident);
-            numbers.push(value);
-        }
-
-        // sort the number discriminants and generate a list of valid ranges
-        numbers.sort_unstable();
-        let mut valid_ranges = Vec::new();
-        let mut start = numbers[0];
-        let mut end = start;
-        for &number in &numbers[1..] {
-            if number == end + 1 {
-                end = number;
-            } else {
-                valid_ranges.push(start..end + 1);
-                start = number;
-                end = start;
-            }
-        }
-        valid_ranges.push(start..end + 1);
-
-        Ok(PacNumberEnum {
-            name: input.ident.clone(),
-            valid_ranges,
-        })
+/// Attribute-like macro that implements the traits of the `riscv-pac` crate for a given enum.
+///
+/// As these traits are unsafe, the macro must be called with the `unsafe` keyword followed by the trait name.
+/// In this way, we warn callers that they must comply with the requirements of the trait.
+///
+/// The trait name must be one of `ExceptionNumber`, `InterruptNumber`, `PriorityNumber`, or `HartIdNumber`.
+/// Marker traits `CoreInterruptNumber` and `ExternalInterruptNumber` cannot be implemented using this macro.
+///
+/// # Note
+///
+/// To implement number-to-enum operation, the macro works with ranges of valid discriminant numbers.
+/// If the number is within any of the valid ranges, the number is transmuted to the enum variant.
+/// In this way, the macro achieves better performance for enums with a large number of consecutive variants.
+/// Thus, the enum must comply with the following requirements:
+///
+/// - All the enum variants must have a valid discriminant number (i.e., a number that is within the valid range of the enum).
+/// - For the `ExceptionNumber`, `InterruptNumber`, and `HartIdNumber` traits, the enum must be annotated as `#[repr(u16)]`
+/// - For the `PriorityNumber` trait, the enum must be annotated as `#[repr(u8)]`
+///
+/// If the enum does not meet these requirements, you will have to implement the traits manually (e.g., `riscv::mcause::Interrupt`).
+/// For enums with a small number of consecutive variants, it might be better to implement the traits manually.
+///
+/// # Safety
+///
+/// The struct to be implemented must comply with the requirements of the specified trait.
+///
+/// # Example
+///
+/// ```rust
+/// use riscv_pac::*;
+///
+/// #[repr(u16)]
+/// #[pac_enum(unsafe ExceptionNumber)]
+/// #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+/// enum Exception {
+///     E1 = 1,
+///     E3 = 3,
+/// }
+///
+/// fn main() {
+///     assert_eq!(Exception::E1.number(), 1);
+///     assert_eq!(Exception::E3.number(), 3);
+///
+///     assert_eq!(Exception::from_number(1), Ok(Exception::E1));
+///     assert_eq!(Exception::from_number(2), Err(2));
+///     assert_eq!(Exception::from_number(3), Ok(Exception::E3));
+///
+///     assert_eq!(Exception::MAX_EXCEPTION_NUMBER, 3);
+/// }
+///```
+#[proc_macro_attribute]
+pub fn pac_enum(attr: TokenStream, item: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(item as DeriveInput);
+    let pac_enum = PacNumberEnum::new(&input);
+
+    // attr should be unsafe ExceptionNumber, unsafe InterruptNumber, unsafe PriorityNumber, or unsafe HartIdNumber
+    // assert that attribute starts with the unsafe token. If not, raise a panic error
+    let attr = attr.to_string();
+    // split string into words and check if the first word is "unsafe"
+    let attrs = attr.split_whitespace().collect::<Vec<&str>>();
+    if attrs.is_empty() {
+        panic!("Attribute is empty. Expected: 'riscv_pac::pac_enum(unsafe <PacTraitToImplement>)'");
+    }
+    if attrs.len() > 2 {
+        panic!(
+            "Wrong attribute format. Expected: 'riscv_pac::pac_enum(unsafe <PacTraitToImplement>)'"
+        );
+    }
+    if attrs[0] != "unsafe" {
+        panic!("Attribute does not start with 'unsafe'. Expected: 'riscv_pac::pac_enum(unsafe <PacTraitToImplement>)'");
     }
-}
-
-#[proc_macro_derive(ExceptionNumber)]
-pub fn exception_number_derive(input: TokenStream) -> TokenStream {
-    let input = parse_macro_input!(input as DeriveInput);
-    let pac_enum = PacNumberEnum::try_from(input).unwrap();
-    pac_enum
-        .quote("ExceptionNumber", "u16", "MAX_EXCEPTION_NUMBER")
-        .into()
-}
-
-#[proc_macro_derive(InterruptNumber)]
-pub fn interrupt_number_derive(input: TokenStream) -> TokenStream {
-    let input = parse_macro_input!(input as DeriveInput);
-    let pac_enum = PacNumberEnum::try_from(input).unwrap();
-    pac_enum
-        .quote("InterruptNumber", "u16", "MAX_INTERRUPT_NUMBER")
-        .into()
-}
-
-#[proc_macro_derive(PriorityNumber)]
-pub fn priority_number_derive(input: TokenStream) -> TokenStream {
-    let input = parse_macro_input!(input as DeriveInput);
-    let pac_enum = PacNumberEnum::try_from(input).unwrap();
-    pac_enum
-        .quote("PriorityNumber", "u8", "MAX_PRIORITY_NUMBER")
-        .into()
-}
 
-#[proc_macro_derive(HartIdNumber)]
-pub fn hart_id_number_derive(input: TokenStream) -> TokenStream {
-    let input = parse_macro_input!(input as DeriveInput);
-    let pac_enum = PacNumberEnum::try_from(input).unwrap();
-    pac_enum
-        .quote("HartIdNumber", "u16", "MAX_HART_ID_NUMBER")
-        .into()
+    let trait_impl = match attrs[1] {
+        "ExceptionNumber" => pac_enum.quote("ExceptionNumber", "u16", "MAX_EXCEPTION_NUMBER"),
+        "InterruptNumber" => pac_enum.quote("InterruptNumber", "u16", "MAX_INTERRUPT_NUMBER"),
+        "PriorityNumber" => pac_enum.quote("PriorityNumber", "u8", "MAX_PRIORITY_NUMBER"),
+        "HartIdNumber" => pac_enum.quote("HartIdNumber", "u16", "MAX_HART_ID_NUMBER"),
+        _ => panic!("Unknown trait '{}'. Expected: 'ExceptionNumber', 'InterruptNumber', 'PriorityNumber', or 'HartIdNumber'", attrs[1]),
+    };
+    quote! {
+        #input
+        #trait_impl
+    }
+    .into()
 }

riscv-pac/src/lib.rs

@@ -4,12 +4,13 @@ pub mod result;
 
 use result::Result;
 
+#[cfg(feature = "riscv-pac-macros")]
 pub use riscv_pac_macros::*;
 
 /// Trait for enums of target-specific exception numbers.
 ///
 /// 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
+/// exceptions for a specific device. Alternatively, the `riscv` crate provides a default
 /// implementation for the RISC-V ISA. Each variant must convert to a `u16` of its exception number.
 ///
 /// # Safety
@@ -35,7 +36,7 @@ pub unsafe trait ExceptionNumber: Copy {
 /// 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
+/// interrupts for a specific device. Alternatively, the `riscv` crate provides a default
 /// implementation for the RISC-V ISA. Each variant must convert to a `u16` of its interrupt number.
 ///
 /// # Safety
@@ -58,20 +59,19 @@ pub unsafe trait InterruptNumber: Copy {
     fn from_number(value: u16) -> Result<Self>;
 }
 
-/// Trait for enums of target-specific core interrupt numbers.
+/// 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
+/// 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 {}
 
-/// Trait for enums of target-specific external interrupt numbers.
+/// 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.
@@ -85,9 +85,8 @@ 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
 ///
@@ -111,9 +110,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
 ///

riscv-pac/tests/test.rs

@@ -0,0 +1,6 @@
+#[test]
+fn ui() {
+    let t = trybuild::TestCases::new();
+    t.compile_fail("tests/ui/fail_*.rs");
+    t.pass("tests/ui/pass_*.rs");
+}

riscv-pac/tests/ui/fail_empty_macro.rs

@@ -0,0 +1,9 @@
+#[riscv_pac::pac_enum]
+#[derive(Clone, Copy, Debug, PartialEq)]
+enum Interrupt {
+    I1 = 1,
+    I2 = 2,
+    I4 = 4,
+}
+
+fn main() {}

riscv-pac/tests/ui/fail_empty_macro.stderr

@@ -0,0 +1,7 @@
+error: custom attribute panicked
+ --> tests/ui/fail_empty_macro.rs:1:1
+  |
+1 | #[riscv_pac::pac_enum]
+  | ^^^^^^^^^^^^^^^^^^^^^^
+  |
+  = help: message: Attribute is empty. Expected: 'riscv_pac::pac_enum(unsafe <PacTraitToImplement>)'

riscv-pac/tests/ui/fail_more_than_one_trait.rs

@@ -0,0 +1,9 @@
+#[riscv_pac::pac_enum(unsafe InterruptNumber, unsafe PriorityNumber)]
+#[derive(Clone, Copy, Debug, PartialEq)]
+enum Interrupt {
+    I1 = 1,
+    I2 = 2,
+    I4 = 4,
+}
+
+fn main() {}

riscv-pac/tests/ui/fail_more_than_one_trait.stderr

@@ -0,0 +1,7 @@
+error: custom attribute panicked
+ --> tests/ui/fail_more_than_one_trait.rs:1:1
+  |
+1 | #[riscv_pac::pac_enum(unsafe InterruptNumber, unsafe PriorityNumber)]
+  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  |
+  = help: message: Wrong attribute format. Expected: 'riscv_pac::pac_enum(unsafe <PacTraitToImplement>)'

riscv-pac/tests/ui/fail_no_unsafe.rs

@@ -0,0 +1,9 @@
+#[riscv_pac::pac_enum(InterruptNumber)]
+#[derive(Clone, Copy, Debug, PartialEq)]
+enum Interrupt {
+    I1 = 1,
+    I2 = 2,
+    I4 = 4,
+}
+
+fn main() {}