Crates.io | svd2utra |
lib.rs | svd2utra |
version | 0.1.22 |
source | src |
created_at | 2022-09-26 06:15:59.429381 |
updated_at | 2024-01-14 16:15:53.150167 |
description | SVD to UTRA library generator |
homepage | https://betrusted.io/xous-book/ |
repository | https://github.com/betrusted-io/xous-core/ |
max_upload_size | |
id | 673981 |
size | 315,234 |
UTRA is a register abstraction for accessing hardware resources. It tries to be:
Here is an example of an ambiguous style of register access, from a PAC generated using svd2rust:
// this seems clear -- as long as all the bit fields are specified
// (they actually aren't, so some non-obvious things are happening)
p.POWER.power.write(|w|
w.discharge().bit(true)
.soc_on().bit(false)
.kbddrive().bit(true)
.kbdscan().bits(3)
);
// what should this do?
// 1. just set the discharge bit to true and everything else to zero?
// 2. read the register first, change only the discharge bit to true, leaving the rest unchanged?
p.POWER.power.write(|w|
w.discharge().bit(true)
);
// answer: it does (1). You need to use the `modify()` function to have (2) happen.
While the closure-chaining is clever syntax, it's also ambiguous.
First, does the chaining imply an order of writes happening in
sequence, or do they all happen at once? The answer depends on Rust's
optimizer, which is very good and one can expect the behavior to be
the latter, but it is still write-ordering behavior that depends upon
the outcome of an optimizer and not a linguistic guarantee. Second,
the term write
itself is ambiguous when it comes to bitfields: do we
write just the bitfield, or do we write the entire register, assuming
the rest of the contents are zero? These types of ambiguity make it
hard to audit code, especially for experts in systems programming
who are not also experts in Rust.
The primary trade-off for achieving unambiguity and thinness is less type checking and type hardening, because we are not fully taking advantage of the advanced syntax features of Rust.
That being said, a certain degree of deliberate malleability in the register abstraction is desired to assist with security-oriented audits: for a security audit, it is often just as important to ask what the undefined bits do, as it is to check the settings of the defined bits. Malleabilty allows an auditor to quickly create targeted 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.
This crate is designed to serve as an alternative to svd2rust
. It generates
a crate which consists of:
soc.svd
fileThe 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 unchangedms(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.
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:
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
// mismatched and nonsensical
audio.wfo(utra::uart::TXFULL_TXFULL, 1);
}