Coder Social home page Coder Social logo

facebook / pcicrawler Goto Github PK

View Code? Open in Web Editor NEW
131.0 11.0 19.0 32 KB

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.

License: MIT License

Python 100.00%

pcicrawler's Introduction


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


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.

  -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.


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": [
        "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


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 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 install

Contributing to pcicrawler

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


pcicrawler is licensed, as found in the LICENSE file.

pcicrawler's People


ifel avatar


Wentao avatar Colby Ray avatar Vladimir Hulagov avatar Andrei Pokrovsky avatar  avatar Javier Tia avatar Suraj Ghimire avatar  avatar Dilan Patel avatar Hannes Baldursson avatar iqminiclip avatar Nicholas Santucci avatar Nick S. B. avatar Thorben avatar Liu Joy avatar Hsuan-Ting Lu avatar Oksana Tozhovez avatar  avatar nasbdh9 avatar  avatar  avatar Bruno Koppel avatar Raphael J Ortolan avatar Teodor Spæren avatar  avatar  avatar N Trivedi avatar  avatar  avatar  avatar  avatar  avatar Roshan Silwal avatar  avatar Aws Ismail avatar Yogesh Upadhyay avatar Christoph Curran avatar Chesky Hershkowitz avatar Alessandro Marchioro avatar  avatar Jean-Francois Panisset avatar j avatar Georgios Migdos avatar Phillip avatar Steven K. Baum avatar Ben Tulloch avatar Anton Yuzhaninov avatar Tristan Helmich avatar Joey Ezechiëls avatar Cedric Van Goethem avatar Tim Wright avatar Paul S avatar Fed avatar Algod Network avatar John Berlin avatar Mateusz Ryczek avatar Herbert Shin avatar Matt Helsley avatar Yiran Zhou avatar Miguel Angel avatar Beau Button avatar  avatar Matteo Dessalvi avatar  avatar Jon Hermansen avatar Krzysztof Wilczyński avatar Gvozden Neskovic avatar James Barton avatar Jonan CM avatar Arthur Wong avatar  avatar  avatar  avatar S J avatar Minwoo Im avatar lilkypimp1 avatar Grant Mackey avatar  avatar  avatar  avatar  avatar  avatar Juang JiaYu avatar Ox avatar Alexander Goldberg avatar Gregory Shulov avatar 爱可可-爱生活 avatar TD Mackey avatar Makoto Shimabukuro avatar  avatar Michał Kowieski avatar Nicolas Leal avatar Marcos  avatar  avatar Person avatar An0 avatar  avatar C A Hart avatar Mauricio Uribe avatar Alex Marchevskiy avatar


Killian Murphy avatar N Trivedi avatar Michael Mohr avatar Allan Young avatar James Cloos avatar Cami Williams avatar  avatar  avatar iqminiclip avatar Huang Jin avatar Nazir Ahamed avatar

pcicrawler's Issues

devices silently dropped when outputting in tree mode

pcicrawler -t displays nothing when all devices are root devices (e.g. when running on a VM as below):

# pcicrawler -t

Adding some print statement, I can see the devices are there, but are silently skipped:

