Skip to contentSkip to conversation

rust: impl_flags: add convenience functions

PATCH Superseded Andreas Hindborg 3 participants 6 messages Feb 15 – May 12 Rust

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Andreas Hindborg

author reviewer
#0 lore raw

cover rust: impl_flags: add convenience functions

Add a few convenience functions that makes it easier to work with the impl_flags module and C APIs.

---
Andreas Hindborg (2):
rust: impl_flags: add conversion functions
rust: impl_flags: add bitwise operations with the underlying type

 rust/kernel/impl_flags.rs | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

---
base-commit: e9ec05addd1a067fc7cb218f20ecdc1b1b0898c0
change-id: 20260215-impl-flags-additions-0340ffcba5b9
prerequisite-change-id: 20250304-feat-add-bitmask-macro-6424b1c317e2:v8
prerequisite-patch-id: 05dfcf648017dee65c356604e4f99959e76ff64d
prerequisite-change-id: 20260212-impl-flags-inner-c61974b27b18:v1
prerequisite-patch-id: edebc37750dccd8d19db0b8fbd5f69f9877675a2

Best regards,

Signature · 1 line
Andreas Hindborg <[email protected]>
author reviewer
#1 lore raw

PATCH 1/2 rust: impl_flags: add conversion functions

Add two conversion functions to the impl_flags! macro:

- A From<_> implementation to convert from the flag value enum to underlying type.

- A `TryFrom<_> implementation to convert from the underlying representation to flag container type.

---
 rust/kernel/impl_flags.rs | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
rust/kernel/impl_flags.rs +20 -0
index 9160e8ce2e126..f34ecbe870d80 100644
@@ -102,6 +102,26 @@ fn from(value: $flags) -> Self {
             }
         }
 
+        impl ::core::convert::From<$flag> for $ty {
+            #[inline]
+            fn from(value: $flag) -> Self {
+                // SAFETY: All `$flag` values are valid for use as `$ty`.
+                unsafe { core::mem::transmute::<$flag, $ty>(value) }
+            }
+        }
+
+        impl ::core::convert::TryFrom<$ty> for $flags {
+            type Error = ::kernel::error::Error;
+
+            fn try_from(value: $ty) -> Result<Self, Self::Error> {
+                match value & !$flags::all_bits() == 0 {
+                    // SAFETY: We checked above that `value` is a valid bit pattern for `$flags`.
+                    true => Ok(unsafe {::core::mem::transmute::<$ty, $flags>(value)}),
+                    false => Err(::kernel::error::code::EINVAL),
+                }
+            }
+        }
+
         impl ::core::ops::BitOr for $flags {
             type Output = Self;
             #[inline]
Signature · 1 line
2.51.2
#2 lore raw

Re: [PATCH 1/2] rust: impl_flags: add conversion functions

rust/kernel/impl_flags.rs fn from(value: $flags) -> Self { · line 111

Quoted 8 lines · Andreas Hindborg
rust/kernel/impl_flags.rs +7 -0
+        impl ::core::convert::From<$flag> for $ty {
+            #[inline]
+            fn from(value: $flag) -> Self {
+                // SAFETY: All `$flag` values are valid for use as `$ty`.
+                unsafe { core::mem::transmute::<$flag, $ty>(value) }
+            }
+        }

Why do we need the transmute instead of a cast? Did you notice a difference?

Same in the other one -- why not constructing the object normally?

Also, you can use Self for $ty and $flags to make it easier to read.

In addition, I would suggest an early return with a simple if.

Finally, it wouldn't hurt adding a one-liner example for each at the top.

Thanks!

Cheers,
Miguel

author reviewer
#3 lore raw

Re: [PATCH 1/2] rust: impl_flags: add conversion functions

Quoted 11 lines · Miguel Ojeda

rust/kernel/impl_flags.rs fn from(value: $flags) -> Self { · line 111

Quoted 8 lines · Andreas Hindborg
rust/kernel/impl_flags.rs +7 -0
+        impl ::core::convert::From<$flag> for $ty {
+            #[inline]
+            fn from(value: $flag) -> Self {
+                // SAFETY: All `$flag` values are valid for use as `$ty`.
+                unsafe { core::mem::transmute::<$flag, $ty>(value) }
+            }
+        }

Why do we need the transmute instead of a cast? Did you notice a difference?

No, I did not think of using as. I can do that.

Quoted 1 line

Same in the other one -- why not constructing the object normally?

Will do.

Quoted 1 line

Also, you can use Self for $ty and $flags to make it easier to read.

Ok.

Quoted 2 lines

In addition, I would suggest an early return with a simple if.

Ok.

Quoted 2 lines

Finally, it wouldn't hurt adding a one-liner example for each at the top.

I'll add an example.

Best regards,
Andreas Hindborg

author reviewer
#4 lore raw

PATCH 2/2 rust: impl_flags: add bitwise operations with the underlying type

In reply to Andreas Hindborg

Add bitwise or operations between the flag value enum and the underlying type. This is useful when manipulating flags from C API without round tripping into the Rust flag container type:

  let mut lim: bindings::queue_limits = unsafe { core::mem::zeroed() };
  ...
  if self.write_cache {
      lim.features |= request::Feature::WriteCache;
  }

The above code would be needlessly verbose without this direct assignment option.

---
 rust/kernel/impl_flags.rs | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
rust/kernel/impl_flags.rs +16 -0
index f34ecbe870d80..f829be815885e 100644
@@ -245,6 +245,22 @@ fn bitxor(self, rhs: $flag) -> Self::Output {
             }
         }
 
+        impl ::core::ops::BitOr<$flag> for $ty {
+            type Output = Self;
+
+            #[inline]
+            fn bitor(self, rhs: $flag) -> Self::Output {
+                self | <$flag as Into<Self>>::into(rhs)
+            }
+        }
+
+        impl ::core::ops::BitOrAssign<$flag> for $ty {
+            #[inline]
+            fn bitor_assign(&mut self, rhs: $flag) {
+                *self = *self | <$flag as Into<Self>>::into(rhs)
+            }
+        }
+
         impl $flags {
             /// Returns an empty instance of `type` where no flags are set.
             #[inline]
Signature · 1 line
2.51.2
reviewer
#5 lore raw
In reply to Andreas Hindborg
Quoted 2 lines · Andreas Hindborg

Add a few convenience functions that makes it easier to work with the impl_flags module and C APIs.

I am not sure that we want to encourage direct manipulation of the underlying bits. Adding these impls would add a surface of misuse.

Best,
Gary

Quoted 18 lines

---
Andreas Hindborg (2):
rust: impl_flags: add conversion functions
rust: impl_flags: add bitwise operations with the underlying type

 rust/kernel/impl_flags.rs | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

---
base-commit: e9ec05addd1a067fc7cb218f20ecdc1b1b0898c0
change-id: 20260215-impl-flags-additions-0340ffcba5b9
prerequisite-change-id: 20250304-feat-add-bitmask-macro-6424b1c317e2:v8
prerequisite-patch-id: 05dfcf648017dee65c356604e4f99959e76ff64d
prerequisite-change-id: 20260212-impl-flags-inner-c61974b27b18:v1
prerequisite-patch-id: edebc37750dccd8d19db0b8fbd5f69f9877675a2

Best regards,