tock-register-interface: move IntLike, RegisterLongName, ...

Move IntLike, RegisterLongName out of crate::registers to the
top-level crate and TryFromValue to crate::fields respectively. These
traits are independent and should therefore not be included in the
registers module. The reasoning for moving IntLike and
RegisterLongName to the top-level crate exports is that these are base
types over which all registers and fields are composed, and thus
represent essential functionality of the library. TryFromValue only
relates to individual register fields and is thus moved to
crate::fields.

Other code in the Tock repository is updated to reflect these changes.

Signed-off-by: Leon Schuermann <leon@is.currently.online>

Author: lschuermann

libraries/tock-register-interface/src/fields.rs

@@ -9,7 +9,7 @@
 //!
 //! A specific section (bitfield) in a register is described by the
 //! [`Field`] type, consisting of an unshifted bitmask over the base
-//! register [`IntLike`](crate::registers::IntLike) type, and a shift
+//! register [`IntLike`](crate::IntLike) type, and a shift
 //! parameter. It is further associated with a specific
 //! [`RegisterLongName`], which can prevent its use with incompatible
 //! registers.
@@ -23,9 +23,9 @@
 //! ## `register_bitfields` macro
 //!
 //! For defining register layouts with an associated
-//! [`RegisterLongName`](crate::registers::RegisterLongName), along
-//! with [`Field`]s and matching [`FieldValue`]s, a convenient
-//! macro-based interface can be used.
+//! [`RegisterLongName`](crate::RegisterLongName), along with
+//! [`Field`]s and matching [`FieldValue`]s, a convenient macro-based
+//! interface can be used.
 //!
 //! The following example demonstrates how two registers can be
 //! defined, over a `u32` base type:
@@ -59,7 +59,6 @@
 //! assert!(reg.get() == 0x00000008);
 //! ```
 
-
 // The register interface uses `+` in a way that is fine for bitfields, but
 // looks unusual (and perhaps problematic) to a linter. We just ignore those
 // lints for this file.
@@ -69,8 +68,7 @@
 use core::marker::PhantomData;
 use core::ops::{Add, AddAssign};
 
-use crate::registers::TryFromValue;
-use crate::registers::{IntLike, RegisterLongName};
+use crate::{IntLike, RegisterLongName};
 
 /// Specific section of a register.
 ///
@@ -249,6 +247,14 @@ impl<T: IntLike, R: RegisterLongName> AddAssign for FieldValue<T, R> {
     }
 }
 
