[PATCH v4] rust: kernel: add support for bits/genmask macros

[PATCH v4] rust: kernel: add support for bits/genmask macros

[Daniel Almeida]

In light of bindgen being unable to generate bindings for macros,
manually define the bit and genmask C macros in Rust.

Bit and genmask are frequently used in drivers, and are simple enough to
just be redefined. Their implementation is also unlikely to ever change.

These macros are converted from their kernel equivalent. Since
genmask_u32 and genmask_u64 are thought to suffice, these two versions
are implemented as const fns instead of declarative macros.

Reviewed-by: Fiona Behrens <me@kloenk.dev>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>
---
Changes in v4:
- Split bits into bits_u32 and bits_u64
- Added r-b's
- Rebased on top of rust-next
- Link to v3: https://lore.kernel.org/r/20250121-topic-panthor-rs-genmask-v3-1-5c3bdf21ce05@collabora.com

Changes in v3:
- Changed from declarative macro to const fn
- Added separate versions for u32 and u64
- Link to v2: https://lore.kernel.org/r/20241024-topic-panthor-rs-genmask-v2-1-85237c1f0cea@collabora.com

Changes in v2:

- Added ticks around `BIT`, and `h >=l` (Thanks, Benno).
- Decided to keep the arguments as `expr`, as I see no issues with that
- Added a proper example, with an assert_eq!() (Thanks, Benno)
- Fixed the condition h <= l, which should be h >= l.
- Checked that the assert for the condition above is described in the
  docs.
---
 rust/kernel/bits.rs | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 rust/kernel/lib.rs  |  1 +
 2 files changed, 50 insertions(+)

diff --git a/rust/kernel/bits.rs b/rust/kernel/bits.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ec13bb480082de9584b7d23c78df0e76d0fbf132
--- /dev/null
+++ b/rust/kernel/bits.rs
@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Bit manipulation macros.
+//!
+//! C header: [`include/linux/bits.h`](srctree/include/linux/bits.h)
+
+/// Produces a literal where bit `n` is set.
+///
+/// Equivalent to the kernel's `BIT` macro.
+pub const fn bit_u32(n: u32) -> u32 {
+    1 << n
+}
+
+/// Produces a literal where bit `n` is set.
+///
+/// Equivalent to the kernel's `BIT` macro.
+pub const fn bit_u64(n: u32) -> u64 {
+    1u64 << n as u64
+}
+
+/// Create a contiguous bitmask starting at bit position `l` and ending at
+/// position `h`, where `h >= l`.
+///
+/// # Examples
+/// ```
+///     use kernel::bits::genmask_u64;
+///     let mask = genmask_u64(39, 21);
+///     assert_eq!(mask, 0x000000ffffe00000);
+/// ```
+///
+pub const fn genmask_u64(h: u32, l: u32) -> u64 {
+    assert!(h >= l);
+    (!0u64 - (1u64 << l) + 1) & (!0u64 >> (64 - 1 - h))
+}
+
+/// Create a contiguous bitmask starting at bit position `l` and ending at
+/// position `h`, where `h >= l`.
+///
+/// # Examples
+/// ```
+///     use kernel::bits::genmask_u32;
+///     let mask = genmask_u32(9, 0);
+///     assert_eq!(mask, 0x000003ff);
+/// ```
+///
+pub const fn genmask_u32(h: u32, l: u32) -> u32 {
+    assert!(h >= l);
+    (!0u32 - (1u32 << l) + 1) & (!0u32 >> (32 - 1 - h))
+}
diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
index c92497c7c655e8faefd85bb4a1d5b4cc696b8499..a90aaf7fe6755a5a42055b7b4008714fcafe6f6f 100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -36,6 +36,7 @@
 pub use ffi;
 
 pub mod alloc;
+pub mod bits;
 #[cfg(CONFIG_BLOCK)]
 pub mod block;
 #[doc(hidden)]

---
base-commit: cf25bc61f8aecad9b0c45fe32697e35ea4b13378
change-id: 20241023-topic-panthor-rs-genmask-fabc573fef43

Best regards,
-- 
Daniel Almeida <daniel.almeida@collabora.com>

Re: [PATCH v4] rust: kernel: add support for bits/genmask macros

[Alexandre Courbot]

Hi Daniel,

On Wed Mar 19, 2025 at 12:34 AM JST, Daniel Almeida wrote:
> In light of bindgen being unable to generate bindings for macros,
> manually define the bit and genmask C macros in Rust.
>
> Bit and genmask are frequently used in drivers, and are simple enough to
> just be redefined. Their implementation is also unlikely to ever change.
>
> These macros are converted from their kernel equivalent. Since
> genmask_u32 and genmask_u64 are thought to suffice, these two versions
> are implemented as const fns instead of declarative macros.
>
> Reviewed-by: Fiona Behrens <me@kloenk.dev>
> Reviewed-by: Alice Ryhl <aliceryhl@google.com>
> Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>

