tests that exercise undefined bits. Existing Rust-based access crates
create strict types that eliminate the class of errors where constants
defined for one register are used in an incorrect type of register,
but they also make it very hard to modify in an ad-hoc manner.
## API
This crate is designed to serve as an alternative to `svd2rust`. It generates
a crate which consists of:
1. A library which is used to perform register accesses
2. A "header file" (library) that is auto-generated from a given `soc.svd` file
The library provides the a function template for `CSR` that provides the following
methods:
*`.r(reg: Register) -> T` - Read. Reads the entire contents of a CSR
*`.rf(field: Field) -> T` - Read Field. Read a CSR and return only the masked and shifted value of a sub-field
*`.wo(reg: Register, value:T)` - Write only. Write `value` into a register, replacing its entire contents
*`.wfo(field: Field, value:T)` - Write field only. Write `value` into a field of a register, zeroizing all the other fields and replacing its entire contents
*`.rmwf(field: Field, value:T)` - Read-modify-write a register. Replace just the contents of `field` while leaving the other fields intact. The current implementation makes no guarantees about atomicity.
`Register` and `Field` are generated by the library; `Field` refers to
the `Register` to which it belongs, and thus it is not necessary to
specify it explicitly. Furthermore, the base address of the `CSR` is
bound when the object is created, which allows the crate to work both
with physical and virtual addresses by replacing the base address with
the desired value depending upon the active addressing mode.
In addition to the `CSR` function template, convenience constants for
the CSR base, as well as any memory bases and interrupts, are also
generated by this crate.
This set of API calls supports the most common set of use cases, which
is reading, writing, and updating single fields of a register, or
entire registers all at once.
The API does not natively support setting two fields
simultaneously. This is because there can be nuances to this that
depend upon the hardware implementation, such as bit fields that are
self-resetting, registers that self-clear on read, or registers that
have other automatic and implicit side effects.
Users that require multiple bit fields to be set simultaneously must
explicitly read the CSR value, bind it to a temporary variable, mask
out the fields they want to replace, and combine in the values before
writing it back to the CSR.
To aid with this, the following helper functions are also available:
*`zf(field:Field, value:T) -> T` - Zeroize field. Take bits corresponding to `field` and set it to zero in `value`, leaving other bits unchanged
*`ms(field:Field, value:T) -> T` - Mask and shift. Take value, mask it to the field width, and then shift to its final position.
The idea here is that the `.r(register)` method is used to read the
entire register; then successive `.zf(field, value)` calls are made to
clear the fields prior to setting. Field values are OR'd with the
result of `.ms(field, value)` to create the final composite register
value. Finally, `.wo(value)` is used to overwrite the entire
register with the final composite register value.
The `.ms(field,value)` can also be used to synthesize initial register
values that need to be committed all at once to a hardware register,
before a `.wo(value)` call.
## Example Usage
Let's assume you've used svd2utra.py to create a `utra` crate in the
same directory as svd2utra.py, and you've added this to your `Cargo.toml` file.
Now, inside your `lib.rs` file, you might have something like this:
```Rust
use utra
fn test_fn() {
// Audio tests
// The audio block is a pointer to *mut 32.
let mut audio = CSR::new(HW_AUDIO_BASE as *mut u32);
// Read the entire contents of the RX_CTL register
audio.r(utra::audio::RX_CTL);
// Or read just one field
audio.rf(utra::audio::RX_CTL_ENABLE);
// Do a read-modify-write of the specified field
audio.rmwf(utra::audio::RX_CTL_RESET, 1);
// Do a multi-field operation where all fields are updated in a single write.
// First read the field into a temp variable.
let mut stat = audio.r(utra::audio::RX_STAT);
// in read replica, zero EMPTY and RDCOUNT
stat = audio.zf(utra::audio::RX_STAT_EMPTY, stat);
stat = audio.zf(utra::audio::RX_STAT_RDCOUNT, stat);
// in read replica, now set RDCOUNT to 0x123
stat |= audio.ms(utra::audio::RX_STAT_RDCOUNT, 0x123);
// commit read replica to register, updating both EMPTY and RDCOUNT in a single write
audio.wo(utra::audio::RX_STAT, stat);
// UART tests
// Create the UART register as a pointer to *mut u8
let mut uart = CSR::new(HW_UART_BASE as *mut u8);
// Write the RXTX field of the RXTX register
uart.wfo(utra::uart::RXTX_RXTX, b'a');
// Or you can write the whole UART register
uart.wo(utra::uart::RXTX, b'a');
assert_ne!(uart.rf(pac::uart::TXFULL_TXFULL), 1);
// Anomalies
// This compiles but requires a cast since `audio` is a pointer to
// u32, whereas `uart` is a pointer to u8.
audio.wfo(utra::uart::RXTX_RXTX, b'a' as _);
// This also compiles, despite the fact that the register offset is