tock-register-interface: move LocalRegisterCopy to own module

Move LocalRegisterCopy to its own module and rexport it through the
top-level crate exports. LocalRegisterCopy is distinct from actual
register types, as it only represents a copy of any other register
type, whether implemented in this crate or outside of it. This is in
contrast to an InMemoryRegister, which represents an actual register
stored in memory. This is further emphasized by the fact that
LocalRegisterCopy does not implement the tock-registers interface
traits (e.g. Readable, Writeable) and uses different method signatures
for manipulating the contained values, and implements the Copy trait.

Hence, this moves it to its own module and reexports it with the
top-level crate exports, as it is of importance regardless of whether
the included register types are used.

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

Author: lschuermann

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

@@ -148,8 +148,7 @@
 //! ```
 
 use crate::fields::{Field, FieldValue, TryFromValue};
-use crate::registers::LocalRegisterCopy;
-use crate::{IntLike, RegisterLongName};
+use crate::{IntLike, LocalRegisterCopy, RegisterLongName};
 
 /// Readable register
 ///

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

@@ -10,6 +10,9 @@ pub mod interfaces;
 pub mod macros;
 pub mod registers;
 
+mod local_register;
+pub use local_register::LocalRegisterCopy;
+
 use core::ops::{BitAnd, BitOr, BitOrAssign, Not, Shl, Shr};
 
 /// Trait representing the base type of registers.

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

@@ -0,0 +1,129 @@
+//! Module containing the [`LocalRegisterCopy`] type. Please refer to
+//! its documentation.
+
+use core::fmt;
+use core::marker::PhantomData;
+
+use crate::fields::{Field, FieldValue, TryFromValue};
+use crate::{IntLike, RegisterLongName};
+
+/// A read-write copy of register contents.
+///
+/// This behaves very similarly to a read-write register, but instead of doing a
+/// volatile read to MMIO to get the value for each function call, a copy of the
+/// register contents are stored locally in memory. This allows a peripheral
+/// to do a single read on a register, and then check which bits are set without
+/// having to do a full MMIO read each time. It also allows the value of the
+/// register to be "cached" in case the peripheral driver needs to clear the
+/// register in hardware yet still be able to check the bits.
+/// You can write to a local register, which will modify the stored value, but
+/// will not modify any hardware because it operates only on local copy.
+///
+/// This type does not implement the
+/// [`Readable`](crate::interfaces::Readable) and
+/// [`Writeable`](crate::interfaces::Writeable) traits because it
+/// requires a mutable reference to modify the contained value. It
+/// still mirrors the interface which would be exposed by a type
+/// implementing [`Readable`](crate::interfaces::Readable),
+/// [`Writeable`](crate::interfaces::Writeable) and
+/// [`ReadWriteable`](crate::interfaces::ReadWriteable).
+#[derive(Copy, Clone)]
+pub struct LocalRegisterCopy<T: IntLike, R: RegisterLongName = ()> {
+    value: T,
+    associated_register: PhantomData<R>,
+}
+
+impl<T: IntLike, R: RegisterLongName> LocalRegisterCopy<T, R> {
+    pub const fn new(value: T) -> Self {
+        LocalRegisterCopy {
+            value: value,
+            associated_register: PhantomData,
+        }
+    }
+
+    /// Get the raw register value
+    #[inline]
+    pub fn get(&self) -> T {
+        self.value
+    }
+
+    /// Set the raw register value
+    #[inline]
+    pub fn set(&mut self, value: T) {
+        self.value = value;
+    }
+
+    /// Read the value of the given field
+    #[inline]
+    pub fn read(&self, field: Field<T, R>) -> T {
+        field.read(self.get())
+    }
+
+    /// Read value of the given field as an enum member
+    #[inline]
+    pub fn read_as_enum<E: TryFromValue<T, EnumType = E>>(&self, field: Field<T, R>) -> Option<E> {
+        field.read_as_enum(self.get())
+    }
+
+    /// Write the value of one or more fields, overwriting the other fields with zero
+    #[inline]
+    pub fn write(&mut self, field: FieldValue<T, R>) {
+        self.set(field.value);
+    }
+
+    /// Write the value of one or more fields, leaving the other fields unchanged
+    #[inline]
+    pub fn modify(&mut self, field: FieldValue<T, R>) {
+        self.set(field.modify(self.get()));
+    }
+
+    /// Check if one or more bits in a field are set
+    #[inline]
+    pub fn is_set(&self, field: Field<T, R>) -> bool {
+        field.is_set(self.get())
+    }
+
+    /// Check if any specified parts of a field match
+    #[inline]
+    pub fn matches_any(&self, field: FieldValue<T, R>) -> bool {
+        field.matches_any(self.get())
+    }
+
+    /// Check if all specified parts of a field match
+    #[inline]
+    pub fn matches_all(&self, field: FieldValue<T, R>) -> bool {
+        field.matches_all(self.get())
+    }
+
+    /// Do a bitwise AND operation of the stored value and the passed in value
+    /// and return a new LocalRegisterCopy.
+    #[inline]
+    pub fn bitand(&self, rhs: T) -> LocalRegisterCopy<T, R> {
+        LocalRegisterCopy::new(self.value & rhs)
+    }
+}
+
+impl<T: IntLike + fmt::Debug, R: RegisterLongName> fmt::Debug for LocalRegisterCopy<T, R> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{:?}", self.value)
+    }
+}
+
+// Helper macro to implement From<LocalRegisterCopy<T: IntLike>, R>>
+// for <T: IntLike>
+macro_rules! From_impl_for {
+    ($type:ty) => {
+        impl<R: RegisterLongName> From<LocalRegisterCopy<$type, R>> for $type {
+            fn from(r: LocalRegisterCopy<$type, R>) -> $type {
+                r.value
+            }
+        }
+    };
+}
+
+From_impl_for!(u8);
+From_impl_for!(u16);
+From_impl_for!(u32);
+From_impl_for!(u64);
+From_impl_for!(u128);
+From_impl_for!(usize);

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