Cool, I'll probably depend on this for the next version of my register
layout patch [1].

[1]
https://lore.kernel.org/rust-for-linux/20250313-registers-v1-1-8d498537e8b2@nvidia.com/

> ---
> Changes in v4:
> - Split bits into bits_u32 and bits_u64
> - Added r-b's
> - Rebased on top of rust-next
> - Link to v3: https://lore.kernel.org/r/20250121-topic-panthor-rs-genmask-v3-1-5c3bdf21ce05@collabora.com
>
> Changes in v3:
> - Changed from declarative macro to const fn
> - Added separate versions for u32 and u64
> - Link to v2: https://lore.kernel.org/r/20241024-topic-panthor-rs-genmask-v2-1-85237c1f0cea@collabora.com
>
> Changes in v2:
>
> - Added ticks around `BIT`, and `h >=l` (Thanks, Benno).
> - Decided to keep the arguments as `expr`, as I see no issues with that
> - Added a proper example, with an assert_eq!() (Thanks, Benno)
> - Fixed the condition h <= l, which should be h >= l.
> - Checked that the assert for the condition above is described in the
>   docs.
> ---
>  rust/kernel/bits.rs | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
>  rust/kernel/lib.rs  |  1 +
>  2 files changed, 50 insertions(+)
>
> diff --git a/rust/kernel/bits.rs b/rust/kernel/bits.rs
> new file mode 100644
> index 0000000000000000000000000000000000000000..ec13bb480082de9584b7d23c78df0e76d0fbf132
> --- /dev/null
> +++ b/rust/kernel/bits.rs
> @@ -0,0 +1,49 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Bit manipulation macros.
> +//!
> +//! C header: [`include/linux/bits.h`](srctree/include/linux/bits.h)
> +
> +/// Produces a literal where bit `n` is set.
> +///
> +/// Equivalent to the kernel's `BIT` macro.
> +pub const fn bit_u32(n: u32) -> u32 {
> +    1 << n
> +}
> +
> +/// Produces a literal where bit `n` is set.
> +///
> +/// Equivalent to the kernel's `BIT` macro.
> +pub const fn bit_u64(n: u32) -> u64 {
> +    1u64 << n as u64
> +}
> +
> +/// Create a contiguous bitmask starting at bit position `l` and ending at
> +/// position `h`, where `h >= l`.
> +///
> +/// # Examples
> +/// ```
> +///     use kernel::bits::genmask_u64;
> +///     let mask = genmask_u64(39, 21);
> +///     assert_eq!(mask, 0x000000ffffe00000);
> +/// ```
> +///
> +pub const fn genmask_u64(h: u32, l: u32) -> u64 {
> +    assert!(h >= l);
> +    (!0u64 - (1u64 << l) + 1) & (!0u64 >> (64 - 1 - h))
> +}
> +
> +/// Create a contiguous bitmask starting at bit position `l` and ending at
> +/// position `h`, where `h >= l`.
> +///
> +/// # Examples
> +/// ```
> +///     use kernel::bits::genmask_u32;
> +///     let mask = genmask_u32(9, 0);
> +///     assert_eq!(mask, 0x000003ff);
> +/// ```
> +///
> +pub const fn genmask_u32(h: u32, l: u32) -> u32 {
> +    assert!(h >= l);
> +    (!0u32 - (1u32 << l) + 1) & (!0u32 >> (32 - 1 - h))
> +}

Would it make sense to also have u16 and u8 variants? I guess one can
always use genmask_u32 and then cast to the desired type though.

Re: [PATCH v4] rust: kernel: add support for bits/genmask macros

[Alexandre Courbot]

