Nouveau - Sep 2025 - [PATCH v2 3/4] nova-core: bitstruct: Add support for custom visiblity

On Thu Sep 4, 2025 at 6:54 AM JST, Joel Fernandes wrote:
> Add support for custom visiblity to allow for users to control visibility
> of the structure and helpers.
>
> Signed-off-by: Joel Fernandes <joelagnelf at nvidia.com>
> ---
>  drivers/gpu/nova-core/bitstruct.rs   | 46 ++++++++++++++--------------
>  drivers/gpu/nova-core/regs/macros.rs | 16 +++++-----
>  2 files changed, 31 insertions(+), 31 deletions(-)
>
> diff --git a/drivers/gpu/nova-core/bitstruct.rs
b/drivers/gpu/nova-core/bitstruct.rs
> index 068334c86981..1047c5c17e2d 100644
> --- a/drivers/gpu/nova-core/bitstruct.rs
> +++ b/drivers/gpu/nova-core/bitstruct.rs
> @@ -9,7 +9,7 @@
>  ///
>  /// ```rust
>  /// bitstruct! {
> -///     struct ControlReg: u32 {
> +///     pub struct ControlReg: u32 {
>  ///         3:0       mode        as u8 ?=> Mode;
>  ///         7:4       state       as u8 => State;
>  ///     }
Maybe mention in the documentation that the field accessors are given
the same visibility as the type - otherwise one might be led into
thinking that they can specify visibility for individual fields as well
(I'm wondering whether we might ever want that in the future?).
> @@ -34,21 +34,21 @@
>  ///   and returns the result. This is useful with fields for which not all
values are valid.
>  macro_rules! bitstruct {
>      // Main entry point - defines the bitfield struct with fields
> -    (struct $name:ident : $storage:ty $(, $comment:literal)? {
$($fields:tt)* }) => {
> -        bitstruct!(@core $name $storage $(, $comment)? { $($fields)* });
> +    ($vis:vis struct $name:ident : $storage:ty $(, $comment:literal)? {
$($fields:tt)* }) => {
> +        bitstruct!(@core $name $vis $storage $(, $comment)? { $($fields)*
});
>      };
>  
>      // All rules below are helpers.
>  
>      // Defines the wrapper `$name` type, as well as its relevant
implementations (`Debug`,
>      // `Default`, `BitOr`, and conversion to the value type) and field
accessor methods.
> -    (@core $name:ident $storage:ty $(, $comment:literal)? { $($fields:tt)*
}) => {
> +    (@core $name:ident $vis:vis $storage:ty $(, $comment:literal)? {
$($fields:tt)* }) => {
Being very nitpicky here, but for consistency why not put `$vis` before
`$name` since it is the order they are given by the caller?
>          $(
>          #[doc=$comment]
>          )?
>          #[repr(transparent)]
>          #[derive(Clone, Copy)]
> -        pub(crate) struct $name($storage);
> +        $vis struct $name($vis $storage);
`$storage` should probably be kept private - we already have accessors
for it, and the visibility parameter is for the outer type, not its
internals.

On Mon Sep 8, 2025 at 12:40 PM JST, Alexandre Courbot
wrote:
> On Thu Sep 4, 2025 at 6:54 AM JST, Joel Fernandes wrote:
>> Add support for custom visiblity to allow for users to control
visibility
>> of the structure and helpers.
>>
>> Signed-off-by: Joel Fernandes <joelagnelf at nvidia.com>
>> ---
>>  drivers/gpu/nova-core/bitstruct.rs   | 46 ++++++++++++++--------------
>>  drivers/gpu/nova-core/regs/macros.rs | 16 +++++-----
>>  2 files changed, 31 insertions(+), 31 deletions(-)
>>
>> diff --git a/drivers/gpu/nova-core/bitstruct.rs
b/drivers/gpu/nova-core/bitstruct.rs
>> index 068334c86981..1047c5c17e2d 100644
>> --- a/drivers/gpu/nova-core/bitstruct.rs
>> +++ b/drivers/gpu/nova-core/bitstruct.rs
>> @@ -9,7 +9,7 @@
>>  ///
>>  /// ```rust
>>  /// bitstruct! {
>> -///     struct ControlReg: u32 {
>> +///     pub struct ControlReg: u32 {
>>  ///         3:0       mode        as u8 ?=> Mode;
>>  ///         7:4       state       as u8 => State;
>>  ///     }
>
> Maybe mention in the documentation that the field accessors are given
> the same visibility as the type - otherwise one might be led into
> thinking that they can specify visibility for individual fields as well
> (I'm wondering whether we might ever want that in the future?).
Answering my own question: it could be useful! One example is
nova-core's `NV_PFALCON_FALCON_HWCFG2::mem_scrubbing` field. It turns
into `0` when scrubbing is completed, which is misleading. So to paliate
that we introduced a `mem_scrubbing_done` method that works as we want,
but the `mem_scrubbing` accessors are still present and can be called by
driver code. Making them private would force all callers to use
`mem_scrubbing_done`.

Another related feature would be a way to make some fields read-only or
write-only through an optional parameter.

I'm just mentioning these for the record; I'm not suggesting they need
to be done for the current series. :)