feat(port_riscv): rename use_timer! → use_mtime!,

To make room for the SBI-based timer driver.

Author: yvt

src/r3_port_riscv/CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - The new option `ThreadingOptions::PRIVILEGE_LEVEL` allows for running the kernel in other privilege levels than M-mode.
 
+### Changed
+
+- Rename `use_timer!` → `use_mtime!`, `TimerOptions` → `MtimeOptions`
+
 ### Fixed
 
 - The default stack alignment (`PortThreading::STACK_ALIGN`) now conforms to the standard ABI requirement (128-bit alignment).

src/r3_port_riscv/src/lib.rs

@@ -68,17 +68,17 @@ pub mod threading {
     pub mod imp;
 }
 
-/// The standard timer driver.
+/// The `mtime`-based timer driver.
 #[doc(hidden)]
-pub mod timer {
+pub mod mtime {
     pub mod cfg;
     pub mod imp;
 }
 
+pub use self::mtime::cfg::*;
 pub use self::plic::cfg::*;
 pub use self::rt::cfg::*;
 pub use self::threading::cfg::*;
-pub use self::timer::cfg::*;
 
 /// Defines the entry points of a port instantiation. Implemented by
 /// [`use_port!`].
@@ -110,7 +110,7 @@ pub trait EntryPoint {
 }
 
 /// An abstract inferface to a port timer driver. Implemented by
-/// [`use_timer!`].
+/// [`use_mtime!`].
 pub trait Timer {
     /// Initialize the driver. This will be called just before entering
     /// [`PortToKernel::boot`].

src/r3_port_riscv/src/timer/cfg.rs renamed to src/r3_port_riscv/src/mtime/cfg.rs

@@ -1,24 +1,24 @@
-//! The public interface for the RISC-V timer.
+//! The public interface for the `mtime`-based timer driver.
 use r3_core::kernel::InterruptNum;
 
-/// Attach the implementation of [`PortTimer`] that is based on the RISC-V timer
-/// (`mtime`/`mtimecfg`) to a given kernel trait type. This macro also
+/// Attach the implementation of [`PortTimer`] based on the RISC-V machine-mode
+/// timer (`mtime`/`mtimecfg`) to a given kernel trait type. This macro also
 /// implements [`Timer`] on the system type.
-/// **Requires [`TimerOptions`].**
+/// **Requires [`MtimeOptions`].**
 ///
 /// [`PortTimer`]: r3_kernel::PortTimer
 /// [`Timer`]: crate::Timer
 ///
 /// You should do the following:
 ///
-///  - Implement [`TimerOptions`] on the system type `$Traits`.
+///  - Implement [`MtimeOptions`] on the system type `$Traits`.
 ///  - Call `$Traits::configure_timer()` in your configuration function.
 ///    See the following example.
 ///
 /// ```rust,ignore
-/// r3_port_riscv::use_timer!(unsafe impl PortTimer for System);
+/// r3_port_riscv::use_mtime!(unsafe impl PortTimer for System);
 ///
-/// impl r3_port_riscv::TimerOptions for System {
+/// impl r3_port_riscv::MtimeOptions for System {
 ///     const MTIME_PTR: usize = 0x1001_1000;
 ///     const MTIMECMP_PTR: usize = 0x1001_1000;
 ///     const FREQUENCY: u64 = 1_000_000;
@@ -32,10 +32,10 @@ use r3_core::kernel::InterruptNum;
 ///
 /// # Safety
 ///
-///  - `TimerOptions` must be configured correctly.
+///  - `MtimeOptions` must be configured correctly.
 ///
 #[macro_export]
-macro_rules! use_timer {
+macro_rules! use_mtime {
     (unsafe impl PortTimer for $Traits:ty) => {
         const _: () = {
             use $crate::r3_core::{
@@ -44,55 +44,55 @@ macro_rules! use_timer {
             };
             use $crate::r3_kernel::{PortTimer, System, UTicks};
             use $crate::r3_portkit::tickless;
-            use $crate::{timer, Timer, TimerOptions};
+            use $crate::{mtime, MtimeOptions, Timer};
 
             impl PortTimer for $Traits {
                 const MAX_TICK_COUNT: UTicks = u32::MAX;
                 const MAX_TIMEOUT: UTicks = u32::MAX;
 
                 unsafe fn tick_count() -> UTicks {
                     // Safety: We are just forwarding the call
-                    unsafe { timer::imp::tick_count::<Self>() }
+                    unsafe { mtime::imp::tick_count::<Self>() }
                 }
 
                 unsafe fn pend_tick() {
                     // Safety: We are just forwarding the call
-                    unsafe { timer::imp::pend_tick::<Self>() }
+                    unsafe { mtime::imp::pend_tick::<Self>() }
                 }
 
                 unsafe fn pend_tick_after(tick_count_delta: UTicks) {
                     // Safety: We are just forwarding the call
-                    unsafe { timer::imp::pend_tick_after::<Self>(tick_count_delta) }
+                    unsafe { mtime::imp::pend_tick_after::<Self>(tick_count_delta) }
                 }
             }
 
             impl Timer for $Traits {
                 unsafe fn init() {
-                    unsafe { timer::imp::init::<Self>() }
+                    unsafe { mtime::imp::init::<Self>() }
                 }
             }
 
             const TICKLESS_CFG: tickless::TicklessCfg =
                 match tickless::TicklessCfg::new(tickless::TicklessOptions {
-                    hw_freq_num: <$Traits as TimerOptions>::FREQUENCY,
-                    hw_freq_denom: <$Traits as TimerOptions>::FREQUENCY_DENOMINATOR,
-                    hw_headroom_ticks: <$Traits as TimerOptions>::HEADROOM,
+                    hw_freq_num: <$Traits as MtimeOptions>::FREQUENCY,
+                    hw_freq_denom: <$Traits as MtimeOptions>::FREQUENCY_DENOMINATOR,
+                    hw_headroom_ticks: <$Traits as MtimeOptions>::HEADROOM,
                     // `mtime` is a 64-bit free-running counter and it is
                     // expensive to create a 32-bit timer with an arbitrary
                     // period out of it.
                     force_full_hw_period: true,
                     // If clearing `mtime` is not allowed, we must record the
                     // starting value of `mtime` by calling `reset`.
-                    resettable: !<$Traits as TimerOptions>::RESET_MTIME,
+                    resettable: !<$Traits as MtimeOptions>::RESET_MTIME,
                 }) {
                     Ok(x) => x,
                     Err(e) => e.panic(),
                 };
 
             static mut TIMER_STATE: tickless::TicklessState<TICKLESS_CFG> = Init::INIT;
 
-            // Safety: Only `use_timer!` is allowed to `impl` this
-            unsafe impl timer::imp::TimerInstance for $Traits {
+            // Safety: Only `use_mtime!` is allowed to `impl` this
+            unsafe impl mtime::imp::TimerInstance for $Traits {
                 const TICKLESS_CFG: tickless::TicklessCfg = TICKLESS_CFG;
 
                 type TicklessState = tickless::TicklessState<TICKLESS_CFG>;
@@ -107,15 +107,15 @@ macro_rules! use_timer {
                 where
                     C: ~const traits::CfgInterruptLine<System = System<Self>>,
                 {
-                    timer::imp::configure(b);
+                    mtime::imp::configure(b);
                 }
             }
         };
     };
 }
 
-/// The options for [`use_timer!`].
-pub trait TimerOptions {
+/// The options for [`use_mtime!`].
+pub trait MtimeOptions {
     /// The memory address of the `mtime` register.
     const MTIME_PTR: usize;
 

src/r3_port_riscv/src/timer/imp.rs renamed to src/r3_port_riscv/src/mtime/imp.rs

@@ -1,4 +1,4 @@
-//! The implementation of the RISC-V timer driver.
+//! The implementation of the `mtime`-based timer driver.
 use r3_core::kernel::{traits, Cfg, StaticInterruptHandler};
 use r3_kernel::{KernelTraits, PortToKernel, System, UTicks};
 use r3_portkit::tickless::{TicklessCfg, TicklessStateTrait};
@@ -7,14 +7,14 @@ use tock_registers::{
     registers::ReadWrite,
 };
 
-use crate::timer::cfg::TimerOptions;
+use crate::mtime::cfg::MtimeOptions;
 
-/// Implemented on a system type by [`use_timer!`].
+/// Implemented on a system type by [`use_mtime!`].
 ///
 /// # Safety
 ///
-/// Only meant to be implemented by [`use_timer!`].
-pub unsafe trait TimerInstance: KernelTraits + TimerOptions {
+/// Only meant to be implemented by [`use_mtime!`].
+pub unsafe trait TimerInstance: KernelTraits + MtimeOptions {
     // FIXME: Specifying `TicklessCfg::new(...)` here causes a "cycle
     //        detected" error
     const TICKLESS_CFG: TicklessCfg;
@@ -30,19 +30,19 @@ pub unsafe trait TimerInstance: KernelTraits + TimerOptions {
 trait TimerInstanceExt: TimerInstance {
     #[inline(always)]
     fn mtime_reg32() -> &'static [ReadWrite<u32>; 2] {
-        // Safety: Verified by the user of `use_timer!`
+        // Safety: Verified by the user of `use_mtime!`
         unsafe { &*(Self::MTIME_PTR as *const _) }
     }
 
     #[inline(always)]
     fn mtime_reg64() -> &'static ReadWrite<u64> {
-        // Safety: Verified by the user of `use_timer!`
+        // Safety: Verified by the user of `use_mtime!`
         unsafe { &*(Self::MTIME_PTR as *const _) }
     }
 
     #[inline(always)]
     fn mtimecmp_reg32() -> &'static [ReadWrite<u32>; 2] {
-        // Safety: Verified by the user of `use_timer!`
+        // Safety: Verified by the user of `use_mtime!`
         unsafe { &*(Self::MTIMECMP_PTR as *const _) }
     }
 
@@ -97,7 +97,7 @@ pub fn init<Traits: TimerInstance>() {
 ///
 /// # Safety
 ///
-/// Only meant to be referenced by `use_timer!`.
+/// Only meant to be referenced by `use_mtime!`.
 pub unsafe fn tick_count<Traits: TimerInstance>() -> UTicks {
     let tcfg = &Traits::TICKLESS_CFG;
 
@@ -112,7 +112,7 @@ pub unsafe fn tick_count<Traits: TimerInstance>() -> UTicks {
 ///
 /// # Safety
 ///
-/// Only meant to be referenced by `use_timer!`.
+/// Only meant to be referenced by `use_mtime!`.
 pub unsafe fn pend_tick<Traits: TimerInstance>() {
     Traits::mtimecmp_reg32()[0].set(0);
     Traits::mtimecmp_reg32()[1].set(0);
@@ -122,7 +122,7 @@ pub unsafe fn pend_tick<Traits: TimerInstance>() {
 ///
 /// # Safety
 ///
-/// Only meant to be referenced by `use_timer!`.
+/// Only meant to be referenced by `use_mtime!`.
 pub unsafe fn pend_tick_after<Traits: TimerInstance>(tick_count_delta: UTicks) {
     let tcfg = &Traits::TICKLESS_CFG;
     // Safety: CPU Lock protects it from concurrent access

src/r3_port_riscv_test_driver/src/main.rs

@@ -79,7 +79,7 @@ macro_rules! instantiate_test {
         type System = r3_kernel::System<SystemTraits>;
         port::use_port!(unsafe struct SystemTraits);
         port::use_rt!(unsafe SystemTraits);
-        port::use_timer!(unsafe impl PortTimer for SystemTraits);
+        port::use_mtime!(unsafe impl PortTimer for SystemTraits);
 
         impl port::ThreadingOptions for SystemTraits {}
 
@@ -106,7 +106,7 @@ macro_rules! instantiate_test {
             const CONTEXT: usize = 0;
         }
 
-        impl port::TimerOptions for SystemTraits {
+        impl port::MtimeOptions for SystemTraits {
             const MTIME_PTR: usize = 0x0200_bff8;
 
             #[cfg(any(