Crate device_register
source ·Expand description
device-register
A no_std
library to describe the registers permissions of a device to ease driver development.
no_std
support- Zero cost, no use of dyn
- No dsl, just a derive macro and impl a trait.
- Error passthrough
Usage
Simply derive using XXRegister
, where XX is the premission.
The following permissions are supported
RORegister
, read only permissionWORegister
, write only permissionEORegister
, edit only permission, when a register need to be read-modify-writeRERegister
, Read and edit permissionRWRegister
, Read, write and edit permission.
To define a register, simply derive using the desired permission.
Then use the register
attribute to define it’s address, type for the address and the error.
use device_register::*;
#[derive(RWRegister)]
#[register( addr = "42", ty = "u8")]
pub struct Register0(pub u16);
Then, your driver only need to implement the RegisterInterface to have access to the read/write/edit traits.
Complete example
Here is a complete example.
See the tests
folder for more, or checkout the tmp117 driver for actual usage.
use std::collections::HashMap;
use device_register::*;
// The type of the address used by the driver
struct Address(pub u8);
// We define the register with Read/Write permission
// Then we pass the address type, value and error type of the driveer
#[derive(Debug, Copy, PartialEq, Eq, Clone, RWRegister)]
#[register( addr = "Address(1)", ty = "Address")]
struct Register0(pub u16);
impl From<u16> for Register0 {
fn from(value: u16) -> Self {
Register0(value)
}
}
impl From<Register0> for u16 {
fn from(value: Register0) -> Self {
value.0
}
}
// Mock of the device driver
struct DeviceDriver {
// Simulate reading from the device
pub registers: HashMap<u8, u16>,
}
// Implement a method directly, by passing the trait for specific usecases like async
impl DeviceDriver {
pub async fn read_async<R>(&self) -> R
where
R: ReadableRegister<Address = Address> + From<u16>,
{
async {
let bytes = self.registers.get(&R::ADDRESS.0).unwrap();
bytes.clone().into()
}.await
}
}
// We implement the required interface
impl<R> RegisterInterface<R, Address> for DeviceDriver
where
R: Register<Address = Address> + Clone + From<u16>,
u16: From<R>,
{
// The type of the error, lets have none for now,
type Error = ();
fn read_register(&mut self) -> Result<R, Self::Error> {
let bytes = self.registers.get(&R::ADDRESS.0).unwrap();
Ok(bytes.clone().into())
}
fn write_register(&mut self, register: &R) -> Result<(), Self::Error> {
self.registers.insert(R::ADDRESS.0, register.clone().into());
Ok(())
}
}
let mut device = DeviceDriver{
registers: HashMap::new(),
};
// We can the Read/Write/Edit the registers that uses the Address type.
let write = Register0(42);
device.write(write).unwrap();
let read: Register0 = device.read().unwrap();
assert_eq!(read, write);
device.edit(|r: &mut Register0| {
r.0 = 43;
}).unwrap();
let read: Register0 = device.read().unwrap();
assert_eq!(read, Register0(43));
// Custom implementation, async is an example of usecase for custom implements
tokio_test::block_on( async {
let read_async: Register0 = device.read_async().await;
assert_eq!(read, Register0(43));
} );
MSRV
The minimum supported rust version is 1.75.0
, but previous versions might work with the library
License
Licensed under either of
-
Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
-
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
License: MIT OR Apache-2.0
Traits
- Trait to safely read-edit-write a register. Usefull when a register has reserved values for internal uses. Avoids writing garbage to the reserved bits.
- Trait of a register that can only be edited. Some registers require a read-edit-write operation since some bits a reserved internally Editing a register allows to “safely” modify only a subset of values
- Trait to safely read a register. Only a readable register can be read.
- Trait of a read only register
- Trait of a register containing an address
- Traits that define how to read and write the registers. Note that those functions should mostly just be implemented and not used since they are not bound by Read/Write/Edit permission.
- Trait a writable register, like a register but can be written to
- Trait to safely write a register. Only a writable register can be written to.
Derive Macros
- Create an edit only register
- Create a read/edit register
- Create a read only register
- Create a read/write register
- Create a write only register