@@ -54,10 +54,8 @@
 //! - Shane Leonard <shanel@stanford.edu>
 
 use core::cell::UnsafeCell;
-use core::fmt;
 use core::marker::PhantomData;
 
-use crate::fields::{Field, FieldValue, TryFromValue};
 use crate::interfaces::{Readable, Writeable};
 use crate::{IntLike, RegisterLongName};
 
@@ -219,122 +217,6 @@ impl<T: IntLike, R: RegisterLongName> Writeable for InMemoryRegister<T, R> {
     }
 }
 
-/// A read-write copy of register contents.
-///
-/// This behaves very similarly to a read-write register, but instead of doing a
-/// volatile read to MMIO to get the value for each function call, a copy of the
-/// register contents are stored locally in memory. This allows a peripheral
-/// to do a single read on a register, and then check which bits are set without
-/// having to do a full MMIO read each time. It also allows the value of the
-/// register to be "cached" in case the peripheral driver needs to clear the
-/// register in hardware yet still be able to check the bits.
-/// You can write to a local register, which will modify the stored value, but
-/// will not modify any hardware because it operates only on local copy.
-///
-/// This type does not implement the [`Readable`] and [`Writeable`]
-/// traits because it requires a mutable reference to modify the
-/// contained value. It still mirrors the interface which would be
-/// exposed by a type implementing [`Readable`], [`Writeable`] and
-/// [`ReadWriteable`](crate::interfaces::ReadWriteable).
-#[derive(Copy, Clone)]
-pub struct LocalRegisterCopy<T: IntLike, R: RegisterLongName = ()> {
-    value: T,
-    associated_register: PhantomData<R>,
-}
-
-impl<T: IntLike, R: RegisterLongName> LocalRegisterCopy<T, R> {
-    pub const fn new(value: T) -> Self {
-        LocalRegisterCopy {
-            value: value,
-            associated_register: PhantomData,
-        }
-    }
-
-    /// Get the raw register value
-    #[inline]
-    pub fn get(&self) -> T {
-        self.value
-    }
-
-    /// Set the raw register value
-    #[inline]
-    pub fn set(&mut self, value: T) {
-        self.value = value;
-    }
-
-    /// Read the value of the given field
-    #[inline]
-    pub fn read(&self, field: Field<T, R>) -> T {
-        field.read(self.get())
-    }
-
-    /// Read value of the given field as an enum member
-    #[inline]
-    pub fn read_as_enum<E: TryFromValue<T, EnumType = E>>(&self, field: Field<T, R>) -> Option<E> {
-        field.read_as_enum(self.get())
-    }
-
-    /// Write the value of one or more fields, overwriting the other fields with zero
-    #[inline]
-    pub fn write(&mut self, field: FieldValue<T, R>) {
-        self.set(field.value);
-    }
-
-    /// Write the value of one or more fields, leaving the other fields unchanged
-    #[inline]
-    pub fn modify(&mut self, field: FieldValue<T, R>) {
-        self.set(field.modify(self.get()));
-    }
-
-    /// Check if one or more bits in a field are set
-    #[inline]
-    pub fn is_set(&self, field: Field<T, R>) -> bool {
-        field.is_set(self.get())
-    }
-
-    /// Check if any specified parts of a field match
-    #[inline]
-    pub fn matches_any(&self, field: FieldValue<T, R>) -> bool {
-        field.matches_any(self.get())
-    }
-
-    /// Check if all specified parts of a field match
-    #[inline]
-    pub fn matches_all(&self, field: FieldValue<T, R>) -> bool {
-        field.matches_all(self.get())
-    }
-
-    /// Do a bitwise AND operation of the stored value and the passed in value
-    /// and return a new LocalRegisterCopy.
-    #[inline]
-    pub fn bitand(&self, rhs: T) -> LocalRegisterCopy<T, R> {
-        LocalRegisterCopy::new(self.value & rhs)
-    }
-}
-
-impl<T: IntLike + fmt::Debug, R: RegisterLongName> fmt::Debug for LocalRegisterCopy<T, R> {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        write!(f, "{:?}", self.value)
-    }
-}
-
-macro_rules! From_impl_for {
-    ($type:ty) => {
-        impl<R: RegisterLongName> From<LocalRegisterCopy<$type, R>> for $type {
-            fn from(r: LocalRegisterCopy<$type, R>) -> $type {
-                r.value
-            }
-        }
-    };
-}
-
-From_impl_for!(u8);
-From_impl_for!(u16);
-From_impl_for!(u32);
-From_impl_for!(u64);
-From_impl_for!(u128);
-From_impl_for!(usize);
-
 #[cfg(not(feature = "no_std_unit_tests"))]
 #[cfg(test)]
 mod tests {
@@ -376,8 +258,8 @@ mod tests {
     }
 
     mod field {
-        use super::super::{Field, TryFromValue};
         use super::Foo;
+        use crate::fields::{Field, TryFromValue};
 
         #[test]
         fn test_new() {
@@ -446,7 +328,7 @@ mod tests {
     }
 
     mod field_value {
-        use super::super::Field;
+        use crate::fields::Field;
 
         #[test]
         fn test_from() {