Add KUNIT tests to make sure the macro is working correctly.
[Added range overlap tests suggested by Yury].
Signed-off-by: Joel Fernandes <joelagnelf@nvidia.com>
---
rust/kernel/bits/bitfield.rs | 320 +++++++++++++++++++++++++++++++++++
1 file changed, 320 insertions(+)
diff --git a/rust/kernel/bits/bitfield.rs b/rust/kernel/bits/bitfield.rs
index 0837fefc270f..f3134f2ffd08 100644
--- a/rust/kernel/bits/bitfield.rs
+++ b/rust/kernel/bits/bitfield.rs
@@ -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 {
+ mt as 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 {
+ p as u16
+ }
+ }
+
+ bitfield! {
+ struct TestPageTableEntry: u64 {
+ 0:0 present as bool;
+ 1:1 writable as bool;
+ 11:9 available as u8;
+ 13:12 mem_type as u8 ?=> MemoryType;
+ 17:14 extended_type as u8 ?=> MemoryType; // 4-bit field for testing failures
+ 51:12 pfn as u64;
+ 51:12 pfn_overlap as u64; // Overlapping field
+ 61:52 available2 as u16;
+ }
+ }
+
+ bitfield! {
+ struct TestControlRegister: u16 {
+ 0:0 enable as bool;
+ 3:1 mode as u8;
+ 5:4 priority as u8 => Priority;
+ 7:4 priority_nibble as u8; // Overlapping field
+ 15:8 channel as u8;
+ }
+ }
+
+ bitfield! {
+ struct TestStatusRegister: u8 {
+ 0:0 ready as bool;
+ 1:1 error as bool;
+ 3:2 state as u8;
+ 7:4 reserved as u8;
+ 7:0 full_byte as 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);
+ }
+}
--
2.34.1On Tue, Sep 09, 2025 at 05:20:39PM -0400, Joel Fernandes wrote:
> 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:
Suggested-by: Yury Norov (NVIDIA) <yury.norov@gmail.com> # For overlapped tests
> Signed-off-by: Joel Fernandes <joelagnelf@nvidia.com>
Some comments inline.
Thanks,
Yury
> ---
> rust/kernel/bits/bitfield.rs | 320 +++++++++++++++++++++++++++++++++++
> 1 file changed, 320 insertions(+)
>
> diff --git a/rust/kernel/bits/bitfield.rs b/rust/kernel/bits/bitfield.rs
> index 0837fefc270f..f3134f2ffd08 100644
> --- a/rust/kernel/bits/bitfield.rs
> +++ b/rust/kernel/bits/bitfield.rs
> @@ -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 {
> + mt as 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 {
> + p as u16
> + }
> + }
> +
> + bitfield! {
> + struct TestPageTableEntry: u64 {
> + 0:0 present as bool;
> + 1:1 writable as bool;
> + 11:9 available as u8;
> + 13:12 mem_type as u8 ?=> MemoryType;
> + 17:14 extended_type as u8 ?=> MemoryType; // 4-bit field for testing failures
> + 51:12 pfn as u64;
> + 51:12 pfn_overlap as u64; // Overlapping field
> + 61:52 available2 as u16;
> + }
> + }
> +
> + bitfield! {
> + struct TestControlRegister: u16 {
> + 0:0 enable as bool;
> + 3:1 mode as u8;
> + 5:4 priority as u8 => Priority;
> + 7:4 priority_nibble as u8; // Overlapping field
> + 15:8 channel as u8;
> + }
> + }
> +
> + bitfield! {
> + struct TestStatusRegister: u8 {
> + 0:0 ready as bool;
> + 1:1 error as bool;
> + 3:2 state as u8;
> + 7:4 reserved as u8;
> + 7:0 full_byte as 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
Please make sure your lines don't exceed 100 chars, preferably less
than 80.
> +
> + // 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?
> + 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);
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.)
> + 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);
> + }
> +}
> --
> 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?
Hi 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:
[...]
>> + #[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
>
> Please make sure your lines don't exceed 100 chars, preferably less
> than 80.
Ok.
>> +
>> + // 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.
>> + #[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);
>
> 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 :)
> 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.
> }
> }
>
> 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.
> Can you add such a test?
Sure, I added 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.
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.
>
> 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.
> Can you drop a comment on that?
Yes, I will do so.
> (In C we've got FIELD_{GET,MODIFY,PREP}. They cover all the static
> cases.)
>
>> + 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);
>> + }
>> +}
>> --
>> 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.
Oh ok, I applied it on top of drm-rust-next. I will rebase on -next for the next
revision, thanks.
> For the next version, can you make sure your series is applicable
> on top of master or -next?
Sure, thanks,
- Joel
On 9/9/2025 11:04 PM, Yury Norov wrote:
> On Tue, Sep 09, 2025 at 05:20:39PM -0400, Joel Fernandes wrote:
>> 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:
>
> Suggested-by: Yury Norov (NVIDIA) <yury.norov@gmail.com> # For overlapped tests
>
>> Signed-off-by: Joel Fernandes <joelagnelf@nvidia.com>
>
> Some comments inline.
>
> Thanks,
> Yury
>
>> ---
>> rust/kernel/bits/bitfield.rs | 320 +++++++++++++++++++++++++++++++++++
>> 1 file changed, 320 insertions(+)
>>
>> diff --git a/rust/kernel/bits/bitfield.rs b/rust/kernel/bits/bitfield.rs
>> index 0837fefc270f..f3134f2ffd08 100644
>> --- a/rust/kernel/bits/bitfield.rs
>> +++ b/rust/kernel/bits/bitfield.rs
>> @@ -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 {
>> + mt as 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 {
>> + p as u16
>> + }
>> + }
>> +
>> + bitfield! {
>> + struct TestPageTableEntry: u64 {
>> + 0:0 present as bool;
>> + 1:1 writable as bool;
>> + 11:9 available as u8;
>> + 13:12 mem_type as u8 ?=> MemoryType;
>> + 17:14 extended_type as u8 ?=> MemoryType; // 4-bit field for testing failures
>> + 51:12 pfn as u64;
>> + 51:12 pfn_overlap as u64; // Overlapping field
>> + 61:52 available2 as u16;
>> + }
>> + }
>> +
>> + bitfield! {
>> + struct TestControlRegister: u16 {
>> + 0:0 enable as bool;
>> + 3:1 mode as u8;
>> + 5:4 priority as u8 => Priority;
>> + 7:4 priority_nibble as u8; // Overlapping field
>> + 15:8 channel as u8;
>> + }
>> + }
>> +
>> + bitfield! {
>> + struct TestStatusRegister: u8 {
>> + 0:0 ready as bool;
>> + 1:1 error as bool;
>> + 3:2 state as u8;
>> + 7:4 reserved as u8;
>> + 7:0 full_byte as 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
>
> Please make sure your lines don't exceed 100 chars, preferably less
> than 80.
>
>> +
>> + // 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?
>
>> + 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);
>
> 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 :)
>
> 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.
> }
> }
>
> 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.
> Can you add such a test?
Sure, I added 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.
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.
>
> 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.
> Can you drop a comment on that?
Yes, I will do so.
>
> 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.
> For the next version, can you make sure your series is applicable
> on top of master or -next?
Sure, thanks.
- Joel
On Wed, Sep 10, 2025 at 07:08:43PM -0400, Joel Fernandes wrote:
> > 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 :)
>
> >
> > 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.
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?
> > }
> > }
> >
> > 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.
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.
> 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".
> > Can you add such a test?
>
> Sure, I added 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.
>
> 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?
> 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.
> 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.
> I added another test here as well, to ensure the behavior is as I describe.
>
> >
> > 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.
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...
> > Can you drop a comment on that?
>
> Yes, I will do so.
>
> >
> > 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.
>
> > For the next version, can you make sure your series is applicable
> > on top of master or -next?
> Sure, thanks.
> - Joel
Hi Jury,
Sorry for late reply, I was busy with conference travel. Now I found a 3 hour
break before my train journey. :-)
On Wed, Sep 10, 2025 at 09:47:04PM -0400, Yury Norov wrote:
> On Wed, Sep 10, 2025 at 07:08:43PM -0400, Joel Fernandes wrote:
> > > 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 :)
> >
> > >
> > > 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.
>
> 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.
> > > }
> > > }
> > >
> > > 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.
>
> 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.
> 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.
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?
> > 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?
> > Sure, I added 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.
> >
> > 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?
I think personally I am OK with rejecting requests about this, so we can
agree on this.
> > 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.
> > I added another test here as well, to ensure the behavior is as I describe.
> >
> > >
> > > 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.
>
> 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...
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
On Tue, Sep 16, 2025 at 05:59:18AM -0400, Joel Fernandes wrote:
[...]
> > > 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
On Sat, Sep 20, 2025 at 2:39 AM Joel Fernandes <joelagnelf@nvidia.com> wrote: > > 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. 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
On 9/19/25 5:39 PM, Joel Fernandes wrote:
> On Tue, Sep 16, 2025 at 05:59:18AM -0400, Joel Fernandes wrote:
> [...]
>>>> 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.
Please no...
>
> 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,
--
John Hubbard
On Tue, Sep 16, 2025 at 05:59:18AM -0400, Joel Fernandes wrote: [...] > > > > 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. > > > > > > 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? > > 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
On Tue, Sep 16, 2025 at 05:59:18AM -0400, Joel Fernandes wrote:
> Hi Jury,
> Sorry for late reply, I was busy with conference travel. Now I found a 3 hour
> break before my train journey. :-)
>
> On Wed, Sep 10, 2025 at 09:47:04PM -0400, Yury Norov wrote:
> > On Wed, Sep 10, 2025 at 07:08:43PM -0400, Joel Fernandes wrote:
> > > > 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 :)
> > >
> > > >
> > > > 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.
> >
> > 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.
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
© 2016 - 2025 Red Hat, Inc.