facebook / pcicrawler

pcicrawler is a Python based command line interface tool which can be used to display, filter and export information about PCI (Peripheral Component Interconnect) or PCIe buses and devices, as well as PCI topology.

pcicrawler

pcicrawler is a CLI tool to display/filter/export information about PCI or PCI Express devices and their topology.

Usage

pcicrawler must be run as root.

The full --help message is shown below.

Usage: pcicrawler [OPTIONS]

  Tool to display/filter/export information about PCI or PCI Express
  devices, as well as their topology.

  Must run as root as it uses privileged sysfs entries.

Options:
  -c, --class-id TEXT             Only show devices matching this PCI class ID
                                  in hex, or one of: nvme, ethernet, raid, gpu
  -d, --device TEXT               Only show devices matching this PCI
                                  vendor/device ID, (syntax like
                                  vendor:device, or vendor:, in hex)
  -e, --express-only / --no-express-only
                                  Only show PCIe devices
  -j, --json / --no-json          Output in JSON format
  -p, --include-path / --no-include-path
                                  Include devices upstream of matched devices
  -s, --addr TEXT                 Show device with this PCI address
  -t, --tree / --no-tree          Output as a tree
  -v, --verbose / --no-verbose    Show debugging output - not compatible with
                                  JSON/tree views
  -V, --vpd / --no-vpd            Include VPD data if present, does not
                                  workwith --tree
  -x, --hexify / --no-hexify      Output vendor/device/class IDs as hex
                                  strings instead of numbers in JSON output
  -a, --aer / --no-aer            Include PCIe Advanced Error Reporting (AER)
                                  information when available - only provided
                                  in JSON output
  --help                          Show this message and exit.

Examples

The most common use for pcicrawler is calling it with its --tree option.

(run as root)

$ pcicrawler -t

00:00.0 root_port
00:1d.0 root_port, "M.2 PCIE SSD - Boot drive SSD 0", slot 8, device present, speed 8GT/s, width x4
 └─01:00.0 endpoint, Toshiba America Info Systems (1179), device 0116
00:1d.4 root_port, "MEZZ_Conn", slot 12, device present, speed 8GT/s, width x2
 └─02:00.0 endpoint, Mellanox Technologies (15b3) MT27710 Family [ConnectX-4 Lx] (1015)
64:02.0 root_port, "M.2 PCIE SSD - 2nd Storage SSD 2", slot 7, device present, speed 8GT/s, width x4
 └─65:00.0 endpoint, Samsung Electronics Co Ltd (144d), device a808
64:03.0 root_port, "M.2 PCIE SSD - 1st Storage SSD 1", slot 8, device present, speed 8GT/s, width x4
 └─66:00.0 endpoint, Samsung Electronics Co Ltd (144d), device a808

Filter the output with the -s option.

(run as root)

$ pcicrawler -s 02:00.0 -t

00:1d.4 root_port, "MEZZ_Conn", slot 12, device present, speed 8GT/s, width x2
 └─02:00.0 endpoint, Mellanox Technologies (15b3) MT27710 Family [ConnectX-4 Lx] (1015)

Filter the output, list VPD data (if any), and put into machine-readable format (JSON).

(run as root)

$ pcicrawler -s 02:00.0 -V -j | python -m json.tool

{
    "0000:02:00.0": {
        "addr": "0000:02:00.0",
        "capable_speed": "8GT/s",
        "capable_width": 2,
        "class_id": 131072,
        "cur_speed": "8GT/s",
        "cur_width": 2,
        "device_id": 4117,
        "express_type": "endpoint",
        "location": "MEZZ_Conn",
        "path": [
            "0000:02:00.0",
            "0000:00:1d.4"
        ],
        "subsystem_device": 633,
        "subsystem_vendor": 5555,
        "target_speed": "8GT/s",
        "vendor_id": 5555,
        "vpd": {
            "fields": {
                "EC": "A2",
                "PN": "MCX4431N-GCAN_FB",
                "SN": "MT1751X14794",
                "V0": "PCIeGen3 x8",
                "V2": "MCX4431N-GCAN_FB",
                "V3": "8427f48749ebe7118000ec0d9ad2c336",
                "VA": "MLX:MODL=CX4431N:MN=MLNX:CSKU=V2:UUID=V3:PCI=V0"
            },
            "identifier_string": "CX4431N - ConnectX-4 LX QSFP28"
        }
    }
}

How pcicrawler works

pcicrawler retrieves information about a device from its resources in sysfs. For more information about how devices are organized on the system, visit https://www.kernel.org/doc/Documentation/filesystems/sysfs-pci.txt.

Requirements

pcicrawler requires Python3 and works with

• CentOS Linux 7

Building pcicrawler

pcicrawler is a Python package and a built .whl distribution can be made with

python3 setup.py bdist_wheel

Installing pcicrawler

pcicrawler is available on PyPi and can be installed with pip:

pip install pcicrawler

Additionally, pcicrawler is a Python package and can be installed from within the directory with

python3 setup.py install

Contributing to pcicrawler

See the CONTRIBUTING file for information on how to help out.

License

pcicrawler is licensed, as found in the LICENSE file.