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 7 use crate::{ 8 bindings, 9 prelude::*, // 10 }; 11 12 pub mod mem; 13 pub mod poll; 14 pub mod resource; 15 16 pub 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. 22 pub 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. 28 pub 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. 38 pub struct IoRaw<const SIZE: usize = 0> { 39 addr: usize, 40 maxsize: usize, 41 } 42 43 impl<const SIZE: usize> IoRaw<SIZE> { 44 /// Returns a new `IoRaw` instance on success, an error otherwise. new(addr: usize, maxsize: usize) -> Result<Self>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] addr(&self) -> usize55 pub fn addr(&self) -> usize { 56 self.addr 57 } 58 59 /// Returns the maximum size of the MMIO region. 60 #[inline] maxsize(&self) -> usize61 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)] 136 pub struct Io<const SIZE: usize = 0>(IoRaw<SIZE>); 137 138 macro_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 // Always inline to optimize out error path of `io_addr_assert`. 146 #[inline(always)] 147 pub fn $name(&self, offset: usize) -> $type_name { 148 let addr = self.io_addr_assert::<$type_name>(offset); 149 150 // SAFETY: By the type invariant `addr` is a valid address for MMIO operations. 151 unsafe { bindings::$c_fn(addr as *const c_void) } 152 } 153 154 /// Read IO data from a given offset. 155 /// 156 /// Bound checks are performed on runtime, it fails if the offset (plus the type size) is 157 /// out of bounds. 158 $(#[$attr])* 159 pub fn $try_name(&self, offset: usize) -> Result<$type_name> { 160 let addr = self.io_addr::<$type_name>(offset)?; 161 162 // SAFETY: By the type invariant `addr` is a valid address for MMIO operations. 163 Ok(unsafe { bindings::$c_fn(addr as *const c_void) }) 164 } 165 }; 166 } 167 168 macro_rules! define_write { 169 ($(#[$attr:meta])* $name:ident, $try_name:ident, $c_fn:ident <- $type_name:ty) => { 170 /// Write IO data from a given offset known at compile time. 171 /// 172 /// Bound checks are performed on compile time, hence if the offset is not known at compile 173 /// time, the build will fail. 174 $(#[$attr])* 175 // Always inline to optimize out error path of `io_addr_assert`. 176 #[inline(always)] 177 pub fn $name(&self, value: $type_name, offset: usize) { 178 let addr = self.io_addr_assert::<$type_name>(offset); 179 180 // SAFETY: By the type invariant `addr` is a valid address for MMIO operations. 181 unsafe { bindings::$c_fn(value, addr as *mut c_void) } 182 } 183 184 /// Write IO data from a given offset. 185 /// 186 /// Bound checks are performed on runtime, it fails if the offset (plus the type size) is 187 /// out of bounds. 188 $(#[$attr])* 189 pub fn $try_name(&self, value: $type_name, offset: usize) -> Result { 190 let addr = self.io_addr::<$type_name>(offset)?; 191 192 // SAFETY: By the type invariant `addr` is a valid address for MMIO operations. 193 unsafe { bindings::$c_fn(value, addr as *mut c_void) } 194 Ok(()) 195 } 196 }; 197 } 198 199 impl<const SIZE: usize> Io<SIZE> { 200 /// Converts an `IoRaw` into an `Io` instance, providing the accessors to the MMIO mapping. 201 /// 202 /// # Safety 203 /// 204 /// Callers must ensure that `addr` is the start of a valid I/O mapped memory region of size 205 /// `maxsize`. from_raw(raw: &IoRaw<SIZE>) -> &Self206 pub unsafe fn from_raw(raw: &IoRaw<SIZE>) -> &Self { 207 // SAFETY: `Io` is a transparent wrapper around `IoRaw`. 208 unsafe { &*core::ptr::from_ref(raw).cast() } 209 } 210 211 /// Returns the base address of this mapping. 212 #[inline] addr(&self) -> usize213 pub fn addr(&self) -> usize { 214 self.0.addr() 215 } 216 217 /// Returns the maximum size of this mapping. 218 #[inline] maxsize(&self) -> usize219 pub fn maxsize(&self) -> usize { 220 self.0.maxsize() 221 } 222 223 #[inline] offset_valid<U>(offset: usize, size: usize) -> bool224 const fn offset_valid<U>(offset: usize, size: usize) -> bool { 225 let type_size = core::mem::size_of::<U>(); 226 if let Some(end) = offset.checked_add(type_size) { 227 end <= size && offset % type_size == 0 228 } else { 229 false 230 } 231 } 232 233 #[inline] io_addr<U>(&self, offset: usize) -> Result<usize>234 fn io_addr<U>(&self, offset: usize) -> Result<usize> { 235 if !Self::offset_valid::<U>(offset, self.maxsize()) { 236 return Err(EINVAL); 237 } 238 239 // Probably no need to check, since the safety requirements of `Self::new` guarantee that 240 // this can't overflow. 241 self.addr().checked_add(offset).ok_or(EINVAL) 242 } 243 244 // Always inline to optimize out error path of `build_assert`. 245 #[inline(always)] io_addr_assert<U>(&self, offset: usize) -> usize246 fn io_addr_assert<U>(&self, offset: usize) -> usize { 247 build_assert!(Self::offset_valid::<U>(offset, SIZE)); 248 249 self.addr() + offset 250 } 251 252 define_read!(read8, try_read8, readb -> u8); 253 define_read!(read16, try_read16, readw -> u16); 254 define_read!(read32, try_read32, readl -> u32); 255 define_read!( 256 #[cfg(CONFIG_64BIT)] 257 read64, 258 try_read64, 259 readq -> u64 260 ); 261 262 define_read!(read8_relaxed, try_read8_relaxed, readb_relaxed -> u8); 263 define_read!(read16_relaxed, try_read16_relaxed, readw_relaxed -> u16); 264 define_read!(read32_relaxed, try_read32_relaxed, readl_relaxed -> u32); 265 define_read!( 266 #[cfg(CONFIG_64BIT)] 267 read64_relaxed, 268 try_read64_relaxed, 269 readq_relaxed -> u64 270 ); 271 272 define_write!(write8, try_write8, writeb <- u8); 273 define_write!(write16, try_write16, writew <- u16); 274 define_write!(write32, try_write32, writel <- u32); 275 define_write!( 276 #[cfg(CONFIG_64BIT)] 277 write64, 278 try_write64, 279 writeq <- u64 280 ); 281 282 define_write!(write8_relaxed, try_write8_relaxed, writeb_relaxed <- u8); 283 define_write!(write16_relaxed, try_write16_relaxed, writew_relaxed <- u16); 284 define_write!(write32_relaxed, try_write32_relaxed, writel_relaxed <- u32); 285 define_write!( 286 #[cfg(CONFIG_64BIT)] 287 write64_relaxed, 288 try_write64_relaxed, 289 writeq_relaxed <- u64 290 ); 291 } 292