rust/kernel/num/bounded.rs

Source file repositories/reference/linux-study-clean/rust/kernel/num/bounded.rs

File Facts

System
Linux kernel
Corpus path
rust/kernel/num/bounded.rs
Extension
.rs
Size
32899 bytes
Lines
1122
Domain
Rust Kernel Layer
Bucket
Rust API Membrane
Inferred role
Rust Kernel Layer: implementation source
Status
source implementation candidate

Why This File Exists

Rust-side wrappers and abstractions around kernel C APIs, ownership contracts, allocation, synchronization, and module integration.

Dependency Surface

Detected Declarations

Annotated Snippet

// SPDX-License-Identifier: GPL-2.0

//! Implementation of [`Bounded`], a wrapper around integer types limiting the number of bits
//! usable for value representation.

use core::{
    cmp,
    fmt,
    ops::{
        self,
        Deref, //
    }, //,
};

use kernel::{
    num::Integer,
    prelude::*, //
};

/// Evaluates to `true` if `$value` can be represented using at most `$n` bits in a `$type`.
///
/// `expr` must be of type `type`, or the result will be incorrect.
///
/// Can be used in const context.
macro_rules! fits_within {
    ($value:expr, $type:ty, $n:expr) => {{
        let shift: u32 = <$type>::BITS - $n;

        // `value` fits within `$n` bits if shifting it left by the number of unused bits, then
        // right by the same number, doesn't change it.
        //
        // This method has the benefit of working for both unsigned and signed values.
        ($value << shift) >> shift == $value
    }};
}

/// Returns `true` if `value` can be represented with at most `N` bits in a `T`.
#[inline(always)]
fn fits_within<T: Integer>(value: T, num_bits: u32) -> bool {
    fits_within!(value, T, num_bits)
}

/// An integer value that requires only the `N` least significant bits of the wrapped type to be
/// encoded.
///
/// This limits the number of usable bits in the wrapped integer type, and thus the stored value to
/// a narrower range, which provides guarantees that can be useful when working within e.g.
/// bitfields.
///
/// # Invariants
///
/// - `N` is greater than `0`.
/// - `N` is less than or equal to `T::BITS`.
/// - Stored values can be represented with at most `N` bits.
///
/// # Examples
///
/// The preferred way to create values is through constants and the [`Bounded::new`] family of
/// constructors, as they trigger a build error if the type invariants cannot be upheld.
///
/// ```
/// use kernel::num::Bounded;
///
/// // An unsigned 8-bit integer, of which only the 4 LSBs are used.
/// // The value `15` is statically validated to fit that constraint at build time.
/// let v = Bounded::<u8, 4>::new::<15>();
/// assert_eq!(v.get(), 15);
///
/// // Same using signed values.
/// let v = Bounded::<i8, 4>::new::<-8>();
/// assert_eq!(v.get(), -8);
///
/// // This doesn't build: a `u8` is smaller than the requested 9 bits.
/// // let _ = Bounded::<u8, 9>::new::<10>();
///
/// // This also doesn't build: the requested value doesn't fit within 4 signed bits.
/// // let _ = Bounded::<i8, 4>::new::<8>();
/// ```
///
/// Values can also be validated at runtime with [`Bounded::try_new`].
///
/// ```
/// use kernel::num::Bounded;
///
/// // This succeeds because `15` can be represented with 4 unsigned bits.
/// assert!(Bounded::<u8, 4>::try_new(15).is_some());
///
/// // This fails because `16` cannot be represented with 4 unsigned bits.
/// assert!(Bounded::<u8, 4>::try_new(16).is_none());
/// ```

Annotation

Implementation Notes