linux/rust/kernel/pci/io.rs

// SPDX-License-Identifier: GPL-2.0

//! PCI memory-mapped I/O infrastructure.

use super::Device;
use crate::{
    bindings,
    device,
    devres::Devres,
    io::{
        Io,
        IoCapable,
        IoKnownSize,
        Mmio,
        MmioRaw, //
    },
    prelude::*, //
};
use core::{
    marker::PhantomData,
    ops::Deref, //
};

/// Represents the size of a PCI configuration space.
///
/// PCI devices can have either a *normal* (legacy) configuration space of 256 bytes,
/// or an *extended* configuration space of 4096 bytes as defined in the PCI Express
/// specification.
#[repr(usize)]
#[derive(Eq, PartialEq)]
pub enum ConfigSpaceSize {
    /// 256-byte legacy PCI configuration space.
    Normal = 256,

    /// 4096-byte PCIe extended configuration space.
    Extended = 4096,
}

impl ConfigSpaceSize {
    /// Get the raw value of this enum.
    #[inline(always)]
    pub const fn into_raw(self) -> usize {
        // CAST: PCI configuration space size is at most 4096 bytes, so the value always fits
        // within `usize` without truncation or sign change.
        self as usize
    }
}

/// Marker type for normal (256-byte) PCI configuration space.
pub struct Normal;

/// Marker type for extended (4096-byte) PCIe configuration space.
pub struct Extended;

/// Trait for PCI configuration space size markers.
///
/// This trait is implemented by [`Normal`] and [`Extended`] to provide
/// compile-time knowledge of the configuration space size.
pub trait ConfigSpaceKind {
    /// The size of this configuration space in bytes.
    const SIZE: usize;
}

impl ConfigSpaceKind for Normal {
    const SIZE: usize = 256;
}

impl ConfigSpaceKind for Extended {
    const SIZE: usize = 4096;
}

/// The PCI configuration space of a device.
///
/// Provides typed read and write accessors for configuration registers
/// using the standard `pci_read_config_*` and `pci_write_config_*` helpers.
///
/// The generic parameter `S` indicates the maximum size of the configuration space.
/// Use [`Normal`] for 256-byte legacy configuration space or [`Extended`] for
/// 4096-byte PCIe extended configuration space (default).
pub struct ConfigSpace<'a, S: ConfigSpaceKind = Extended> {
    pub(crate) pdev: &'a Device<device::Bound>,
    _marker: PhantomData<S>,
}

/// Implements [`IoCapable`] on [`ConfigSpace`] for `$ty` using `$read_fn` and `$write_fn`.
macro_rules! impl_config_space_io_capable {
    ($ty:ty, $read_fn:ident, $write_fn:ident) => {
        impl<'a, S: ConfigSpaceKind> IoCapable<$ty> for ConfigSpace<'a, S> {
            unsafe fn io_read(&self, address: usize) -> $ty {
                let mut val: $ty = 0;

                // Return value from C function is ignored in infallible accessors.
                let _ret =
                    // SAFETY: By the type invariant `self.pdev` is a valid address.
                    // CAST: The offset is cast to `i32` because the C functions expect a 32-bit
                    // signed offset parameter. PCI configuration space size is at most 4096 bytes,
                    // so the value always fits within `i32` without truncation or sign change.
                    unsafe { bindings::$read_fn(self.pdev.as_raw(), address as i32, &mut val) };

                val
            }

            unsafe fn io_write(&self, value: $ty, address: usize) {
                // Return value from C function is ignored in infallible accessors.
                let _ret =
                    // SAFETY: By the type invariant `self.pdev` is a valid address.
                    // CAST: The offset is cast to `i32` because the C functions expect a 32-bit
                    // signed offset parameter. PCI configuration space size is at most 4096 bytes,
                    // so the value always fits within `i32` without truncation or sign change.
                    unsafe { bindings::$write_fn(self.pdev.as_raw(), address as i32, value) };
            }
        }
    };
}

// PCI configuration space supports 8, 16, and 32-bit accesses.
impl_config_space_io_capable!(u8, pci_read_config_byte, pci_write_config_byte);
impl_config_space_io_capable!(u16, pci_read_config_word, pci_write_config_word);
impl_config_space_io_capable!(u32, pci_read_config_dword, pci_write_config_dword);

impl<'a, S: ConfigSpaceKind> Io for ConfigSpace<'a, S> {
    /// Returns the base address of the I/O region. It is always 0 for configuration space.
    #[inline]
    fn addr(&self) -> usize {
        0
    }

    /// Returns the maximum size of the configuration space.
    #[inline]
    fn maxsize(&self) -> usize {
        self.pdev.cfg_size().into_raw()
    }
}

impl<'a, S: ConfigSpaceKind> IoKnownSize for ConfigSpace<'a, S> {
    const MIN_SIZE: usize = S::SIZE;
}

/// A PCI BAR to perform I/O-Operations on.
///
/// I/O backend assumes that the device is little-endian and will automatically
/// convert from little-endian to CPU endianness.
///
/// # Invariants
///
/// `Bar` always holds an `IoRaw` instance that holds a valid pointer to the start of the I/O
/// memory mapped PCI BAR and its size.
pub struct Bar<'a, const SIZE: usize = 0> {
    pdev: &'a Device<device::Bound>,
    io: MmioRaw<SIZE>,
    num: i32,
}

