kernel/
io.rs

1// SPDX-License-Identifier: GPL-2.0
2
3//! Memory-mapped IO.
4//!
5//! C header: [`include/asm-generic/io.h`](srctree/include/asm-generic/io.h)
6
7use crate::{
8    bindings,
9    prelude::*, //
10};
11
12pub mod mem;
13pub mod poll;
14pub mod resource;
15
16pub use resource::Resource;
17
18/// Physical address type.
19///
20/// This is a type alias to either `u32` or `u64` depending on the config option
21/// `CONFIG_PHYS_ADDR_T_64BIT`, and it can be a u64 even on 32-bit architectures.
22pub type PhysAddr = bindings::phys_addr_t;
23
24/// Resource Size type.
25///
26/// This is a type alias to either `u32` or `u64` depending on the config option
27/// `CONFIG_PHYS_ADDR_T_64BIT`, and it can be a u64 even on 32-bit architectures.
28pub type ResourceSize = bindings::resource_size_t;
29
30/// Raw representation of an MMIO region.
31///
32/// By itself, the existence of an instance of this structure does not provide any guarantees that
33/// the represented MMIO region does exist or is properly mapped.
34///
35/// Instead, the bus specific MMIO implementation must convert this raw representation into an `Io`
36/// instance providing the actual memory accessors. Only by the conversion into an `Io` structure
37/// any guarantees are given.
38pub struct IoRaw<const SIZE: usize = 0> {
39    addr: usize,
40    maxsize: usize,
41}
42
43impl<const SIZE: usize> IoRaw<SIZE> {
44    /// Returns a new `IoRaw` instance on success, an error otherwise.
45    pub fn new(addr: usize, maxsize: usize) -> Result<Self> {
46        if maxsize < SIZE {
47            return Err(EINVAL);
48        }
49
50        Ok(Self { addr, maxsize })
51    }
52
53    /// Returns the base address of the MMIO region.
54    #[inline]
55    pub fn addr(&self) -> usize {
56        self.addr
57    }
58
59    /// Returns the maximum size of the MMIO region.
60    #[inline]
61    pub fn maxsize(&self) -> usize {
62        self.maxsize
63    }
64}
65
66/// IO-mapped memory region.
67///
68/// The creator (usually a subsystem / bus such as PCI) is responsible for creating the
69/// mapping, performing an additional region request etc.
70///
71/// # Invariant
72///
73/// `addr` is the start and `maxsize` the length of valid I/O mapped memory region of size
74/// `maxsize`.
75///
76/// # Examples
77///
78/// ```no_run
79/// use kernel::{
80///     bindings,
81///     ffi::c_void,
82///     io::{
83///         Io,
84///         IoRaw,
85///         PhysAddr,
86///     },
87/// };
88/// use core::ops::Deref;
89///
90/// // See also [`pci::Bar`] for a real example.
91/// struct IoMem<const SIZE: usize>(IoRaw<SIZE>);
92///
93/// impl<const SIZE: usize> IoMem<SIZE> {
94///     /// # Safety
95///     ///
96///     /// [`paddr`, `paddr` + `SIZE`) must be a valid MMIO region that is mappable into the CPUs
97///     /// virtual address space.
98///     unsafe fn new(paddr: usize) -> Result<Self>{
99///         // SAFETY: By the safety requirements of this function [`paddr`, `paddr` + `SIZE`) is
100///         // valid for `ioremap`.
101///         let addr = unsafe { bindings::ioremap(paddr as PhysAddr, SIZE) };
102///         if addr.is_null() {
103///             return Err(ENOMEM);
104///         }
105///
106///         Ok(IoMem(IoRaw::new(addr as usize, SIZE)?))
107///     }
108/// }
109///
110/// impl<const SIZE: usize> Drop for IoMem<SIZE> {
111///     fn drop(&mut self) {
112///         // SAFETY: `self.0.addr()` is guaranteed to be properly mapped by `Self::new`.
113///         unsafe { bindings::iounmap(self.0.addr() as *mut c_void); };
114///     }
115/// }
116///
117/// impl<const SIZE: usize> Deref for IoMem<SIZE> {
118///    type Target = Io<SIZE>;
119///
120///    fn deref(&self) -> &Self::Target {
121///         // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`.
122///         unsafe { Io::from_raw(&self.0) }
123///    }
124/// }
125///
126///# fn no_run() -> Result<(), Error> {
127/// // SAFETY: Invalid usage for example purposes.
128/// let iomem = unsafe { IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD)? };
129/// iomem.write32(0x42, 0x0);
130/// assert!(iomem.try_write32(0x42, 0x0).is_ok());
131/// assert!(iomem.try_write32(0x42, 0x4).is_err());
132/// # Ok(())
133/// # }
134/// ```
135#[repr(transparent)]
136pub struct Io<const SIZE: usize = 0>(IoRaw<SIZE>);
137
138macro_rules! define_read {
139    ($(#[$attr:meta])* $name:ident, $try_name:ident, $c_fn:ident -> $type_name:ty) => {
140        /// Read IO data from a given offset known at compile time.
141        ///
142        /// Bound checks are performed on compile time, hence if the offset is not known at compile
143        /// time, the build will fail.
144        $(#[$attr])*
145        #[inline]
146        pub fn $name(&self, offset: usize) -> $type_name {
147            let addr = self.io_addr_assert::<$type_name>(offset);
148
149            // SAFETY: By the type invariant `addr` is a valid address for MMIO operations.
150            unsafe { bindings::$c_fn(addr as *const c_void) }
151        }
152
153        /// Read IO data from a given offset.
154        ///
155        /// Bound checks are performed on runtime, it fails if the offset (plus the type size) is
156        /// out of bounds.
157        $(#[$attr])*
158        pub fn $try_name(&self, offset: usize) -> Result<$type_name> {
159            let addr = self.io_addr::<$type_name>(offset)?;
160
161            // SAFETY: By the type invariant `addr` is a valid address for MMIO operations.
162            Ok(unsafe { bindings::$c_fn(addr as *const c_void) })
163        }
164    };
165}
166
167macro_rules! define_write {
168    ($(#[$attr:meta])* $name:ident, $try_name:ident, $c_fn:ident <- $type_name:ty) => {
169        /// Write IO data from a given offset known at compile time.
170        ///
171        /// Bound checks are performed on compile time, hence if the offset is not known at compile
172        /// time, the build will fail.
173        $(#[$attr])*
174        #[inline]
175        pub fn $name(&self, value: $type_name, offset: usize) {
176            let addr = self.io_addr_assert::<$type_name>(offset);
177
178            // SAFETY: By the type invariant `addr` is a valid address for MMIO operations.
179            unsafe { bindings::$c_fn(value, addr as *mut c_void) }
180        }
181
182        /// Write IO data from a given offset.
183        ///
184        /// Bound checks are performed on runtime, it fails if the offset (plus the type size) is
185        /// out of bounds.
186        $(#[$attr])*
187        pub fn $try_name(&self, value: $type_name, offset: usize) -> Result {
188            let addr = self.io_addr::<$type_name>(offset)?;
189
190            // SAFETY: By the type invariant `addr` is a valid address for MMIO operations.
191            unsafe { bindings::$c_fn(value, addr as *mut c_void) }
192            Ok(())
193        }
194    };
195}
196
197impl<const SIZE: usize> Io<SIZE> {
198    /// Converts an `IoRaw` into an `Io` instance, providing the accessors to the MMIO mapping.
199    ///
200    /// # Safety
201    ///
202    /// Callers must ensure that `addr` is the start of a valid I/O mapped memory region of size
203    /// `maxsize`.
204    pub unsafe fn from_raw(raw: &IoRaw<SIZE>) -> &Self {
205        // SAFETY: `Io` is a transparent wrapper around `IoRaw`.
206        unsafe { &*core::ptr::from_ref(raw).cast() }
207    }
208
209    /// Returns the base address of this mapping.
210    #[inline]
211    pub fn addr(&self) -> usize {
212        self.0.addr()
213    }
214
215    /// Returns the maximum size of this mapping.
216    #[inline]
217    pub fn maxsize(&self) -> usize {
218        self.0.maxsize()
219    }
220
221    #[inline]
222    const fn offset_valid<U>(offset: usize, size: usize) -> bool {
223        let type_size = core::mem::size_of::<U>();
224        if let Some(end) = offset.checked_add(type_size) {
225            end <= size && offset % type_size == 0
226        } else {
227            false
228        }
229    }
230
231    #[inline]
232    fn io_addr<U>(&self, offset: usize) -> Result<usize> {
233        if !Self::offset_valid::<U>(offset, self.maxsize()) {
234            return Err(EINVAL);
235        }
236
237        // Probably no need to check, since the safety requirements of `Self::new` guarantee that
238        // this can't overflow.
239        self.addr().checked_add(offset).ok_or(EINVAL)
240    }
241
242    #[inline]
243    fn io_addr_assert<U>(&self, offset: usize) -> usize {
244        build_assert!(Self::offset_valid::<U>(offset, SIZE));
245
246        self.addr() + offset
247    }
248
249    define_read!(read8, try_read8, readb -> u8);
250    define_read!(read16, try_read16, readw -> u16);
251    define_read!(read32, try_read32, readl -> u32);
252    define_read!(
253        #[cfg(CONFIG_64BIT)]
254        read64,
255        try_read64,
256        readq -> u64
257    );
258
259    define_read!(read8_relaxed, try_read8_relaxed, readb_relaxed -> u8);
260    define_read!(read16_relaxed, try_read16_relaxed, readw_relaxed -> u16);
261    define_read!(read32_relaxed, try_read32_relaxed, readl_relaxed -> u32);
262    define_read!(
263        #[cfg(CONFIG_64BIT)]
264        read64_relaxed,
265        try_read64_relaxed,
266        readq_relaxed -> u64
267    );
268
269    define_write!(write8, try_write8, writeb <- u8);
270    define_write!(write16, try_write16, writew <- u16);
271    define_write!(write32, try_write32, writel <- u32);
272    define_write!(
273        #[cfg(CONFIG_64BIT)]
274        write64,
275        try_write64,
276        writeq <- u64
277    );
278
279    define_write!(write8_relaxed, try_write8_relaxed, writeb_relaxed <- u8);
280    define_write!(write16_relaxed, try_write16_relaxed, writew_relaxed <- u16);
281    define_write!(write32_relaxed, try_write32_relaxed, writel_relaxed <- u32);
282    define_write!(
283        #[cfg(CONFIG_64BIT)]
284        write64_relaxed,
285        try_write64_relaxed,
286        writeq_relaxed <- u64
287    );
288}
kernel/io.rs

kernel/
io.rs
