Crate pci_info

source ·
Expand description

The pci-info crate provides a simple API to enumerate PCI devices across “desktop” operating systems (Linux, Windows, MacOS, with more to be added), or to parse PCI headers from files or memory buffers.

It supports parsing of PCI metadata and availability of the various fields (including possibly the entire standard PCI configuration space of a device); the level of support is subject to the capabilities of the enumerator in use.

It uses user-mode APIs only, accessible from normal users (i.e. no root/Administrator needed). All code has been implemented from scratch through openly available documentation. As such it usually provides less data than some alternative solutions (e.g. libpci) but with less strict requirements (both in terms of licensing and available properties on some platforms).

PCI device classes, subclassses and interface functions are optionally exposed as rusty enums for quick matching, and have been implemented from publicly available documentation.

PCI vendor and device ids are kept as u16 and have to be manually interpreted or transformed into strings using other crates; the publicly available list of PCI vendors and devices is intentionally not included to contain the crate size (the complete list is large) and to avoid licensing issues (this crate being MIT+Apache dual licensed, the list being GPL+BSD dual licensed).

§Functionality

  • Enumeration of devices using OS usermode APIs on Windows, Linux and macOS, with more platforms to be added. See the PciInfo type.
  • Parsing of PCI headers starting from byte arrays of the PCI configuration space. See the pci_headers module.
  • Parsing of PCI device classes, subclasses and interface-functions from their codes. See the pci_enums module.

§Examples

Using the library with a default enumerator is straightforward:

use pci_info::PciInfo;

pub fn main() {
    // Enumerate the devices on the PCI bus using the default
    // enumerator for the current platform. The `unwrap()` panics if
    // the enumeration fatally fails.
    let info = PciInfo::enumerate_pci().unwrap();

    // Print out some properties of the enumerated devices.
    // Note that the collection contains both devices and errors
    // as the enumeration of PCI devices can fail entirely (in which
    // case `PciInfo::enumerate_pci()` would return error) or
    // partially (in which case an error would be inserted in the
    // result).
    for r in info {
        match r {
            Ok(device) => println!("{device:?}"),
            Err(error) => eprintln!("{error}"),
        }
    }
}

§Using a custom enumerator

If so desired, a custom enumerator can be used, using the enumerate_pci_with_enumerator method of the PciInfo type.

For example:

// NOTE: This example runs only on Windows as it uses a platform
// specific PCI enumerator.

use pci_info::{enumerators, PciInfo, PciInfoError};

#[cfg(target_os = "windows")]
pub fn main() -> Result<(), PciInfoError> {
    // Enumerate the devices by accessing the `enumerate_pci_with_enumerator`
    // method of the `PciInfo` type.
    let info = PciInfo::enumerate_pci_with_enumerator(enumerators::WindowsWmiPciEnumerator)?;

    for r in info {
        match r {
            Ok(device) => println!("{device:?}"),
            Err(error) => eprintln!("{error}"),
        }
    }

    Ok(())
}

Alternatively, you can directly call the enumerate_pci of the PciEnumerator trait. The recommended syntax is through the PciInfo::enumerate_pci_with_enumerator method, though.

// NOTE: This example runs only on Linux as it uses a platform
// specific PCI enumerator.

use pci_info::{enumerators, enumerators::PciEnumerator, PciInfoError};

#[cfg(target_os = "linux")]
pub fn main() -> Result<(), PciInfoError> {
    // Create a Linux-specific custom enumerator.
    let enumerator = enumerators::LinuxProcFsPciEnumerator::Fastest;
    // Enumerate the devices by accessing the `enumerate_pci`
    // method of the `PciEnumerator` trait. Works but using
    // `PciInfo::enumerate_pci_with_enumerator` is preferred.
    let info = enumerator.enumerate_pci()?;

    for r in info {
        match r {
            Ok(device) => println!("{device:?}"),
            Err(error) => eprintln!("{error}"),
        }
    }

    Ok(())
}

§Features

The crate is configurable with the following features:

Crate featureDefaultDescription
pci_class_debug_stringsYESIncludes human readable debug strings for variants of pci_enums::PciDeviceClass. Disable to reduce the binary size.
pci_subclass_debug_stringsYESIncludes human readable debug strings for variants of pci_enums::PciDeviceSubclass. Disable to reduce the binary size.
pci_interface_func_debug_stringYESIncludes human readable debug strings for variants of pci_enums::PciDeviceInterfaceFunc. Disable to reduce the binary size.

Re-exports§

Modules§

  • enumerators
    This module implements the various enumerations that can be used to enumerate PCI devices. In addition, it also provides the default_pci_enumerator() function to create the current platform’s default enumerator.
  • pci_enums
    This module contains enumerations describing the possible value for device class codes (PciDeviceClass), device subclass codes (PciDeviceSubclass) and interface function codes (PciDeviceInterfaceFunc).
  • pci_headers
    This module offers access to the raw values of the PCI configuration space headers, if (and only if) supported by the PCI enumerator in use.

Structs§

  • PciBusNumber
    A bus number in the PCI hierarchy (i.e. a segment:bus tuple). The segment (also called domain in some contexts) is usually zero and unsupported by most enumerators.
  • PciDevice
    A struct representing the data of a PCI device as discovered through the OS APIs by the enumerator in use. An enumerator is not required to fill all the fields of a PciDevice object. As such most members are optional and only the vendor_id() and device_id() are required to be valid. Check the documentation of the enumerator in use to see what values are expected to be filled.
  • PciDeviceEnumerationError
    A non-fatal error that impacted the enumeration of one or more devices.
  • PciInfo
    Holds the result of an enumeration of PCI devices. Use the enumerate_pci and enumerate_pci_with_enumerator methods to enumerate PCI devices and create a new instance, or simply use the PciEnumerator::enumerate_pci trait method.
  • PciInfoErrorString
    A string type used to optimize size and various operations on the error types of this crate.
  • PciLocation
    A location in the PCI hierarchy (i.e. a segment:bus:device.function tuple). The segment (also called domain in some contexts) is usually zero and unsupported by most enumerators.

Enums§