From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 9D6F727713; Sat, 14 Jun 2025 19:10:03 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749928203; cv=none; b=RfC5iljkAm0BraHFsw5dfqj+C76yJYPdv1+KJKRm7PTqQ5QitbKOLHa8LRcDjT55W8/tEPUx9h16Ydan61IdrhQeooImQ2bEvLNZmjJguBPFaY84n0gwkjOG5UHNFQ2kgp8pBSBPiikirRtaPfqwEz2DCpgV6Ldp7Qy0XVPcw/g= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749928203; c=relaxed/simple; bh=bjhQYBIAmrs9fPgWYClOvqQFEvjW34DMUYRym/0xXuk=; h=Mime-Version:Content-Type:Date:Message-Id:Cc:Subject:From:To: References:In-Reply-To; b=SV+i/sviqTqf3uJRxii998BclLKURNDlMtu3vhxDB9j7Sjgy1LRXslXgw0ZNeVOXlldesaV/LhFecpN45qgrhSPr+OkYCfyGu5RkoGOPRjBg2n6Yv9WFMrxlG3MGwdBNmhNzWR+vk/LeWYF2emRg+F9lJZVy5Tj87QRo0FyR740= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=LmgLRGRg; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="LmgLRGRg" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BB087C4CEEB; Sat, 14 Jun 2025 19:09:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749928203; bh=bjhQYBIAmrs9fPgWYClOvqQFEvjW34DMUYRym/0xXuk=; h=Date:Cc:Subject:From:To:References:In-Reply-To:From; b=LmgLRGRgImgkAbFP5aE23D9Mnm25p09TaVKJ9zqT+zbRd3MKgHb7Z1K9dmP9jqwC7 yV/6kDzAOmkgICrDQwt9aswCEqh4DgkTQov3DVkY1ESAJy4psz0tc6oIBGD3VtVZa7 bKff5WGCyT7PrORS7yrPCnnp+zoaxJ0+l5JLGDzOtm9jahYAzXGetAf7o1onU1fGV4 dlgPTqsZPmfy3JwO2MOQC/CnRaFbB7/F306yttjk7itM4l+ak5pssywcfBpjHnEs0Q p2H4lsDM0zXPW2QVuAkKYPpDxRc3i1nSshFwsNlqdAkJLJo1Fq8kRpcq8RQEu03S6C iFvRSyLgxgbug== Precedence: bulk X-Mailing-List: rust-for-linux@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=UTF-8 Date: Sat, 14 Jun 2025 21:09:57 +0200 Message-Id: Cc: "John Hubbard" , "Ben Skeggs" , "Joel Fernandes" , "Timur Tabi" , "Alistair Popple" , , , , Subject: Re: [PATCH v5 04/23] rust: add new `num` module with `PowerOfTwo` type From: "Benno Lossin" To: "Alexandre Courbot" , "Miguel Ojeda" , "Alex Gaynor" , "Boqun Feng" , "Gary Guo" , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= , "Andreas Hindborg" , "Alice Ryhl" , "Trevor Gross" , "Danilo Krummrich" , "David Airlie" , "Simona Vetter" , "Maarten Lankhorst" , "Maxime Ripard" , "Thomas Zimmermann" X-Mailer: aerc 0.20.1 References: <20250612-nova-frts-v5-0-14ba7eaf166b@nvidia.com> <20250612-nova-frts-v5-4-14ba7eaf166b@nvidia.com> In-Reply-To: <20250612-nova-frts-v5-4-14ba7eaf166b@nvidia.com> On Thu Jun 12, 2025 at 4:01 PM CEST, Alexandre Courbot wrote: > diff --git a/rust/kernel/num.rs b/rust/kernel/num.rs > new file mode 100644 > index 0000000000000000000000000000000000000000..ee0f67ad1a89e69f5f8d2077e= ba5541b472e7d8a > --- /dev/null > +++ b/rust/kernel/num.rs > @@ -0,0 +1,173 @@ > +// SPDX-License-Identifier: GPL-2.0 > + > +//! Numerical and binary utilities for primitive types. > + > +use crate::build_assert; > +use core::borrow::Borrow; > +use core::fmt::Debug; > +use core::hash::Hash; > +use core::ops::Deref; > + > +/// An unsigned integer which is guaranteed to be a power of 2. > +#[derive(Debug, Clone, Copy)] > +#[repr(transparent)] Let's add a `# Safety` section with the invariant that `T` is a power of 2. Maybe we should even have an `Int` trait for the different integer types that we constrain `T` to. > +pub struct PowerOfTwo(T); > + > +macro_rules! power_of_two_impl { > + ($($t:ty),+) =3D> { > + $( > + impl PowerOfTwo<$t> { > + /// Validates that `v` is a power of two at build-time, = and returns it wrapped into > + /// `PowerOfTwo`. > + /// > + /// A build error is triggered if `v` cannot be asserted= to be a power of two. > + /// > + /// # Examples > + /// > + /// ``` > + /// use kernel::num::PowerOfTwo; > + /// > + /// let v =3D PowerOfTwo::::new(256); > + /// assert_eq!(v.value(), 256); > + /// ``` > + #[inline(always)] > + pub const fn new(v: $t) -> Self { > + build_assert!(v.count_ones() =3D=3D 1); > + Self(v) > + } We also probably want an `unsafe new_unchecked(v: $t) -> Self`. It can still use a `debug_assert!` to verify the value. > + > + /// Validates that `v` is a power of two at runtime, and= returns it wrapped into > + /// `PowerOfTwo`. > + /// > + /// `None` is returned if `v` was not a power of two. > + /// > + /// # Examples > + /// > + /// ``` > + /// use kernel::num::PowerOfTwo; > + /// > + /// assert_eq!(PowerOfTwo::::try_new(16).unwrap().v= alue(), 16); > + /// assert_eq!(PowerOfTwo::::try_new(15), None); > + /// ``` > + #[inline(always)] > + pub const fn try_new(v: $t) -> Option { > + match v.count_ones() { > + 1 =3D> Some(Self(v)), > + _ =3D> None, > + } > + } > + > + /// Returns the value of this instance. > + /// > + /// It is guaranteed to be a power of two. > + /// > + /// # Examples > + /// > + /// ``` > + /// use kernel::num::PowerOfTwo; > + /// > + /// let v =3D PowerOfTwo::::new(256); > + /// assert_eq!(v.value(), 256); > + /// ``` > + #[inline(always)] > + pub const fn value(&self) -> $t { Since this type is `Copy`, we should use `self` here instead of `&self`. Why not add if !self.0.is_power_of_two() { unsafe { ::core::hint::unreachable_unchecked() } } here? > + self.0 > + } > + > + /// Returns the mask corresponding to `self.value() - 1`= . > + #[inline(always)] > + pub const fn mask(&self) -> $t { > + self.0.wrapping_sub(1) And then use `self.value()` here instead? (we could even use `self.value() - 1`, since the optimizer can remove the overflow check: https://godbolt.org/z/nvGaozGMW but wrapping_sub is fine. The optimizations will most likely be more useful in other arithmetic with `.value()`) > + } > + > + /// Aligns `self` down to `alignment`. > + /// > + /// # Examples > + /// > + /// ``` > + /// use kernel::num::PowerOfTwo; > + /// > + /// assert_eq!(PowerOfTwo::::new(0x1000).align_down= (0x4fff), 0x4000); > + /// ``` > + #[inline(always)] > + pub const fn align_down(self, value: $t) -> $t { > + value & !self.mask() > + } > + > + /// Aligns `value` up to `self`. > + /// > + /// Wraps around to `0` if the requested alignment pushe= s the result above the > + /// type's limits. > + /// > + /// # Examples > + /// > + /// ``` > + /// use kernel::num::PowerOfTwo; > + /// > + /// assert_eq!(PowerOfTwo::::new(0x1000).align_up(0= x4fff), 0x5000); > + /// assert_eq!(PowerOfTwo::::new(0x1000).align_up(0= x4000), 0x4000); > + /// assert_eq!(PowerOfTwo::::new(0x1000).align_up(0= x0), 0x0); > + /// assert_eq!(PowerOfTwo::::new(0x100).align_up(0x= ffff), 0x0); > + /// ``` > + #[inline(always)] > + pub const fn align_up(self, value: $t) -> $t { > + self.align_down(value.wrapping_add(self.mask())) > + } > + } > + )+ > + }; > +} > + > +power_of_two_impl!(usize, u8, u16, u32, u64, u128); > + > +impl Deref for PowerOfTwo { > + type Target =3D T; > + > + fn deref(&self) -> &Self::Target { > + &self.0 > + } > +} > + > +impl PartialEq for PowerOfTwo > +where > + T: PartialEq, > +{ > + fn eq(&self, other: &Self) -> bool { > + self.0 =3D=3D other.0 > + } > +} > + > +impl Eq for PowerOfTwo where T: Eq {} > + > +impl PartialOrd for PowerOfTwo > +where > + T: PartialOrd, > +{ > + fn partial_cmp(&self, other: &Self) -> Option { > + self.0.partial_cmp(&other.0) > + } > +} > + > +impl Ord for PowerOfTwo > +where > + T: Ord, > +{ > + fn cmp(&self, other: &Self) -> core::cmp::Ordering { > + self.0.cmp(&other.0) > + } > +} > + > +impl Hash for PowerOfTwo > +where > + T: Hash, > +{ > + fn hash(&self, state: &mut H) { > + self.0.hash(state); > + } > +} Can't these traits also be implemented using the derive macros? --- Cheers, Benno > + > +impl Borrow for PowerOfTwo { > + fn borrow(&self) -> &T { > + &self.0 > + } > +}