Introduce bitfield and move register macro to rust/kernel/
Subsystems (5)
v3 cover Introduce bitfield and move register macro to rust/kernel/
These patches extract and enhance the bitfield support in the register macro in nova to define Rust structures with bitfields. This is extremely useful as it allows clean Rust structure definitions without requiring explicit masks and shifts.
See [1] example code using it.
v2 of the patches is at:
https://lore.kernel.org/all/[email protected]/
v1 of the patches is at:
https://lore.kernel.org/all/[email protected]/
v2->v3:
* Renamed bitstruct to bitfield.
* Various suggestions to improve code (Alex, Yury, Miguel).
* Added reviewed-by tags from Elle Rhumsaa.
* Added KUNIT tests including tests for overlap.
* Added F: maintainers file entry for new files under BITOPS.
v1->v2:
* Use build_assert in bitstruct
* Split move and enhance patches for easier review
* Move out of Nova into kernel crate for other drivers like Tyr which will use.
* Miscellaneous cosmetic improvements.
Joel Fernandes (5):
nova-core: bitfield: Move bitfield-specific code from register! into
new macro
nova-core: bitfield: Add support for different storage widths
nova-core: bitfield: Add support for custom visiblity
rust: Move register and bitfield macros out of Nova
rust: Add KUNIT tests for bitfield
MAINTAINERS | 1 + drivers/gpu/nova-core/falcon.rs | 2 +- drivers/gpu/nova-core/falcon/gsp.rs | 3 +- drivers/gpu/nova-core/falcon/sec2.rs | 2 +- drivers/gpu/nova-core/regs.rs | 6 +- rust/kernel/bits.rs | 2 + rust/kernel/bits/bitfield.rs | 661 ++++++++++++++++++ rust/kernel/io.rs | 1 + .../macros.rs => rust/kernel/io/register.rs | 289 +------- 9 files changed, 698 insertions(+), 269 deletions(-) create mode 100644 rust/kernel/bits/bitfield.rs rename drivers/gpu/nova-core/regs/macros.rs => rust/kernel/io/register.rs (73%)
Signature · 1 line
2.34.1
PATCH v3 1/5 nova-core: bitfield: Move bitfield-specific code from register! into new macro
The bitfield-specific into new macro. This will be used to define structs with bitfields, similar to C language.
--- drivers/gpu/nova-core/bitfield.rs | 314 +++++++++++++++++++++++++++ drivers/gpu/nova-core/nova_core.rs | 3 + drivers/gpu/nova-core/regs/macros.rs | 259 +--------------------- 3 files changed, 327 insertions(+), 249 deletions(-) create mode 100644 drivers/gpu/nova-core/bitfield.rs
drivers/gpu/nova-core/bitfield.rs new file +314 -0
@@ -0,0 +1,314 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Bitfield library for Rust structures +//! +//! Support for defining bitfields in Rust structures. Also used by the [`register!`] macro. +//! +//! # Syntax +//! +//! ```rust +//! #[derive(Debug, Clone, Copy)] +//! enum Mode { +//! Low = 0, +//! High = 1, +//! Auto = 2, +//! } +//! +//! impl TryFrom<u8> for Mode { +//! type Error = u8; +//! fn try_from(value: u8) -> Result<Self, Self::Error> { +//! match value { +//! 0 => Ok(Mode::Low), +//! 1 => Ok(Mode::High), +//! 2 => Ok(Mode::Auto), +//! _ => Err(value), +//! } +//! } +//! } +//! +//! impl From<Mode> for u32 { +//! fn from(mode: Mode) -> u32 { +//! mode as u32 +//! } +//! } +//! +//! #[derive(Debug, Clone, Copy)] +//! enum State { +//! Inactive = 0, +//! Active = 1, +//! } +//! +//! impl From<bool> for State { +//! fn from(value: bool) -> Self { +//! if value { State::Active } else { State::Inactive } +//! } +//! } +//! +//! impl From<State> for u32 { +//! fn from(state: State) -> u32 { +//! state as u32 +//! } +//! } +//! +//! bitfield! { +//! struct ControlReg { +//! 3:0 mode as u8 ?=> Mode; +//! 7 state as bool => State; +//! } +//! } +//! ``` +//! +//! This generates a struct with: +//! - Field accessors: `mode()`, `state()`, etc. +//! - Field setters: `set_mode()`, `set_state()`, etc. (supports chaining with builder pattern). +//! - Debug and Default implementations +//! +//! The field setters can be used with the builder pattern, example: +//! ControlReg::default().set_mode(mode).set_state(state); +//! +//! Fields are defined as follows: +//! +//! - `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 with fields for which not all values are valid. +//! +macro_rules! bitfield { +// Main entry point - defines the bitfield struct with fields + (struct $name:ident $(, $comment:literal)? { $($fields:tt)* }) => { +bitfield! (@core $name $(, $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 $(, $comment:literal)? { $($fields:tt)* }) => { + $( +#[doc=$comment] + )? +#[repr(transparent)] +#[derive( Clone , Copy )] +pub (crate )struct $name(u32 ); + +impl ::core::ops::BitOr for $name { +type Output =Self ; + +fn bitor (self, rhs:Self ) ->Self ::Output { +Self (self.0 | rhs.0 ) + } + } + +impl ::core::convert::From <$name>for u32 { +fn from (val: $name) ->u32 { + val.0 + } + } + +bitfield! (@fields_dispatcher $name { $($fields)* }); + }; + +// Captures the fields and passes them to all the implementers that require field information. +// +// Used to simplify the matching rules for implementers, so they don't need to match the entire +// complex fields rule even though they only make use of part of it. + (@fields_dispatcher $name:ident { + $($hi:tt:$lo:tt $field:identas $type:tt + $(?=> $try_into_type:ty)? + $(=> $into_type:ty)? + $(, $comment:literal)? + ; + )* + } + ) => { +bitfield! (@field_accessors $name { + $( + $hi:$lo $fieldas $type + $(?=> $try_into_type)? + $(=> $into_type)? + $(, $comment)? + ; + )* + }); +bitfield! (@debug $name { $($field;)* }); +bitfield! (@default $name { $($field;)* }); + }; + +// Defines all the field getter/setter methods for `$name`. + ( + @field_accessors $name:ident { + $($hi:tt:$lo:tt $field:identas $type:tt + $(?=> $try_into_type:ty)? + $(=> $into_type:ty)? + $(, $comment:literal)? + ; + )* + } + ) => { + $( +bitfield! (@check_field_bounds $hi:$lo $fieldas $type ); + )* + +#[allow(dead_code)] +impl $name { + $( +bitfield! (@field_accessor $name $hi:$lo $fieldas $type + $(?=> $try_into_type)? + $(=> $into_type)? + $(, $comment)? + ; + ); + )* + } + }; + +// Boolean fields must have `$hi == $lo`. + (@check_field_bounds $hi:tt:$lo:tt $field:identas bool ) => { +#[allow(clippy::eq_op)] +const _: () = { + ::kernel::build_assert!( + $hi == $lo, +concat! ("boolean field `" ,stringify! ($field),"` covers more than one bit" ) + ); + }; + }; + +// Non-boolean fields must have `$hi >= $lo`. + (@check_field_bounds $hi:tt:$lo:tt $field:identas $type:tt) => { +#[allow(clippy::eq_op)] +const _: () = { + ::kernel::build_assert!( + $hi >= $lo, +concat! ("field `" ,stringify! ($field),"`'s MSB is smaller than its LSB" ) + ); + }; + }; + +// Catches fields defined as `bool` and convert them into a boolean value. + ( + @field_accessor $name:ident $hi:tt:$lo:tt $field:identas bool => $into_type:ty + $(, $comment:literal)?; + ) => { +bitfield! ( + @leaf_accessor $name $hi:$lo $field + { |f| <$into_type>::from (if f !=0 {true }else {false }) } + $into_type => $into_type $(, $comment)?; + ); + }; + +// Shortcut for fields defined as `bool` without the `=>` syntax. + ( + @field_accessor $name:ident $hi:tt:$lo:tt $field:identas bool $(, $comment:literal)?; + ) => { +bitfield! (@field_accessor $name $hi:$lo $fieldas bool =>bool $(, $comment)?;); + }; + +// Catches the `?=>` syntax for non-boolean fields. + ( + @field_accessor $name:ident $hi:tt:$lo:tt $field:identas $type:tt ?=> $try_into_type:ty + $(, $comment:literal)?; + ) => { +bitfield! (@leaf_accessor $name $hi:$lo $field + { |f| <$try_into_type>::try_from (fas $type ) } $try_into_type => + ::core::result::Result < + $try_into_type, + <$try_into_typeas ::core::convert::TryFrom <$type >>::Error + > + $(, $comment)?;); + }; + +// Catches the `=>` syntax for non-boolean fields. + ( + @field_accessor $name:ident $hi:tt:$lo:tt $field:identas $type:tt => $into_type:ty + $(, $comment:literal)?; + ) => { +bitfield! (@leaf_accessor $name $hi:$lo $field + { |f| <$into_type>::from (fas $type ) } $into_type => $into_type $(, $comment)?;); + }; + +// Shortcut for non-boolean fields defined without the `=>` or `?=>` syntax. + ( + @field_accessor $name:ident $hi:tt:$lo:tt $field:identas $type:tt + $(, $comment:literal)?; + ) => { +bitfield! (@field_accessor $name $hi:$lo $fieldas $type => $type $(, $comment)?;); + }; + +// Generates the accessor methods for a single field. + ( + @leaf_accessor $name:ident $hi:tt:$lo:tt $field:ident + { $process:expr } $to_type:ty => $res_type:ty $(, $comment:literal)?; + ) => { + ::kernel::macros::paste!( +const [<$field:upper_RANGE >]: ::core::ops::RangeInclusive <u8 > = $lo..=$hi; +const [<$field:upper _MASK>]:u32 = ((((1 << $hi) -1 ) <<1 ) +1 ) - ((1 << $lo) -1 ); +const [<$field:upper_SHIFT >]:u32 =Self ::[<$field:upper _MASK>].trailing_zeros (); + ); + + $( +#[doc= "Returns the value of this field:" ] +#[doc=$comment] + )? +#[inline(always)] +pub (crate )fn $field(self) -> $res_type { + ::kernel::macros::paste!( +const MASK :u32 = $name::[<$field:upper _MASK>]; +const SHIFT :u32 = $name::[<$field:upper_SHIFT >]; + ); +let field = ((self.0 &MASK ) >>SHIFT ); + + $process(field) + } + + ::kernel::macros::paste!( + $( +#[doc= "Sets the value of this field:" ] +#[doc=$comment] + )? +#[inline(always)] +pub (crate )fn [<set_ $field>](mut self, value: $to_type) ->Self { +const MASK :u32 = $name::[<$field:upper _MASK>]; +const SHIFT :u32 = $name::[<$field:upper_SHIFT >]; +let value = (u32 ::from (value) <<SHIFT ) &MASK ; + self.0 = (self.0 & !MASK ) | value; + + self + } + ); + }; + +// Generates the `Debug` implementation for `$name`. + (@debug $name:ident { $($field:ident;)* }) => { +impl ::core::fmt::Debug for $name { +fn fmt (&self, f: &mut ::core::fmt::Formatter <'_>) -> ::core::fmt::Result { + f.debug_struct (stringify! ($name)) + .field ("<raw>" , &format_args! ("{:#x}" , &self.0 )) + $( + .field (stringify! ($field), &self.$field()) + )* + .finish () + } + } + }; + +// Generates the `Default` implementation for `$name`. + (@default $name:ident { $($field:ident;)* }) => { +/// Returns a value for the bitfield where all fields are set to their default value. +impl ::core::default ::Default for $name { +fn default () ->Self { +#[allow(unused_mut)] +let mut value =Self (Default ::default ()); + + ::kernel::macros::paste!( + $( + value.[<set_ $field>](Default ::default ()); + )* + ); + + value + } + } + }; +}
drivers/gpu/nova-core/nova_core.rs +3 -0
@@ -2,6 +2,9 @@//! Nova Core GPU Driver +#[macro_use] +mod bitfield; +mod dma;mod driver;mod falcon;
drivers/gpu/nova-core/regs/macros.rs +10 -249
319 lines not on this page · raw message
Signature · 1 line
2.34.1
PATCH v3 2/5 nova-core: bitfield: Add support for different storage widths
In reply to Joel FernandesPreviously, bitfields were hardcoded to use u32 as the underlying storage type. Add support for different storage types (u8, u16, u32, u64) to the bitfield macro.
New syntax is: struct Name: <type ex., u32> { ... }
--- drivers/gpu/nova-core/bitfield.rs | 69 +++++++++++++++++----------- drivers/gpu/nova-core/regs/macros.rs | 16 +++---- 2 files changed, 50 insertions(+), 35 deletions(-)
drivers/gpu/nova-core/bitfield.rs +42 -27
@@ -51,7 +51,7 @@//! } //! //! bitfield! { -//! struct ControlReg { +//! struct ControlReg: u32 { //! 3:0 mode as u8 ?=> Mode; //! 7 state as bool => State; //! }
@@ -77,21 +77,21 @@//! macro_rules! bitfield {// Main entry point - defines the bitfield struct with fields - (struct $name:ident $(, $comment:literal)? { $($fields:tt)* }) => { -bitfield! (@core $name $(, $comment)? { $($fields)* }); + (struct $name:ident : $storage:ty $(, $comment:literal)? { $($fields:tt)* }) => { +bitfield! (@core $name $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 $(, $comment:literal)? { $($fields:tt)* }) => { + (@core $name:ident $storage:ty $(, $comment:literal)? { $($fields:tt)* }) => { $(#[doc=$comment] )?#[repr(transparent)] #[derive( Clone , Copy )] -pub (crate )struct $name(u32 ); +pub (crate )struct $name($storage);impl ::core::ops::BitOr for $name {type Output =Self ;
@@ -101,20 +101,26 @@ fn bitor(self, rhs: Self) -> Self::Output { } } -impl ::core::convert::From <$name>for u32 { -fn from (val: $name) ->u32 { +impl ::core::convert::From <$name>for $storage { +fn from (val: $name) -> $storage { val.0 } } -bitfield! (@fields_dispatcher $name { $($fields)* }); +impl ::core::convert::From <$storage>for $name { +fn from (val: $storage) ->Self { +Self (val) + } + } + +bitfield! (@fields_dispatcher $name $storage { $($fields)* }); };// Captures the fields and passes them to all the implementers that require field information. // // Used to simplify the matching rules for implementers, so they don't need to match the entire // complex fields rule even though they only make use of part of it. - (@fields_dispatcher $name:ident { + (@fields_dispatcher $name:ident $storage:ty { $($hi:tt:$lo:tt $field:ident as $type:tt $(?=> $try_into_type:ty)? $(=> $into_type:ty)?
@@ -123,7 +129,7 @@ fn from(val: $name) -> u32 { )* } ) => { - bitfield!(@field_accessors $name { + bitfield!(@field_accessors $name $storage { $( $hi:$lo $field as $type $(?=> $try_into_type)?
@@ -138,7 +144,7 @@ fn from(val: $name) -> u32 {// Defines all the field getter/setter methods for `$name`. ( - @field_accessors $name:ident { + @field_accessors $name:ident $storage:ty { $($hi:tt:$lo:tt $field:ident as $type:tt $(?=> $try_into_type:ty)? $(=> $into_type:ty)?
@@ -154,7 +160,7 @@ fn from(val: $name) -> u32 {#[allow(dead_code)] impl $name { $( -bitfield! (@field_accessor $name $hi:$lo $fieldas $type +bitfield! (@field_accessor $name $storage, $hi:$lo $fieldas $type $(?=> $try_into_type)? $(=> $into_type)? $(, $comment)?
@@ -188,11 +194,11 @@ impl $name {// Catches fields defined as `bool` and convert them into a boolean value. ( - @field_accessor $name:ident $hi:tt:$lo:tt $field:ident as bool => $into_type:ty + @field_accessor $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as bool => $into_type:ty $(, $comment:literal)?; ) => {bitfield! ( - @leaf_accessor $name $hi:$lo $field + @leaf_accessor $name $storage, $hi:$lo $field { |f| <$into_type>::from (if f !=0 {true }else {false }) } $into_type => $into_type $(, $comment)?; );
@@ -200,17 +206,17 @@ impl $name {// Shortcut for fields defined as `bool` without the `=>` syntax. ( - @field_accessor $name:ident $hi:tt:$lo:tt $field:ident as bool $(, $comment:literal)?; + @field_accessor $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as bool $(, $comment:literal)?; ) => { -bitfield! (@field_accessor $name $hi:$lo $fieldas bool =>bool $(, $comment)?;); +bitfield! (@field_accessor $name $storage, $hi:$lo $fieldas bool =>bool $(, $comment)?;); };// Catches the `?=>` syntax for non-boolean fields. ( - @field_accessor $name:ident $hi:tt:$lo:tt $field:ident as $type:tt ?=> $try_into_type:ty + @field_accessor $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as $type:tt ?=> $try_into_type:ty $(, $comment:literal)?; ) => { -bitfield! (@leaf_accessor $name $hi:$lo $field +bitfield! (@leaf_accessor $name $storage, $hi:$lo $field { |f| <$try_into_type>::try_from (fas $type ) } $try_into_type => ::core::result::Result < $try_into_type,
@@ -221,29 +227,38 @@ impl $name {// Catches the `=>` syntax for non-boolean fields. ( - @field_accessor $name:ident $hi:tt:$lo:tt $field:ident as $type:tt => $into_type:ty + @field_accessor $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as $type:tt => $into_type:ty $(, $comment:literal)?; ) => { -bitfield! (@leaf_accessor $name $hi:$lo $field +bitfield! (@leaf_accessor $name $storage, $hi:$lo $field { |f| <$into_type>::from (fas $type ) } $into_type => $into_type $(, $comment)?;); };// Shortcut for non-boolean fields defined without the `=>` or `?=>` syntax. ( - @field_accessor $name:ident $hi:tt:$lo:tt $field:ident as $type:tt + @field_accessor $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as $type:tt $(, $comment:literal)?; ) => { -bitfield! (@field_accessor $name $hi:$lo $fieldas $type => $type $(, $comment)?;); +bitfield! (@field_accessor $name $storage, $hi:$lo $fieldas $type => $type $(, $comment)?;); };// Generates the accessor methods for a single field. ( - @leaf_accessor $name:ident $hi:tt:$lo:tt $field:ident + @leaf_accessor $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident { $process:expr } $to_type:ty => $res_type:ty $(, $comment:literal)?; ) => { ::kernel::macros::paste!(const [<$field:upper_RANGE >]: ::core::ops::RangeInclusive <u8 > = $lo..=$hi; -const [<$field:upper _MASK>]:u32 = ((((1 << $hi) -1 ) <<1 ) +1 ) - ((1 << $lo) -1 ); +const [<$field:upper _MASK>]: $storage = { +// Generate mask for shifting +match ::core::mem::size_of ::<$storage>() { +1 => ::kernel::bits::genmask_u8 ($lo..=$hi)as $storage, +2 => ::kernel::bits::genmask_u16 ($lo..=$hi)as $storage, +4 => ::kernel::bits::genmask_u32 ($lo..=$hi)as $storage, +8 => ::kernel::bits::genmask_u64 ($lo..=$hi)as $storage, + _ => ::kernel::build_error!("Unsupported storage type size" ) + } + };const [<$field:upper_SHIFT >]:u32 =Self ::[<$field:upper _MASK>].trailing_zeros (); );
@@ -254,7 +269,7 @@ impl $name {#[inline(always)] pub (crate )fn $field(self) -> $res_type { ::kernel::macros::paste!( -const MASK :u32 = $name::[<$field:upper _MASK>]; +const MASK : $storage = $name::[<$field:upper _MASK>];const SHIFT :u32 = $name::[<$field:upper_SHIFT >]; );let field = ((self.0 &MASK ) >>SHIFT );
@@ -269,9 +284,9 @@ pub(crate) fn $field(self) -> $res_type { )?#[inline(always)] pub(crate) fn [<set_ $field>](mut self, value: $to_type) -> Self { - const MASK: u32 = $name::[<$field:upper _MASK>]; + const MASK: $storage = $name::[<$field:upper _MASK>]; const SHIFT: u32 = $name::[<$field:upper _SHIFT>]; -let value = (u32::from (value) <<SHIFT ) &MASK ; +let value = (<$storage>::from (value) <<SHIFT ) &MASK ; self.0 = (self.0 & !MASK ) | value; self
drivers/gpu/nova-core/regs/macros.rs +8 -8
@@ -276,25 +276,25 @@ pub(crate) trait RegisterBase<T> {macro_rules! register {// Creates a register at a fixed offset of the MMIO space. ($name:ident @ $offset:literal $(, $comment:literal)? { $($fields:tt)* } ) => { - bitfield!(struct $name $(, $comment)? { $($fields)* } ); + bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } );register! (@io_fixed $name @ $offset); };// Creates an alias register of fixed offset register `alias` with its own fields. ($name:ident => $alias:ident $(, $comment:literal)? { $($fields:tt)* } ) => { - bitfield!(struct $name $(, $comment)? { $($fields)* } ); + bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } );register! (@io_fixed $name @ $alias::OFFSET ); };// Creates a register at a relative offset from a base address provider. ($name:ident @ $base:ty [ $offset:literal ] $(, $comment:literal)? { $($fields:tt)* } ) => { - bitfield!(struct $name $(, $comment)? { $($fields)* } ); + bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } );register! (@io_relative $name @ $base [ $offset ]); };// Creates an alias register of relative offset register `alias` with its own fields. ($name:ident => $base:ty [ $alias:ident ] $(, $comment:literal)? { $($fields:tt)* }) => { - bitfield!(struct $name $(, $comment)? { $($fields)* } ); + bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } );register! (@io_relative $name @ $base [ $alias::OFFSET ]); };
@@ -305,7 +305,7 @@ macro_rules! register { } ) => {static_assert! (::core::mem::size_of ::<u32 >() <= $stride); - bitfield!(struct $name $(, $comment)? { $($fields)* } ); + bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } );register! (@io_array $name @ $offset [ $size ; $stride ]); };
@@ -326,7 +326,7 @@ macro_rules! register { $(, $comment:literal)? { $($fields:tt)* } ) => {static_assert! (::core::mem::size_of ::<u32 >() <= $stride); - bitfield!(struct $name $(, $comment)? { $($fields)* } ); + bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } );register! (@io_relative_array $name @ $base [ $offset [ $size ; $stride ] ]); };
@@ -348,7 +348,7 @@ macro_rules! register { } ) => {static_assert! ($idx < $alias::SIZE ); - bitfield!(struct $name $(, $comment)? { $($fields)* } ); + bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } );register! (@io_relative $name @ $base [ $alias::OFFSET + $idx * $alias::STRIDE ] ); };
@@ -357,7 +357,7 @@ macro_rules! register {// to avoid it being interpreted in place of the relative register array alias rule. ($name:ident => $alias:ident [ $idx:expr ] $(, $comment:literal)? { $($fields:tt)* }) => {static_assert! ($idx < $alias::SIZE ); - bitfield!(struct $name $(, $comment)? { $($fields)* } ); + bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } );register! (@io_fixed $name @ $alias::OFFSET + $idx * $alias::STRIDE ); };
Signature · 1 line
2.34.1
PATCH v3 3/5 nova-core: bitfield: Add support for custom visiblity
In reply to Joel FernandesAdd support for custom visiblity to allow for users to control visibility of the structure and helpers.
--- drivers/gpu/nova-core/bitfield.rs | 55 ++++++++++++++++------------ drivers/gpu/nova-core/regs/macros.rs | 16 ++++---- 2 files changed, 40 insertions(+), 31 deletions(-)
drivers/gpu/nova-core/bitfield.rs +32 -23
@@ -51,7 +51,7 @@//! } //! //! bitfield! { -//! struct ControlReg: u32 { +//! pub struct ControlReg: u32 { //! 3:0 mode as u8 ?=> Mode; //! 7 state as bool => State; //! }
@@ -63,6 +63,9 @@//! - Field setters: `set_mode()`, `set_state()`, etc. (supports chaining with builder pattern). //! - Debug and Default implementations //! +//! Note: Field accessors and setters inherit the same visibility as the struct itself. +//! In the example above, both `mode()` and `set_mode()` methods will be `pub`. +//! //! The field setters can be used with the builder pattern, example: //! ControlReg::default().set_mode(mode).set_state(state); //!
@@ -77,21 +80,21 @@//! macro_rules! bitfield {// Main entry point - defines the bitfield struct with fields - (struct $name:ident : $storage:ty $(, $comment:literal)? { $($fields:tt)* }) => { -bitfield! (@core $name $storage $(, $comment)? { $($fields)* }); + ($vis:visstruct $name:ident : $storage:ty $(, $comment:literal)? { $($fields:tt)* }) => { +bitfield! (@core $vis $name $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 $vis:vis $name:ident $storage:ty $(, $comment:literal)? { $($fields:tt)* }) => { $(#[doc=$comment] )?#[repr(transparent)] #[derive( Clone , Copy )] -pub (crate )struct $name($storage); + $visstruct $name($storage);impl ::core::ops::BitOr for $name {type Output =Self ;
@@ -113,14 +116,14 @@ fn from(val: $storage) -> Self { } } -bitfield! (@fields_dispatcher $name $storage { $($fields)* }); +bitfield! (@fields_dispatcher $vis $name $storage { $($fields)* }); };// Captures the fields and passes them to all the implementers that require field information. // // Used to simplify the matching rules for implementers, so they don't need to match the entire // complex fields rule even though they only make use of part of it. - (@fields_dispatcher $name:ident $storage:ty { + (@fields_dispatcher $vis:vis $name:ident $storage:ty { $($hi:tt:$lo:tt $field:ident as $type:tt $(?=> $try_into_type:ty)? $(=> $into_type:ty)?
@@ -129,7 +132,7 @@ fn from(val: $storage) -> Self { )* } ) => { - bitfield!(@field_accessors $name $storage { + bitfield!(@field_accessors $vis $name $storage { $( $hi:$lo $field as $type $(?=> $try_into_type)?
@@ -144,7 +147,7 @@ fn from(val: $storage) -> Self {// Defines all the field getter/setter methods for `$name`. ( - @field_accessors $name:ident $storage:ty { + @field_accessors $vis:vis $name:ident $storage:ty { $($hi:tt:$lo:tt $field:ident as $type:tt $(?=> $try_into_type:ty)? $(=> $into_type:ty)?
@@ -159,8 +162,14 @@ fn from(val: $storage) -> Self {#[allow(dead_code)] impl $name { +/// Returns the raw underlying value +#[inline(always)] + $vis fn raw(&self) -> $storage { + self.0 + } + $( -bitfield! (@field_accessor $name $storage, $hi:$lo $fieldas $type +bitfield! (@field_accessor $vis $name $storage, $hi:$lo $fieldas $type $(?=> $try_into_type)? $(=> $into_type)? $(, $comment)?
@@ -194,11 +203,11 @@ impl $name {// Catches fields defined as `bool` and convert them into a boolean value. ( - @field_accessor $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as bool => $into_type:ty + @field_accessor $vis:vis $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as bool => $into_type:ty $(, $comment:literal)?; ) => {bitfield! ( - @leaf_accessor $name $storage, $hi:$lo $field + @leaf_accessor $vis $name $storage, $hi:$lo $field { |f| <$into_type>::from (if f !=0 {true }else {false }) } $into_type => $into_type $(, $comment)?; );
@@ -206,17 +215,17 @@ impl $name {// Shortcut for fields defined as `bool` without the `=>` syntax. ( - @field_accessor $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as bool $(, $comment:literal)?; + @field_accessor $vis:vis $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as bool $(, $comment:literal)?; ) => { -bitfield! (@field_accessor $name $storage, $hi:$lo $fieldas bool =>bool $(, $comment)?;); +bitfield! (@field_accessor $vis $name $storage, $hi:$lo $fieldas bool =>bool $(, $comment)?;); };// Catches the `?=>` syntax for non-boolean fields. ( - @field_accessor $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as $type:tt ?=> $try_into_type:ty + @field_accessor $vis:vis $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as $type:tt ?=> $try_into_type:ty $(, $comment:literal)?; ) => { -bitfield! (@leaf_accessor $name $storage, $hi:$lo $field +bitfield! (@leaf_accessor $vis $name $storage, $hi:$lo $field { |f| <$try_into_type>::try_from (fas $type ) } $try_into_type => ::core::result::Result < $try_into_type,
@@ -227,24 +236,24 @@ impl $name {// Catches the `=>` syntax for non-boolean fields. ( - @field_accessor $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as $type:tt => $into_type:ty + @field_accessor $vis:vis $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as $type:tt => $into_type:ty $(, $comment:literal)?; ) => { -bitfield! (@leaf_accessor $name $storage, $hi:$lo $field +bitfield! (@leaf_accessor $vis $name $storage, $hi:$lo $field { |f| <$into_type>::from (fas $type ) } $into_type => $into_type $(, $comment)?;); };// Shortcut for non-boolean fields defined without the `=>` or `?=>` syntax. ( - @field_accessor $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as $type:tt + @field_accessor $vis:vis $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as $type:tt $(, $comment:literal)?; ) => { -bitfield! (@field_accessor $name $storage, $hi:$lo $fieldas $type => $type $(, $comment)?;); +bitfield! (@field_accessor $vis $name $storage, $hi:$lo $fieldas $type => $type $(, $comment)?;); };// Generates the accessor methods for a single field. ( - @leaf_accessor $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident + @leaf_accessor $vis:vis $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident { $process:expr } $to_type:ty => $res_type:ty $(, $comment:literal)?; ) => { ::kernel::macros::paste!(
@@ -267,7 +276,7 @@ impl $name {#[doc=$comment] )?#[inline(always)] -pub (crate )fn $field(self) -> $res_type { + $vis fn $field(self) -> $res_type { ::kernel::macros::paste!(const MASK : $storage = $name::[<$field:upper _MASK>];const SHIFT :u32 = $name::[<$field:upper_SHIFT >];
@@ -283,7 +292,7 @@ pub(crate) fn $field(self) -> $res_type {#[doc=$comment] )?#[inline(always)] - pub(crate) fn [<set_ $field>](mut self, value: $to_type) -> Self { + $vis fn [<set_ $field>](mut self, value: $to_type) -> Self { const MASK: $storage = $name::[<$field:upper _MASK>]; const SHIFT: u32 = $name::[<$field:upper _SHIFT>]; let value = (<$storage>::from(value) << SHIFT) & MASK;
drivers/gpu/nova-core/regs/macros.rs +8 -8
@@ -276,25 +276,25 @@ pub(crate) trait RegisterBase<T> {macro_rules! register {// Creates a register at a fixed offset of the MMIO space. ($name:ident @ $offset:literal $(, $comment:literal)? { $($fields:tt)* } ) => { - bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } ); +bitfield! (pub (crate )struct $name:u32 $(, $comment)? { $($fields)* } );register! (@io_fixed $name @ $offset); };// Creates an alias register of fixed offset register `alias` with its own fields. ($name:ident => $alias:ident $(, $comment:literal)? { $($fields:tt)* } ) => { - bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } ); +bitfield! (pub (crate )struct $name:u32 $(, $comment)? { $($fields)* } );register! (@io_fixed $name @ $alias::OFFSET ); };// Creates a register at a relative offset from a base address provider. ($name:ident @ $base:ty [ $offset:literal ] $(, $comment:literal)? { $($fields:tt)* } ) => { - bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } ); +bitfield! (pub (crate )struct $name:u32 $(, $comment)? { $($fields)* } );register! (@io_relative $name @ $base [ $offset ]); };// Creates an alias register of relative offset register `alias` with its own fields. ($name:ident => $base:ty [ $alias:ident ] $(, $comment:literal)? { $($fields:tt)* }) => { - bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } ); +bitfield! (pub (crate )struct $name:u32 $(, $comment)? { $($fields)* } );register! (@io_relative $name @ $base [ $alias::OFFSET ]); };
@@ -305,7 +305,7 @@ macro_rules! register { } ) => {static_assert! (::core::mem::size_of ::<u32 >() <= $stride); - bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } ); +bitfield! (pub (crate )struct $name:u32 $(, $comment)? { $($fields)* } );register! (@io_array $name @ $offset [ $size ; $stride ]); };
@@ -326,7 +326,7 @@ macro_rules! register { $(, $comment:literal)? { $($fields:tt)* } ) => {static_assert! (::core::mem::size_of ::<u32 >() <= $stride); - bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } ); +bitfield! (pub (crate )struct $name:u32 $(, $comment)? { $($fields)* } );register! (@io_relative_array $name @ $base [ $offset [ $size ; $stride ] ]); };
@@ -348,7 +348,7 @@ macro_rules! register { } ) => {static_assert! ($idx < $alias::SIZE ); - bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } ); +bitfield! (pub (crate )struct $name:u32 $(, $comment)? { $($fields)* } );register! (@io_relative $name @ $base [ $alias::OFFSET + $idx * $alias::STRIDE ] ); };
@@ -357,7 +357,7 @@ macro_rules! register {// to avoid it being interpreted in place of the relative register array alias rule. ($name:ident => $alias:ident [ $idx:expr ] $(, $comment:literal)? { $($fields:tt)* }) => {static_assert! ($idx < $alias::SIZE ); - bitfield!(struct $name: u32 $(, $comment)? { $($fields)* } ); +bitfield! (pub (crate )struct $name:u32 $(, $comment)? { $($fields)* } );register! (@io_fixed $name @ $alias::OFFSET + $idx * $alias::STRIDE ); };
Signature · 1 line
2.34.1
PATCH v3 4/5 rust: Move register and bitfield macros out of Nova
In reply to Joel FernandesOut of broad need for these macros in Rust, move them out. Several folks have shown interest (Nova, Tyr GPU drivers).
bitfield moved into bits modules - defines bitfields in Rust structs similar to C. register moved into io module - defines hardware registers and accessors.
[Added F: record to MAINTAINERS file entry as suggested by Yury.]
---
MAINTAINERS | 1 +
drivers/gpu/nova-core/falcon.rs | 2 +-
drivers/gpu/nova-core/falcon/gsp.rs | 3 +-
drivers/gpu/nova-core/falcon/sec2.rs | 2 +-
drivers/gpu/nova-core/nova_core.rs | 3 --
drivers/gpu/nova-core/regs.rs | 6 +--
rust/kernel/bits.rs | 2 +
.../kernel/bits}/bitfield.rs | 27 ++++++-----
rust/kernel/io.rs | 1 +
.../macros.rs => rust/kernel/io/register.rs | 46 ++++++++++---------
10 files changed, 50 insertions(+), 43 deletions(-)
rename {drivers/gpu/nova-core => rust/kernel/bits}/bitfield.rs (91%)
rename drivers/gpu/nova-core/regs/macros.rs => rust/kernel/io/register.rs (93%)MAINTAINERS +1 -0
@@ -4313,6 +4313,7 @@ F: include/asm-generic/bitops.h F: include/linux/bitops.h F: lib/test_bitops.c F: tools/*/bitops* +F: rust/kernel/bits* BLINKM RGB LED DRIVER M: Jan-Simon Moeller <[email protected]>
drivers/gpu/nova-core/falcon.rs +1 -1
@@ -6,6 +6,7 @@use hal::FalconHal ;use kernel::device;use kernel::dma::DmaAddress ; +use kernel::io::register::RegisterBase ;use kernel::prelude::*;use kernel::sync::aref::ARef ;use kernel::time::Delta ;
@@ -14,7 +15,6 @@use crate ::driver::Bar0 ;use crate ::gpu::Chipset ;use crate ::regs; -use crate ::regs::macros::RegisterBase ;use crate ::util;pub (crate )mod gsp;
drivers/gpu/nova-core/falcon/gsp.rs +2 -1
@@ -1,12 +1,13 @@// SPDX-License-Identifier: GPL-2.0 +use kernel::io::register::RegisterBase ;use kernel::prelude::*;use kernel::time::Delta ;use crate ::{ driver::Bar0 , falcon::{Falcon ,FalconEngine ,PFalcon2Base ,PFalconBase }, - regs::{self, macros::RegisterBase }, + regs, util::wait_on, };
drivers/gpu/nova-core/falcon/sec2.rs +1 -1
@@ -1,7 +1,7 @@// SPDX-License-Identifier: GPL-2.0 use crate ::falcon::{FalconEngine ,PFalcon2Base ,PFalconBase }; -use crate ::regs::macros::RegisterBase ; +use kernel::io::register::RegisterBase ;/// Type specifying the `Sec2` falcon engine. Cannot be instantiated. pub (crate )struct Sec2 (());
drivers/gpu/nova-core/nova_core.rs +0 -3
@@ -2,9 +2,6 @@//! Nova Core GPU Driver -#[macro_use] -mod bitfield; -mod dma;mod driver;mod falcon;
drivers/gpu/nova-core/regs.rs +3 -3
@@ -4,15 +4,13 @@// but are mapped to types. #![allow(non_camel_case_types)] -#[macro_use] -pub (crate )mod macros; -use crate ::falcon::{DmaTrfCmdSize ,FalconCoreRev ,FalconCoreRevSubversion ,FalconFbifMemType ,FalconFbifTarget ,FalconModSelAlgo ,FalconSecurityModel ,PFalcon2Base ,PFalconBase ,PeregrineCoreSelect , };use crate ::gpu::{Architecture ,Chipset };use kernel::prelude::*; +use kernel::register;// PMC
@@ -352,6 +350,7 @@ pub(crate) fn mem_scrubbing_done(self) -> bool {pub (crate )mod gm107 {// FUSE +use kernel::register;register! (NV_FUSE_STATUS_OPT_DISPLAY @0x00021c04 {0 :0 display_disabledas bool ;
@@ -360,6 +359,7 @@ pub(crate) mod gm107 {pub (crate )mod ga100 {// FUSE +use kernel::register;register! (NV_FUSE_STATUS_OPT_DISPLAY @0x00820c04 {0 :0 display_disabledas bool ;
rust/kernel/bits.rs +2 -0
@@ -201,3 +201,5 @@ pub const fn [<genmask_ $ty>](range: RangeInclusive<u32>) -> $ty {/// assert_eq!(genmask_u8(0..=7), u8::MAX); /// ``` ); + +pub mod bitfield;
rust/kernel/bits/bitfield.rs renamed from drivers/gpu/nova-core/bitfield.rs +15 -12
@@ -78,10 +78,13 @@//! - `as <type> ?=> <try_into_type>` calls `<try_into_type>`'s `TryFrom::<<type>>` implementation //! and returns the result. This is useful with fields for which not all values are valid. //! + +/// bitfield macro definition +#[macro_export] macro_rules! bitfield {// Main entry point - defines the bitfield struct with fields ($vis:visstruct $name:ident : $storage:ty $(, $comment:literal)? { $($fields:tt)* }) => { -bitfield! (@core $vis $name $storage $(, $comment)? { $($fields)* }); + ::kernel::bitfield!(@core $vis $name $storage $(, $comment)? { $($fields)* }); };// All rules below are helpers.
@@ -116,7 +119,7 @@ fn from(val: $storage) -> Self { } } -bitfield! (@fields_dispatcher $vis $name $storage { $($fields)* }); + ::kernel::bitfield!(@fields_dispatcher $vis $name $storage { $($fields)* }); };// Captures the fields and passes them to all the implementers that require field information.
@@ -132,7 +135,7 @@ fn from(val: $storage) -> Self { )* } ) => { - bitfield!(@field_accessors $vis $name $storage { + ::kernel::bitfield!(@field_accessors $vis $name $storage { $( $hi:$lo $field as $type $(?=> $try_into_type)?
@@ -141,8 +144,8 @@ fn from(val: $storage) -> Self { ; )* }); -bitfield! (@debug $name { $($field;)* }); -bitfield! (@default $name { $($field;)* }); + ::kernel::bitfield!(@debug $name { $($field;)* }); + ::kernel::bitfield!(@default $name { $($field;)* }); };// Defines all the field getter/setter methods for `$name`.
@@ -157,7 +160,7 @@ fn from(val: $storage) -> Self { } ) => { $( - bitfield!(@check_field_bounds $hi:$lo $field as $type); + ::kernel::bitfield!(@check_field_bounds $hi:$lo $field as $type); )*#[allow(dead_code)]
@@ -169,7 +172,7 @@ impl $name { } $( - bitfield!(@field_accessor $vis $name $storage, $hi:$lo $field as $type + ::kernel::bitfield!(@field_accessor $vis $name $storage, $hi:$lo $field as $type $(?=> $try_into_type)? $(=> $into_type)? $(, $comment)?
@@ -206,7 +209,7 @@ impl $name { @field_accessor $vis:vis $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as bool => $into_type:ty $(, $comment:literal)?; ) => { -bitfield! ( + ::kernel::bitfield!( @leaf_accessor $vis $name $storage, $hi:$lo $field { |f| <$into_type>::from (if f !=0 {true }else {false }) } $into_type => $into_type $(, $comment)?;
@@ -217,7 +220,7 @@ impl $name { ( @field_accessor $vis:vis $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as bool $(, $comment:literal)?; ) => { -bitfield! (@field_accessor $vis $name $storage, $hi:$lo $fieldas bool =>bool $(, $comment)?;); + ::kernel::bitfield!(@field_accessor $vis $name $storage, $hi:$lo $fieldas bool =>bool $(, $comment)?;); };// Catches the `?=>` syntax for non-boolean fields.
@@ -225,7 +228,7 @@ impl $name { @field_accessor $vis:vis $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as $type:tt ?=> $try_into_type:ty $(, $comment:literal)?; ) => { -bitfield! (@leaf_accessor $vis $name $storage, $hi:$lo $field + ::kernel::bitfield!(@leaf_accessor $vis $name $storage, $hi:$lo $field { |f| <$try_into_type>::try_from (fas $type ) } $try_into_type => ::core::result::Result < $try_into_type,
@@ -239,7 +242,7 @@ impl $name { @field_accessor $vis:vis $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as $type:tt => $into_type:ty $(, $comment:literal)?; ) => { -bitfield! (@leaf_accessor $vis $name $storage, $hi:$lo $field + ::kernel::bitfield!(@leaf_accessor $vis $name $storage, $hi:$lo $field { |f| <$into_type>::from (fas $type ) } $into_type => $into_type $(, $comment)?;); };
@@ -248,7 +251,7 @@ impl $name { @field_accessor $vis:vis $name:ident $storage:ty, $hi:tt:$lo:tt $field:ident as $type:tt $(, $comment:literal)?; ) => { -bitfield! (@field_accessor $vis $name $storage, $hi:$lo $fieldas $type => $type $(, $comment)?;); + ::kernel::bitfield!(@field_accessor $vis $name $storage, $hi:$lo $fieldas $type => $type $(, $comment)?;); };// Generates the accessor methods for a single field.
rust/kernel/io.rs +1 -0
@@ -8,6 +8,7 @@use crate ::{bindings, build_assert, ffi::c_void};pub mod mem; +pub mod register;pub mod resource;pub use resource::Resource ;
rust/kernel/io/register.rs renamed from drivers/gpu/nova-core/regs/macros.rs +24 -22
169 lines not on this page · raw message
Signature · 1 line
2.34.1
Re: [PATCH v3 4/5] rust: Move register and bitfield macros out of Nova
Quoted 3 lines · Joel Fernandes
Out of broad need for these macros in Rust, move them out. Several folks have shown interest (Nova, Tyr GPU drivers).
Please Cc the rust-for-Linux mailing list, especially so for patches that add things to the core infrastructure.
I notice easily because I tag the ones that are in my client :)
Quoted 1 line
[Added F: record to
MAINTAINERSfile entry as suggested by Yury.]
Please don't use [ ... ] nor the past tense -- for normal changes, please use the imperative instead.
(I guess you picked this up from other [ ... ] notation, but that is normally only done for modifications of a patch by someone else, e.g. by maintainers.)
Thanks!
Cheers,
Miguel
Re: [PATCH v3 4/5] rust: Move register and bitfield macros out of Nova
Quoted 13 lines · Miguel Ojeda
Quoted 3 lines · Joel Fernandes
Out of broad need for these macros in Rust, move them out. Several folks have shown interest (Nova, Tyr GPU drivers).
Please Cc the rust-for-Linux mailing list, especially so for patches that add things to the core infrastructure.
I notice easily because I tag the ones that are in my client :)
Oops my bad. I shall do so, will await other comments if any before reposting.
Quoted 5 lines
Quoted 2 lines
[Added F: record to
MAINTAINERSfile entry as suggested by Yury.]Please don't use [ ... ] nor the past tense -- for normal changes, please use the imperative instead.
Sure, will do.
thanks,
- Joel
Quoted 9 lines
(I guess you picked this up from other [ ... ] notation, but that is normally only done for modifications of a patch by someone else, e.g. by maintainers.)
Thanks!
Cheers,
Miguel
PATCH v3 5/5 rust: Add KUNIT tests for bitfield
In reply to Joel FernandesAdd KUNIT tests to make sure the macro is working correctly.
[Added range overlap tests suggested by Yury].
--- rust/kernel/bits/bitfield.rs | 320 +++++++++++++++++++++++++++++++++++ 1 file changed, 320 insertions(+)
rust/kernel/bits/bitfield.rs +320 -0
@@ -339,3 +339,323 @@ fn default() -> Self { } }; } + +#[::kernel::macros::kunit_tests(kernel_bitfield)] +mod tests { +use core::convert::TryFrom ; + +// Enum types for testing => and ?=> conversions +#[derive( Debug , Clone , Copy , PartialEq )] +enum MemoryType { +Unmapped =0 , +Normal =1 , +Device =2 , +Reserved =3 , + } + +impl Default for MemoryType { +fn default () ->Self { +MemoryType ::Unmapped + } + } + +impl TryFrom <u8 >for MemoryType { +type Error =u8 ; +fn try_from (value:u8 ) ->Result <Self ,Self ::Error > { +match value { +0 =>Ok (MemoryType ::Unmapped ), +1 =>Ok (MemoryType ::Normal ), +2 =>Ok (MemoryType ::Device ), +3 =>Ok (MemoryType ::Reserved ), + _ =>Err (value), + } + } + } + +impl From <MemoryType >for u64 { +fn from (mt:MemoryType ) ->u64 { + mtas u64 + } + } + +#[derive( Debug , Clone , Copy , PartialEq )] +enum Priority { +Low =0 , +Medium =1 , +High =2 , +Critical =3 , + } + +impl Default for Priority { +fn default () ->Self { +Priority ::Low + } + } + +impl From <u8 >for Priority { +fn from (value:u8 ) ->Self { +match value &0x3 { +0 =>Priority ::Low , +1 =>Priority ::Medium , +2 =>Priority ::High , + _ =>Priority ::Critical , + } + } + } + +impl From <Priority >for u16 { +fn from (p:Priority ) ->u16 { + pas u16 + } + } + +bitfield! { +struct TestPageTableEntry :u64 { +0 :0 presentas bool ; +1 :1 writableas bool ; +11 :9 availableas u8 ; +13 :12 mem_typeas u8 ?=>MemoryType ; +17 :14 extended_typeas u8 ?=>MemoryType ;// 4-bit field for testing failures +51 :12 pfnas u64 ; +51 :12 pfn_overlapas u64 ;// Overlapping field +61 :52 available2as u16 ; + } + } + +bitfield! { +struct TestControlRegister :u16 { +0 :0 enableas bool ; +3 :1 modeas u8 ; +5 :4 priorityas u8 =>Priority ; +7 :4 priority_nibbleas u8 ;// Overlapping field +15 :8 channelas u8 ; + } + } + +bitfield! { +struct TestStatusRegister :u8 { +0 :0 readyas bool ; +1 :1 erroras bool ; +3 :2 stateas u8 ; +7 :4 reservedas u8 ; +7 :0 full_byteas u8 ;// Overlapping field for entire register + } + } + +#[test] +fn test_single_bits () { +let mut pte =TestPageTableEntry ::default (); + +// Test bool field +assert! (!pte.present ()); +assert! (!pte.writable ()); + + pte = pte.set_present (true ); +assert! (pte.present ()); + + pte = pte.set_writable (true ); +assert! (pte.writable ()); + + pte = pte.set_writable (false ); +assert! (!pte.writable ()); + +assert_eq! (pte.available (),0 ); + pte = pte.set_available (0x5 ); +assert_eq! (pte.available (),0x5 ); + } + +#[test] +fn test_range_fields () { +let mut pte =TestPageTableEntry ::default (); + + pte = pte.set_pfn (0x123456 ); +assert_eq! (pte.pfn (),0x123456 ); +// Test overlapping field reads same value +assert_eq! (pte.pfn_overlap (),0x123456 ); + + pte = pte.set_available (0x7 ); +assert_eq! (pte.available (),0x7 ); + + pte = pte.set_available2 (0x3FF ); +assert_eq! (pte.available2 (),0x3FF ); + +// Test TryFrom with ?=> for MemoryType + pte = pte.set_mem_type (MemoryType ::Device ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Device )); + + pte = pte.set_mem_type (MemoryType ::Normal ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Normal )); + +// Test all valid values for mem_type + pte = pte.set_mem_type (MemoryType ::Reserved );// Valid value: 3 +assert_eq! (pte.mem_type (),Ok (MemoryType ::Reserved )); + +// Test failure case using extended_type field which has 4 bits (0-15) +// MemoryType only handles 0-3, so values 4-15 should return Err +let mut raw = pte.raw (); + raw = (raw & !(0xF <<14 )) | (0x7 <<14 );// Set bits 17:14 to 7 (invalid for MemoryType) +let invalid_pte =TestPageTableEntry ::from (raw); +assert_eq! (invalid_pte.extended_type (),Err (0x7 ));// Should return Err with the invalid value + +// Test a valid value after testing invalid to ensure both cases work + raw = (raw & !(0xF <<14 )) | (0x2 <<14 );// Set bits 17:14 to 2 (valid: Device) +let valid_pte =TestPageTableEntry ::from (raw); +assert_eq! (valid_pte.extended_type (),Ok (MemoryType ::Device ));// Should return Ok with Device + +let max_pfn = (1u64 <<40 ) -1 ; + pte = pte.set_pfn (max_pfn); +assert_eq! (pte.pfn (), max_pfn); +assert_eq! (pte.pfn_overlap (), max_pfn); + } + +#[test] +fn test_builder_pattern () { +let pte =TestPageTableEntry ::default () + .set_present (true ) + .set_writable (true ) + .set_available (0x7 ) + .set_pfn (0xABCDEF ) + .set_mem_type (MemoryType ::Reserved ) + .set_available2 (0x3FF ); + +assert! (pte.present ()); +assert! (pte.writable ()); +assert_eq! (pte.available (),0x7 ); +assert_eq! (pte.pfn (),0xABCDEF ); +assert_eq! (pte.pfn_overlap (),0xABCDEF ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Reserved )); +assert_eq! (pte.available2 (),0x3FF ); + } + +#[test] +fn test_raw_operations () { +let raw_value =0x3FF0000003123E03u64 ; + +// Test using ::from() syntax +let pte =TestPageTableEntry ::from (raw_value); +assert_eq! (pte.raw (), raw_value); + +assert! (pte.present ()); +assert! (pte.writable ()); +assert_eq! (pte.available (),0x7 ); +assert_eq! (pte.pfn (),0x3123 ); +assert_eq! (pte.pfn_overlap (),0x3123 ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Reserved )); +assert_eq! (pte.available2 (),0x3FF ); + +// Test using direct constructor syntax TestStruct(value) +let pte2 =TestPageTableEntry (raw_value); +assert_eq! (pte2.raw (), raw_value); + } + +#[test] +fn test_u16_bitfield () { +let mut ctrl =TestControlRegister ::default (); + +assert! (!ctrl.enable ()); +assert_eq! (ctrl.mode (),0 ); +assert_eq! (ctrl.priority (),Priority ::Low ); +assert_eq! (ctrl.priority_nibble (),0 ); +assert_eq! (ctrl.channel (),0 ); + + ctrl = ctrl.set_enable (true ); +assert! (ctrl.enable ()); + + ctrl = ctrl.set_mode (0x5 ); +assert_eq! (ctrl.mode (),0x5 ); + +// Test From conversion with => + ctrl = ctrl.set_priority (Priority ::High ); +assert_eq! (ctrl.priority (),Priority ::High ); +assert_eq! (ctrl.priority_nibble (),0x2 );// High = 2 in bits 5:4 + + ctrl = ctrl.set_channel (0xAB ); +assert_eq! (ctrl.channel (),0xAB ); + +// Test overlapping fields + ctrl = ctrl.set_priority_nibble (0xF ); +assert_eq! (ctrl.priority_nibble (),0xF ); +assert_eq! (ctrl.priority (),Priority ::Critical );// bits 5:4 = 0x3 + +let ctrl2 =TestControlRegister ::default () + .set_enable (true ) + .set_mode (0x3 ) + .set_priority (Priority ::Medium ) + .set_channel (0x42 ); + +assert! (ctrl2.enable ()); +assert_eq! (ctrl2.mode (),0x3 ); +assert_eq! (ctrl2.priority (),Priority ::Medium ); +assert_eq! (ctrl2.channel (),0x42 ); + +let raw_value:u16 =0x4217 ; +let ctrl3 =TestControlRegister ::from (raw_value); +assert_eq! (ctrl3.raw (), raw_value); +assert! (ctrl3.enable ()); +assert_eq! (ctrl3.priority (),Priority ::Medium ); +assert_eq! (ctrl3.priority_nibble (),0x1 ); +assert_eq! (ctrl3.channel (),0x42 ); + } + +#[test] +fn test_u8_bitfield () { +let mut status =TestStatusRegister ::default (); + +assert! (!status.ready ()); +assert! (!status.error ()); +assert_eq! (status.state (),0 ); +assert_eq! (status.reserved (),0 ); +assert_eq! (status.full_byte (),0 ); + + status = status.set_ready (true ); +assert! (status.ready ()); +assert_eq! (status.full_byte (),0x01 ); + + status = status.set_error (true ); +assert! (status.error ()); +assert_eq! (status.full_byte (),0x03 ); + + status = status.set_state (0x3 ); +assert_eq! (status.state (),0x3 ); +assert_eq! (status.full_byte (),0x0F ); + + status = status.set_reserved (0xA ); +assert_eq! (status.reserved (),0xA ); +assert_eq! (status.full_byte (),0xAF ); + +// Test overlapping field + status = status.set_full_byte (0x55 ); +assert_eq! (status.full_byte (),0x55 ); +assert! (status.ready ()); +assert! (!status.error ()); +assert_eq! (status.state (),0x1 ); +assert_eq! (status.reserved (),0x5 ); + +let status2 =TestStatusRegister ::default () + .set_ready (true ) + .set_state (0x2 ) + .set_reserved (0x5 ); + +assert! (status2.ready ()); +assert! (!status2.error ()); +assert_eq! (status2.state (),0x2 ); +assert_eq! (status2.reserved (),0x5 ); +assert_eq! (status2.full_byte (),0x59 ); + +let raw_value:u8 =0x59 ; +let status3 =TestStatusRegister ::from (raw_value); +assert_eq! (status3.raw (), raw_value); +assert! (status3.ready ()); +assert! (!status3.error ()); +assert_eq! (status3.state (),0x2 ); +assert_eq! (status3.reserved (),0x5 ); +assert_eq! (status3.full_byte (),0x59 ); + +let status4 =TestStatusRegister ::from (0xFF ); +assert! (status4.ready ()); +assert! (status4.error ()); +assert_eq! (status4.state (),0x3 ); +assert_eq! (status4.reserved (),0xF ); +assert_eq! (status4.full_byte (),0xFF ); + } +}
Signature · 1 line
2.34.1
Re: [PATCH v3 5/5] rust: Add KUNIT tests for bitfield
Quoted 3 lines · Joel Fernandes
Add KUNIT tests to make sure the macro is working correctly.
[Added range overlap tests suggested by Yury].
Please no brackets and personal references in commit messages. If you believe it's worth mentioning my suggestion, then:
Quoted 1 line
Signed-off-by Joel Fernandes <[email protected]>
Some comments inline.
Thanks,
Yury
Quoted 159 lines
--- rust/kernel/bits/bitfield.rs | 320 +++++++++++++++++++++++++++++++++++ 1 file changed, 320 insertions(+)rust/kernel/bits/bitfield.rs +147
-0@@ -339,3 +339,323 @@ fn default() -> Self { } }; } + +#[::kernel::macros::kunit_tests(kernel_bitfield)] +mod tests { +use core::convert::TryFrom ; + +// Enum types for testing => and ?=> conversions +#[derive( Debug , Clone , Copy , PartialEq )] +enum MemoryType { +Unmapped =0 , +Normal =1 , +Device =2 , +Reserved =3 , + } + +impl Default for MemoryType { +fn default () ->Self { +MemoryType ::Unmapped + } + } + +impl TryFrom <u8 >for MemoryType { +type Error =u8 ; +fn try_from (value:u8 ) ->Result <Self ,Self ::Error > { +match value { +0 =>Ok (MemoryType ::Unmapped ), +1 =>Ok (MemoryType ::Normal ), +2 =>Ok (MemoryType ::Device ), +3 =>Ok (MemoryType ::Reserved ), + _ =>Err (value), + } + } + } + +impl From <MemoryType >for u64 { +fn from (mt:MemoryType ) ->u64 { + mtas u64 + } + } + +#[derive( Debug , Clone , Copy , PartialEq )] +enum Priority { +Low =0 , +Medium =1 , +High =2 , +Critical =3 , + } + +impl Default for Priority { +fn default () ->Self { +Priority ::Low + } + } + +impl From <u8 >for Priority { +fn from (value:u8 ) ->Self { +match value &0x3 { +0 =>Priority ::Low , +1 =>Priority ::Medium , +2 =>Priority ::High , + _ =>Priority ::Critical , + } + } + } + +impl From <Priority >for u16 { +fn from (p:Priority ) ->u16 { + pas u16 + } + } + +bitfield! { +struct TestPageTableEntry :u64 { +0 :0 presentas bool ; +1 :1 writableas bool ; +11 :9 availableas u8 ; +13 :12 mem_typeas u8 ?=>MemoryType ; +17 :14 extended_typeas u8 ?=>MemoryType ;// 4-bit field for testing failures +51 :12 pfnas u64 ; +51 :12 pfn_overlapas u64 ;// Overlapping field +61 :52 available2as u16 ; + } + } + +bitfield! { +struct TestControlRegister :u16 { +0 :0 enableas bool ; +3 :1 modeas u8 ; +5 :4 priorityas u8 =>Priority ; +7 :4 priority_nibbleas u8 ;// Overlapping field +15 :8 channelas u8 ; + } + } + +bitfield! { +struct TestStatusRegister :u8 { +0 :0 readyas bool ; +1 :1 erroras bool ; +3 :2 stateas u8 ; +7 :4 reservedas u8 ; +7 :0 full_byteas u8 ;// Overlapping field for entire register + } + } + +#[test] +fn test_single_bits () { +let mut pte =TestPageTableEntry ::default (); + +// Test bool field +assert! (!pte.present ()); +assert! (!pte.writable ()); + + pte = pte.set_present (true ); +assert! (pte.present ()); + + pte = pte.set_writable (true ); +assert! (pte.writable ()); + + pte = pte.set_writable (false ); +assert! (!pte.writable ()); + +assert_eq! (pte.available (),0 ); + pte = pte.set_available (0x5 ); +assert_eq! (pte.available (),0x5 ); + } + +#[test] +fn test_range_fields () { +let mut pte =TestPageTableEntry ::default (); + + pte = pte.set_pfn (0x123456 ); +assert_eq! (pte.pfn (),0x123456 ); +// Test overlapping field reads same value +assert_eq! (pte.pfn_overlap (),0x123456 ); + + pte = pte.set_available (0x7 ); +assert_eq! (pte.available (),0x7 ); + + pte = pte.set_available2 (0x3FF ); +assert_eq! (pte.available2 (),0x3FF ); + +// Test TryFrom with ?=> for MemoryType + pte = pte.set_mem_type (MemoryType ::Device ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Device )); + + pte = pte.set_mem_type (MemoryType ::Normal ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Normal )); +
rust/kernel/bits/bitfield.rs fn default() -> Self { · line 498
Quoted 10 lines
rust/kernel/bits/bitfield.rs +10
-0+// Test all valid values for mem_type + pte = pte.set_mem_type (MemoryType ::Reserved );// Valid value: 3 +assert_eq! (pte.mem_type (),Ok (MemoryType ::Reserved )); + +// Test failure case using extended_type field which has 4 bits (0-15) +// MemoryType only handles 0-3, so values 4-15 should return Err +let mut raw = pte.raw (); + raw = (raw & !(0xF <<14 )) | (0x7 <<14 );// Set bits 17:14 to 7 (invalid for MemoryType) +let invalid_pte =TestPageTableEntry ::from (raw); +assert_eq! (invalid_pte.extended_type (),Err (0x7 ));// Should return Err with the invalid value
Please make sure your lines don't exceed 100 chars, preferably less than 80.
rust/kernel/bits/bitfield.rs fn default() -> Self { · line 501
Quoted 3 lines
rust/kernel/bits/bitfield.rs +3
-0+ +// Test a valid value after testing invalid to ensure both cases work + raw = (raw & !(0xF <<14 )) | (0x2 <<14 );// Set bits 17:14 to 2 (valid: Device)
Can you use genmask!() here and everywhere else?
Quoted 141 lines
rust/kernel/bits/bitfield.rs +141
-0+let valid_pte =TestPageTableEntry ::from (raw); +assert_eq! (valid_pte.extended_type (),Ok (MemoryType ::Device ));// Should return Ok with Device + +let max_pfn = (1u64 <<40 ) -1 ; + pte = pte.set_pfn (max_pfn); +assert_eq! (pte.pfn (), max_pfn); +assert_eq! (pte.pfn_overlap (), max_pfn); + } + +#[test] +fn test_builder_pattern () { +let pte =TestPageTableEntry ::default () + .set_present (true ) + .set_writable (true ) + .set_available (0x7 ) + .set_pfn (0xABCDEF ) + .set_mem_type (MemoryType ::Reserved ) + .set_available2 (0x3FF ); + +assert! (pte.present ()); +assert! (pte.writable ()); +assert_eq! (pte.available (),0x7 ); +assert_eq! (pte.pfn (),0xABCDEF ); +assert_eq! (pte.pfn_overlap (),0xABCDEF ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Reserved )); +assert_eq! (pte.available2 (),0x3FF ); + } + +#[test] +fn test_raw_operations () { +let raw_value =0x3FF0000003123E03u64 ; + +// Test using ::from() syntax +let pte =TestPageTableEntry ::from (raw_value); +assert_eq! (pte.raw (), raw_value); + +assert! (pte.present ()); +assert! (pte.writable ()); +assert_eq! (pte.available (),0x7 ); +assert_eq! (pte.pfn (),0x3123 ); +assert_eq! (pte.pfn_overlap (),0x3123 ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Reserved )); +assert_eq! (pte.available2 (),0x3FF ); + +// Test using direct constructor syntax TestStruct(value) +let pte2 =TestPageTableEntry (raw_value); +assert_eq! (pte2.raw (), raw_value); + } + +#[test] +fn test_u16_bitfield () { +let mut ctrl =TestControlRegister ::default (); + +assert! (!ctrl.enable ()); +assert_eq! (ctrl.mode (),0 ); +assert_eq! (ctrl.priority (),Priority ::Low ); +assert_eq! (ctrl.priority_nibble (),0 ); +assert_eq! (ctrl.channel (),0 ); + + ctrl = ctrl.set_enable (true ); +assert! (ctrl.enable ()); + + ctrl = ctrl.set_mode (0x5 ); +assert_eq! (ctrl.mode (),0x5 ); + +// Test From conversion with => + ctrl = ctrl.set_priority (Priority ::High ); +assert_eq! (ctrl.priority (),Priority ::High ); +assert_eq! (ctrl.priority_nibble (),0x2 );// High = 2 in bits 5:4 + + ctrl = ctrl.set_channel (0xAB ); +assert_eq! (ctrl.channel (),0xAB ); + +// Test overlapping fields + ctrl = ctrl.set_priority_nibble (0xF ); +assert_eq! (ctrl.priority_nibble (),0xF ); +assert_eq! (ctrl.priority (),Priority ::Critical );// bits 5:4 = 0x3 + +let ctrl2 =TestControlRegister ::default () + .set_enable (true ) + .set_mode (0x3 ) + .set_priority (Priority ::Medium ) + .set_channel (0x42 ); + +assert! (ctrl2.enable ()); +assert_eq! (ctrl2.mode (),0x3 ); +assert_eq! (ctrl2.priority (),Priority ::Medium ); +assert_eq! (ctrl2.channel (),0x42 ); + +let raw_value:u16 =0x4217 ; +let ctrl3 =TestControlRegister ::from (raw_value); +assert_eq! (ctrl3.raw (), raw_value); +assert! (ctrl3.enable ()); +assert_eq! (ctrl3.priority (),Priority ::Medium ); +assert_eq! (ctrl3.priority_nibble (),0x1 ); +assert_eq! (ctrl3.channel (),0x42 ); + } + +#[test] +fn test_u8_bitfield () { +let mut status =TestStatusRegister ::default (); + +assert! (!status.ready ()); +assert! (!status.error ()); +assert_eq! (status.state (),0 ); +assert_eq! (status.reserved (),0 ); +assert_eq! (status.full_byte (),0 ); + + status = status.set_ready (true ); +assert! (status.ready ()); +assert_eq! (status.full_byte (),0x01 ); + + status = status.set_error (true ); +assert! (status.error ()); +assert_eq! (status.full_byte (),0x03 ); + + status = status.set_state (0x3 ); +assert_eq! (status.state (),0x3 ); +assert_eq! (status.full_byte (),0x0F ); + + status = status.set_reserved (0xA ); +assert_eq! (status.reserved (),0xA ); +assert_eq! (status.full_byte (),0xAF ); + +// Test overlapping field + status = status.set_full_byte (0x55 ); +assert_eq! (status.full_byte (),0x55 ); +assert! (status.ready ()); +assert! (!status.error ()); +assert_eq! (status.state (),0x1 ); +assert_eq! (status.reserved (),0x5 ); + +let status2 =TestStatusRegister ::default () + .set_ready (true ) + .set_state (0x2 ) + .set_reserved (0x5 ); + +assert! (status2.ready ()); +assert! (!status2.error ()); +assert_eq! (status2.state (),0x2 ); +assert_eq! (status2.reserved (),0x5 );
rust/kernel/bits/bitfield.rs fn default() -> Self { · line 652
Quoted 10 lines
rust/kernel/bits/bitfield.rs +10
-0+assert_eq! (status2.full_byte (),0x59 ); + +let raw_value:u8 =0x59 ; +let status3 =TestStatusRegister ::from (raw_value); +assert_eq! (status3.raw (), raw_value); +assert! (status3.ready ()); +assert! (!status3.error ()); +assert_eq! (status3.state (),0x2 ); +assert_eq! (status3.reserved (),0x5 ); +assert_eq! (status3.full_byte (),0x59 );
You've got only one negative test that covers the .from() method. Can you add more?
What if I create a bitfield from a runtime value that exceeds the capacity?
bitfield! {
struct bf: u8 {
0:0 ready as bool;
1:1 error as bool;
3:2 state as u32;
}
}
let raw_value: u8 = 0xff;
let bf = bf::from(raw_value);I guess you'd return None or similar. Can you add such a test? The same question for the setters. What would happen for this:
let bf = bf::default()
.set_state(0xf)
.set_ready(true);I think that after the first out-of-boundary in set_state(), you should abort the call chain, make sure you're not touching memory in set_ready() and returning some type of error.
And for this:
let ret: u32 = -EINVAL;
bf = bf::default();
bf = bf.set_state(ret);For compile-time initializes, it should be a compile-time error, right? Can you drop a comment on that?
(In C we've got FIELD_{GET,MODIFY,PREP}. They cover all the static cases.)
Quoted 10 lines
rust/kernel/bits/bitfield.rs +8
-0+let status4 =TestStatusRegister ::from (0xFF ); +assert! (status4.ready ()); +assert! (status4.error ()); +assert_eq! (status4.state (),0x3 ); +assert_eq! (status4.reserved (),0xF ); +assert_eq! (status4.full_byte (),0xFF ); + } +}Signature · 1 line
2.34.1
I tried to apply your series on top of master, but it failed. So my apologies for not finding the answers to some questions above by myself.
For the next version, can you make sure your series is applicable on top of master or -next?
Re: [PATCH v3 5/5] rust: Add KUNIT tests for bitfield
Quoted 342 lines · Yury Norov
Quoted 3 lines · Joel Fernandes
Add KUNIT tests to make sure the macro is working correctly.
[Added range overlap tests suggested by Yury].
Please no brackets and personal references in commit messages. If you believe it's worth mentioning my suggestion, then:
Quoted 1 line
Signed-off-by Joel Fernandes <[email protected]>Some comments inline.
Thanks,
YuryQuoted 159 lines
--- rust/kernel/bits/bitfield.rs | 320 +++++++++++++++++++++++++++++++++++ 1 file changed, 320 insertions(+)rust/kernel/bits/bitfield.rs +147
-0@@ -339,3 +339,323 @@ fn default() -> Self { } }; } + +#[::kernel::macros::kunit_tests(kernel_bitfield)] +mod tests { +use core::convert::TryFrom ; + +// Enum types for testing => and ?=> conversions +#[derive( Debug , Clone , Copy , PartialEq )] +enum MemoryType { +Unmapped =0 , +Normal =1 , +Device =2 , +Reserved =3 , + } + +impl Default for MemoryType { +fn default () ->Self { +MemoryType ::Unmapped + } + } + +impl TryFrom <u8 >for MemoryType { +type Error =u8 ; +fn try_from (value:u8 ) ->Result <Self ,Self ::Error > { +match value { +0 =>Ok (MemoryType ::Unmapped ), +1 =>Ok (MemoryType ::Normal ), +2 =>Ok (MemoryType ::Device ), +3 =>Ok (MemoryType ::Reserved ), + _ =>Err (value), + } + } + } + +impl From <MemoryType >for u64 { +fn from (mt:MemoryType ) ->u64 { + mtas u64 + } + } + +#[derive( Debug , Clone , Copy , PartialEq )] +enum Priority { +Low =0 , +Medium =1 , +High =2 , +Critical =3 , + } + +impl Default for Priority { +fn default () ->Self { +Priority ::Low + } + } + +impl From <u8 >for Priority { +fn from (value:u8 ) ->Self { +match value &0x3 { +0 =>Priority ::Low , +1 =>Priority ::Medium , +2 =>Priority ::High , + _ =>Priority ::Critical , + } + } + } + +impl From <Priority >for u16 { +fn from (p:Priority ) ->u16 { + pas u16 + } + } + +bitfield! { +struct TestPageTableEntry :u64 { +0 :0 presentas bool ; +1 :1 writableas bool ; +11 :9 availableas u8 ; +13 :12 mem_typeas u8 ?=>MemoryType ; +17 :14 extended_typeas u8 ?=>MemoryType ;// 4-bit field for testing failures +51 :12 pfnas u64 ; +51 :12 pfn_overlapas u64 ;// Overlapping field +61 :52 available2as u16 ; + } + } + +bitfield! { +struct TestControlRegister :u16 { +0 :0 enableas bool ; +3 :1 modeas u8 ; +5 :4 priorityas u8 =>Priority ; +7 :4 priority_nibbleas u8 ;// Overlapping field +15 :8 channelas u8 ; + } + } + +bitfield! { +struct TestStatusRegister :u8 { +0 :0 readyas bool ; +1 :1 erroras bool ; +3 :2 stateas u8 ; +7 :4 reservedas u8 ; +7 :0 full_byteas u8 ;// Overlapping field for entire register + } + } + +#[test] +fn test_single_bits () { +let mut pte =TestPageTableEntry ::default (); + +// Test bool field +assert! (!pte.present ()); +assert! (!pte.writable ()); + + pte = pte.set_present (true ); +assert! (pte.present ()); + + pte = pte.set_writable (true ); +assert! (pte.writable ()); + + pte = pte.set_writable (false ); +assert! (!pte.writable ()); + +assert_eq! (pte.available (),0 ); + pte = pte.set_available (0x5 ); +assert_eq! (pte.available (),0x5 ); + } + +#[test] +fn test_range_fields () { +let mut pte =TestPageTableEntry ::default (); + + pte = pte.set_pfn (0x123456 ); +assert_eq! (pte.pfn (),0x123456 ); +// Test overlapping field reads same value +assert_eq! (pte.pfn_overlap (),0x123456 ); + + pte = pte.set_available (0x7 ); +assert_eq! (pte.available (),0x7 ); + + pte = pte.set_available2 (0x3FF ); +assert_eq! (pte.available2 (),0x3FF ); + +// Test TryFrom with ?=> for MemoryType + pte = pte.set_mem_type (MemoryType ::Device ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Device )); + + pte = pte.set_mem_type (MemoryType ::Normal ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Normal )); +rust/kernel/bits/bitfield.rs fn default() -> Self { · line 498
Quoted 10 lines
rust/kernel/bits/bitfield.rs +10
-0+// Test all valid values for mem_type + pte = pte.set_mem_type (MemoryType ::Reserved );// Valid value: 3 +assert_eq! (pte.mem_type (),Ok (MemoryType ::Reserved )); + +// Test failure case using extended_type field which has 4 bits (0-15) +// MemoryType only handles 0-3, so values 4-15 should return Err +let mut raw = pte.raw (); + raw = (raw & !(0xF <<14 )) | (0x7 <<14 );// Set bits 17:14 to 7 (invalid for MemoryType) +let invalid_pte =TestPageTableEntry ::from (raw); +assert_eq! (invalid_pte.extended_type (),Err (0x7 ));// Should return Err with the invalid value Please make sure your lines don't exceed 100 chars, preferably less than 80.
rust/kernel/bits/bitfield.rs fn default() -> Self { · line 501
Quoted 3 lines
rust/kernel/bits/bitfield.rs +3
-0+ +// Test a valid value after testing invalid to ensure both cases work + raw = (raw & !(0xF <<14 )) | (0x2 <<14 );// Set bits 17:14 to 2 (valid: Device) Can you use genmask!() here and everywhere else?
Quoted 146 lines
rust/kernel/bits/bitfield.rs +146
-0+let valid_pte =TestPageTableEntry ::from (raw); +assert_eq! (valid_pte.extended_type (),Ok (MemoryType ::Device ));// Should return Ok with Device + +let max_pfn = (1u64 <<40 ) -1 ; + pte = pte.set_pfn (max_pfn); +assert_eq! (pte.pfn (), max_pfn); +assert_eq! (pte.pfn_overlap (), max_pfn); + } + +#[test] +fn test_builder_pattern () { +let pte =TestPageTableEntry ::default () + .set_present (true ) + .set_writable (true ) + .set_available (0x7 ) + .set_pfn (0xABCDEF ) + .set_mem_type (MemoryType ::Reserved ) + .set_available2 (0x3FF ); + +assert! (pte.present ()); +assert! (pte.writable ()); +assert_eq! (pte.available (),0x7 ); +assert_eq! (pte.pfn (),0xABCDEF ); +assert_eq! (pte.pfn_overlap (),0xABCDEF ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Reserved )); +assert_eq! (pte.available2 (),0x3FF ); + } + +#[test] +fn test_raw_operations () { +let raw_value =0x3FF0000003123E03u64 ; + +// Test using ::from() syntax +let pte =TestPageTableEntry ::from (raw_value); +assert_eq! (pte.raw (), raw_value); + +assert! (pte.present ()); +assert! (pte.writable ()); +assert_eq! (pte.available (),0x7 ); +assert_eq! (pte.pfn (),0x3123 ); +assert_eq! (pte.pfn_overlap (),0x3123 ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Reserved )); +assert_eq! (pte.available2 (),0x3FF ); + +// Test using direct constructor syntax TestStruct(value) +let pte2 =TestPageTableEntry (raw_value); +assert_eq! (pte2.raw (), raw_value); + } + +#[test] +fn test_u16_bitfield () { +let mut ctrl =TestControlRegister ::default (); + +assert! (!ctrl.enable ()); +assert_eq! (ctrl.mode (),0 ); +assert_eq! (ctrl.priority (),Priority ::Low ); +assert_eq! (ctrl.priority_nibble (),0 ); +assert_eq! (ctrl.channel (),0 ); + + ctrl = ctrl.set_enable (true ); +assert! (ctrl.enable ()); + + ctrl = ctrl.set_mode (0x5 ); +assert_eq! (ctrl.mode (),0x5 ); + +// Test From conversion with => + ctrl = ctrl.set_priority (Priority ::High ); +assert_eq! (ctrl.priority (),Priority ::High ); +assert_eq! (ctrl.priority_nibble (),0x2 );// High = 2 in bits 5:4 + + ctrl = ctrl.set_channel (0xAB ); +assert_eq! (ctrl.channel (),0xAB ); + +// Test overlapping fields + ctrl = ctrl.set_priority_nibble (0xF ); +assert_eq! (ctrl.priority_nibble (),0xF ); +assert_eq! (ctrl.priority (),Priority ::Critical );// bits 5:4 = 0x3 + +let ctrl2 =TestControlRegister ::default () + .set_enable (true ) + .set_mode (0x3 ) + .set_priority (Priority ::Medium ) + .set_channel (0x42 ); + +assert! (ctrl2.enable ()); +assert_eq! (ctrl2.mode (),0x3 ); +assert_eq! (ctrl2.priority (),Priority ::Medium ); +assert_eq! (ctrl2.channel (),0x42 ); + +let raw_value:u16 =0x4217 ; +let ctrl3 =TestControlRegister ::from (raw_value); +assert_eq! (ctrl3.raw (), raw_value); +assert! (ctrl3.enable ()); +assert_eq! (ctrl3.priority (),Priority ::Medium ); +assert_eq! (ctrl3.priority_nibble (),0x1 ); +assert_eq! (ctrl3.channel (),0x42 ); + } + +#[test] +fn test_u8_bitfield () { +let mut status =TestStatusRegister ::default (); + +assert! (!status.ready ()); +assert! (!status.error ()); +assert_eq! (status.state (),0 ); +assert_eq! (status.reserved (),0 ); +assert_eq! (status.full_byte (),0 ); + + status = status.set_ready (true ); +assert! (status.ready ()); +assert_eq! (status.full_byte (),0x01 ); + + status = status.set_error (true ); +assert! (status.error ()); +assert_eq! (status.full_byte (),0x03 ); + + status = status.set_state (0x3 ); +assert_eq! (status.state (),0x3 ); +assert_eq! (status.full_byte (),0x0F ); + + status = status.set_reserved (0xA ); +assert_eq! (status.reserved (),0xA ); +assert_eq! (status.full_byte (),0xAF ); + +// Test overlapping field + status = status.set_full_byte (0x55 ); +assert_eq! (status.full_byte (),0x55 ); +assert! (status.ready ()); +assert! (!status.error ()); +assert_eq! (status.state (),0x1 ); +assert_eq! (status.reserved (),0x5 ); + +let status2 =TestStatusRegister ::default () + .set_ready (true ) + .set_state (0x2 ) + .set_reserved (0x5 ); + +assert! (status2.ready ()); +assert! (!status2.error ()); +assert_eq! (status2.state (),0x2 ); +assert_eq! (status2.reserved (),0x5 ); +assert_eq! (status2.full_byte (),0x59 ); + +let raw_value:u8 =0x59 ; +let status3 =TestStatusRegister ::from (raw_value); +assert_eq! (status3.raw (), raw_value);
Quoted 8 lines
rust/kernel/bits/bitfield.rs fn default() -> Self { · line 652
Quoted 5 lines
rust/kernel/bits/bitfield.rs +5
-0+assert! (status3.ready ()); +assert! (!status3.error ()); +assert_eq! (status3.state (),0x2 ); +assert_eq! (status3.reserved (),0x5 ); +assert_eq! (status3.full_byte (),0x59 );You've got only one negative test that covers the .from() method. Can you add more?
Sure, but note that we can only add negative tests if there is a chance of failure, which at runtime can mainly happen with the fallible usage (?=> pattern). Also just to note, we already at ~300 lines of test code now :)
Quoted 9 lines
What if I create a bitfield from a runtime value that exceeds the capacity?
bitfield! { struct bf: u8 { 0:0 ready as bool; 1:1 error as bool; 3:2 state as u32;
Here you mean 'as u8', otherwise it wont compile.
Quoted 7 lines
} } let raw_value: u8 = 0xff; let bf = bf::from(raw_value);I guess you'd return None or similar.
No, we would ignore the extra bits sent. There is a .raw() method and 'bf' is 8-bits, bf.raw() will return 0xff. So it is perfectly valid to do so. I don't think we should return None here, this is also valid in C.
Quoted 1 line
Can you add such a test?
Sure, I added such a test.
Quoted 9 lines
The same question for the setters. What would happen for this:
let bf = bf::default() .set_state(0xf) .set_ready(true);I think that after the first out-of-boundary in
set_state(), you should abort the call chain, make sure you're not touching memory inset_ready()and returning some type of error.
Here, on out of boundary, we just ignore the extra bits passed to set_state. I think it would be odd if we errored out honestly. We are using 'as u8' in the struct so we would accept any u8 as input, but then if we complained that extra bits were sent, that would be odd. In C also this is valid. If you passed a higher value than what the bitfield can hold, the compiler will still just use the bits that it needs and ignore the rest.
Now, I am not opposed to error'ing out on that, but that's not what we currently do and it is also not easy to do. The setters in the patch return Self, not Result<Self>, so they are infallible, which is what allows them to be chained as well (builder pattern).
I added another test here as well, to ensure the behavior is as I describe.
Quoted 8 lines
And for this:
let ret: u32 = -EINVAL; bf = bf::default(); bf = bf.set_state(ret);For compile-time initializes, it should be a compile-time error, right?
Yes, since the struct in this example is u8, this wont compile. Yes, I will add a comment.
Quoted 1 line
Can you drop a comment on that?
Yes, I will do so.
Quoted 4 lines
I tried to apply your series on top of master, but it failed. So my apologies for not finding the answers to some questions above by myself.
Oh ok, I applied it on top of drm-rust-next. I will rebase on -next for the next revision, thanks.
Quoted 2 lines
For the next version, can you make sure your series is applicable on top of master or -next?
Sure, thanks.
- Joel
Re: [PATCH v3 5/5] rust: Add KUNIT tests for bitfield
Quoted 11 lines · Joel Fernandes
Quoted 2 lines
You've got only one negative test that covers the .from() method. Can you add more?
Sure, but note that we can only add negative tests if there is a chance of failure, which at runtime can mainly happen with the fallible usage (?=> pattern). Also just to note, we already at ~300 lines of test code now :)
Quoted 4 lines
What if I create a bitfield from a runtime value that exceeds the capacity?
Quoted 6 lines
Quoted 5 lines
bitfield! { struct bf: u8 { 0:0 ready as bool; 1:1 error as bool; 3:2 state as u32;Here you mean 'as u8', otherwise it wont compile.
No, I meant u32. Can you explain this limitation in docs please? From a user perspective, the 'state' is a 2-bit variable, so any type wider than that should be OK to hold the data. If it's just an implementation limitation, maybe it's worth to relax it?
Quoted 10 lines
Quoted 7 lines
} } let raw_value: u8 = 0xff; let bf = bf::from(raw_value);I guess you'd return None or similar.
No, we would ignore the extra bits sent. There is a .raw() method and 'bf' is 8-bits,
bf.raw()will return0xff. So it is perfectly valid to do so.
So I'm lost. Do you ignore or keep untouched?
Imagine a code relying on the behavior you've just described. So, I create a 5-bit bitfield residing in a u8 storage, and my user one day starts using that 3-bit tail for his own purposes.
Is that OK? Can you guarantee that any possible combination of methods that you've implemented or will implement in future will keep the tail untouched?
In bitmaps, even for a single-bit bitmap the API reserves the whole word, thus we have a similar problem. And we state clearly that any bit beyond the requested area is 'don't care'. It's OK for C. Is it OK for rust?
(And even that, we have a couple of functions that take care of tails for some good reasons.)
So the question is: do you
- provide the same minimal guarantees as C does (undefined behavior); or
- preserve tails untouched, so user can play with them; or
- clean the tails for user; or
- reject such requests?
Or something else? Whichever option you choose, please describe it explicitly.
Quoted 2 lines
I don't
think we should return None here, this is also valid in C.
This doesn't sound like an argument in the rust world, isn't? :) I've been told many times that the main purpose of rust is the bullet-proof way of coding. Particularly: "rust is free of undefined behavior gray zone".
Quoted 10 lines
Quoted 1 line
Can you add such a test?
Sure, I added such a test.
Quoted 6 lines
The same question for the setters. What would happen for this:
let bf = bf::default() .set_state(0xf) .set_ready(true);
Quoted 8 lines
Quoted 3 lines
I think that after the first out-of-boundary in
set_state(), you should abort the call chain, make sure you're not touching memory inset_ready()and returning some type of error.Here, on out of boundary, we just ignore the extra bits passed to
set_state. I think it would be odd if we errored out honestly. We are using 'as u8' in the struct so we would accept any u8 as input, but then if we complained that extra bits were sent, that would be odd.
That really depends on your purpose. If your end goal is the safest API in the world, and you're ready to sacrifice some performance (which is exactly opposite to the C case), then you'd return to your user with a simple question: are you sure you can fit this 8-bit number into a 3-bit storage?
Quoted 3 lines
In C also this is valid. If you passed a
higher value than what the bitfield can hold, the compiler will still just use the bits that it needs and ignore the rest.
In C we've got FIELD_{PREP,GET,MODIFY}, implementing the checks. So those who want to stay on safe side have a choice.
Quoted 4 lines
Now, I am not opposed to error'ing out on that, but that's not what we currently do and it is also not easy to do. The setters in the patch return Self, not Result<Self>, so they are infallible, which is what allows them to be chained as well (builder pattern).
That 'chainability' looks optional to me, not saying weird, anyways.
Quoted 5 lines
I added another test here as well, to ensure the behavior is as I describe.
Quoted 3 lines
And for this:
Quoted 8 lines
Quoted 5 lines
let ret: u32 = -EINVAL; bf = bf::default(); bf = bf.set_state(ret);For compile-time initializes, it should be a compile-time error, right?
Yes, since the struct in this example is u8, this wont compile. Yes, I will add a comment.
So, the following would work?
bitfield! {
struct bf: u32 {
0:0 ready as bool;
1:1 error as bool;
3:2 state as u32;
...
}
}
let state: u32 = some_C_wrapper(); // returns 0..3 or -EINVAL
bf = bf::default();
bf = bf.set_state(state);That doesn't look right...
Quoted 16 lines
Quoted 1 line
Can you drop a comment on that?
Yes, I will do so.
Quoted 4 lines
I tried to apply your series on top of master, but it failed. So my apologies for not finding the answers to some questions above by myself.
Oh ok, I applied it on top of drm-rust-next. I will rebase on -next for the next revision, thanks.
Quoted 2 lines
For the next version, can you make sure your series is applicable on top of master or -next?
Sure, thanks.
- Joel
Re: [PATCH v3 5/5] rust: Add KUNIT tests for bitfield
Hi Jury,
Sorry for late reply, I was busy with conference travel. Now I found a 3 hour break before my train journey. :-)
Quoted 17 lines · Yury Norov
Quoted 16 lines · Joel Fernandes
Quoted 2 lines
You've got only one negative test that covers the .from() method. Can you add more?
Sure, but note that we can only add negative tests if there is a chance of failure, which at runtime can mainly happen with the fallible usage (?=> pattern). Also just to note, we already at ~300 lines of test code now :)
Quoted 9 lines
What if I create a bitfield from a runtime value that exceeds the capacity?
bitfield! { struct bf: u8 { 0:0 ready as bool; 1:1 error as bool; 3:2 state as u32;
Quoted 6 lines
Quoted 1 line
Here you mean 'as u8', otherwise it wont compile.
No, I meant u32. Can you explain this limitation in docs please? From a user perspective, the 'state' is a 2-bit variable, so any type wider than that should be OK to hold the data. If it's just an implementation limitation, maybe it's worth to relax it?
Yes it is a limitation because of the way the code does mask and shifts, it requires the width to not exceed the width of the struct itself. Yes, I can add a comment.
I think to do what you want, you have to write it as 'as u8 => u32'. Otherwise it wont compile.
Just to note, the bitfield code reused the code in the register macro, so it is existing code in nova-core. We can improve it, but I just did a code movement with few features on top (sizes other than u32 for the overall struct, visibility etc) so I look at such changes as an improvement on top (which will be other patches in this series or later). We can certainly improve the bitfield support now and as we go.
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
} } let raw_value: u8 = 0xff; let bf = bf::from(raw_value);
Quoted 6 lines
Quoted 4 lines
Quoted 1 line
I guess you'd return None or similar.
No, we would ignore the extra bits sent. There is a .raw() method and 'bf' is 8-bits,
bf.raw()will return0xff. So it is perfectly valid to do so.So I'm lost. Do you ignore or keep untouched?
It would be ignored for the field, but kept in the struct. So .raw() will return the full 8 bits, and the field will return a subset.
Quoted 15 lines
Imagine a code relying on the behavior you've just described. So, I create a 5-bit bitfield residing in a u8 storage, and my user one day starts using that 3-bit tail for his own purposes.
Is that OK? Can you guarantee that any possible combination of methods that you've implemented or will implement in future will keep the tail untouched?
In bitmaps, even for a single-bit bitmap the API reserves the whole word, thus we have a similar problem. And we state clearly that any bit beyond the requested area is 'don't care'. It's OK for C. Is it OK for rust?
(And even that, we have a couple of functions that take care of tails for some good reasons.)
Quoted 8 lines
So the question is: do you
- provide the same minimal guarantees as C does (undefined behavior); or
- preserve tails untouched, so user can play with them; or
- clean the tails for user; or
- reject such requests?Or something else? Whichever option you choose, please describe it explicitly.
I feel this is macro-user's policy, if the user wants to use hidden bits, they should document it in their struct. They could mention it is 'dont care' or 'do not touch' in code comments. Obviously if they decide not to expose it in the fields, that would be one way to deter users of the struct from touching it without knowing what they are done. In that sense it is undefined behavior, it is up to the user I'd say. Does that sound reasonable?
Quoted 8 lines
Quoted 2 lines
I don't
think we should return None here, this is also valid in C.This doesn't sound like an argument in the rust world, isn't? :) I've been told many times that the main purpose of rust is the bullet-proof way of coding. Particularly: "rust is free of undefined behavior gray zone".
Since we only partially quoted my reply, lets take a step back and paste the code snip here again. The following should not return None IMO:
bitfield! {
struct bf: u8 {
0:0 ready as bool;
1:1 error as bool;
3:2 state as u32;
}
}
let raw_value: u8 = 0xff;
let b = bf::from(raw_value);Maybe I used 'ignore' incorrectly in my last reply. The above code snip is perfectly valid code IMO. Because b.raw() will return 0xff. The fact that we don't have defined bitfields for the value should not prevent us from accessing the entire raw value right? If we want, we can set it up as policy that there are really no undefined bits, everything is defined even if only a few of them have accessors, and '.raw()' is the ultimate catch-all. Does that sound reasonable?
Quoted 17 lines
Quoted 8 lines
Sure, I added such a test.
Quoted 6 lines
The same question for the setters. What would happen for this:
let bf = bf::default() .set_state(0xf) .set_ready(true);Quoted 8 lines
Quoted 3 lines
I think that after the first out-of-boundary in
set_state(), you should abort the call chain, make sure you're not touching memory inset_ready()and returning some type of error.Here, on out of boundary, we just ignore the extra bits passed to
set_state. I think it would be odd if we errored out honestly. We are using 'as u8' in the struct so we would accept any u8 as input, but then if we complained that extra bits were sent, that would be odd.
Quoted 5 lines
That really depends on your purpose. If your end goal is the safest API in the world, and you're ready to sacrifice some performance (which is exactly opposite to the C case), then you'd return to your user with a simple question: are you sure you can fit this 8-bit number into a 3-bit storage?
I think personally I am OK with rejecting requests about this, so we can agree on this.
Quoted 6 lines
Quoted 3 lines
In C also this is valid. If you passed a
higher value than what the bitfield can hold, the compiler will still just use the bits that it needs and ignore the rest.In C we've got FIELD_{PREP,GET,MODIFY}, implementing the checks. So those who want to stay on safe side have a choice.
Ah ok. We can add these checks then for the accessors, I will do so in v4.
Quoted 29 lines
Quoted 5 lines
I added another test here as well, to ensure the behavior is as I describe.
Quoted 3 lines
And for this:
Quoted 8 lines
Quoted 5 lines
let ret: u32 = -EINVAL; bf = bf::default(); bf = bf.set_state(ret);For compile-time initializes, it should be a compile-time error, right?
Yes, since the struct in this example is u8, this wont compile. Yes, I will add a comment.
So, the following would work?
bitfield! { struct bf: u32 { 0:0 ready as bool; 1:1 error as bool; 3:2 state as u32; ... } } let state: u32 = some_C_wrapper(); // returns 0..3 or -EINVAL bf = bf::default(); bf = bf.set_state(state);
Quoted 1 line
That doesn't look right...
I agree with you, a better approach is to reject anything great than 2 bits. We do agree on that, and I can make that change. *Currently* what happens is we mask and shift ignoring all extra bits passed, instead of rejecting.
I hope we're on the same page now, but let me know any other concerns. Just to emphasize again, I moved *existing* code out of the register macro related to bitfields, so this has been mostly a code move. That said, we can certainly improve it incrementally.
Thanks!
- Joel
Re: [PATCH v3 5/5] rust: Add KUNIT tests for bitfield
Quoted 29 lines · Joel Fernandes
Hi Jury,
Sorry for late reply, I was busy with conference travel. Now I found a 3 hour break before my train journey. :-)Quoted 17 lines · Yury Norov
Quoted 16 lines · Joel Fernandes
Quoted 2 lines
You've got only one negative test that covers the .from() method. Can you add more?
Sure, but note that we can only add negative tests if there is a chance of failure, which at runtime can mainly happen with the fallible usage (?=> pattern). Also just to note, we already at ~300 lines of test code now :)
Quoted 9 lines
What if I create a bitfield from a runtime value that exceeds the capacity?
bitfield! { struct bf: u8 { 0:0 ready as bool; 1:1 error as bool; 3:2 state as u32;Quoted 6 lines
Quoted 1 line
Here you mean 'as u8', otherwise it wont compile.
No, I meant u32. Can you explain this limitation in docs please? From a user perspective, the 'state' is a 2-bit variable, so any type wider than that should be OK to hold the data. If it's just an implementation limitation, maybe it's worth to relax it?
Quoted 6 lines
Yes it is a limitation because of the way the code does mask and shifts, it requires the width to not exceed the width of the struct itself. Yes, I can add a comment.
I think to do what you want, you have to write it as 'as u8 => u32'. Otherwise it wont compile.
I think I am convinced we should fix this, it is too much of a burden to the user otherwise. 'as u32' should just work out of the box.. I'll add support for this in v4 but if anyone has any objections, please let me know, thanks!
- Joel
Re: [PATCH v3 5/5] rust: Add KUNIT tests for bitfield
In reply to Joel FernandesOn Tue, Sep 16, 2025 at 05:59:18AM -0400, Joel Fernandes wrote:
[...]
Quoted 15 lines
Quoted 15 lines
Quoted 14 lines
Quoted 9 lines
The same question for the setters. What would happen for this:
let bf = bf::default() .set_state(0xf) .set_ready(true);I think that after the first out-of-boundary in
set_state(), you should abort the call chain, make sure you're not touching memory inset_ready()and returning some type of error.Here, on out of boundary, we just ignore the extra bits passed to
set_state. I think it would be odd if we errored out honestly. We are using 'as u8' in the struct so we would accept any u8 as input, but then if we complained that extra bits were sent, that would be odd.
Quoted 8 lines
Quoted 5 lines
That really depends on your purpose. If your end goal is the safest API in the world, and you're ready to sacrifice some performance (which is exactly opposite to the C case), then you'd return to your user with a simple question: are you sure you can fit this 8-bit number into a 3-bit storage?
I think personally I am OK with rejecting requests about this, so we can agree on this.
It is not possible to reject values passed to set, because it returns Self and follows the builder-pattern, to do this we will need to return Result, and have the caller unwrap it, and have to rename it to try_set().
Instead of that, I would just extract the bits from the value the user passed and ignore the rest (example if 0xff is passed for a 4-bit bitfield, then the field is 0xf.)
Alex what do you think, should set_ be fallible?
thanks,
- Joel
Re: [PATCH v3 5/5] rust: Add KUNIT tests for bitfield
In reply to Joel FernandesOn Tue, Sep 16, 2025 at 05:59:18AM -0400, Joel Fernandes wrote:
[...]
Quoted 8 lines
Quoted 6 lines
Quoted 3 lines
In C also this is valid. If you passed a higher value than what the bitfield can hold, the compiler will still just use the bits that it needs and ignore the rest.
In C we've got FIELD_{PREP,GET,MODIFY}, implementing the checks. So those who want to stay on safe side have a choice.
Ah ok. We can add these checks then for the accessors, I will do so in v4.
The C checks use BUILD_BUG_ON, in rust-for-linux we have build_assert but it is fragile and depends on the value being a constant. Since the setter API accepts a run-time value and not a constant, we cannot use this.
Or, we can fail at runtime, but that requires changing the set_* to try_set_* and returning a Result instead of Self. Alternatively, we can have a debug option that panics if the setter API is misued.
Thoughts?
Or for the moment, we can keep it simple and filter out / ignore extra bits of the larger value passed (which is what nova-core's register macro bitfield implementation currently does anyway).
thanks,
- Joel
Re: [PATCH v3 5/5] rust: Add KUNIT tests for bitfield
Quoted 11 lines · Joel Fernandes
On Tue, Sep 16, 2025 at 05:59:18AM -0400, Joel Fernandes wrote:
[...]Quoted 8 lines
Quoted 6 lines
Quoted 3 lines
In C also this is valid. If you passed a higher value than what the bitfield can hold, the compiler will still just use the bits that it needs and ignore the rest.
In C we've got FIELD_{PREP,GET,MODIFY}, implementing the checks. So those who want to stay on safe side have a choice.
Ah ok. We can add these checks then for the accessors, I will do so in v4.
Quoted 7 lines
The C checks use
BUILD_BUG_ON, in rust-for-linux we havebuild_assertbut it is fragile and depends on the value being a constant. Since the setter API accepts a run-time value and not a constant, we cannot use this.Or, we can fail at runtime, but that requires changing the set_* to try_set_* and returning a Result instead of Self. Alternatively, we can have a debug option that panics if the setter API is misued.
Please no...
Quoted 7 lines
Thoughts?
Or for the moment, we can keep it simple and filter out / ignore extra bits of the larger value passed (which is what nova-core's register macro bitfield implementation currently does anyway).
Yes. Assuming that I'm not completely lost here, you are proposing to simply truncate to the size of the bitfield--no panics, no warnings. And that's perfectly fine here IMHO.
thanks,
Signature · 1 line
John Hubbard
Re: [PATCH v3 5/5] rust: Add KUNIT tests for bitfield
Hello, John,
Quoted 18 lines · John Hubbard
Quoted 15 lines · Joel Fernandes
On Tue, Sep 16, 2025 at 05:59:18AM -0400, Joel Fernandes wrote:
[...]Quoted 8 lines
Quoted 6 lines
Quoted 3 lines
In C also this is valid. If you passed a higher value than what the bitfield can hold, the compiler will still just use the bits that it needs and ignore the rest.
In C we've got FIELD_{PREP,GET,MODIFY}, implementing the checks. So those who want to stay on safe side have a choice.
Ah ok. We can add these checks then for the accessors, I will do so in v4.
The C checks use
BUILD_BUG_ON, in rust-for-linux we havebuild_assertbut it is fragile and depends on the value being a constant. Since the setter API accepts a run-time value and not a constant, we cannot use this.
Quoted 5 lines
Quoted 3 lines
Or, we can fail at runtime, but that requires changing the set_* to try_set_* and returning a Result instead of Self. Alternatively, we can have a debug option that panics if the setter API is misued.
Please no...
True, it requires significant complication.
Quoted 4 lines
Quoted 4 lines
Thoughts?
Quoted 8 lines
Quoted 4 lines
Or for the moment, we can keep it simple and filter out / ignore extra bits of the larger value passed (which is what nova-core's register macro bitfield implementation currently does anyway).
Yes. Assuming that I'm not completely lost here, you are proposing to simply truncate to the size of the bitfield--no panics, no warnings. And that's perfectly fine here IMHO.
Ok, thanks. Yeah truncate. This is what register macro also currently does for its bitfields. To the point Jury is making though, the C equivalents do have build checks. We could do that once he have a better build_assert in rust but until then.. hopefully this suffices.
I am currently also research better ways of implementing build_assert.
- Joel
Quoted 5 lines
thanks,
--
John Hubbard
Re: [PATCH v3 5/5] rust: Add KUNIT tests for bitfield
In reply to Joel FernandesQuoted 3 lines · Joel Fernandes
The C checks use
BUILD_BUG_ON, in rust-for-linux we havebuild_assertbut it is fragile and depends on the value being a constant.
What do you mean?
build_assert! works essentially like BUILD_BUG_ON, i.e. after the optimizer, and does not depend on the value being a constant.
You may be thinking of static_assert!, which is the compiler-based one.
Cheers,
Miguel
Re: [PATCH v3 5/5] rust: Add KUNIT tests for bitfield
In reply to Yury NorovHi Jury,
Some reason I messed up with my email client while trimming, so I am re-sending. Sorry :)
On 9/9/2025 11:04 PM, Yury Norov wrote:
[...]
Quoted 27 lines
Quoted 27 lines
rust/kernel/bits/bitfield.rs +27
-0+#[test] +fn test_range_fields () { +let mut pte =TestPageTableEntry ::default (); + + pte = pte.set_pfn (0x123456 ); +assert_eq! (pte.pfn (),0x123456 ); +// Test overlapping field reads same value +assert_eq! (pte.pfn_overlap (),0x123456 ); + + pte = pte.set_available (0x7 ); +assert_eq! (pte.available (),0x7 ); + + pte = pte.set_available2 (0x3FF ); +assert_eq! (pte.available2 (),0x3FF ); + +// Test TryFrom with ?=> for MemoryType + pte = pte.set_mem_type (MemoryType ::Device ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Device )); + + pte = pte.set_mem_type (MemoryType ::Normal ); +assert_eq! (pte.mem_type (),Ok (MemoryType ::Normal )); + +// Test all valid values for mem_type + pte = pte.set_mem_type (MemoryType ::Reserved );// Valid value: 3 +assert_eq! (pte.mem_type (),Ok (MemoryType ::Reserved )); + +// Test failure case using extended_type field which has 4 bits (0-15)
Quoted 8 lines
rust/kernel/bits/bitfield.rs fn default() -> Self { · line 498
Quoted 5 lines
rust/kernel/bits/bitfield.rs +5
-0+// MemoryType only handles 0-3, so values 4-15 should return Err +let mut raw = pte.raw (); + raw = (raw & !(0xF <<14 )) | (0x7 <<14 );// Set bits 17:14 to 7 (invalid for MemoryType) +let invalid_pte =TestPageTableEntry ::from (raw); +assert_eq! (invalid_pte.extended_type (),Err (0x7 ));// Should return Err with the invalid value Please make sure your lines don't exceed 100 chars, preferably less than 80.
Ok.
Quoted 5 lines
rust/kernel/bits/bitfield.rs fn default() -> Self { · line 501
Quoted 3 lines
rust/kernel/bits/bitfield.rs +3
-0+ +// Test a valid value after testing invalid to ensure both cases work + raw = (raw & !(0xF <<14 )) | (0x2 <<14 );// Set bits 17:14 to 2 (valid: Device) Can you use genmask!() here and everywhere else?
Ok.
Quoted 48 lines
Quoted 48 lines
rust/kernel/bits/bitfield.rs +48
-0+#[test] +fn test_u8_bitfield () { +let mut status =TestStatusRegister ::default (); + +assert! (!status.ready ()); +assert! (!status.error ()); +assert_eq! (status.state (),0 ); +assert_eq! (status.reserved (),0 ); +assert_eq! (status.full_byte (),0 ); + + status = status.set_ready (true ); +assert! (status.ready ()); +assert_eq! (status.full_byte (),0x01 ); + + status = status.set_error (true ); +assert! (status.error ()); +assert_eq! (status.full_byte (),0x03 ); + + status = status.set_state (0x3 ); +assert_eq! (status.state (),0x3 ); +assert_eq! (status.full_byte (),0x0F ); + + status = status.set_reserved (0xA ); +assert_eq! (status.reserved (),0xA ); +assert_eq! (status.full_byte (),0xAF ); + +// Test overlapping field + status = status.set_full_byte (0x55 ); +assert_eq! (status.full_byte (),0x55 ); +assert! (status.ready ()); +assert! (!status.error ()); +assert_eq! (status.state (),0x1 ); +assert_eq! (status.reserved (),0x5 ); + +let status2 =TestStatusRegister ::default () + .set_ready (true ) + .set_state (0x2 ) + .set_reserved (0x5 ); + +assert! (status2.ready ()); +assert! (!status2.error ()); +assert_eq! (status2.state (),0x2 ); +assert_eq! (status2.reserved (),0x5 ); +assert_eq! (status2.full_byte (),0x59 ); + +let raw_value:u8 =0x59 ; +let status3 =TestStatusRegister ::from (raw_value); +assert_eq! (status3.raw (), raw_value);
Quoted 9 lines
rust/kernel/bits/bitfield.rs fn default() -> Self { · line 652
Quoted 5 lines
rust/kernel/bits/bitfield.rs +5
-0+assert! (status3.ready ()); +assert! (!status3.error ()); +assert_eq! (status3.state (),0x2 ); +assert_eq! (status3.reserved (),0x5 ); +assert_eq! (status3.full_byte (),0x59 );You've got only one negative test that covers the .from() method. Can you add more?
Sure, by negative you mean the test that returned an error code? If so, just to note, we can only add negative tests if there is a chance of runtime failure, which at runtime can mainly happen with the fallible usage (?=> pattern). Also just to note, we already at ~300 lines of test code now :)
Quoted 8 lines
What if I create a bitfield from a runtime value that exceeds the capacity?
bitfield! { struct bf: u8 { 0:0 ready as bool; 1:1 error as bool; 3:2 state as u32;
Here you mean 'as u8', otherwise it wont compile.
Quoted 7 lines
} } let raw_value: u8 = 0xff; let bf = bf::from(raw_value);I guess you'd return None or similar.
No, we would ignore the extra bits sent. There is a .raw() method and 'bf' is 8-bits, bf.raw() will return 0xff. So it is perfectly valid to do so. I don't think we should return None here, this is also valid in C.
Quoted 1 line
Can you add such a test?
Sure, I added such a test.
Quoted 9 lines
The same question for the setters. What would happen for this:
let bf = bf::default() .set_state(0xf) .set_ready(true);I think that after the first out-of-boundary in
set_state(), you should abort the call chain, make sure you're not touching memory inset_ready()and returning some type of error.
Here, on out of boundary, we just ignore the extra bits passed to set_state. I think it would be odd if we errored out honestly. We are using 'as u8' in the struct so we would accept any u8 as input, but then if we complained that extra bits were sent, that would be odd. In C also this is valid. If you passed a higher value than what the bitfield can hold, the compiler will still just use the bits that it needs and ignore the rest.
Now, I am not opposed to error'ing out on that, but that's not what we currently do and it is also not easy to do. The setters in the patch return Self, not Result<Self>, so they are infallible, which is what allows them to be chained as well (builder pattern).
I added another test here as well, to ensure the behavior is as I describe.
Quoted 8 lines
And for this:
let ret: u32 = -EINVAL; bf = bf::default(); bf = bf.set_state(ret);For compile-time initializes, it should be a compile-time error, right?
Yes, since the struct in this example is u8, this wont compile. Yes, I will add a comment.
Quoted 1 line
Can you drop a comment on that?
Yes, I will do so.
Quoted 14 lines
(In C we've got FIELD_{GET,MODIFY,PREP}. They cover all the static cases.)
Quoted 10 lines
rust/kernel/bits/bitfield.rs +8
-0+let status4 =TestStatusRegister ::from (0xFF ); +assert! (status4.ready ()); +assert! (status4.error ()); +assert_eq! (status4.state (),0x3 ); +assert_eq! (status4.reserved (),0xF ); +assert_eq! (status4.full_byte (),0xFF ); + } +}Signature · 1 line
2.34.1
Quoted 3 lines
I tried to apply your series on top of master, but it failed. So my apologies for not finding the answers to some questions above by myself.
Oh ok, I applied it on top of drm-rust-next. I will rebase on -next for the next revision, thanks.
Quoted 2 lines
For the next version, can you make sure your series is applicable on top of master or -next?
Sure, thanks,
- Joel