33/// Macro to create interfaces to CLINT peripherals in PACs.
44/// The resulting struct will be named `CLINT`, and will provide safe access to the CLINT registers.
55///
6- /// This macro expects 4 different argument types:
6+ /// This macro expects 5 different argument types:
77///
88/// - Base address (**MANDATORY**): base address of the CLINT peripheral of the target.
99/// - Frequency (**OPTIONAL**): clock frequency (in Hz) of the `MTIME` register. It enables the `delay` method of the `CLINT` struct.
10+ /// - Async flag (**OPTIONAL**): It enables the `async_delay` method of the `CLINT struct`.
11+ /// You must activate the `embedded-hal-async` feature to use this flag.
1012/// - Per-HART mtimecmp registers (**OPTIONAL**): a list of `mtimecmp` registers for easing access to per-HART mtimecmp regs.
1113/// - Per-HART msip registers (**OPTIONAL**): a list of `msip` registers for easing access to per-HART msip regs.
1214///
1719/// ## Base address only
1820///
1921/// ```
20- /// use riscv_peripheral::clint_codegen;
21- ///
22- /// clint_codegen!(base 0x0200_0000, freq 32_768,); // do not forget the ending comma!
22+ /// riscv_peripheral::clint_codegen!(base 0x0200_0000, freq 32_768,); // do not forget the ending comma!
2323///
24- /// let mswi = CLINT::mswi(); // MSWI peripheral
24+ /// let mswi = CLINT::mswi(); // MSWI peripheral
2525/// let mtimer = CLINT::mtimer(); // MTIMER peripheral
26- /// let delay = CLINT::delay(); // For the `embedded_hal::delay::DelayNs` trait
26+ /// let delay = CLINT::delay(); // For the `embedded_hal::delay::DelayNs` trait
2727/// ```
2828///
2929/// ## Base address and per-HART mtimecmp registers
3030///
3131/// ```
32- /// use riscv_peripheral::clint_codegen;
3332/// use riscv_pac::result::{Error, Result};
3433///
3534/// /// HART IDs for the target CLINT peripheral
3635/// #[derive(Clone, Copy, Debug, Eq, PartialEq)]
37- /// #[repr(u16)]
3836/// pub enum HartId { H0 = 0, H1 = 1, H2 = 2 }
3937///
4038/// // Implement `HartIdNumber` for `HartId`
4139/// unsafe impl riscv_peripheral::aclint::HartIdNumber for HartId {
4240/// const MAX_HART_ID_NUMBER: u16 = 2;
4341/// fn number(self) -> u16 { self as _ }
4442/// fn from_number(number: u16) -> Result<Self> {
45- /// if number > Self::MAX_HART_ID_NUMBER {
46- /// Err(Error::InvalidVariant(number as usize))
47- /// } else {
48- /// // SAFETY: valid context number
49- /// Ok(unsafe { core::mem::transmute (number) })
43+ /// match number {
44+ /// 0 => Ok(HartId::H0),
45+ /// 1 => Ok(HartId::H1),
46+ /// 2 => Ok(HartId::H2),
47+ /// _ => Err(Error::InvalidVariant (number as _)),
5048/// }
5149/// }
5250/// }
5351///
54- /// clint_codegen!(
52+ /// riscv_peripheral:: clint_codegen!(
5553/// base 0x0200_0000,
5654/// mtimecmps [mtimecmp0 = (HartId::H0, "`H0`"), mtimecmp1 = (HartId::H1, "`H1`"), mtimecmp2 = (HartId::H2, "`H2`")],
5755/// msips [msip0=(HartId::H0,"`H0`"), msip1=(HartId::H1,"`H1`"), msip2=(HartId::H2,"`H2`")], // do not forget the ending comma!
@@ -206,7 +204,7 @@ macro_rules! clint_codegen {
206204///
207205/// # Note
208206///
209- /// You must export the `riscv_peripheral::hal:: delay::DelayNs` trait in order to use delay methods.
207+ /// You must export the [`embedded_hal:: delay::DelayNs`] trait in order to use delay methods.
210208[ inline]
211209 pub const fn delay( ) -> $crate:: hal:: aclint:: Delay {
212210 $crate:: hal:: aclint:: Delay :: new( Self :: mtime( ) , Self :: freq( ) )
@@ -220,7 +218,7 @@ macro_rules! clint_codegen {
220218///
221219/// # Note
222220///
223- /// You must export the `riscv_peripheral::hal_async:: delay::DelayNs` trait in order to use delay methods.
221+ /// You must export the [`embedded_hal_async:: delay::DelayNs`] trait in order to use delay methods.
224222///
225223/// This implementation relies on the machine-level timer interrupts to wake futures.
226224/// Therefore, it needs to schedule the machine-level timer interrupts via the `MTIMECMP` register assigned to the current HART.
@@ -264,6 +262,27 @@ macro_rules! clint_codegen {
264262}
265263
266264/// Macro to create interfaces to PLIC peripherals in PACs.
265+ /// The resulting struct will be named `PLIC`, and will provide safe access to the PLIC registers.
266+ ///
267+ /// This macro expects 2 different argument types:
268+ ///
269+ /// - Base address (**MANDATORY**): base address of the PLIC peripheral of the target.
270+ /// - Per-HART contexts (**OPTIONAL**): a list of `ctx` contexts for easing access to per-HART PLIC contexts.
271+ ///
272+ /// Check the examples below for more details about the usage and syntax of this macro.
273+ ///
274+ /// # Example
275+ ///
276+ /// ## Base address only
277+ ///
278+ /// ```
279+ /// use riscv_peripheral::clint_codegen;
280+ ///
281+ /// riscv_peripheral::plic_codegen!(base 0x0C00_0000,); // do not forget the ending comma!
282+ ///
283+ /// let priorities = PLIC::priorities(); // Priorities registers
284+ /// let pendings = PLIC::pendings(); // Pendings registers
285+ /// ```
267286#[ macro_export]
268287macro_rules! plic_codegen {
269288 ( ) => {
0 commit comments