Skip to contentSkip to conversation

rust: add macros to define registers layout

RFC PATCH New Alexandre Courbot 1 participant 1 message Mar 20, 2025

Subsystems (2)
lore
Share & tools
lore

Alexandre Courbot

author reviewer
#0 lore raw

RFC PATCH v2 1/1 rust: add macros to define registers layout

Add two macros, register!() and register_rel!(), that define a given register's layout and provide accessors for absolute or relative offsets, respectively.

The following example (taken from the rustdoc) helps understanding how they are used:

    register!(Boot0@0x00000100, "Basic revision information about the chip";
        3:0     minor_rev => as u8, "minor revision of the chip";
        7:4     major_rev => as u8, "major revision of the chip";
        28:20   chipset => try_into Chipset, "chipset model"
    );

This defines a Boot0 type which can be read or written from offset 0x100 of an Io region. It is composed of 3 fields, for instance minor_rev is made of the 4 less significant bits of the register. Each field can be accessed and modified using helper methods:

    // Read from offset `0x100`.
    let boot0 = Boot0::read(&bar);
    pr_info!("chip revision: {}.{}", boot0.major_rev(), boot0.minor_rev());

    // `Chipset::try_from` will be called with the value of the field and
    // returns an error if the value is invalid.
    let chipset = boot0.chipset()?;

    // Update some fields and write the value back.
    boot0.set_major_rev(3).set_minor_rev(10).write(&bar);

    // Or just update the register value in a single step:
    Boot0::alter(&bar, |r| r.set_major_rev(3).set_minor_rev(10));

Fields are made accessible using one of the following strategies:

- as <type> simply casts the field value to the requested type.
- as_bit <type> turns the field into a boolean and calls <type>::from()` with the obtained value. To be used with single-bit fields.
- into <type> calls <type>::from() on the value of the field. It is expected to handle all the possible values for the bit range selected.
- try_into <type> calls <type>::try_from() on the value of the field and returns its result.

The documentation strings are optional. If present, they will be added to the type or the field getter and setter methods they are attached to.

---
I have written these initially for the nova-core driver, then it has been suggested that they might be useful outside of it as well, so here goes.

I have considered as suggested to turn these into a single procedural macro, but could not even get even the basics to parse properly yet - procedural macros are not easy to begin with, but kernel procedural macros are also different from user-space ones, making it all the more difficult. I will keep looking into it but wanted to post a new revision meanwhile, since it is used by my next nova-core series revision.

The following things needs to be improved before we can remove the [RFC] flag:

- Inner types other than u32 need to be supported - this can probably just be an extra parameter of the macro.
- The syntax can certainly be improved. I've tried to some with something that makes the register layout obvious, while fitting within the expectations of the Rust macro parser, but my lack of experience certainly shows here.
- We probably need an option to make some fields or whole registers read-only.
- The I/O offset and read/write methods should be optional, so the layout part can be used for things that are not registers.
- The visibility of the helper macros is a bit of a headache - I haven't found a way to completely hide them to the outside, so I have prefixed them with __ for now. Using a procedural macro should help with that too.

Dependencies:

- [1] https://lore.kernel.org/rust-for-linux/20250318-topic-panthor-rs-genmask-v4-1-35004fca6ac5@collabora.com/
- [2] https://lore.kernel.org/rust-for-linux/[email protected]/
---
Changes in v2:
- Moved to the io module.
- Rename the macros to "register!()" and "register_rel!()".
- Properly clear field in setter methods.
- Use the genmask macros from [1].
- Add "alter" and "try_alter" methods to modify a register's content
using a closure.
- Link to v1: https://lore.kernel.org/r/[email protected]

---
 rust/kernel/io.rs          |   2 +
 rust/kernel/io/register.rs | 305 +++++++++++++++++++++++++++++++++++++++++++++
 rust/kernel/reg.rs         |   2 +
 3 files changed, 309 insertions(+)
rust/kernel/io.rs +2 -0
index d4a73e52e3ee68f7b558749ed0108acde92ae5fe..acecbf196be1751c9de7bc50dc47b213f9ba2362 100644
@@ -7,6 +7,8 @@
 use crate::error::{code::EINVAL, Result};
 use crate::{bindings, build_assert};
 
+mod register;
+
 /// Raw representation of an MMIO region.
 ///
 /// By itself, the existence of an instance of this structure does not provide any guarantees that
rust/kernel/io/register.rs new file +305 -0

305 lines not on this page · raw message

rust/kernel/reg.rs new file +2 -0
new file mode 100644
index 0000000000000000000000000000000000000000..139597f9cb07c5d48bed18984ec4747f4b4f3438
@@ -0,0 +1,2 @@
+
+

---
base-commit: 1d53763dc16c9fc9329a4cdc14d691979d47568f
change-id: 20250313-registers-7fdcb3d926b0
prerequisite-change-id: 20241023-topic-panthor-rs-genmask-fabc573fef43:v4
prerequisite-patch-id: 182945904fd914573eed9388a559ce8a642310ef
prerequisite-message-id: <[email protected]>
prerequisite-patch-id: de15c0d16727e6af2d79f88f5b67be4c06212552
prerequisite-patch-id: f8bca95d983222da29508cc6e6886e4b0f992588
prerequisite-patch-id: 1ae8f68250fb43808342285a284bcf7b572263fe
prerequisite-patch-id: fa5ce1308e1dbc71374a381537ab3978babe20a0
prerequisite-patch-id: 7225e000f745bb5fd45fc43393d801d1d9adb767

Best regards,

Signature · 1 line
Alexandre Courbot <[email protected]>