On Wed Mar 19, 2025 at 11:25 PM JST, Alexandre Courbot wrote:
> Hi Daniel,
>
> On Wed Mar 19, 2025 at 12:34 AM JST, Daniel Almeida wrote:
>> In light of bindgen being unable to generate bindings for macros,
>> manually define the bit and genmask C macros in Rust.
>>
>> Bit and genmask are frequently used in drivers, and are simple enough to
>> just be redefined. Their implementation is also unlikely to ever change.
>>
>> These macros are converted from their kernel equivalent. Since
>> genmask_u32 and genmask_u64 are thought to suffice, these two versions
>> are implemented as const fns instead of declarative macros.
>>
>> Reviewed-by: Fiona Behrens <me@kloenk.dev>
>> Reviewed-by: Alice Ryhl <aliceryhl@google.com>
>> Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>
>
> Cool, I'll probably depend on this for the next version of my register
> layout patch [1].
>
> [1]
> https://lore.kernel.org/rust-for-linux/20250313-registers-v1-1-8d498537e8b2@nvidia.com/
>
>> ---
>> Changes in v4:
>> - Split bits into bits_u32 and bits_u64
>> - Added r-b's
>> - Rebased on top of rust-next
>> - Link to v3: https://lore.kernel.org/r/20250121-topic-panthor-rs-genmask-v3-1-5c3bdf21ce05@collabora.com
>>
>> Changes in v3:
>> - Changed from declarative macro to const fn
>> - Added separate versions for u32 and u64
>> - Link to v2: https://lore.kernel.org/r/20241024-topic-panthor-rs-genmask-v2-1-85237c1f0cea@collabora.com
>>
>> Changes in v2:
>>
>> - Added ticks around `BIT`, and `h >=l` (Thanks, Benno).
>> - Decided to keep the arguments as `expr`, as I see no issues with that
>> - Added a proper example, with an assert_eq!() (Thanks, Benno)
>> - Fixed the condition h <= l, which should be h >= l.
>> - Checked that the assert for the condition above is described in the
>>   docs.
>> ---
>>  rust/kernel/bits.rs | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
>>  rust/kernel/lib.rs  |  1 +
>>  2 files changed, 50 insertions(+)
>>
>> diff --git a/rust/kernel/bits.rs b/rust/kernel/bits.rs
>> new file mode 100644
>> index 0000000000000000000000000000000000000000..ec13bb480082de9584b7d23c78df0e76d0fbf132
>> --- /dev/null
>> +++ b/rust/kernel/bits.rs
>> @@ -0,0 +1,49 @@
>> +// SPDX-License-Identifier: GPL-2.0
>> +
>> +//! Bit manipulation macros.
>> +//!
>> +//! C header: [`include/linux/bits.h`](srctree/include/linux/bits.h)
>> +
>> +/// Produces a literal where bit `n` is set.
>> +///
>> +/// Equivalent to the kernel's `BIT` macro.
>> +pub const fn bit_u32(n: u32) -> u32 {
>> +    1 << n
>> +}
>> +
>> +/// Produces a literal where bit `n` is set.
>> +///
>> +/// Equivalent to the kernel's `BIT` macro.
>> +pub const fn bit_u64(n: u32) -> u64 {
>> +    1u64 << n as u64
>> +}
>> +
>> +/// Create a contiguous bitmask starting at bit position `l` and ending at
>> +/// position `h`, where `h >= l`.
>> +///
>> +/// # Examples
>> +/// ```
>> +///     use kernel::bits::genmask_u64;
>> +///     let mask = genmask_u64(39, 21);
>> +///     assert_eq!(mask, 0x000000ffffe00000);
>> +/// ```
>> +///
>> +pub const fn genmask_u64(h: u32, l: u32) -> u64 {
>> +    assert!(h >= l);
>> +    (!0u64 - (1u64 << l) + 1) & (!0u64 >> (64 - 1 - h))
>> +}
>> +
>> +/// Create a contiguous bitmask starting at bit position `l` and ending at
>> +/// position `h`, where `h >= l`.
>> +///
>> +/// # Examples
>> +/// ```
>> +///     use kernel::bits::genmask_u32;
>> +///     let mask = genmask_u32(9, 0);
>> +///     assert_eq!(mask, 0x000003ff);
>> +/// ```
>> +///
>> +pub const fn genmask_u32(h: u32, l: u32) -> u32 {
>> +    assert!(h >= l);
>> +    (!0u32 - (1u32 << l) + 1) & (!0u32 >> (32 - 1 - h))
>> +}
>
> Would it make sense to also have u16 and u8 variants? I guess one can
> always use genmask_u32 and then cast to the desired type though.

Forgot to mention:

Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Tested-by: Alexandre Courbot <acourbot@nvidia.com>

Re: [PATCH v4] rust: kernel: add support for bits/genmask macros

[Daniel Almeida]

Hi Alex,

> Would it make sense to also have u16 and u8 variants? I guess one can
> always use genmask_u32 and then cast to the desired type though.

There’s no u16 and u8 variants because I did not think there would be users. 

I can add them otherwise, IMHO we should refrain from using casts when possible.

— Daniel

Re: [PATCH v4] rust: kernel: add support for bits/genmask macros

[Alexandre Courbot]

On Thu Mar 20, 2025 at 10:50 PM JST, Daniel Almeida wrote:
> Hi Alex,
>
>> Would it make sense to also have u16 and u8 variants? I guess one can
>> always use genmask_u32 and then cast to the desired type though.
>
> There’s no u16 and u8 variants because I did not think there would be users. 
>
> I can add them otherwise, IMHO we should refrain from using casts when possible.

The plan with the register definition macros is to also support 16-bit
and 8-bit registers, in this case it would be useful to have these as
well.

Since the body of these functions is roughly the same, maybe you can use
a macro to define all the variants?