kernel/pci.rs
1// SPDX-License-Identifier: GPL-2.0
2
3//! Abstractions for the PCI bus.
4//!
5//! C header: [`include/linux/pci.h`](srctree/include/linux/pci.h)
6
7use crate::{
8 alloc::flags::*,
9 bindings, device,
10 device_id::RawDeviceId,
11 devres::Devres,
12 driver,
13 error::{to_result, Result},
14 io::Io,
15 io::IoRaw,
16 str::CStr,
17 types::{ARef, ForeignOwnable, Opaque},
18 ThisModule,
19};
20use core::{
21 marker::PhantomData,
22 ops::Deref,
23 ptr::{addr_of_mut, NonNull},
24};
25use kernel::prelude::*;
26
27/// An adapter for the registration of PCI drivers.
28pub struct Adapter<T: Driver>(T);
29
30// SAFETY: A call to `unregister` for a given instance of `RegType` is guaranteed to be valid if
31// a preceding call to `register` has been successful.
32unsafe impl<T: Driver + 'static> driver::RegistrationOps for Adapter<T> {
33 type RegType = bindings::pci_driver;
34
35 unsafe fn register(
36 pdrv: &Opaque<Self::RegType>,
37 name: &'static CStr,
38 module: &'static ThisModule,
39 ) -> Result {
40 // SAFETY: It's safe to set the fields of `struct pci_driver` on initialization.
41 unsafe {
42 (*pdrv.get()).name = name.as_char_ptr();
43 (*pdrv.get()).probe = Some(Self::probe_callback);
44 (*pdrv.get()).remove = Some(Self::remove_callback);
45 (*pdrv.get()).id_table = T::ID_TABLE.as_ptr();
46 }
47
48 // SAFETY: `pdrv` is guaranteed to be a valid `RegType`.
49 to_result(unsafe {
50 bindings::__pci_register_driver(pdrv.get(), module.0, name.as_char_ptr())
51 })
52 }
53
54 unsafe fn unregister(pdrv: &Opaque<Self::RegType>) {
55 // SAFETY: `pdrv` is guaranteed to be a valid `RegType`.
56 unsafe { bindings::pci_unregister_driver(pdrv.get()) }
57 }
58}
59
60impl<T: Driver + 'static> Adapter<T> {
61 extern "C" fn probe_callback(
62 pdev: *mut bindings::pci_dev,
63 id: *const bindings::pci_device_id,
64 ) -> kernel::ffi::c_int {
65 // SAFETY: The PCI bus only ever calls the probe callback with a valid pointer to a
66 // `struct pci_dev`.
67 //
68 // INVARIANT: `pdev` is valid for the duration of `probe_callback()`.
69 let pdev = unsafe { &*pdev.cast::<Device<device::Core>>() };
70
71 // SAFETY: `DeviceId` is a `#[repr(transparent)` wrapper of `struct pci_device_id` and
72 // does not add additional invariants, so it's safe to transmute.
73 let id = unsafe { &*id.cast::<DeviceId>() };
74 let info = T::ID_TABLE.info(id.index());
75
76 match T::probe(pdev, info) {
77 Ok(data) => {
78 // Let the `struct pci_dev` own a reference of the driver's private data.
79 // SAFETY: By the type invariant `pdev.as_raw` returns a valid pointer to a
80 // `struct pci_dev`.
81 unsafe { bindings::pci_set_drvdata(pdev.as_raw(), data.into_foreign() as _) };
82 }
83 Err(err) => return Error::to_errno(err),
84 }
85
86 0
87 }
88
89 extern "C" fn remove_callback(pdev: *mut bindings::pci_dev) {
90 // SAFETY: The PCI bus only ever calls the remove callback with a valid pointer to a
91 // `struct pci_dev`.
92 let ptr = unsafe { bindings::pci_get_drvdata(pdev) };
93
94 // SAFETY: `remove_callback` is only ever called after a successful call to
95 // `probe_callback`, hence it's guaranteed that `ptr` points to a valid and initialized
96 // `KBox<T>` pointer created through `KBox::into_foreign`.
97 let _ = unsafe { KBox::<T>::from_foreign(ptr) };
98 }
99}
100
101/// Declares a kernel module that exposes a single PCI driver.
102///
103/// # Example
104///
105///```ignore
106/// kernel::module_pci_driver! {
107/// type: MyDriver,
108/// name: "Module name",
109/// authors: ["Author name"],
110/// description: "Description",
111/// license: "GPL v2",
112/// }
113///```
114#[macro_export]
115macro_rules! module_pci_driver {
116($($f:tt)*) => {
117 $crate::module_driver!(<T>, $crate::pci::Adapter<T>, { $($f)* });
118};
119}
120
121/// Abstraction for the PCI device ID structure ([`struct pci_device_id`]).
122///
123/// [`struct pci_device_id`]: https://docs.kernel.org/PCI/pci.html#c.pci_device_id
124#[repr(transparent)]
125#[derive(Clone, Copy)]
126pub struct DeviceId(bindings::pci_device_id);
127
128impl DeviceId {
129 const PCI_ANY_ID: u32 = !0;
130
131 /// Equivalent to C's `PCI_DEVICE` macro.
132 ///
133 /// Create a new `pci::DeviceId` from a vendor and device ID number.
134 pub const fn from_id(vendor: u32, device: u32) -> Self {
135 Self(bindings::pci_device_id {
136 vendor,
137 device,
138 subvendor: DeviceId::PCI_ANY_ID,
139 subdevice: DeviceId::PCI_ANY_ID,
140 class: 0,
141 class_mask: 0,
142 driver_data: 0,
143 override_only: 0,
144 })
145 }
146
147 /// Equivalent to C's `PCI_DEVICE_CLASS` macro.
148 ///
149 /// Create a new `pci::DeviceId` from a class number and mask.
150 pub const fn from_class(class: u32, class_mask: u32) -> Self {
151 Self(bindings::pci_device_id {
152 vendor: DeviceId::PCI_ANY_ID,
153 device: DeviceId::PCI_ANY_ID,
154 subvendor: DeviceId::PCI_ANY_ID,
155 subdevice: DeviceId::PCI_ANY_ID,
156 class,
157 class_mask,
158 driver_data: 0,
159 override_only: 0,
160 })
161 }
162}
163
164// SAFETY:
165// * `DeviceId` is a `#[repr(transparent)` wrapper of `pci_device_id` and does not add
166// additional invariants, so it's safe to transmute to `RawType`.
167// * `DRIVER_DATA_OFFSET` is the offset to the `driver_data` field.
168unsafe impl RawDeviceId for DeviceId {
169 type RawType = bindings::pci_device_id;
170
171 const DRIVER_DATA_OFFSET: usize = core::mem::offset_of!(bindings::pci_device_id, driver_data);
172
173 fn index(&self) -> usize {
174 self.0.driver_data as _
175 }
176}
177
178/// `IdTable` type for PCI.
179pub type IdTable<T> = &'static dyn kernel::device_id::IdTable<DeviceId, T>;
180
181/// Create a PCI `IdTable` with its alias for modpost.
182#[macro_export]
183macro_rules! pci_device_table {
184 ($table_name:ident, $module_table_name:ident, $id_info_type: ty, $table_data: expr) => {
185 const $table_name: $crate::device_id::IdArray<
186 $crate::pci::DeviceId,
187 $id_info_type,
188 { $table_data.len() },
189 > = $crate::device_id::IdArray::new($table_data);
190
191 $crate::module_device_table!("pci", $module_table_name, $table_name);
192 };
193}
194
195/// The PCI driver trait.
196///
197/// # Example
198///
199///```
200/// # use kernel::{bindings, device::Core, pci};
201///
202/// struct MyDriver;
203///
204/// kernel::pci_device_table!(
205/// PCI_TABLE,
206/// MODULE_PCI_TABLE,
207/// <MyDriver as pci::Driver>::IdInfo,
208/// [
209/// (pci::DeviceId::from_id(bindings::PCI_VENDOR_ID_REDHAT, bindings::PCI_ANY_ID as _), ())
210/// ]
211/// );
212///
213/// impl pci::Driver for MyDriver {
214/// type IdInfo = ();
215/// const ID_TABLE: pci::IdTable<Self::IdInfo> = &PCI_TABLE;
216///
217/// fn probe(
218/// _pdev: &pci::Device<Core>,
219/// _id_info: &Self::IdInfo,
220/// ) -> Result<Pin<KBox<Self>>> {
221/// Err(ENODEV)
222/// }
223/// }
224///```
225/// Drivers must implement this trait in order to get a PCI driver registered. Please refer to the
226/// `Adapter` documentation for an example.
227pub trait Driver: Send {
228 /// The type holding information about each device id supported by the driver.
229 // TODO: Use `associated_type_defaults` once stabilized:
230 //
231 // ```
232 // type IdInfo: 'static = ();
233 // ```
234 type IdInfo: 'static;
235
236 /// The table of device ids supported by the driver.
237 const ID_TABLE: IdTable<Self::IdInfo>;
238
239 /// PCI driver probe.
240 ///
241 /// Called when a new platform device is added or discovered.
242 /// Implementers should attempt to initialize the device here.
243 fn probe(dev: &Device<device::Core>, id_info: &Self::IdInfo) -> Result<Pin<KBox<Self>>>;
244}
245
246/// The PCI device representation.
247///
248/// This structure represents the Rust abstraction for a C `struct pci_dev`. The implementation
249/// abstracts the usage of an already existing C `struct pci_dev` within Rust code that we get
250/// passed from the C side.
251///
252/// # Invariants
253///
254/// A [`Device`] instance represents a valid `struct device` created by the C portion of the kernel.
255#[repr(transparent)]
256pub struct Device<Ctx: device::DeviceContext = device::Normal>(
257 Opaque<bindings::pci_dev>,
258 PhantomData<Ctx>,
259);
260
261/// A PCI BAR to perform I/O-Operations on.
262///
263/// # Invariants
264///
265/// `Bar` always holds an `IoRaw` inststance that holds a valid pointer to the start of the I/O
266/// memory mapped PCI bar and its size.
267pub struct Bar<const SIZE: usize = 0> {
268 pdev: ARef<Device>,
269 io: IoRaw<SIZE>,
270 num: i32,
271}
272
273impl<const SIZE: usize> Bar<SIZE> {
274 fn new(pdev: &Device, num: u32, name: &CStr) -> Result<Self> {
275 let len = pdev.resource_len(num)?;
276 if len == 0 {
277 return Err(ENOMEM);
278 }
279
280 // Convert to `i32`, since that's what all the C bindings use.
281 let num = i32::try_from(num)?;
282
283 // SAFETY:
284 // `pdev` is valid by the invariants of `Device`.
285 // `num` is checked for validity by a previous call to `Device::resource_len`.
286 // `name` is always valid.
287 let ret = unsafe { bindings::pci_request_region(pdev.as_raw(), num, name.as_char_ptr()) };
288 if ret != 0 {
289 return Err(EBUSY);
290 }
291
292 // SAFETY:
293 // `pdev` is valid by the invariants of `Device`.
294 // `num` is checked for validity by a previous call to `Device::resource_len`.
295 // `name` is always valid.
296 let ioptr: usize = unsafe { bindings::pci_iomap(pdev.as_raw(), num, 0) } as usize;
297 if ioptr == 0 {
298 // SAFETY:
299 // `pdev` valid by the invariants of `Device`.
300 // `num` is checked for validity by a previous call to `Device::resource_len`.
301 unsafe { bindings::pci_release_region(pdev.as_raw(), num) };
302 return Err(ENOMEM);
303 }
304
305 let io = match IoRaw::new(ioptr, len as usize) {
306 Ok(io) => io,
307 Err(err) => {
308 // SAFETY:
309 // `pdev` is valid by the invariants of `Device`.
310 // `ioptr` is guaranteed to be the start of a valid I/O mapped memory region.
311 // `num` is checked for validity by a previous call to `Device::resource_len`.
312 unsafe { Self::do_release(pdev, ioptr, num) };
313 return Err(err);
314 }
315 };
316
317 Ok(Bar {
318 pdev: pdev.into(),
319 io,
320 num,
321 })
322 }
323
324 /// # Safety
325 ///
326 /// `ioptr` must be a valid pointer to the memory mapped PCI bar number `num`.
327 unsafe fn do_release(pdev: &Device, ioptr: usize, num: i32) {
328 // SAFETY:
329 // `pdev` is valid by the invariants of `Device`.
330 // `ioptr` is valid by the safety requirements.
331 // `num` is valid by the safety requirements.
332 unsafe {
333 bindings::pci_iounmap(pdev.as_raw(), ioptr as _);
334 bindings::pci_release_region(pdev.as_raw(), num);
335 }
336 }
337
338 fn release(&self) {
339 // SAFETY: The safety requirements are guaranteed by the type invariant of `self.pdev`.
340 unsafe { Self::do_release(&self.pdev, self.io.addr(), self.num) };
341 }
342}
343
344impl Bar {
345 fn index_is_valid(index: u32) -> bool {
346 // A `struct pci_dev` owns an array of resources with at most `PCI_NUM_RESOURCES` entries.
347 index < bindings::PCI_NUM_RESOURCES
348 }
349}
350
351impl<const SIZE: usize> Drop for Bar<SIZE> {
352 fn drop(&mut self) {
353 self.release();
354 }
355}
356
357impl<const SIZE: usize> Deref for Bar<SIZE> {
358 type Target = Io<SIZE>;
359
360 fn deref(&self) -> &Self::Target {
361 // SAFETY: By the type invariant of `Self`, the MMIO range in `self.io` is properly mapped.
362 unsafe { Io::from_raw(&self.io) }
363 }
364}
365
366impl Device {
367 fn as_raw(&self) -> *mut bindings::pci_dev {
368 self.0.get()
369 }
370
371 /// Returns the PCI vendor ID.
372 pub fn vendor_id(&self) -> u16 {
373 // SAFETY: `self.as_raw` is a valid pointer to a `struct pci_dev`.
374 unsafe { (*self.as_raw()).vendor }
375 }
376
377 /// Returns the PCI device ID.
378 pub fn device_id(&self) -> u16 {
379 // SAFETY: `self.as_raw` is a valid pointer to a `struct pci_dev`.
380 unsafe { (*self.as_raw()).device }
381 }
382
383 /// Returns the size of the given PCI bar resource.
384 pub fn resource_len(&self, bar: u32) -> Result<bindings::resource_size_t> {
385 if !Bar::index_is_valid(bar) {
386 return Err(EINVAL);
387 }
388
389 // SAFETY:
390 // - `bar` is a valid bar number, as guaranteed by the above call to `Bar::index_is_valid`,
391 // - by its type invariant `self.as_raw` is always a valid pointer to a `struct pci_dev`.
392 Ok(unsafe { bindings::pci_resource_len(self.as_raw(), bar.try_into()?) })
393 }
394
395 /// Mapps an entire PCI-BAR after performing a region-request on it. I/O operation bound checks
396 /// can be performed on compile time for offsets (plus the requested type size) < SIZE.
397 pub fn iomap_region_sized<const SIZE: usize>(
398 &self,
399 bar: u32,
400 name: &CStr,
401 ) -> Result<Devres<Bar<SIZE>>> {
402 let bar = Bar::<SIZE>::new(self, bar, name)?;
403 let devres = Devres::new(self.as_ref(), bar, GFP_KERNEL)?;
404
405 Ok(devres)
406 }
407
408 /// Mapps an entire PCI-BAR after performing a region-request on it.
409 pub fn iomap_region(&self, bar: u32, name: &CStr) -> Result<Devres<Bar>> {
410 self.iomap_region_sized::<0>(bar, name)
411 }
412}
413
414impl Device<device::Core> {
415 /// Enable memory resources for this device.
416 pub fn enable_device_mem(&self) -> Result {
417 // SAFETY: `self.as_raw` is guaranteed to be a pointer to a valid `struct pci_dev`.
418 to_result(unsafe { bindings::pci_enable_device_mem(self.as_raw()) })
419 }
420
421 /// Enable bus-mastering for this device.
422 pub fn set_master(&self) {
423 // SAFETY: `self.as_raw` is guaranteed to be a pointer to a valid `struct pci_dev`.
424 unsafe { bindings::pci_set_master(self.as_raw()) };
425 }
426}
427
428impl Deref for Device<device::Core> {
429 type Target = Device;
430
431 fn deref(&self) -> &Self::Target {
432 let ptr: *const Self = self;
433
434 // CAST: `Device<Ctx>` is a transparent wrapper of `Opaque<bindings::pci_dev>`.
435 let ptr = ptr.cast::<Device>();
436
437 // SAFETY: `ptr` was derived from `&self`.
438 unsafe { &*ptr }
439 }
440}
441
442impl From<&Device<device::Core>> for ARef<Device> {
443 fn from(dev: &Device<device::Core>) -> Self {
444 (&**dev).into()
445 }
446}
447
448// SAFETY: Instances of `Device` are always reference-counted.
449unsafe impl crate::types::AlwaysRefCounted for Device {
450 fn inc_ref(&self) {
451 // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
452 unsafe { bindings::pci_dev_get(self.as_raw()) };
453 }
454
455 unsafe fn dec_ref(obj: NonNull<Self>) {
456 // SAFETY: The safety requirements guarantee that the refcount is non-zero.
457 unsafe { bindings::pci_dev_put(obj.cast().as_ptr()) }
458 }
459}
460
461impl AsRef<device::Device> for Device {
462 fn as_ref(&self) -> &device::Device {
463 // SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
464 // `struct pci_dev`.
465 let dev = unsafe { addr_of_mut!((*self.as_raw()).dev) };
466
467 // SAFETY: `dev` points to a valid `struct device`.
468 unsafe { device::Device::as_ref(dev) }
469 }
470}
471
472// SAFETY: A `Device` is always reference-counted and can be released from any thread.
473unsafe impl Send for Device {}
474
475// SAFETY: `Device` can be shared among threads because all methods of `Device`
476// (i.e. `Device<Normal>) are thread safe.
477unsafe impl Sync for Device {}