# pcicrawler -t
<PCIDevice vendor_id=0x8086 device_id=0x1237 class_id=0x60000 domain_id=0x0000 bus_id=0x0000 bus_device_id=0x0000 device_function_id=0x0000>
<PCIDevice vendor_id=0x8086 device_id=0x7000 class_id=0x60100 domain_id=0x0000 bus_id=0x0000 bus_device_id=0x0001 device_function_id=0x0000>
<PCIDevice vendor_id=0x8086 device_id=0x7010 class_id=0x10180 domain_id=0x0000 bus_id=0x0000 bus_device_id=0x0001 device_function_id=0x0001>
<PCIDevice vendor_id=0x8086 device_id=0x7020 class_id=0xc0300 domain_id=0x0000 bus_id=0x0000 bus_device_id=0x0001 device_function_id=0x0002>
<PCIDevice vendor_id=0x8086 device_id=0x7113 class_id=0x68000 domain_id=0x0000 bus_id=0x0000 bus_device_id=0x0001 device_function_id=0x0003>
<PCIDevice vendor_id=0x1013 device_id=0x00B8 class_id=0x30000 domain_id=0x0000 bus_id=0x0000 bus_device_id=0x0002 device_function_id=0x0000>
<PCIDevice vendor_id=0x1AF4 device_id=0x1000 class_id=0x20000 domain_id=0x0000 bus_id=0x0000 bus_device_id=0x0003 device_function_id=0x0000>
<PCIDevice vendor_id=0x1AF4 device_id=0x1001 class_id=0x10000 domain_id=0x0000 bus_id=0x0000 bus_device_id=0x0004 device_function_id=0x0000>
<PCIDevice vendor_id=0x1AF4 device_id=0x1002 class_id=0xff00 domain_id=0x0000 bus_id=0x0000 bus_device_id=0x0005 device_function_id=0x0000>

Would it be possible to display these devices in tree mode?

Compare to e.g. the output of lspci in tree mode:

# lspci -t -vv
-[0000:00]-+-00.0  Intel Corporation 440FX - 82441FX PMC [Natoma]
           +-01.0  Intel Corporation 82371SB PIIX3 ISA [Natoma/Triton II]
           +-01.1  Intel Corporation 82371SB PIIX3 IDE [Natoma/Triton II]
           +-01.2  Intel Corporation 82371SB PIIX3 USB [Natoma/Triton II]
           +-01.3  Intel Corporation 82371AB/EB/MB PIIX4 ACPI
           +-02.0  Cirrus Logic GD 5446
           +-03.0  Red Hat, Inc. Virtio network device
           +-04.0  Red Hat, Inc. Virtio block device
           \-05.0  Red Hat, Inc. Virtio memory balloon

or to the output of pcicrawler without tree mode:

# pcicrawler
0000:00:04.0, Red Hat, Inc. (1af4) Virtio block device (1001)
0000:00:05.0, Red Hat, Inc. (1af4) Virtio memory balloon (1002)
0000:00:01.1, Intel Corporation (8086) 82371SB PIIX3 IDE [Natoma/Triton II] (7010)
0000:00:01.3, Intel Corporation (8086) 82371AB/EB/MB PIIX4 ACPI (7113)
0000:00:02.0, Cirrus Logic (1013) GD 5446 (00b8)
0000:00:03.0, Red Hat, Inc. (1af4) Virtio network device (1000)
0000:00:01.2, Intel Corporation (8086) 82371SB PIIX3 USB [Natoma/Triton II] (7020)
0000:00:01.0, Intel Corporation (8086) 82371SB PIIX3 ISA [Natoma/Triton II] (7000)
0000:00:00.0, Intel Corporation (8086) 440FX - 82441FX PMC [Natoma] (1237)

Error while running `pcicrawler` utility

While running the pcicrawler utility from within a virtual-environment - Following ModuleNotFound error is observed -

(venv) [email protected]:~/backup/personal-code/pcicrawler$ pcicrawler
Traceback (most recent call last):
  File "/home/gabhijit/backup/personal-code/pcicrawler/venv/bin/pcicrawler", line 11, in <module>
    load_entry_point('pcicrawler==0.1.0', 'console_scripts', 'pcicrawler')()
  File "/home/gabhijit/backup/personal-code/pcicrawler/venv/lib/python3.7/site-packages/pkg_resources/", line 490, in load_entry_point
    return get_distribution(dist).load_entry_point(group, name)
  File "/home/gabhijit/backup/personal-code/pcicrawler/venv/lib/python3.7/site-packages/pkg_resources/", line 2859, in load_entry_point
    return ep.load()
  File "/home/gabhijit/backup/personal-code/pcicrawler/venv/lib/python3.7/site-packages/pkg_resources/", line 2450, in load
    return self.resolve()
  File "/home/gabhijit/backup/personal-code/pcicrawler/venv/lib/python3.7/site-packages/pkg_resources/", line 2456, in resolve
    module = __import__(self.module_name, fromlist=['__name__'], level=0)
  File "/home/gabhijit/backup/personal-code/pcicrawler/venv/lib/python3.7/site-packages/pcicrawler-0.1.0-py3.7.egg/pcicrawler/", line 12, in <module>