impl<'a, const SIZE: usize> Bar<'a, SIZE> {
    pub(super) fn new(
        pdev: &'a Device<device::Bound>,
        num: u32,
        name: &'static CStr,
    ) -> Result<Self> {
        let len = pdev.resource_len(num)?;
        if len == 0 {
            return Err(ENOMEM);
        }

        // Convert to `i32`, since that's what all the C bindings use.
        let num = i32::try_from(num)?;

        // SAFETY:
        // `pdev` is valid by the invariants of `Device`.
        // `num` is checked for validity by a previous call to `Device::resource_len`.
        // `name` is always valid.
        let ret = unsafe { bindings::pci_request_region(pdev.as_raw(), num, name.as_char_ptr()) };
        if ret != 0 {
            return Err(EBUSY);
        }

        // SAFETY:
        // `pdev` is valid by the invariants of `Device`.
        // `num` is checked for validity by a previous call to `Device::resource_len`.
        // `name` is always valid.
        let ioptr: usize = unsafe { bindings::pci_iomap(pdev.as_raw(), num, 0) } as usize;
        if ioptr == 0 {
            // SAFETY:
            // `pdev` is valid by the invariants of `Device`.
            // `num` is checked for validity by a previous call to `Device::resource_len`.
            unsafe { bindings::pci_release_region(pdev.as_raw(), num) };
            return Err(ENOMEM);
        }

        let io = match MmioRaw::new(ioptr, len as usize) {
            Ok(io) => io,
            Err(err) => {
                // SAFETY:
                // `pdev` is valid by the invariants of `Device`.
                // `ioptr` is guaranteed to be the start of a valid I/O mapped memory region.
                // `num` is checked for validity by a previous call to `Device::resource_len`.
                unsafe { Self::do_release(pdev, ioptr, num) };
                return Err(err);
            }
        };

        Ok(Bar { pdev, io, num })
    }

    /// # Safety
    ///
    /// `ioptr` must be a valid pointer to the memory mapped PCI BAR number `num`.
    unsafe fn do_release(pdev: &Device, ioptr: usize, num: i32) {
        // SAFETY:
        // `pdev` is valid by the invariants of `Device`.
        // `ioptr` is valid by the safety requirements.
        // `num` is valid by the safety requirements.
        unsafe {
            bindings::pci_iounmap(pdev.as_raw(), ioptr as *mut c_void);
            bindings::pci_release_region(pdev.as_raw(), num);
        }
    }

    fn release(&self) {
        // SAFETY: The safety requirements are guaranteed by the type invariant of `self.pdev`.
        unsafe { Self::do_release(self.pdev, self.io.addr(), self.num) };
    }

    /// Consume the `Bar` and register it as a device-managed resource.
    ///
    /// The returned `Devres<Bar<'static, SIZE>>` can outlive the original lifetime `'a`. Access
    /// to the BAR is revoked when the device is unbound.
    pub fn into_devres(self) -> Result<Devres<Bar<'static, SIZE>>> {
        // SAFETY: Casting to `'static` is sound because `Devres` guarantees the `Bar` does not
        // actually outlive the device -- access is revoked and the resource is released when the
        // device is unbound.
        let bar: Bar<'static, SIZE> = unsafe { core::mem::transmute(self) };
        let pdev = bar.pdev;
        Devres::new(pdev.as_ref(), bar)
    }
}

impl Bar<'_> {
    #[inline]
    pub(super) fn index_is_valid(index: u32) -> bool {
        // A `struct pci_dev` owns an array of resources with at most `PCI_NUM_RESOURCES` entries.
        index < bindings::PCI_NUM_RESOURCES
    }
}

impl<const SIZE: usize> Drop for Bar<'_, SIZE> {
    fn drop(&mut self) {
        self.release();
    }
}

impl<const SIZE: usize> Deref for Bar<'_, SIZE> {
    type Target = Mmio<SIZE>;

    fn deref(&self) -> &Self::Target {
        // SAFETY: By the type invariant of `Self`, the MMIO range in `self.io` is properly mapped.
        unsafe { Mmio::from_raw(&self.io) }
    }
}

impl Device<device::Bound> {
    /// Maps an entire PCI BAR after performing a region-request on it. I/O operation bound checks
    /// can be performed on compile time for offsets (plus the requested type size) < SIZE.
    pub fn iomap_region_sized<'a, const SIZE: usize>(
        &'a self,
        bar: u32,
        name: &'static CStr,
    ) -> Result<Bar<'a, SIZE>> {
        Bar::new(self, bar, name)
    }

    /// Maps an entire PCI BAR after performing a region-request on it.
    pub fn iomap_region<'a>(&'a self, bar: u32, name: &'static CStr) -> Result<Bar<'a>> {
        self.iomap_region_sized::<0>(bar, name)
    }

    /// Returns the size of configuration space.
    pub fn cfg_size(&self) -> ConfigSpaceSize {
        // SAFETY: `self.as_raw` is a valid pointer to a `struct pci_dev`.
        let size = unsafe { (*self.as_raw()).cfg_size };
        match size {
            256 => ConfigSpaceSize::Normal,
            4096 => ConfigSpaceSize::Extended,
            _ => {
                // PANIC: The PCI subsystem only ever reports the configuration space size as either
                // `ConfigSpaceSize::Normal` or `ConfigSpaceSize::Extended`.
                unreachable!();
            }
        }
    }

    /// Return an initialized normal (256-byte) config space object.
    pub fn config_space<'a>(&'a self) -> ConfigSpace<'a, Normal> {
        ConfigSpace {
            pdev: self,
            _marker: PhantomData,
        }
    }

    /// Return an initialized extended (4096-byte) config space object.
    pub fn config_space_extended<'a>(&'a self) -> Result<ConfigSpace<'a, Extended>> {
        if self.cfg_size() != ConfigSpaceSize::Extended {
            return Err(EINVAL);
        }

        Ok(ConfigSpace {
            pdev: self,
            _marker: PhantomData,
        })
    }
}