projects/linux·blob master · refs

348 lines · 11.9 KiB

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