+/// Conversion of raw register value into enumerated values member.
+/// Implemented inside register_bitfields! macro for each bit field.
+pub trait TryFromValue<V> {
+    type EnumType;
+
+    fn try_from(v: V) -> Option<Self::EnumType>;
+}
+
 /// Helper macro for computing bitmask of variable number of bits
 #[macro_export]
 macro_rules! bitmask {
@@ -322,8 +328,7 @@ macro_rules! register_bitmasks {
         $(#[$outer])*
         pub mod $field {
             #[allow(unused_imports)]
-            use $crate::registers::TryFromValue;
-            use $crate::fields::FieldValue;
+            use $crate::fields::{TryFromValue, FieldValue};
             use super::$reg_desc;
 
             $(
@@ -389,8 +394,7 @@ macro_rules! register_bitmasks {
         $(#[$outer])*
         pub mod $field {
             #[allow(unused_imports)]
-            use $crate::registers::TryFromValue;
-            use $crate::fields::FieldValue;
+            use $crate::fields::{FieldValue, TryFromValue};
             use super::$reg_desc;
 
             #[allow(non_upper_case_globals)]
@@ -438,7 +442,7 @@ macro_rules! register_bitfields {
                 // (if you can access $reg, you can access $reg::Register)
                 #[derive(Clone, Copy)]
                 pub struct Register;
-                impl $crate::registers::RegisterLongName for Register {}
+                impl $crate::RegisterLongName for Register {}
 
                 use $crate::fields::Field;
 

libraries/tock-register-interface/src/interfaces.rs

@@ -7,14 +7,13 @@
 //!
 //! Each trait has two associated type parameters, namely:
 //!
-//! - `T`: [`IntLike`](crate::registers::IntLike), indicating the
-//!   underlying integer type used to represent the register's raw
-//!   contents.
+//! - `T`: [`IntLike`](crate::IntLike), indicating the underlying
+//!   integer type used to represent the register's raw contents.
 //!
-//! - `R`: [`RegisterLongName`](crate::registers::RegisterLongName),
-//!   functioning as a type to identify this register's descriptive
-//!   name and semantic meaning. It is further used to impose type
-//!   constraints on values passed through the API, such as
+//! - `R`: [`RegisterLongName`](crate::RegisterLongName), functioning
+//!   as a type to identify this register's descriptive name and
+//!   semantic meaning. It is further used to impose type constraints
+//!   on values passed through the API, such as
 //!   [`FieldValue`](crate::fields::FieldValue).
 //!
 //! Registers can have different access levels, which are mapped to
@@ -35,10 +34,9 @@
 //!   example a memory-mapped UART register might transmit when
 //!   writing and receive when reading.
 //!
-//!   If a type implements both [`Readable`] and [`Writeable`], and the
-//!   associated
-//!   [`RegisterLongName`](crate::registers::RegisterLongName) type
-//!   parameters are identical, it will automatically implement
+//!   If a type implements both [`Readable`] and [`Writeable`], and
+//!   the associated [`RegisterLongName`](crate::RegisterLongName)
+//!   type parameters are identical, it will automatically implement
 //!   [`ReadWriteable`]. In particular, for
 //!   [`Aliased`](crate::registers::Aliased) this is -- in general --
 //!   not the case, so
@@ -91,7 +89,7 @@
 //! # use core::marker::PhantomData;
 //! #
 //! # use tock_registers::interfaces::{Readable, Writeable, ReadWriteable};
-//! # use tock_registers::registers::RegisterLongName;
+//! # use tock_registers::RegisterLongName;
 //! # use tock_registers::register_bitfields;
 //! #
 //! struct DummyRegister<'a, R: RegisterLongName> {
@@ -149,8 +147,9 @@
 //! assert!(dummy.read(DummyReg::HIGH) == 0xb);
 //! ```
 
-use crate::fields::{Field, FieldValue};
-use crate::registers::{IntLike, LocalRegisterCopy, RegisterLongName, TryFromValue};
+use crate::fields::{Field, FieldValue, TryFromValue};
+use crate::registers::LocalRegisterCopy;
+use crate::{IntLike, RegisterLongName};
 
 /// Readable register
 ///

libraries/tock-register-interface/src/lib.rs

@@ -9,3 +9,62 @@ pub mod fields;
 pub mod interfaces;
 pub mod macros;
 pub mod registers;
+
+use core::ops::{BitAnd, BitOr, BitOrAssign, Not, Shl, Shr};
+
+/// Trait representing the base type of registers.
+///
+/// IntLike defines basic properties of types required to
+/// read/write/modify a register through its methods and supertrait
+/// requirements.
+///
+/// It features a range of default implementations for common integer
+/// types, such as [`u8`], [`u16`], [`u32`], [`u64`], [`u128`] and
+/// [`usize`].
+pub trait IntLike:
+    BitAnd<Output = Self>
+    + BitOr<Output = Self>
+    + BitOrAssign
+    + Not<Output = Self>
+    + Eq
+    + Shr<usize, Output = Self>
+    + Shl<usize, Output = Self>
+    + Copy
+    + Clone
+{
+    /// Return the representation of the value `0` in the implementing
+    /// type.
+    ///
+    /// This can be used to acquire values of the [`IntLike`] type,
+    /// even in generic implementations. For instance, to get the
+    /// value `1`, one can use `<T as IntLike>::zero() + 1`. To get
+    /// the largest representable value, use a bitwise negation: `~(<T
+    /// as IntLike>::zero())`.
+    fn zero() -> Self;
+}
+
+// Helper macro for implementing the IntLike trait on differrent
+// types.
+macro_rules! IntLike_impl_for {
+    ($type:ty) => {
+        impl IntLike for $type {
+            fn zero() -> Self {
+                0
+            }
+        }
+    };
+}
+
+IntLike_impl_for!(u8);
+IntLike_impl_for!(u16);
+IntLike_impl_for!(u32);
+IntLike_impl_for!(u64);
+IntLike_impl_for!(u128);
+IntLike_impl_for!(usize);
+
+/// Descriptive name for each register.
+pub trait RegisterLongName {}
+
+// Useful implementation for when no RegisterLongName is required
+// (e.g. no fields need to be accessed, just the raw register values)
+impl RegisterLongName for () {}

libraries/tock-register-interface/src/registers.rs

@@ -56,55 +56,10 @@
 use core::cell::UnsafeCell;
 use core::fmt;
 use core::marker::PhantomData;
-use core::ops::{BitAnd, BitOr, BitOrAssign, Not, Shl, Shr};
 
-use crate::fields::{Field, FieldValue};
+use crate::fields::{Field, FieldValue, TryFromValue};
 use crate::interfaces::{Readable, Writeable};
-
-/// IntLike properties needed to read/write/modify a register.
-pub trait IntLike:
-    BitAnd<Output = Self>
-    + BitOr<Output = Self>
-    + BitOrAssign
-    + Not<Output = Self>
-    + Eq
-    + Shr<usize, Output = Self>
-    + Shl<usize, Output = Self>
-    + Copy
-    + Clone
-{
-    fn zero() -> Self;
-}
-
-macro_rules! IntLike_impl_for {
-    ($type:ty) => {
-        impl IntLike for $type {
-            fn zero() -> Self {
-                0
-            }
-        }
-    };
-}
-
-IntLike_impl_for!(u8);
-IntLike_impl_for!(u16);
-IntLike_impl_for!(u32);
-IntLike_impl_for!(u64);
-IntLike_impl_for!(u128);
-IntLike_impl_for!(usize);
-
-/// Descriptive name for each register.
-pub trait RegisterLongName {}
-
-impl RegisterLongName for () {}
-
-/// Conversion of raw register value into enumerated values member.
-/// Implemented inside register_bitfields! macro for each bit field.
-pub trait TryFromValue<V> {
-    type EnumType;
-
-    fn try_from(v: V) -> Option<Self::EnumType>;
-}
+use crate::{IntLike, RegisterLongName};
 
 /// Read/Write registers.
 ///
@@ -395,14 +350,14 @@ mod tests {
         Foo7,
     }
 
-    impl super::TryFromValue<u16> for Foo {
+    impl crate::fields::TryFromValue<u16> for Foo {
         type EnumType = Foo;
 
         fn try_from(v: u16) -> Option<Self::EnumType> {
             Self::try_from(v as u32)
         }
     }
-    impl super::TryFromValue<u32> for Foo {
+    impl crate::fields::TryFromValue<u32> for Foo {
         type EnumType = Foo;
 
         fn try_from(v: u32) -> Option<Self::EnumType> {