rust: num: bounded: mark __new as unsafe

The `Bounded::__new()` constructor relies on the caller to ensure the
value can be represented within N bits. Failing to uphold this
requirement breaks the type invariant. Mark it as unsafe and document
this requirement in a Safety section to make the contract explicit.

Update all call sites to use unsafe blocks and change their comments
from `INVARIANT:` to `SAFETY:`, as they are now justifying unsafe
operations rather than establishing type invariants.

Fixes: 01e345e82ec3a ("rust: num: add Bounded integer wrapping type")
Link: https://lore.kernel.org/all/aS1qC_ol2XEpZ44b@google.com/
Reported-by: Miguel Ojeda <ojeda@kernel.org>
Closes: https://github.com/Rust-for-Linux/linux/issues/1211
Signed-off-by: Hsiu Che Yu <yu.whisper.personal@gmail.com>
Acked-by: Alexandre Courbot <acourbot@nvidia.com>
Link: https://patch.msgid.link/20251204033849.23480-1-yu.whisper.personal@gmail.com
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

authored by

Hsiu Che Yu and committed by

Miguel Ojeda 6 months ago 3a1ec424 609db7e7

+19 -15

1 changed file

expand all

rust

kernel

num

bounded.rs

+19 -15

rust/kernel/num/bounded.rs

··· 259 259 assert!(fits_within!(VALUE, $type, N)); 260 260 } 261 261 262 - // INVARIANT: `fits_within` confirmed that `VALUE` can be represented within 262 + // SAFETY: `fits_within` confirmed that `VALUE` can be represented within 263 263 // `N` bits. 264 - Self::__new(VALUE) 264 + unsafe { Self::__new(VALUE) } 265 265 } 266 266 } 267 267 )* ··· 284 284 /// 285 285 /// The caller remains responsible for checking, either statically or dynamically, that `value` 286 286 /// can be represented as a `T` using at most `N` bits. 287 - const fn __new(value: T) -> Self { 287 + /// 288 + /// # Safety 289 + /// 290 + /// The caller must ensure that `value` can be represented within `N` bits. 291 + const unsafe fn __new(value: T) -> Self { 288 292 // Enforce the type invariants. 289 293 const { 290 294 // `N` cannot be zero. ··· 332 328 /// ``` 333 329 pub fn try_new(value: T) -> Option<Self> { 334 330 fits_within(value, N).then(|| { 335 - // INVARIANT: `fits_within` confirmed that `value` can be represented within `N` bits. 336 - Self::__new(value) 331 + // SAFETY: `fits_within` confirmed that `value` can be represented within `N` bits. 332 + unsafe { Self::__new(value) } 337 333 }) 338 334 } 339 335 ··· 374 370 "Requested value larger than maximal representable value." 375 371 ); 376 372 377 - // INVARIANT: `fits_within` confirmed that `expr` can be represented within `N` bits. 378 - Self::__new(expr) 373 + // SAFETY: `fits_within` confirmed that `expr` can be represented within `N` bits. 374 + unsafe { Self::__new(expr) } 379 375 } 380 376 381 377 /// Returns the wrapped value as the backing type. ··· 414 410 ); 415 411 } 416 412 417 - // INVARIANT: The value did fit within `N` bits, so it will all the more fit within 413 + // SAFETY: The value did fit within `N` bits, so it will all the more fit within 418 414 // the larger `M` bits. 419 - Bounded::__new(self.0) 415 + unsafe { Bounded::__new(self.0) } 420 416 } 421 417 422 418 /// Attempts to shrink the number of bits usable for `self`. ··· 470 466 // `U` and `T` have the same sign, hence this conversion cannot fail. 471 467 let value = unsafe { U::try_from(self.get()).unwrap_unchecked() }; 472 468 473 - // INVARIANT: Although the backing type has changed, the value is still represented within 469 + // SAFETY: Although the backing type has changed, the value is still represented within 474 470 // `N` bits, and with the same signedness. 475 - Bounded::__new(value) 471 + unsafe { Bounded::__new(value) } 476 472 } 477 473 } 478 474 ··· 948 944 Self: AtLeastXBits<{ <$type as Integer>::BITS as usize }>, 949 945 { 950 946 fn from(value: $type) -> Self { 951 - // INVARIANT: The trait bound on `Self` guarantees that `N` bits is 947 + // SAFETY: The trait bound on `Self` guarantees that `N` bits is 952 948 // enough to hold any value of the source type. 953 - Self::__new(T::from(value)) 949 + unsafe { Self::__new(T::from(value)) } 954 950 } 955 951 } 956 952 )* ··· 1055 1051 T: Integer + From<bool>, 1056 1052 { 1057 1053 fn from(value: bool) -> Self { 1058 - // INVARIANT: A boolean can be represented using a single bit, and thus fits within any 1054 + // SAFETY: A boolean can be represented using a single bit, and thus fits within any 1059 1055 // integer type for any `N` > 0. 1060 - Self::__new(T::from(value)) 1056 + unsafe { Self::__new(T::from(value)) } 1061 1057 } 1062 1058 }

Configure Feed

Configure Feed