tock_registers/
lib.rs

1// Licensed under the Apache License, Version 2.0 or the MIT License.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3// Copyright Tock Contributors 2022.
4
5//! Tock Register Interface
6//!
7//! Provides efficient mechanisms to express and use type-checked
8//! memory mapped registers and bitfields.
9//!
10//! ```rust
11//! # fn main() {}
12//!
13//! use tock_registers::registers::{ReadOnly, ReadWrite};
14//! use tock_registers::register_bitfields;
15//!
16//! // Register maps are specified like this:
17//! #[repr(C)]
18//! struct Registers {
19//!     // Control register: read-write
20//!     cr: ReadWrite<u32, Control::Register>,
21//!     // Status register: read-only
22//!     s: ReadOnly<u32, Status::Register>,
23//! }
24//!
25//! // Register fields and definitions look like this:
26//! register_bitfields![u32,
27//!     // Simpler bitfields are expressed concisely:
28//!     Control [
29//!         /// Stop the Current Transfer
30//!         STOP 8,
31//!         /// Software Reset
32//!         SWRST 7,
33//!         /// Master Disable
34//!         MDIS 1,
35//!         /// Master Enable
36//!         MEN 0
37//!     ],
38//!
39//!     // More complex registers can express subtypes:
40//!     Status [
41//!         TXCOMPLETE  OFFSET(0) NUMBITS(1) [],
42//!         TXINTERRUPT OFFSET(1) NUMBITS(1) [],
43//!         RXCOMPLETE  OFFSET(2) NUMBITS(1) [],
44//!         RXINTERRUPT OFFSET(3) NUMBITS(1) [],
45//!         MODE        OFFSET(4) NUMBITS(3) [
46//!             FullDuplex = 0,
47//!             HalfDuplex = 1,
48//!             Loopback = 2,
49//!             Disabled = 3
50//!         ],
51//!         ERRORCOUNT OFFSET(6) NUMBITS(3) []
52//!     ]
53//! ];
54//! ```
55//!
56//! Author
57//! ------
58//! - Shane Leonard <shanel@stanford.edu>
59
60#![no_std]
61// If we don't build any actual register types, we don't need unsafe
62// code in this crate
63#![cfg_attr(not(feature = "register_types"), forbid(unsafe_code))]
64
65pub mod fields;
66pub mod interfaces;
67pub mod macros;
68
69#[cfg(feature = "register_types")]
70pub mod registers;
71
72pub mod debug;
73
74mod local_register;
75pub use local_register::LocalRegisterCopy;
76
77use core::fmt::Debug;
78use core::ops::{BitAnd, BitOr, BitOrAssign, Not, Shl, Shr};
79
80/// Trait representing the base type of registers.
81///
82/// UIntLike defines basic properties of types required to
83/// read/write/modify a register through its methods and supertrait
84/// requirements.
85///
86/// It features a range of default implementations for common unsigned
87/// integer types, such as [`u8`], [`u16`], [`u32`], [`u64`], [`u128`],
88/// and [`usize`].
89pub trait UIntLike:
90    BitAnd<Output = Self>
91    + BitOr<Output = Self>
92    + BitOrAssign
93    + Not<Output = Self>
94    + Eq
95    + Shr<usize, Output = Self>
96    + Shl<usize, Output = Self>
97    + Copy
98    + Clone
99    + Debug
100{
101    /// Return the representation of the value `0` in the implementing
102    /// type.
103    ///
104    /// This can be used to acquire values of the [`UIntLike`] type,
105    /// even in generic implementations. For instance, to get the
106    /// value `1`, one can use `<T as UIntLike>::zero() + 1`. To get
107    /// the largest representable value, use a bitwise negation: `~(<T
108    /// as UIntLike>::zero())`.
109    fn zero() -> Self;
110}
111
112// Helper macro for implementing the UIntLike trait on differrent
113// types.
114macro_rules! UIntLike_impl_for {
115    ($type:ty) => {
116        impl UIntLike for $type {
117            fn zero() -> Self {
118                0
119            }
120        }
121    };
122}
123
124UIntLike_impl_for!(u8);
125UIntLike_impl_for!(u16);
126UIntLike_impl_for!(u32);
127UIntLike_impl_for!(u64);
128UIntLike_impl_for!(u128);
129UIntLike_impl_for!(usize);
130
131/// Descriptive name for each register.
132pub trait RegisterLongName {}
133
134// Useful implementation for when no RegisterLongName is required
135// (e.g. no fields need to be accessed, just the raw register values)
136impl RegisterLongName for () {}
tock_registers/lib.rs

tock_registers/
lib.rs
