> On 18 Jul 2025, at 04:26, Alexandre Courbot <[email protected]> wrote:
>
> Reword parts of the documentation that were a bit heavy to read, and
> harmonize/fix the examples.
>
> The relative registers section is about to be redesigned and its
> documentation rewritten, so do not touch this part.
>
> Signed-off-by: Alexandre Courbot <[email protected]>
> ---
> drivers/gpu/nova-core/regs/macros.rs | 24 +++++++++++++-----------
> 1 file changed, 13 insertions(+), 11 deletions(-)
>
> diff --git a/drivers/gpu/nova-core/regs/macros.rs
> b/drivers/gpu/nova-core/regs/macros.rs
> index
> d015a9f8a0b01afe1ff5093991845864aa81665e..dac02f8055e76da68e9a82133fa09a1e794252bc
> 100644
> --- a/drivers/gpu/nova-core/regs/macros.rs
> +++ b/drivers/gpu/nova-core/regs/macros.rs
> @@ -33,25 +33,25 @@
> /// let boot0 = BOOT_0::read(&bar);
> /// pr_info!("chip revision: {}.{}", boot0.major_revision(),
> boot0.minor_revision());
> ///
> -/// // `Chipset::try_from` will be called with the value of the field and
> returns an error if the
> -/// // value is invalid.
> +/// // `Chipset::try_from` is called with the value of the `chipset` field
> and returns an
> +/// // error if it is invalid.
> /// let chipset = boot0.chipset()?;
> ///
> /// // Update some fields and write the value back.
> /// boot0.set_major_revision(3).set_minor_revision(10).write(&bar);
> ///
> -/// // Or just read and update the register in a single step:
> +/// // Or, just read and update the register in a single step:
> /// BOOT_0::alter(&bar, |r| r.set_major_revision(3).set_minor_revision(10));
> /// ```
> ///
> -/// Fields can be defined as follows:
> +/// Fields are defined as follows:
> ///
> -/// - `as <type>` simply returns the field value casted as the requested
> integer type, typically
> -/// `u32`, `u16`, `u8` or `bool`. Note that `bool` fields must have a
> range of 1 bit.
> +/// - `as <type>` simply returns the field value casted to <type>, typically
> `u32`, `u16`, `u8` or
> +/// `bool`. Note that `bool` fields must have a range of 1 bit.
> /// - `as <type> => <into_type>` calls `<into_type>`'s `From::<<type>>`
> implementation and returns
> /// the result.
> /// - `as <type> ?=> <try_into_type>` calls `<try_into_type>`'s
> `TryFrom::<<type>>` implementation
> -/// and returns the result. This is useful on fields for which not all
> values are value.
> +/// and returns the result. This is useful with fields for which not all
> values are valid.
> ///
> /// The documentation strings are optional. If present, they will be added to
> the type's
> /// definition, or the field getter and setter methods they are attached to.
> @@ -76,15 +76,17 @@
> /// for cases where a register's interpretation depends on the context:
> ///
> /// ```no_run
> -/// register!(SCRATCH_0 @ 0x0000100, "Scratch register 0" {
> +/// register!(SCRATCH @ 0x00000200, "Scratch register" {
> /// 31:0 value as u32, "Raw value";
> +/// });
> ///
> -/// register!(SCRATCH_0_BOOT_STATUS => SCRATCH_0, "Boot status of the
> firmware" {
> +/// register!(SCRATCH_BOOT_STATUS => SCRATCH, "Boot status of the firmware" {
> /// 0:0 completed as bool, "Whether the firmware has completed
> booting";
> +/// });
> /// ```
> ///
> -/// In this example, `SCRATCH_0_BOOT_STATUS` uses the same I/O address as
> `SCRATCH_0`, while also
> -/// providing its own `completed` method.
> +/// In this example, `SCRATCH_0_BOOT_STATUS` uses the same I/O address as
> `SCRATCH`, while also
> +/// providing its own `completed` field.
> macro_rules! register {
> // Creates a register at a fixed offset of the MMIO space.
> (
>
> --
> 2.50.1
>
Reviewed-by: Daniel Almeida <[email protected]>
