Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367// SPDX-License-Identifier: GPL-2.0
//! Infrastructure for handling projections.
use core::{ mem::MaybeUninit, ops::Deref, //};
use crate::prelude::*;
/// Error raised when a projection is attempted on an array or slice out of bounds.pub struct OutOfBound;
impl From<OutOfBound> for Error { #[inline(always)] fn from(_: OutOfBound) -> Self { ERANGE }}
/// A helper trait to perform index projection.////// This is similar to [`core::slice::SliceIndex`], but operates on raw pointers safely and/// fallibly.////// # Safety////// For a given input pointer `slice` and return value `output`, the implementation of `index`,/// `build_index` and `get` (if [`Some`] is returned) must ensure that:/// - `output` has the same provenance as `slice`;/// - `output.byte_offset_from(slice)` is between 0 to/// `KnownSize::size(slice) - KnownSize::size(output)`.////// This means that if the input pointer is valid, then the pointer returned by `get`, `index`/// or `build_index` is also valid.#[diagnostic::on_unimplemented(message = "`{Self}` cannot be used to index `{T}`")]#[doc(hidden)]pub unsafe trait ProjectIndex<T: ?Sized>: Sized { type Output: ?Sized;
/// Returns an index-projected pointer, if in bounds. fn get(self, slice: *mut T) -> Option<*mut Self::Output>;
/// Returns an index-projected pointer; panic if out of bounds. fn index(self, slice: *mut T) -> *mut Self::Output;
/// Returns an index-projected pointer; fail the build if it cannot be proved to be in bounds. #[inline(always)] fn build_index(self, slice: *mut T) -> *mut Self::Output { match Self::get(self, slice) { Some(v) => v, None => build_error!(), } }}
// Forward array impl to slice impl.//// SAFETY: Safety requirement guaranteed by the forwarded impl.unsafe impl<T, I, const N: usize> ProjectIndex<[T; N]> for Iwhere I: ProjectIndex<[T]>,{ type Output = <I as ProjectIndex<[T]>>::Output;
#[inline(always)] fn get(self, slice: *mut [T; N]) -> Option<*mut Self::Output> { <I as ProjectIndex<[T]>>::get(self, slice) }
#[inline(always)] fn index(self, slice: *mut [T; N]) -> *mut Self::Output { <I as ProjectIndex<[T]>>::index(self, slice) }
#[inline(always)] fn build_index(self, slice: *mut [T; N]) -> *mut Self::Output { <I as ProjectIndex<[T]>>::build_index(self, slice) }}
// SAFETY: `get`-returned pointer has the same provenance as `slice` and the offset is checked to// not exceed the required bound.unsafe impl<T> ProjectIndex<[T]> for usize { type Output = T;
#[inline(always)] fn get(self, slice: *mut [T]) -> Option<*mut T> { if self >= slice.len() { None } else { Some(slice.cast::<T>().wrapping_add(self)) } }
#[inline(always)] fn index(self, slice: *mut [T]) -> *mut T { // Leverage Rust built-in operators for bounds checking. // SAFETY: All non-null and aligned pointers are valid for ZST read. let zst_slice = unsafe { core::slice::from_raw_parts::<()>(core::ptr::dangling(), slice.len()) }; let () = zst_slice[self]; slice.cast::<T>().wrapping_add(self) }}
// SAFETY: `get`-returned pointer has the same provenance as `slice` and the offset is checked to// not exceed the required bound.unsafe impl<T> ProjectIndex<[T]> for core::ops::Range<usize> { type Output = [T];
#[inline(always)] fn get(self, slice: *mut [T]) -> Option<*mut [T]> { let new_len = self.end.checked_sub(self.start)?; if self.end > slice.len() { return None; } Some(core::ptr::slice_from_raw_parts_mut( slice.cast::<T>().wrapping_add(self.start), new_len, )) }
#[inline(always)] fn index(self, slice: *mut [T]) -> *mut [T] { // Leverage Rust built-in operators for bounds checking. // SAFETY: All non-null and aligned pointers are valid for ZST read. let zst_slice = unsafe { core::slice::from_raw_parts::<()>(core::ptr::dangling(), slice.len()) }; _ = zst_slice[self.clone()];
// SAFETY: Bounds checked. unsafe { self.get(slice).unwrap_unchecked() } }}
// SAFETY: Safety requirement guaranteed by the forwarded impl.unsafe impl<T> ProjectIndex<[T]> for core::ops::RangeTo<usize> { type Output = [T];
#[inline(always)] fn get(self, slice: *mut [T]) -> Option<*mut [T]> { (0..self.end).get(slice) }
#[inline(always)] fn index(self, slice: *mut [T]) -> *mut [T] { (0..self.end).index(slice) }}
// SAFETY: Safety requirement guaranteed by the forwarded impl.unsafe impl<T> ProjectIndex<[T]> for core::ops::RangeFrom<usize> { type Output = [T];
#[inline(always)] fn get(self, slice: *mut [T]) -> Option<*mut [T]> { (self.start..slice.len()).get(slice) }
#[inline(always)] fn index(self, slice: *mut [T]) -> *mut [T] { (self.start..slice.len()).index(slice) }}
// SAFETY: `get` returned the pointer as is, so it always has the same provenance and offset of 0.unsafe impl<T> ProjectIndex<[T]> for core::ops::RangeFull { type Output = [T];
#[inline(always)] fn get(self, slice: *mut [T]) -> Option<*mut [T]> { Some(slice) }
#[inline(always)] fn index(self, slice: *mut [T]) -> *mut [T] { slice }}
/// A helper trait to perform field projection.////// This trait has a `DEREF` generic parameter so it can be implemented twice for types that/// implement [`Deref`]. This will cause an ambiguity error and thus block [`Deref`] types being/// used as base of projection, as they can inject unsoundness. Users therefore must not specify/// `DEREF` and should always leave it to be inferred.////// # Safety////// `proj` may only invoke `f` with a valid allocation, as the documentation of [`Self::proj`]/// describes.#[doc(hidden)]pub unsafe trait ProjectField<const DEREF: bool> { /// Project a pointer to a type to a pointer of a field. /// /// `f` may only be invoked with a valid allocation so it can safely obtain raw pointers to /// fields using `&raw mut`. /// /// This is needed because `base` might not point to a valid allocation, while `&raw mut` /// requires pointers to be in bounds of a valid allocation. /// /// # Safety /// /// `f` must return a pointer in bounds of the provided pointer. unsafe fn proj<F>(base: *mut Self, f: impl FnOnce(*mut Self) -> *mut F) -> *mut F;}
// NOTE: in theory, this API should work for `T: ?Sized` and `F: ?Sized`, too. However, we cannot// currently support that as we need to obtain a valid allocation that `&raw const` can operate on.//// SAFETY: `proj` invokes `f` with valid allocation.unsafe impl<T> ProjectField<false> for T { #[inline(always)] unsafe fn proj<F>(base: *mut Self, f: impl FnOnce(*mut Self) -> *mut F) -> *mut F { // Create a valid allocation to start projection, as `base` is not necessarily so. The // memory is never actually used so it will be optimized out, so it should work even for // very large `T` (`memoffset` crate also relies on this). To be extra certain, we also // annotate `f` closure with `#[inline(always)]` in the macro. let mut place = MaybeUninit::uninit(); let place_base = place.as_mut_ptr(); let field = f(place_base); // SAFETY: `field` is in bounds from `base` per safety requirement. let offset = unsafe { field.byte_offset_from(place_base) }; // Use `wrapping_byte_offset` as `base` does not need to be of valid allocation. base.wrapping_byte_offset(offset).cast() }}
// SAFETY: Vacuously satisfied.unsafe impl<T: Deref> ProjectField<true> for T { #[inline(always)] unsafe fn proj<F>(_: *mut Self, _: impl FnOnce(*mut Self) -> *mut F) -> *mut F { build_error!("this function is a guard against `Deref` impl and is never invoked"); }}
/// Create a projection from a raw pointer.////// The projected pointer is within the memory region marked by the input pointer. There is no/// requirement that the input raw pointer needs to be valid, so this macro may be used for/// projecting pointers outside normal address space, e.g. I/O pointers. However, if the input/// pointer is valid, the projected pointer is also valid.////// Supported projections include field projections and index projections./// It is not allowed to project into types that implement custom [`Deref`] or/// [`Index`](core::ops::Index).////// The macro has basic syntax of `kernel::ptr::project!(ptr, projection)`, where `ptr` is an/// expression that evaluates to a raw pointer which serves as the base of projection. `projection`/// can be a projection expression of form `.field` (normally identifier, or numeral in case of/// tuple structs) or of form `[index]`.////// If a mutable pointer is needed, the macro input can be prefixed with the `mut` keyword, i.e./// `kernel::ptr::project!(mut ptr, projection)`. By default, a const pointer is created.////// The `ptr::project!` macro can perform both fallible indexing and build-time checked indexing./// The syntax is of the form `[<flavor>: index]` where `flavor` indicates the way of handling/// index out-of-bounds errors./// - `try` will raise an [`OutOfBound`] error (which is convertible to [`ERANGE`])./// - `build` will use the [`build_assert!`] mechanism to have the compiler validate the index is/// in bounds./// - `panic` will cause a Rust [`panic!`] if the index goes out of bounds.////// # Examples////// Field projections are performed with `.field_name`:////// ```/// struct MyStruct { field: u32, }/// let ptr: *const MyStruct = core::ptr::dangling();/// let field_ptr: *const u32 = kernel::ptr::project!(ptr, .field);////// struct MyTupleStruct(u32, u32);////// fn proj(ptr: *const MyTupleStruct) {/// let field_ptr: *const u32 = kernel::ptr::project!(ptr, .1);/// }/// ```////// Index projections are performed with `[<flavor>: index]`, where `flavor` is `try`, `build` or/// `panic`:////// ```/// fn proj(ptr: *const [u8; 32]) -> Result {/// let field_ptr: *const u8 = kernel::ptr::project!(ptr, [build: 1]);/// // The following invocation, if uncommented, would fail the build./// ///// // kernel::ptr::project!(ptr, [build: 128]);////// // This will raise an `OutOfBound` error (which is convertible to `ERANGE`)./// kernel::ptr::project!(ptr, [try: 128]);////// // This will panic at runtime if executed./// kernel::ptr::project!(ptr, [panic: 128]);/// Ok(())/// }/// ```////// If you need to match on the error instead of propagate, put the invocation inside a closure:////// ```/// let ptr: *const [u8; 32] = core::ptr::dangling();/// let field_ptr: Result<*const u8> = (|| -> Result<_> {/// Ok(kernel::ptr::project!(ptr, [try: 128]))/// })();/// assert!(field_ptr.is_err());/// ```////// For mutable pointers, put `mut` as the first token in macro invocation.////// ```/// let ptr: *mut [(u8, u16); 32] = core::ptr::dangling_mut();/// let field_ptr: *mut u16 = kernel::ptr::project!(mut ptr, [build: 1].1);/// ```#[macro_export]macro_rules! project_pointer { (@gen $ptr:ident, ) => {}; // Field projection. `$field` needs to be `tt` to support tuple index like `.0`. (@gen $ptr:ident, .$field:tt $($rest:tt)*) => { // SAFETY: The provided closure always returns an in-bounds pointer. let $ptr = unsafe { $crate::ptr::projection::ProjectField::proj($ptr, #[inline(always)] |ptr| { // Check unaligned field. Not all users (e.g. DMA) can handle unaligned // projections. if false { let _ = &(*ptr).$field; } // SAFETY: `$field` is in bounds, and no implicit `Deref` is possible (if the // type implements `Deref`, Rust cannot infer the generic parameter `DEREF`). &raw mut (*ptr).$field }) }; $crate::ptr::project!(@gen $ptr, $($rest)*) }; // Fallible index projection. (@gen $ptr:ident, [try: $index:expr] $($rest:tt)*) => { let $ptr = $crate::ptr::projection::ProjectIndex::get($index, $ptr) .ok_or($crate::ptr::projection::OutOfBound)?; $crate::ptr::project!(@gen $ptr, $($rest)*) }; // Panicking index projection. (@gen $ptr:ident, [panic: $index:expr] $($rest:tt)*) => { let $ptr = $crate::ptr::projection::ProjectIndex::index($index, $ptr); $crate::ptr::project!(@gen $ptr, $($rest)*) }; // Build-time checked index projection. (@gen $ptr:ident, [build: $index:expr] $($rest:tt)*) => { let $ptr = $crate::ptr::projection::ProjectIndex::build_index($index, $ptr); $crate::ptr::project!(@gen $ptr, $($rest)*) };
(mut $ptr:expr, $($proj:tt)*) => {{ let ptr: *mut _ = $ptr; $crate::ptr::project!(@gen ptr, $($proj)*); ptr }}; ($ptr:expr, $($proj:tt)*) => {{ let ptr = <*const _>::cast_mut($ptr); // We currently always project using mutable pointer, as it is not decided whether `&raw // const` allows the resulting pointer to be mutated (see documentation of `addr_of!`). $crate::ptr::project!(@gen ptr, $($proj)*); ptr.cast_const() }};}