1 // SPDX-License-Identifier: GPL-2.0 2 3 //! PCI memory-mapped I/O infrastructure. 4 5 use super::Device; 6 use crate::{ 7 bindings, 8 device, 9 devres::Devres, 10 io::{ 11 Io, 12 IoCapable, 13 IoKnownSize, 14 Mmio, 15 MmioRaw, // 16 }, 17 prelude::*, // 18 }; 19 use core::{ 20 marker::PhantomData, 21 ops::Deref, // 22 }; 23 24 /// Represents the size of a PCI configuration space. 25 /// 26 /// PCI devices can have either a *normal* (legacy) configuration space of 256 bytes, 27 /// or an *extended* configuration space of 4096 bytes as defined in the PCI Express 28 /// specification. 29 #[repr(usize)] 30 #[derive(Eq, PartialEq)] 31 pub enum ConfigSpaceSize { 32 /// 256-byte legacy PCI configuration space. 33 Normal = 256, 34 35 /// 4096-byte PCIe extended configuration space. 36 Extended = 4096, 37 } 38 39 impl ConfigSpaceSize { 40 /// Get the raw value of this enum. 41 #[inline(always)] 42 pub const fn into_raw(self) -> usize { 43 // CAST: PCI configuration space size is at most 4096 bytes, so the value always fits 44 // within `usize` without truncation or sign change. 45 self as usize 46 } 47 } 48 49 /// Marker type for normal (256-byte) PCI configuration space. 50 pub struct Normal; 51 52 /// Marker type for extended (4096-byte) PCIe configuration space. 53 pub struct Extended; 54 55 /// Trait for PCI configuration space size markers. 56 /// 57 /// This trait is implemented by [`Normal`] and [`Extended`] to provide 58 /// compile-time knowledge of the configuration space size. 59 pub trait ConfigSpaceKind { 60 /// The size of this configuration space in bytes. 61 const SIZE: usize; 62 } 63 64 impl ConfigSpaceKind for Normal { 65 const SIZE: usize = 256; 66 } 67 68 impl ConfigSpaceKind for Extended { 69 const SIZE: usize = 4096; 70 } 71 72 /// The PCI configuration space of a device. 73 /// 74 /// Provides typed read and write accessors for configuration registers 75 /// using the standard `pci_read_config_*` and `pci_write_config_*` helpers. 76 /// 77 /// The generic parameter `S` indicates the maximum size of the configuration space. 78 /// Use [`Normal`] for 256-byte legacy configuration space or [`Extended`] for 79 /// 4096-byte PCIe extended configuration space (default). 80 pub struct ConfigSpace<'a, S: ConfigSpaceKind = Extended> { 81 pub(crate) pdev: &'a Device<device::Bound>, 82 _marker: PhantomData<S>, 83 } 84 85 /// Implements [`IoCapable`] on [`ConfigSpace`] for `$ty` using `$read_fn` and `$write_fn`. 86 macro_rules! impl_config_space_io_capable { 87 ($ty:ty, $read_fn:ident, $write_fn:ident) => { 88 impl<'a, S: ConfigSpaceKind> IoCapable<$ty> for ConfigSpace<'a, S> { 89 unsafe fn io_read(&self, address: usize) -> $ty { 90 let mut val: $ty = 0; 91 92 // Return value from C function is ignored in infallible accessors. 93 let _ret = 94 // SAFETY: By the type invariant `self.pdev` is a valid address. 95 // CAST: The offset is cast to `i32` because the C functions expect a 32-bit 96 // signed offset parameter. PCI configuration space size is at most 4096 bytes, 97 // so the value always fits within `i32` without truncation or sign change. 98 unsafe { bindings::$read_fn(self.pdev.as_raw(), address as i32, &mut val) }; 99 100 val 101 } 102 103 unsafe fn io_write(&self, value: $ty, address: usize) { 104 // Return value from C function is ignored in infallible accessors. 105 let _ret = 106 // SAFETY: By the type invariant `self.pdev` is a valid address. 107 // CAST: The offset is cast to `i32` because the C functions expect a 32-bit 108 // signed offset parameter. PCI configuration space size is at most 4096 bytes, 109 // so the value always fits within `i32` without truncation or sign change. 110 unsafe { bindings::$write_fn(self.pdev.as_raw(), address as i32, value) }; 111 } 112 } 113 }; 114 } 115 116 // PCI configuration space supports 8, 16, and 32-bit accesses. 117 impl_config_space_io_capable!(u8, pci_read_config_byte, pci_write_config_byte); 118 impl_config_space_io_capable!(u16, pci_read_config_word, pci_write_config_word); 119 impl_config_space_io_capable!(u32, pci_read_config_dword, pci_write_config_dword); 120 121 impl<'a, S: ConfigSpaceKind> Io for ConfigSpace<'a, S> { 122 /// Returns the base address of the I/O region. It is always 0 for configuration space. 123 #[inline] 124 fn addr(&self) -> usize { 125 0 126 } 127 128 /// Returns the maximum size of the configuration space. 129 #[inline] 130 fn maxsize(&self) -> usize { 131 self.pdev.cfg_size().into_raw() 132 } 133 } 134 135 impl<'a, S: ConfigSpaceKind> IoKnownSize for ConfigSpace<'a, S> { 136 const MIN_SIZE: usize = S::SIZE; 137 } 138 139 /// A PCI BAR to perform I/O-Operations on. 140 /// 141 /// I/O backend assumes that the device is little-endian and will automatically 142 /// convert from little-endian to CPU endianness. 143 /// 144 /// # Invariants 145 /// 146 /// `Bar` always holds an `IoRaw` instance that holds a valid pointer to the start of the I/O 147 /// memory mapped PCI BAR and its size. 148 pub struct Bar<'a, const SIZE: usize = 0> { 149 pdev: &'a Device<device::Bound>, 150 io: MmioRaw<SIZE>, 151 num: i32, 152 } 153 154 impl<'a, const SIZE: usize> Bar<'a, SIZE> { 155 pub(super) fn new( 156 pdev: &'a Device<device::Bound>, 157 num: u32, 158 name: &'static CStr, 159 ) -> Result<Self> { 160 let len = pdev.resource_len(num)?; 161 if len == 0 { 162 return Err(ENOMEM); 163 } 164 165 // Convert to `i32`, since that's what all the C bindings use. 166 let num = i32::try_from(num)?; 167 168 // SAFETY: 169 // `pdev` is valid by the invariants of `Device`. 170 // `num` is checked for validity by a previous call to `Device::resource_len`. 171 // `name` is always valid. 172 let ret = unsafe { bindings::pci_request_region(pdev.as_raw(), num, name.as_char_ptr()) }; 173 if ret != 0 { 174 return Err(EBUSY); 175 } 176 177 // SAFETY: 178 // `pdev` is valid by the invariants of `Device`. 179 // `num` is checked for validity by a previous call to `Device::resource_len`. 180 // `name` is always valid. 181 let ioptr: usize = unsafe { bindings::pci_iomap(pdev.as_raw(), num, 0) } as usize; 182 if ioptr == 0 { 183 // SAFETY: 184 // `pdev` is valid by the invariants of `Device`. 185 // `num` is checked for validity by a previous call to `Device::resource_len`. 186 unsafe { bindings::pci_release_region(pdev.as_raw(), num) }; 187 return Err(ENOMEM); 188 } 189 190 let io = match MmioRaw::new(ioptr, len as usize) { 191 Ok(io) => io, 192 Err(err) => { 193 // SAFETY: 194 // `pdev` is valid by the invariants of `Device`. 195 // `ioptr` is guaranteed to be the start of a valid I/O mapped memory region. 196 // `num` is checked for validity by a previous call to `Device::resource_len`. 197 unsafe { Self::do_release(pdev, ioptr, num) }; 198 return Err(err); 199 } 200 }; 201 202 Ok(Bar { pdev, io, num }) 203 } 204 205 /// # Safety 206 /// 207 /// `ioptr` must be a valid pointer to the memory mapped PCI BAR number `num`. 208 unsafe fn do_release(pdev: &Device, ioptr: usize, num: i32) { 209 // SAFETY: 210 // `pdev` is valid by the invariants of `Device`. 211 // `ioptr` is valid by the safety requirements. 212 // `num` is valid by the safety requirements. 213 unsafe { 214 bindings::pci_iounmap(pdev.as_raw(), ioptr as *mut c_void); 215 bindings::pci_release_region(pdev.as_raw(), num); 216 } 217 } 218 219 fn release(&self) { 220 // SAFETY: The safety requirements are guaranteed by the type invariant of `self.pdev`. 221 unsafe { Self::do_release(self.pdev, self.io.addr(), self.num) }; 222 } 223 224 /// Consume the `Bar` and register it as a device-managed resource. 225 /// 226 /// The returned `Devres<Bar<'static, SIZE>>` can outlive the original lifetime `'a`. Access 227 /// to the BAR is revoked when the device is unbound. 228 pub fn into_devres(self) -> Result<Devres<Bar<'static, SIZE>>> { 229 // SAFETY: Casting to `'static` is sound because `Devres` guarantees the `Bar` does not 230 // actually outlive the device -- access is revoked and the resource is released when the 231 // device is unbound. 232 let bar: Bar<'static, SIZE> = unsafe { core::mem::transmute(self) }; 233 let pdev = bar.pdev; 234 Devres::new(pdev.as_ref(), bar) 235 } 236 } 237 238 impl Bar<'_> { 239 #[inline] 240 pub(super) fn index_is_valid(index: u32) -> bool { 241 // A `struct pci_dev` owns an array of resources with at most `PCI_NUM_RESOURCES` entries. 242 index < bindings::PCI_NUM_RESOURCES 243 } 244 } 245 246 impl<const SIZE: usize> Drop for Bar<'_, SIZE> { 247 fn drop(&mut self) { 248 self.release(); 249 } 250 } 251 252 impl<const SIZE: usize> Deref for Bar<'_, SIZE> { 253 type Target = Mmio<SIZE>; 254 255 fn deref(&self) -> &Self::Target { 256 // SAFETY: By the type invariant of `Self`, the MMIO range in `self.io` is properly mapped. 257 unsafe { Mmio::from_raw(&self.io) } 258 } 259 } 260 261 impl Device<device::Bound> { 262 /// Maps an entire PCI BAR after performing a region-request on it. I/O operation bound checks 263 /// can be performed on compile time for offsets (plus the requested type size) < SIZE. 264 pub fn iomap_region_sized<'a, const SIZE: usize>( 265 &'a self, 266 bar: u32, 267 name: &'static CStr, 268 ) -> Result<Bar<'a, SIZE>> { 269 Bar::new(self, bar, name) 270 } 271 272 /// Maps an entire PCI BAR after performing a region-request on it. 273 pub fn iomap_region<'a>(&'a self, bar: u32, name: &'static CStr) -> Result<Bar<'a>> { 274 self.iomap_region_sized::<0>(bar, name) 275 } 276 277 /// Returns the size of configuration space. 278 pub fn cfg_size(&self) -> ConfigSpaceSize { 279 // SAFETY: `self.as_raw` is a valid pointer to a `struct pci_dev`. 280 let size = unsafe { (*self.as_raw()).cfg_size }; 281 match size { 282 256 => ConfigSpaceSize::Normal, 283 4096 => ConfigSpaceSize::Extended, 284 _ => { 285 // PANIC: The PCI subsystem only ever reports the configuration space size as either 286 // `ConfigSpaceSize::Normal` or `ConfigSpaceSize::Extended`. 287 unreachable!(); 288 } 289 } 290 } 291 292 /// Return an initialized normal (256-byte) config space object. 293 pub fn config_space<'a>(&'a self) -> ConfigSpace<'a, Normal> { 294 ConfigSpace { 295 pdev: self, 296 _marker: PhantomData, 297 } 298 } 299 300 /// Return an initialized extended (4096-byte) config space object. 301 pub fn config_space_extended<'a>(&'a self) -> Result<ConfigSpace<'a, Extended>> { 302 if self.cfg_size() != ConfigSpaceSize::Extended { 303 return Err(EINVAL); 304 } 305 306 Ok(ConfigSpace { 307 pdev: self, 308 _marker: PhantomData, 309 }) 310 } 311 } 312