// SPDX-License-Identifier: GPL-2.0 //! Memory-mapped IO.//!//! C header: [`include/asm-generic/io.h`](srctree/include/asm-generic/io.h) use core::{ marker::PhantomData, mem::MaybeUninit, //}; use crate::{ bindings, prelude::*, ptr::{ Alignment, KnownSize, // }, //}; #[cfg(CONFIG_HAS_IOMEM)]pub mod mem;pub mod poll;pub mod register;pub mod resource; pub use crate::register;pub use resource::Resource; use register::LocatedRegister; /// Physical address type.////// This is a type alias to either `u32` or `u64` depending on the config option/// `CONFIG_PHYS_ADDR_T_64BIT`, and it can be a u64 even on 32-bit architectures.pub type PhysAddr = bindings::phys_addr_t; /// Resource Size type.////// This is a type alias to either `u32` or `u64` depending on the config option/// `CONFIG_PHYS_ADDR_T_64BIT`, and it can be a u64 even on 32-bit architectures.pub type ResourceSize = bindings::resource_size_t; /// Untyped I/O region.////// This type can be used when an I/O region without known type information has a compile-time known/// minimum size (and a runtime known actual size).////// # Invariants////// - Size of the region is at least as large as the `SIZE` generic parameter./// - Size of the region is multiple of 4.#[repr(C, align(4))]#[derive(FromBytes)]pub struct Region<const SIZE: usize = 0> { inner: [u8],} impl<const SIZE: usize> Region<SIZE> { /// Create a raw mutable pointer from given base address and size. /// /// `size` should be at least as large as the minimum size `SIZE`, and `base` and `size` should /// be 4-byte aligned to uphold the type invariant. /// /// Just like other methods on raw pointers, it is not unsafe to create a raw pointer /// that does not uphold the type invariants. However such pointers are not valid. #[inline] pub fn ptr_from_raw_parts_mut(base: *mut u8, size: usize) -> *mut Self { core::ptr::slice_from_raw_parts_mut(base, size) as *mut Region<SIZE> } /// Create a raw mutable pointer from given base address and size. /// /// The alignment of `base` is checked, and `size` is checked against the minimum size specified /// via const generics. #[inline] pub fn ptr_try_from_raw_parts_mut(base: *mut u8, size: usize) -> Result<*mut Self> { if size < SIZE || base.align_offset(4) != 0 || !size.is_multiple_of(4) { return Err(EINVAL); } Ok(Self::ptr_from_raw_parts_mut(base, size)) }} impl<const SIZE: usize> KnownSize for Region<SIZE> { const MIN_SIZE: usize = SIZE; // Alignment of 4 is the most common; different base types can be added once required. const MIN_ALIGN: Alignment = Alignment::new::<4>(); #[inline(always)] fn size(p: *const Self) -> usize { (p as *const [u8]).len() }} // SAFETY:// - Values read from I/O are always treated as initialized.// - Per type invariant the size is multiple of 4 and the type is 4-byte aligned, so it is padding// free.//// This cannot be derived as `derive(IntoBytes)` as the padding free property comes from type// invariant which the macro does not know.unsafe impl<const SIZE: usize> IntoBytes for Region<SIZE> { #[inline] #[allow(unused)] // Rust 1.87+ stops requiring this and will emit unused warnings. fn only_derive_is_allowed_to_implement_this_trait() {}} /// Raw representation of an MMIO region.////// `MmioRaw<T>` is equivalent to `T __iomem *` in C.////// By itself, the existence of an instance of this structure does not provide any guarantees that/// the represented MMIO region does exist or is properly mapped.////// Instead, the bus specific MMIO implementation must convert this raw representation into an/// `Mmio` instance providing the actual memory accessors. Only by the conversion into an `Mmio`/// structure any guarantees are given.pub struct MmioRaw<T: ?Sized> { /// Pointer is in I/O address space. /// /// The provenance does not matter, only the address and metadata do. ptr: *mut T,} impl<T: ?Sized> Copy for MmioRaw<T> {}impl<T: ?Sized> Clone for MmioRaw<T> { #[inline] fn clone(&self) -> Self { *self }} // SAFETY: `MmioRaw` is just an address, so is thread-safe.unsafe impl<T: ?Sized> Send for MmioRaw<T> {}// SAFETY: `MmioRaw` is just an address, so is thread-safe.unsafe impl<T: ?Sized> Sync for MmioRaw<T> {} impl<T> MmioRaw<T> { /// Create a `MmioRaw` from address. #[inline] pub fn new(addr: usize) -> Self { Self { ptr: core::ptr::without_provenance_mut(addr), } }} impl<const SIZE: usize> MmioRaw<Region<SIZE>> { /// Create a `MmioRaw` representing a I/O region with given size. /// /// The size is checked against the minimum size specified via const generics. #[inline] pub fn new_region(addr: usize, size: usize) -> Result<Self> { Ok(Self { ptr: Region::ptr_try_from_raw_parts_mut(core::ptr::without_provenance_mut(addr), size)?, }) }} impl<T: ?Sized + KnownSize> MmioRaw<T> { /// Returns the base address of the MMIO region. #[inline] pub fn addr(&self) -> usize { self.ptr.addr() } /// Returns the size of the MMIO region. #[inline] pub fn size(&self) -> usize { KnownSize::size(self.ptr) }} /// Checks whether an access of type `U` at the given `base` and the given `offset`/// is valid within this region.////// The `base` is used for alignment checking only. This can be set to 0 to skip the check.#[inline]const fn offset_valid<U>(base: usize, offset: usize, size: usize) -> bool { if let Some(end) = offset.checked_add(size_of::<U>()) { end <= size && (base.wrapping_add(offset) % align_of::<U>() == 0) } else { false }} /// Returns a view for a given `offset`, performing compile-time bound checks.// Always inline to optimize out error path of `build_assert`.#[inline(always)]fn io_view_assert<'a, IO: Io<'a>, U>( this: IO, offset: usize,) -> <IO::Backend as IoBackend>::View<'a, U> { // We cannot check alignment with `offset_valid` using `ptr.addr()`. So set 0 for it and // ensure alignment by checking that the alignment of `U` is smaller or equal to the // alignment of `IO::Target`. const_assert!(Alignment::of::<U>().as_usize() <= IO::Target::MIN_ALIGN.as_usize()); build_assert!(offset_valid::<U>(0, offset, IO::Target::MIN_SIZE)); let view = this.as_view(); let ptr = IO::Backend::as_ptr(view); let projected_ptr = ptr.cast::<U>().wrapping_byte_add(offset); // SAFETY: `offset_valid` checks for size and alignment and therefore `projected_ptr` is a // valid projection. unsafe { IO::Backend::project_view(view, projected_ptr) }} /// Returns a view for a given `offset`, performing runtime bound checks.#[inline]fn io_view<'a, IO: Io<'a>, U>( this: IO, offset: usize,) -> Result<<IO::Backend as IoBackend>::View<'a, U>> { let view = this.as_view(); let ptr = IO::Backend::as_ptr(view); if !offset_valid::<U>(ptr.addr(), offset, KnownSize::size(ptr)) { return Err(EINVAL); } let projected_ptr = ptr.cast::<U>().wrapping_byte_add(offset); // SAFETY: `offset_valid` checks for size and alignment and therefore `projected_ptr` is a // valid projection. Ok(unsafe { IO::Backend::project_view(view, projected_ptr) })} /// I/O backends.////// This is an abstract representation to be implemented by arbitrary I/O/// backends (e.g. MMIO, PCI config space, etc.).////// The base trait only defines the projection operations; which I/O methods are available depends/// on which [`IoCapable<T>`] traits are implemented for the type. For example, for MMIO regions,/// all widths (u8, u16, u32, and u64 on 64-bit systems) are typically supported. For PCI/// configuration space, u8, u16, and u32 are supported but u64 is not.////// This trait is separate from the `Io` trait as multiple different I/O types may share the same/// operation.pub trait IoBackend { /// View type for this I/O backend. type View<'a, T: ?Sized + KnownSize>: IoBase<'a, Backend = Self, Target = T>; /// Convert a `view` to a raw pointer for projection. /// /// The returned pointer is private implementation detail of the backend; it is likely not /// valid. It should not be dereferenced. fn as_ptr<'a, T: ?Sized + KnownSize>(view: Self::View<'a, T>) -> *mut T; /// Project `view` to its subregion indicated by `ptr`. /// /// If input `view` is valid, returned view must also be valid. /// /// # Safety /// /// `ptr` must be a projection of `Self::as_ptr(view)`. unsafe fn project_view<'a, T: ?Sized + KnownSize, U: ?Sized + KnownSize>( view: Self::View<'a, T>, ptr: *mut U, ) -> Self::View<'a, U>;} /// Trait indicating that an I/O backend supports operations of a certain type and providing an/// implementation for these operations.////// Different I/O backends can implement this trait to expose only the operations they support.////// For example, a PCI configuration space may implement `IoCapable<u8>`, `IoCapable<u16>`,/// and `IoCapable<u32>`, but not `IoCapable<u64>`, while an MMIO region on a 64-bit/// system might implement all four.pub trait IoCapable<T>: IoBackend { /// Performs an I/O read of type `T` at `view` and returns the result. fn io_read<'a>(view: Self::View<'a, T>) -> T; /// Performs an I/O write of `value` at `view`. fn io_write<'a>(view: Self::View<'a, T>, value: T);} /// Trait indicating that an I/O backend supports memory copy operations.pub trait IoCopyable: IoBackend { /// Copy contents of `view` to `buffer`. /// /// # Safety /// /// - `buffer` is valid for volatile write for `view.size()` bytes. /// - `buffer` should not overlap with `view`. unsafe fn copy_from_io(view: Self::View<'_, [u8]>, buffer: *mut u8); /// Copy contents from `buffer` to `view`. /// /// # Safety /// /// - `buffer` is valid for volatile read for `view.size()` bytes. /// - `buffer` should not overlap with `view`. unsafe fn copy_to_io(view: Self::View<'_, [u8]>, buffer: *const u8); /// Copy from `view` and return the value. #[inline] fn copy_read<T: FromBytes>(view: Self::View<'_, T>) -> T { // Project `self` to `[u8]`. let ptr = Self::as_ptr(view); // SAFETY: This is a identity projection. let slice_view = unsafe { Self::project_view( view, core::ptr::slice_from_raw_parts_mut::<u8>(ptr.cast(), size_of::<T>()), ) }; let mut buf = MaybeUninit::<T>::uninit(); // SAFETY: // - `buf.as_mut_ptr()` is valid for write for `size_of::<T>()` bytes. // - `buf` is local so `buf.as_mut_ptr()` cannot overlap with `slice_view`. unsafe { Self::copy_from_io(slice_view, buf.as_mut_ptr().cast()) }; // SAFETY: `T: FromBytes` guarantee that all bit patterns are valid. unsafe { buf.assume_init() } } /// Copy `value` to `view`. /// /// Destructor of `value` will not be executed, consistent with [`zerocopy::transmute`]. #[inline] fn copy_write<T: IntoBytes>(view: Self::View<'_, T>, value: T) { // Project `self` to `[u8]`. let ptr = Self::as_ptr(view); // SAFETY: This is a identity projection. let slice_view = unsafe { Self::project_view( view, core::ptr::slice_from_raw_parts_mut::<u8>(ptr.cast(), size_of::<T>()), ) }; // SAFETY: // - `&raw const value` is valid for read for `size_of::<T>()` bytes. // - `value` is local so `&raw const value` cannot overlap with `slice_view`. unsafe { Self::copy_to_io(slice_view, (&raw const value).cast()) }; core::mem::forget(value); }} /// Describes a given I/O location: its offset, width, and type to convert the raw value from and/// into.////// This trait is the key abstraction allowing [`Io::read`], [`Io::write`], and [`Io::update`] (and/// their fallible [`try_read`](Io::try_read), [`try_write`](Io::try_write) and/// [`try_update`](Io::try_update) counterparts) to work uniformly with both raw [`usize`] offsets/// (for primitive types like [`u32`]) and typed ones (like those generated by the [`register!`]/// macro).////// An `IoLoc<Base, T>` carries the following pieces of information:////// - The valid `Base` to operate on. For most registers, this should be [`Region`]./// - The offset to access (returned by [`IoLoc::offset`]),/// - The width of the access (determined by [`IoLoc::IoType`]),/// - The type `T` in which the raw data is returned or provided.////// `T` and `IoLoc::IoType` may differ: for instance, a typed register has `T` = the register type/// with its bitfields, and `IoType` = its backing primitive (e.g. `u32`).pub trait IoLoc<Base: ?Sized, T> { /// Size ([`u8`], [`u16`], etc) of the I/O performed on the returned [`offset`](IoLoc::offset). type IoType: Into<T> + From<T>; /// Consumes `self` and returns the offset of this location. fn offset(self) -> usize;} /// Implements [`IoLoc<Region<SIZE>, $ty>`] for [`usize`], allowing [`usize`] to be used as a/// parameter of [`Io::read`] and [`Io::write`].macro_rules! impl_usize_ioloc { ($($ty:ty),*) => { $( impl<const SIZE: usize> IoLoc<Region<SIZE>, $ty> for usize { type IoType = $ty; #[inline(always)] fn offset(self) -> usize { self } } )* }} // Provide the ability to read any primitive type from a [`usize`].impl_usize_ioloc!(u8, u16, u32, u64); /// Types implementing this trait (e.g. MMIO BARs or PCI config regions)/// can perform I/O operations on regions of memory.////// This trait defines which backend shall be used for I/O operations and provides a method to/// convert into [`IoBackend::View`]. Users should use the [`Io`] trait which provides the actual/// methods to perform I/O operations.////// This should be implemented on cheaply copyable handles, such as references or view types.pub trait IoBase<'a>: Copy { /// Type that defines all I/O operations. type Backend: IoBackend; /// Type of this I/O region. For untyped regions, [`Region`] can be used. type Target: ?Sized + KnownSize; /// Return a view that covers the full region. fn as_view(self) -> <Self::Backend as IoBackend>::View<'a, Self::Target>;} /// Extension trait to provide I/O operation methods to types that implement [`IoBase`].////// This trait provides:/// - Helper methods for offset validation and address calculation/// - Fallible (runtime checked) accessors for different data widths////// Which I/O methods are available depends on the associated [`IoBackend`] implementation.pub trait Io<'a>: IoBase<'a> { /// Returns the size of this I/O region. #[inline] fn size(self) -> usize { KnownSize::size(Self::Backend::as_ptr(self.as_view())) } /// Returns the length of the slice in number of elements. #[inline] fn len<T>(self) -> usize where Self: Io<'a, Target = [T]>, { Self::Backend::as_ptr(self.as_view()).len() } /// Returns `true` if the slice has a length of 0. #[inline] fn is_empty<T>(self) -> bool where Self: Io<'a, Target = [T]>, { self.len() == 0 } /// Try to convert into a different typed I/O view. /// /// A runtime check is performed to ensure that the target type is of same or smaller size to /// current type, and the current view is properly aligned for the target type. Returns /// `Err(EINVAL)` if the runtime check fails. /// /// # Examples /// /// ```no_run /// use kernel::io::{ /// io_project, /// Mmio, /// Io, /// Region, /// }; /// #[derive(FromBytes, IntoBytes)] /// #[repr(C)] /// struct MyStruct { field: u32, } /// /// # fn test(mmio: &Mmio<'_, Region>) -> Result { /// // let mmio: Mmio<'_, Region>; /// let whole: Mmio<'_, MyStruct> = mmio.try_cast()?; /// # Ok::<(), Error>(()) } /// ``` #[inline] fn try_cast<U>(self) -> Result<<Self::Backend as IoBackend>::View<'a, U>> where Self::Target: FromBytes + IntoBytes, U: FromBytes + IntoBytes, { let view = self.as_view(); let ptr = Self::Backend::as_ptr(view); if size_of::<U>() > KnownSize::size(ptr) { return Err(EINVAL); } if ptr.addr() % align_of::<U>() != 0 { return Err(EINVAL); } // SAFETY: We have checked bounds and alignment, so this is a valid projection. Ok(unsafe { Self::Backend::project_view(view, ptr.cast()) }) } /// Read a value from I/O. /// /// This only works for primitives supported by the I/O backend. /// /// # Examples /// /// ```no_run /// # use kernel::io::*; /// # fn test_read_val(mmio: Mmio<'_, u32>) { /// // let mmio: Mmio<'_, u32>; /// let val: u32 = mmio.read_val(); /// # } /// ``` #[inline] fn read_val(self) -> Self::Target whereLines 1–500 of 1754. Load more
// SPDX-License-Identifier: GPL-2.0 //! Memory-mapped IO. //! //! C header: [`include/asm-generic/io.h`](srctree/include/asm-generic/io.h) use core::{ marker::PhantomData, mem::MaybeUninit, // }; use crate::{ bindings, prelude::*, ptr::{ Alignment, KnownSize, // }, // }; #[cfg(CONFIG_HAS_IOMEM)] pub mod mem; pub mod poll; pub mod register; pub mod resource; pub use crate::register; pub use resource::Resource; use register::LocatedRegister; /// Physical address type. /// /// This is a type alias to either `u32` or `u64` depending on the config option /// `CONFIG_PHYS_ADDR_T_64BIT`, and it can be a u64 even on 32-bit architectures. pub type PhysAddr = bindings::phys_addr_t; /// Resource Size type. /// /// This is a type alias to either `u32` or `u64` depending on the config option /// `CONFIG_PHYS_ADDR_T_64BIT`, and it can be a u64 even on 32-bit architectures. pub type ResourceSize = bindings::resource_size_t; /// Untyped I/O region. /// /// This type can be used when an I/O region without known type information has a compile-time known /// minimum size (and a runtime known actual size). /// /// # Invariants /// /// - Size of the region is at least as large as the `SIZE` generic parameter. /// - Size of the region is multiple of 4. #[repr(C, align(4))] #[derive(FromBytes)] pub struct Region<const SIZE: usize = 0> { inner: [u8], } impl<const SIZE: usize> Region<SIZE> { /// Create a raw mutable pointer from given base address and size. /// /// `size` should be at least as large as the minimum size `SIZE`, and `base` and `size` should /// be 4-byte aligned to uphold the type invariant. /// /// Just like other methods on raw pointers, it is not unsafe to create a raw pointer /// that does not uphold the type invariants. However such pointers are not valid. #[inline] pub fn ptr_from_raw_parts_mut(base: *mut u8, size: usize) -> *mut Self { core::ptr::slice_from_raw_parts_mut(base, size) as *mut Region<SIZE> } /// Create a raw mutable pointer from given base address and size. /// /// The alignment of `base` is checked, and `size` is checked against the minimum size specified /// via const generics. #[inline] pub fn ptr_try_from_raw_parts_mut(base: *mut u8, size: usize) -> Result<*mut Self> { if size < SIZE || base.align_offset(4) != 0 || !size.is_multiple_of(4) { return Err(EINVAL); } Ok(Self::ptr_from_raw_parts_mut(base, size)) } } impl<const SIZE: usize> KnownSize for Region<SIZE> { const MIN_SIZE: usize = SIZE; // Alignment of 4 is the most common; different base types can be added once required. const MIN_ALIGN: Alignment = Alignment::new::<4>(); #[inline(always)] fn size(p: *const Self) -> usize { (p as *const [u8]).len() } } // SAFETY: // - Values read from I/O are always treated as initialized. // - Per type invariant the size is multiple of 4 and the type is 4-byte aligned, so it is padding // free. // // This cannot be derived as `derive(IntoBytes)` as the padding free property comes from type // invariant which the macro does not know. unsafe impl<const SIZE: usize> IntoBytes for Region<SIZE> { #[inline] #[allow(unused)] // Rust 1.87+ stops requiring this and will emit unused warnings. fn only_derive_is_allowed_to_implement_this_trait() {} } /// Raw representation of an MMIO region. /// /// `MmioRaw<T>` is equivalent to `T __iomem *` in C. /// /// By itself, the existence of an instance of this structure does not provide any guarantees that /// the represented MMIO region does exist or is properly mapped. /// /// Instead, the bus specific MMIO implementation must convert this raw representation into an /// `Mmio` instance providing the actual memory accessors. Only by the conversion into an `Mmio` /// structure any guarantees are given. pub struct MmioRaw<T: ?Sized> { /// Pointer is in I/O address space. /// /// The provenance does not matter, only the address and metadata do. ptr: *mut T, } impl<T: ?Sized> Copy for MmioRaw<T> {} impl<T: ?Sized> Clone for MmioRaw<T> { #[inline] fn clone(&self) -> Self { *self } } // SAFETY: `MmioRaw` is just an address, so is thread-safe. unsafe impl<T: ?Sized> Send for MmioRaw<T> {} // SAFETY: `MmioRaw` is just an address, so is thread-safe. unsafe impl<T: ?Sized> Sync for MmioRaw<T> {} impl<T> MmioRaw<T> { /// Create a `MmioRaw` from address. #[inline] pub fn new(addr: usize) -> Self { Self { ptr: core::ptr::without_provenance_mut(addr), } } } impl<const SIZE: usize> MmioRaw<Region<SIZE>> { /// Create a `MmioRaw` representing a I/O region with given size. /// /// The size is checked against the minimum size specified via const generics. #[inline] pub fn new_region(addr: usize, size: usize) -> Result<Self> { Ok(Self { ptr: Region::ptr_try_from_raw_parts_mut(core::ptr::without_provenance_mut(addr), size)?, }) } } impl<T: ?Sized + KnownSize> MmioRaw<T> { /// Returns the base address of the MMIO region. #[inline] pub fn addr(&self) -> usize { self.ptr.addr() } /// Returns the size of the MMIO region. #[inline] pub fn size(&self) -> usize { KnownSize::size(self.ptr) } } /// Checks whether an access of type `U` at the given `base` and the given `offset` /// is valid within this region. /// /// The `base` is used for alignment checking only. This can be set to 0 to skip the check. #[inline] const fn offset_valid<U>(base: usize, offset: usize, size: usize) -> bool { if let Some(end) = offset.checked_add(size_of::<U>()) { end <= size && (base.wrapping_add(offset) % align_of::<U>() == 0) } else { false } } /// Returns a view for a given `offset`, performing compile-time bound checks. // Always inline to optimize out error path of `build_assert`. #[inline(always)] fn io_view_assert<'a, IO: Io<'a>, U>( this: IO, offset: usize, ) -> <IO::Backend as IoBackend>::View<'a, U> { // We cannot check alignment with `offset_valid` using `ptr.addr()`. So set 0 for it and // ensure alignment by checking that the alignment of `U` is smaller or equal to the // alignment of `IO::Target`. const_assert!(Alignment::of::<U>().as_usize() <= IO::Target::MIN_ALIGN.as_usize()); build_assert!(offset_valid::<U>(0, offset, IO::Target::MIN_SIZE)); let view = this.as_view(); let ptr = IO::Backend::as_ptr(view); let projected_ptr = ptr.cast::<U>().wrapping_byte_add(offset); // SAFETY: `offset_valid` checks for size and alignment and therefore `projected_ptr` is a // valid projection. unsafe { IO::Backend::project_view(view, projected_ptr) } } /// Returns a view for a given `offset`, performing runtime bound checks. #[inline] fn io_view<'a, IO: Io<'a>, U>( this: IO, offset: usize, ) -> Result<<IO::Backend as IoBackend>::View<'a, U>> { let view = this.as_view(); let ptr = IO::Backend::as_ptr(view); if !offset_valid::<U>(ptr.addr(), offset, KnownSize::size(ptr)) { return Err(EINVAL); } let projected_ptr = ptr.cast::<U>().wrapping_byte_add(offset); // SAFETY: `offset_valid` checks for size and alignment and therefore `projected_ptr` is a // valid projection. Ok(unsafe { IO::Backend::project_view(view, projected_ptr) }) } /// I/O backends. /// /// This is an abstract representation to be implemented by arbitrary I/O /// backends (e.g. MMIO, PCI config space, etc.). /// /// The base trait only defines the projection operations; which I/O methods are available depends /// on which [`IoCapable<T>`] traits are implemented for the type. For example, for MMIO regions, /// all widths (u8, u16, u32, and u64 on 64-bit systems) are typically supported. For PCI /// configuration space, u8, u16, and u32 are supported but u64 is not. /// /// This trait is separate from the `Io` trait as multiple different I/O types may share the same /// operation. pub trait IoBackend { /// View type for this I/O backend. type View<'a, T: ?Sized + KnownSize>: IoBase<'a, Backend = Self, Target = T>; /// Convert a `view` to a raw pointer for projection. /// /// The returned pointer is private implementation detail of the backend; it is likely not /// valid. It should not be dereferenced. fn as_ptr<'a, T: ?Sized + KnownSize>(view: Self::View<'a, T>) -> *mut T; /// Project `view` to its subregion indicated by `ptr`. /// /// If input `view` is valid, returned view must also be valid. /// /// # Safety /// /// `ptr` must be a projection of `Self::as_ptr(view)`. unsafe fn project_view<'a, T: ?Sized + KnownSize, U: ?Sized + KnownSize>( view: Self::View<'a, T>, ptr: *mut U, ) -> Self::View<'a, U>; } /// Trait indicating that an I/O backend supports operations of a certain type and providing an /// implementation for these operations. /// /// Different I/O backends can implement this trait to expose only the operations they support. /// /// For example, a PCI configuration space may implement `IoCapable<u8>`, `IoCapable<u16>`, /// and `IoCapable<u32>`, but not `IoCapable<u64>`, while an MMIO region on a 64-bit /// system might implement all four. pub trait IoCapable<T>: IoBackend { /// Performs an I/O read of type `T` at `view` and returns the result. fn io_read<'a>(view: Self::View<'a, T>) -> T; /// Performs an I/O write of `value` at `view`. fn io_write<'a>(view: Self::View<'a, T>, value: T); } /// Trait indicating that an I/O backend supports memory copy operations. pub trait IoCopyable: IoBackend { /// Copy contents of `view` to `buffer`. /// /// # Safety /// /// - `buffer` is valid for volatile write for `view.size()` bytes. /// - `buffer` should not overlap with `view`. unsafe fn copy_from_io(view: Self::View<'_, [u8]>, buffer: *mut u8); /// Copy contents from `buffer` to `view`. /// /// # Safety /// /// - `buffer` is valid for volatile read for `view.size()` bytes. /// - `buffer` should not overlap with `view`. unsafe fn copy_to_io(view: Self::View<'_, [u8]>, buffer: *const u8); /// Copy from `view` and return the value. #[inline] fn copy_read<T: FromBytes>(view: Self::View<'_, T>) -> T { // Project `self` to `[u8]`. let ptr = Self::as_ptr(view); // SAFETY: This is a identity projection. let slice_view = unsafe { Self::project_view( view, core::ptr::slice_from_raw_parts_mut::<u8>(ptr.cast(), size_of::<T>()), ) }; let mut buf = MaybeUninit::<T>::uninit(); // SAFETY: // - `buf.as_mut_ptr()` is valid for write for `size_of::<T>()` bytes. // - `buf` is local so `buf.as_mut_ptr()` cannot overlap with `slice_view`. unsafe { Self::copy_from_io(slice_view, buf.as_mut_ptr().cast()) }; // SAFETY: `T: FromBytes` guarantee that all bit patterns are valid. unsafe { buf.assume_init() } } /// Copy `value` to `view`. /// /// Destructor of `value` will not be executed, consistent with [`zerocopy::transmute`]. #[inline] fn copy_write<T: IntoBytes>(view: Self::View<'_, T>, value: T) { // Project `self` to `[u8]`. let ptr = Self::as_ptr(view); // SAFETY: This is a identity projection. let slice_view = unsafe { Self::project_view( view, core::ptr::slice_from_raw_parts_mut::<u8>(ptr.cast(), size_of::<T>()), ) }; // SAFETY: // - `&raw const value` is valid for read for `size_of::<T>()` bytes. // - `value` is local so `&raw const value` cannot overlap with `slice_view`. unsafe { Self::copy_to_io(slice_view, (&raw const value).cast()) }; core::mem::forget(value); } } /// Describes a given I/O location: its offset, width, and type to convert the raw value from and /// into. /// /// This trait is the key abstraction allowing [`Io::read`], [`Io::write`], and [`Io::update`] (and /// their fallible [`try_read`](Io::try_read), [`try_write`](Io::try_write) and /// [`try_update`](Io::try_update) counterparts) to work uniformly with both raw [`usize`] offsets /// (for primitive types like [`u32`]) and typed ones (like those generated by the [`register!`] /// macro). /// /// An `IoLoc<Base, T>` carries the following pieces of information: /// /// - The valid `Base` to operate on. For most registers, this should be [`Region`]. /// - The offset to access (returned by [`IoLoc::offset`]), /// - The width of the access (determined by [`IoLoc::IoType`]), /// - The type `T` in which the raw data is returned or provided. /// /// `T` and `IoLoc::IoType` may differ: for instance, a typed register has `T` = the register type /// with its bitfields, and `IoType` = its backing primitive (e.g. `u32`). pub trait IoLoc<Base: ?Sized, T> { /// Size ([`u8`], [`u16`], etc) of the I/O performed on the returned [`offset`](IoLoc::offset). type IoType: Into<T> + From<T>; /// Consumes `self` and returns the offset of this location. fn offset(self) -> usize; } /// Implements [`IoLoc<Region<SIZE>, $ty>`] for [`usize`], allowing [`usize`] to be used as a /// parameter of [`Io::read`] and [`Io::write`]. macro_rules! impl_usize_ioloc { ($($ty:ty),*) => { $( impl<const SIZE: usize> IoLoc<Region<SIZE>, $ty> for usize { type IoType = $ty; #[inline(always)] fn offset(self) -> usize { self } } )* } } // Provide the ability to read any primitive type from a [`usize`]. impl_usize_ioloc!(u8, u16, u32, u64); /// Types implementing this trait (e.g. MMIO BARs or PCI config regions) /// can perform I/O operations on regions of memory. /// /// This trait defines which backend shall be used for I/O operations and provides a method to /// convert into [`IoBackend::View`]. Users should use the [`Io`] trait which provides the actual /// methods to perform I/O operations. /// /// This should be implemented on cheaply copyable handles, such as references or view types. pub trait IoBase<'a>: Copy { /// Type that defines all I/O operations. type Backend: IoBackend; /// Type of this I/O region. For untyped regions, [`Region`] can be used. type Target: ?Sized + KnownSize; /// Return a view that covers the full region. fn as_view(self) -> <Self::Backend as IoBackend>::View<'a, Self::Target>; } /// Extension trait to provide I/O operation methods to types that implement [`IoBase`]. /// /// This trait provides: /// - Helper methods for offset validation and address calculation /// - Fallible (runtime checked) accessors for different data widths /// /// Which I/O methods are available depends on the associated [`IoBackend`] implementation. pub trait Io<'a>: IoBase<'a> { /// Returns the size of this I/O region. #[inline] fn size(self) -> usize { KnownSize::size(Self::Backend::as_ptr(self.as_view())) } /// Returns the length of the slice in number of elements. #[inline] fn len<T>(self) -> usize where Self: Io<'a, Target = [T]>, { Self::Backend::as_ptr(self.as_view()).len() } /// Returns `true` if the slice has a length of 0. #[inline] fn is_empty<T>(self) -> bool where Self: Io<'a, Target = [T]>, { self.len() == 0 } /// Try to convert into a different typed I/O view. /// /// A runtime check is performed to ensure that the target type is of same or smaller size to /// current type, and the current view is properly aligned for the target type. Returns /// `Err(EINVAL)` if the runtime check fails. /// /// # Examples /// /// ```no_run /// use kernel::io::{ /// io_project, /// Mmio, /// Io, /// Region, /// }; /// #[derive(FromBytes, IntoBytes)] /// #[repr(C)] /// struct MyStruct { field: u32, } /// /// # fn test(mmio: &Mmio<'_, Region>) -> Result { /// // let mmio: Mmio<'_, Region>; /// let whole: Mmio<'_, MyStruct> = mmio.try_cast()?; /// # Ok::<(), Error>(()) } /// ``` #[inline] fn try_cast<U>(self) -> Result<<Self::Backend as IoBackend>::View<'a, U>> where Self::Target: FromBytes + IntoBytes, U: FromBytes + IntoBytes, { let view = self.as_view(); let ptr = Self::Backend::as_ptr(view); if size_of::<U>() > KnownSize::size(ptr) { return Err(EINVAL); } if ptr.addr() % align_of::<U>() != 0 { return Err(EINVAL); } // SAFETY: We have checked bounds and alignment, so this is a valid projection. Ok(unsafe { Self::Backend::project_view(view, ptr.cast()) }) } /// Read a value from I/O. /// /// This only works for primitives supported by the I/O backend. /// /// # Examples /// /// ```no_run /// # use kernel::io::*; /// # fn test_read_val(mmio: Mmio<'_, u32>) { /// // let mmio: Mmio<'_, u32>; /// let val: u32 = mmio.read_val(); /// # } /// ``` #[inline] fn read_val(self) -> Self::Target where