tock-register-interface: update crate::registers doc comment

Move the previous documentation comment of crate::registers to the
top-level module, as it not only describes the register types but also
Fields and macros.

Introduce a new documentation comment, providing an overview of the
included register types.

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

Author: lschuermann

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

@@ -1,10 +1,60 @@
 //! Tock Register Interface
 //!
+//! Provides efficient mechanisms to express and use type-checked
+//! memory mapped registers and bitfields.
 //!
+//! ```rust
+//! # fn main() {}
+//!
+//! use tock_registers::registers::{ReadOnly, ReadWrite};
+//! use tock_registers::register_bitfields;
+//!
+//! // Register maps are specified like this:
+//! #[repr(C)]
+//! struct Registers {
+//!     // Control register: read-write
+//!     cr: ReadWrite<u32, Control::Register>,
+//!     // Status register: read-only
+//!     s: ReadOnly<u32, Status::Register>,
+//! }
+//!
+//! // Register fields and definitions look like this:
+//! register_bitfields![u32,
+//!     // Simpler bitfields are expressed concisely:
+//!     Control [
+//!         /// Stop the Current Transfer
+//!         STOP 8,
+//!         /// Software Reset
+//!         SWRST 7,
+//!         /// Master Disable
+//!         MDIS 1,
+//!         /// Master Enable
+//!         MEN 0
+//!     ],
+//!
+//!     // More complex registers can express subtypes:
+//!     Status [
+//!         TXCOMPLETE  OFFSET(0) NUMBITS(1) [],
+//!         TXINTERRUPT OFFSET(1) NUMBITS(1) [],
+//!         RXCOMPLETE  OFFSET(2) NUMBITS(1) [],
+//!         RXINTERRUPT OFFSET(3) NUMBITS(1) [],
+//!         MODE        OFFSET(4) NUMBITS(3) [
+//!             FullDuplex = 0,
+//!             HalfDuplex = 1,
+//!             Loopback = 2,
+//!             Disabled = 3
+//!         ],
+//!         ERRORCOUNT OFFSET(6) NUMBITS(3) []
+//!     ]
+//! ];
+//! ```
+//!
+//! Author
+//! ------
+//! - Shane Leonard <shanel@stanford.edu>
 
 #![feature(const_fn_trait_bound)]
 #![no_std]
-
 // If we don't build any actual register types, we don't need unsafe
 // code in this crate
 #![cfg_attr(not(feature = "register_types"), forbid(unsafe_code))]

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

@@ -1,57 +1,20 @@
-//! Implementation of registers and bitfields.
+//! Implementation of included register types.
 //!
-//! Provides efficient mechanisms to express and use type-checked memory mapped
-//! registers and bitfields.
+//! This module provides a standard set of register types, which can
+//! describe different access levels:
 //!
-//! ```rust
-//! # fn main() {}
+//! - [`ReadWrite`] for registers which can be read and written to
+//! - [`ReadOnly`] for registers which can only be read
+//! - [`WriteOnly`] for registers which can only be written to
+//! - [`Aliased`] for registers which can be both read and written,
+//!   but represent different registers depending on the operation
+//! - [`InMemoryRegister`] provide a register-type in RAM using
+//!   volatile operations
 //!
-//! use tock_registers::registers::{ReadOnly, ReadWrite};
-//! use tock_registers::register_bitfields;
-//!
-//! // Register maps are specified like this:
-//! #[repr(C)]
-//! struct Registers {
-//!     // Control register: read-write
-//!     cr: ReadWrite<u32, Control::Register>,
-//!     // Status register: read-only
-//!     s: ReadOnly<u32, Status::Register>,
-//! }
-//!
-//! // Register fields and definitions look like this:
-//! register_bitfields![u32,
-//!     // Simpler bitfields are expressed concisely:
-//!     Control [
-//!         /// Stop the Current Transfer
-//!         STOP 8,
-//!         /// Software Reset
-//!         SWRST 7,
-//!         /// Master Disable
-//!         MDIS 1,
-//!         /// Master Enable
-//!         MEN 0
-//!     ],
-//!
-//!     // More complex registers can express subtypes:
-//!     Status [
-//!         TXCOMPLETE  OFFSET(0) NUMBITS(1) [],
-//!         TXINTERRUPT OFFSET(1) NUMBITS(1) [],
-//!         RXCOMPLETE  OFFSET(2) NUMBITS(1) [],
-//!         RXINTERRUPT OFFSET(3) NUMBITS(1) [],
-//!         MODE        OFFSET(4) NUMBITS(3) [
-//!             FullDuplex = 0,
-//!             HalfDuplex = 1,
-//!             Loopback = 2,
-//!             Disabled = 3
-//!         ],
-//!         ERRORCOUNT OFFSET(6) NUMBITS(3) []
-//!     ]
-//! ];
-//! ```
-//!
-//! Author
-//! ------
-//! - Shane Leonard <shanel@stanford.edu>
+//! These types can be disabled by removing the `register_types` crate
+//! feature (part of the default features). This is useful if this
+//! crate should be used only as an interface library, or if all
+//! unsafe code should be disabled.
 
 use core::cell::UnsafeCell;
 use core::marker::PhantomData;