Currently, using NonZero/Bounded constants is quite verbose. It's
unfortunate because it disincentivizes using it in interface boundaries.
Introduce a macro to make it nicer to use. The macro `cv!` (for constant
value) takes a const integer expression and widens it to i128 (at build
time only) before passing it as a const generic value to a new trait
`FromConst`. The value is then converted and appears in the
associated constant `FromConst::VALUE`. The trait is implemented by
NonZero, Bounded, and Alignment and lets values of each be constructed
from constants without a verbose turbofish syntax.
For example, `const { NonZero::new(1).unwrap() }` can be written as
`cv!(1)`.
Add the `cv!` macro to the prelude so it doesn't need to be imported
explicitly to use it.
Suggested-by: Gary Guo <[email protected]>
Reviewed-by: Gary Guo <[email protected]>
Acked-by: Miguel Ojeda <[email protected]>
Reviewed-by: Alice Ryhl <[email protected]>
Acked-by: Danilo Krummrich <[email protected]>
Signed-off-by: Eliot Courtney <[email protected]>
---
rust/kernel/num.rs | 149 +++++++++++++++++++++++++++++++++++++++++++++
rust/kernel/num/bounded.rs | 16 +++++
rust/kernel/prelude.rs | 1 +
rust/kernel/ptr.rs | 12 +++-
4 files changed, 177 insertions(+), 1 deletion(-)
diff --git a/rust/kernel/num.rs b/rust/kernel/num.rs
index dbe848e30efe..a387a94e97e7 100644
--- a/rust/kernel/num.rs
+++ b/rust/kernel/num.rs
@@ -79,3 +79,152 @@ impl Integer for $type {
i128: Signed,
isize: Signed
);
+
+/// Creates a constant value ("cv") from an integer constant expression, with
validity checked at
+/// compile time.
+///
+/// This works for any type that implements [`FromConst`], with the target
type inferred from
+/// the context, or named explicitly with `cv!(value => Type)`. It can also be
used in const
+/// contexts.
+///
+/// # Pitfalls
+///
+/// Only the target type is inferred from the context. The expression passed
to `cv!` is typed by
+/// itself. So, unsuffixed integer literal expressions default to `i32`. For
example `cv!(2 << 31)`
+/// does not evaluate to the same value as `cv!(2i64 << 31)`, since `2 << 31`
is treated as an `i32`
+/// before being widened to `i128` internally. Literals and arithmetic
expressions that overflow
+/// `i32` are a compile error, it's just left shifts that require care.
+///
+/// # Examples
+///
+/// ```
+/// use core::num::NonZero;
+///
+/// use kernel::{
+/// num::Bounded,
+/// ptr::Alignment, //
+/// };
+///
+/// let v: NonZero<usize> = cv!(8);
+/// assert_eq!(v.get(), 8);
+///
+/// // Any integer constant expression works, not only literals.
+/// let m: NonZero<usize> = cv!(usize::MAX);
+/// assert_eq!(m.get(), usize::MAX);
+///
+/// let b: Bounded<u32, 4> = cv!(15);
+/// assert_eq!(b.get(), 15);
+///
+/// let a: Alignment = cv!(4096);
+/// assert_eq!(a.as_usize(), 4096);
+///
+/// // Checked narrowing of integer constants, including in `const` items.
+/// const SMALL: u8 = cv!(200u32);
+/// assert_eq!(SMALL, 200);
+///
+/// const N: NonZero<u8> = cv!(5);
+/// assert_eq!(N.get(), 5);
+///
+/// // The target type can be given explicitly.
+/// let e = cv!(200u32 => u8);
+/// assert_eq!(e, 200);
+///
+/// // With an explicit primitive target, the expression can use generic
parameters.
+/// const fn as_u64<const KEY: u16>() -> u64 {
+/// cv!(KEY => u64)
+/// }
+/// assert_eq!(as_u64::<0x40>(), 0x40);
+/// ```
+#[macro_export]
+#[doc(hidden)]
+macro_rules! cv {
+ (@cast $v:expr => $t:ty) => {
+ const {
+ #[allow(unused_comparisons, unused_assignments,
clippy::as_underscore)]
+ {
+ let v = $v;
+ let r = v as $t;
+ // Pin `back` to `v`'s type so `as _` casts back to the source
type.
+ let mut back = v;
+ back = r as _;
+
+ ::core::assert!(
+ back == v && (v < 0) == (r < 0),
+ "value does not fit into the target type"
+ );
+
+ r
+ }
+ }
+ };
+
+ // Using `FromConst<V>::VALUE` means const generic expressions can't be
used, since it requires
+ // the `generic_const_exprs` feature. Provide a special path for each
primitive type that allows
+ // const generic expressions.
+ ($v:expr => u8) => { $crate::cv!(@cast $v => u8) };
+ ($v:expr => u16) => { $crate::cv!(@cast $v => u16) };
+ ($v:expr => u32) => { $crate::cv!(@cast $v => u32) };
+ ($v:expr => u64) => { $crate::cv!(@cast $v => u64) };
+ ($v:expr => u128) => { $crate::cv!(@cast $v => u128) };
+ ($v:expr => usize) => { $crate::cv!(@cast $v => usize) };
+ ($v:expr => i8) => { $crate::cv!(@cast $v => i8) };
+ ($v:expr => i16) => { $crate::cv!(@cast $v => i16) };
+ ($v:expr => i32) => { $crate::cv!(@cast $v => i32) };
+ ($v:expr => i64) => { $crate::cv!(@cast $v => i64) };
+ ($v:expr => i128) => { $crate::cv!(@cast $v => i128) };
+ ($v:expr => isize) => { $crate::cv!(@cast $v => isize) };
+ ($v:expr => $t:ty) => {
+ <$t as $crate::num::FromConst<{ $crate::cv!(@cast $v => i128)
}>>::VALUE
+ };
+ ($v:expr) => {
+ <_ as $crate::num::FromConst<{ $crate::cv!(@cast $v => i128) }>>::VALUE
+ };
+}
+#[doc(inline)]
+pub use cv;
+
+/// Types that can be created from an integer constant expression validated at
compile time.
+///
+/// Implement this trait to make a type usable with [`cv!`]. Use the [`cv!`]
macro, not this trait
+/// directly, for creating values.
+#[diagnostic::on_unimplemented(message = "`{Self}` cannot be converted from a
constant")]
+pub trait FromConst<const V: i128>: Sized {
+ /// The value that corresponds to the constant `V`.
+ ///
+ /// Fails the build if `V` is not a valid value for [`Self`].
+ const VALUE: Self;
+}
+
+/// Implements [`FromConst`] for primitive integer types and their
[`NonZero`](core::num::NonZero)
+/// versions.
+macro_rules! impl_from_const {
+ ($($type:ty)*) => {
+ $(
+ impl<const V: i128> FromConst<V> for $type {
+ const VALUE: Self = {
+ // CAST: The macro is only used for types up to 64 bits wide,
so `MIN` and `MAX`
+ // widen to `i128` losslessly.
+ assert!(
+ V >= <$type>::MIN as i128 && V <= <$type>::MAX as i128,
+ "constant cannot be represented by the target type"
+ );
+
+ // CAST: The assert above confirmed that `V` fits in `$type`.
+ V as $type
+ };
+ }
+
+ impl<const V: i128> FromConst<V> for core::num::NonZero<$type> {
+ const VALUE: Self = match core::num::NonZero::new(<$type as
FromConst<V>>::VALUE) {
+ Some(value) => value,
+ None => panic!("constant cannot be zero"),
+ };
+ }
+ )*
+ };
+}
+
+impl_from_const!(
+ u8 u16 u32 u64 usize
+ i8 i16 i32 i64 isize
+);
diff --git a/rust/kernel/num/bounded.rs b/rust/kernel/num/bounded.rs
index 2a2b0a4bca5e..0b32f4343922 100644
--- a/rust/kernel/num/bounded.rs
+++ b/rust/kernel/num/bounded.rs
@@ -14,6 +14,7 @@
use kernel::{
num::{
+ FromConst,
Integer,
Unsigned, //
},
@@ -272,6 +273,21 @@ pub const fn new<const VALUE: $type>() -> Self {
unsafe { Self::__new(VALUE) }
}
}
+
+ impl<const N: u32, const V: i128> FromConst<V> for Bounded<$type, N> {
+ const VALUE: Self = {
+ let value = <$type as FromConst<V>>::VALUE;
+ // Statically assert that `value` fits within the set number
of bits.
+ assert!(
+ fits_within!(value, $type, N),
+ "constant cannot be represented within the given number of
bits"
+ );
+
+ // SAFETY: The assert above confirmed that `value` can be
represented within `N`
+ // bits.
+ unsafe { Self::__new(value) }
+ };
+ }
)*
};
}
diff --git a/rust/kernel/prelude.rs b/rust/kernel/prelude.rs
index ca396f1f78a6..5facf8f7af90 100644
--- a/rust/kernel/prelude.rs
+++ b/rust/kernel/prelude.rs
@@ -106,6 +106,7 @@
Result, //
},
init::InPlaceInit,
+ num::cv,
pr_alert,
pr_crit,
pr_debug,
diff --git a/rust/kernel/ptr.rs b/rust/kernel/ptr.rs
index 82acb531b17b..2c12e4fd4572 100644
--- a/rust/kernel/ptr.rs
+++ b/rust/kernel/ptr.rs
@@ -11,7 +11,10 @@
};
use core::num::NonZero;
-use crate::const_assert;
+use crate::{
+ const_assert,
+ num::FromConst, //
+};
/// Type representing an alignment, which is always a power of two.
///
@@ -166,6 +169,13 @@ pub const fn mask(self) -> usize {
}
}
+impl<const V: i128> FromConst<V> for Alignment {
+ const VALUE: Self = match Alignment::new_checked(<usize as
FromConst<V>>::VALUE) {
+ Some(alignment) => alignment,
+ None => panic!("constant is not a power of two"),
+ };
+}
+
/// Trait for items that can be aligned against an [`Alignment`].
pub trait Alignable: Sized {
/// Aligns `self` down to `alignment`.
--
2.56.0