ModuleNotFoundError: No module named 'pcicrawler.lib'

Indeed there is no module named lib inside pcicrawler.

This error is observed while running from the checked out repo after doing a install in virtualenv.

Extend the tool to dump config space

Bumped into this tool. Built and installed it for ubuntu 18.04. I was hoping this would dump config space in a humanly readable format. Let me know if this is something being planned.

Failure when running on ubuntu focal


Traceback (most recent call last):
  File "/usr/local/bin/pcicrawler", line 8, in <module>
  File "/usr/local/lib/python3.8/dist-packages/click/", line 1137, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.8/dist-packages/click/", line 1062, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.8/dist-packages/click/", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.8/dist-packages/click/", line 763, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/lib/python3.8/dist-packages/pcicrawler/", line 292, in main
    exptype = dev.express_type
  File "/usr/local/lib/python3.8/dist-packages/pci_lib/", line 42, in __get__
    value = obj.__dict__[self.func.__name__] = self.func(obj)
  File "/usr/local/lib/python3.8/dist-packages/pci_lib/", line 553, in express_type
    express = find_capability(config, PCI_CAP_EXPRESS)
  File "/usr/local/lib/python3.8/dist-packages/pci_lib/", line 153, in find_capability
    cap_id = read_u8(config, pos)
  File "/usr/local/lib/python3.8/dist-packages/pci_lib/", line 122, in read_u8
    r, = struct.unpack('B', data[offset:offset + 1])
  File "/usr/local/lib/python3.8/dist-packages/pci_lib/", line 299, in __getitem__
    return b''.join(int2byte(b) for b in data)
  File "/usr/local/lib/python3.8/dist-packages/pci_lib/", line 299, in <genexpr>
    return b''.join(int2byte(b) for b in data)
struct.error: required argument is not an integer```

Root permissions should not be a requirement?

After looking at all the options available through --help. It looks like this is a read-only access to pci config space. So ideally root access should not be a requirement.

Also took a quick look at sysfs - /sys/pci/devices/

ls -rtl /sys/devices/pci0000\:00/0000\:00\:00.0/config 
-rw-r--r-- 1 root root 256 Aug  6 23:28 /sys/devices/pci0000:00/0000:00:00.0/config

shows config space is world readable.

Also, I can run lspci -t without a root user.

I quickly tried to remove the check and test - it's not working consistently. But once or twice it did show up a couple of devices!

Add to PyPi

Publish a package for this on PyPi. Among other things, this will make it easier to get pcicrawler packaged in distros

Renaming master branch to main

Renaming master branch to main

As a part of a broad effort to avoid problematic terminology in our software, we are renaming our default branch from master to main. We recognize that this is only a small step, but it is an opportunity to make our project and community more welcoming to historically marginalized communities.

How does this impact my development process?

There should be very little impact. GitHub will surface the branch name change in your fork, if you have one. For new forks, you will automatically have main as the default branch.

We encourage the use of feature branches for local development. The only change in practice is changing which branch your feature branch is started from. When sending Pull Requests on GitHub, the target will default to our main branch, so there are no changes to make there.

I have a lot of tools that depend on master being the upstream branch name. How can I fix that?

master has always been only a default value and a number of projects have used other names for their primary development branch for years. We encourage updating your tooling to instead dynamically determine the branch to use. This article provides insight into how you can do that. Additionally, you can always set up a branch locally of any name to track our main branch.

I'd like to do this for my own projects, do you have any documentation on how this works?

GitHub has published a guide documenting their tooling. We recommend reading that and the accompanying documentation.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.