PREV_LEC  |  NEXT_LEC

What You Will Learn

Prerequisites

This lecture continues our PCI/PCIe device driver series. Before reading further, we recommend finishing the earlier lectures on PCI/PCIe bus topology and enumeration, header types and BDF addressing, PCI address spaces and BAR mapping, and PCI interrupt distribution (legacy INTx vs MSI/MSI-X). A working knowledge of C, basic kernel module loading (insmod/rmmod), and a QEMU test environment is assumed — all covered earlier in this free linux kernel development course.

The Three Layers of the Linux PCI Software Stack

One of the most confusing parts for newcomers to Linux kernel PCI data structures is understanding *who* actually creates the device objects the driver eventually binds to. The kernel splits this responsibility across three cooperating layers, each with a distinct job:

Architecture PCI glue is the earliest piece to run. On modern ARM64 and most embedded SoCs this work has largely moved into the generic PCI core plus the host controller driver, but conceptually its job stays the same: get the bus numbered and ready before anything else touches it.

The host controller (often called the root complex) is SoC-specific. You will find these drivers under drivers/pci/controller/ in a modern kernel tree — for example the generic DesignWare-based controllers live under drivers/pci/controller/dwc/, while other SoC vendors ship their own controller driver in the same directory. This layer is responsible for generating configuration-space read/write cycles, exposing the memory/IO resource windows the SoC provides, and wiring up the INTx and MSI interrupt lines. Without a correctly initialized host controller, the PCI core has no bus to scan at all.

The PCI core, implemented mainly in drivers/pci/probe.c, is where the actual struct pci_dev and struct pci_bus objects are born. The core walks every bus/device/function combination reachable through the host controller, reads the standard configuration header from each function that responds, and allocates a pci_dev instance for it. It also creates the sysfs entries under /sys/bus/pci/devices/ that you use every day with tools like lspci, handles PCI Express port/bridge devices, and provides the MSI/MSI-X interrupt allocation framework your driver will call into.

Once the core has built this tree, it matches each pci_dev against the pci_device_id tables registered by loaded pci_driver structures and calls your probe() function — which brings us to the object your driver actually works with: struct pci_dev.

Inside struct pci_dev on a Modern Kernel

Every PCI or PCIe function detected on the bus gets exactly one struct pci_dev, defined in include/linux/pci.h. Understanding its fields is central to writing correct Linux kernel PCI data structures-aware drivers. Here are the fields you will use constantly:

The single most misunderstood field is irq. At boot, before any driver has touched interrupt configuration, irq simply holds the legacy INTx line the host controller pre-assigned. It stays that way until your driver explicitly calls pci_alloc_irq_vectors() (the modern replacement for the older pci_enable_msi() family). Once MSI mode is successfully negotiated, the kernel rewrites irq to the base Linux IRQ number of the allocated vector block — vector N then corresponds to pci_irq_vector(pdev, N), which is the API you should call rather than doing pointer arithmetic on pdev->irq yourself. This distinction matters a lot in real Linux kernel PCI data structures work, because reading irq too early, or assuming it never changes, is a recurring source of interrupt-routing bugs in embedded PCIe drivers.

Original Demo: Dumping pci_dev Fields From a Live Driver

Rather than reading about these fields in the abstract, let’s write a small original driver — ep_pci_dev_dump — that binds to a PCI function and logs the fields we just discussed straight into dmesg. We target the QEMU edu educational PCI device we introduced earlier in this series, since it is free, safe to experiment with, and needs no real hardware.

// ep_pci_dev_dump.c
#include <linux/module.h>
#include <linux/pci.h>
#include <linux/interrupt.h>

#define EP_VENDOR_ID 0x1234
#define EP_DEVICE_ID 0x11e8

static int ep_pci_dev_dump_probe(struct pci_dev *pdev,
                                  const struct pci_device_id *id)
{
    int nvec;

    if (pci_enable_device(pdev)) {
        dev_err(&pdev->dev, "ep_pci_dev_dump: enable failed\n");
        return -EIO;
    }

    dev_info(&pdev->dev, "ep_pci_dev_dump: vendor=0x%04x device=0x%04x\n",
              pdev->vendor, pdev->device);
    dev_info(&pdev->dev, "ep_pci_dev_dump: class=0x%06x revision=0x%02x\n",
              pdev->class, pdev->revision);
    dev_info(&pdev->dev, "ep_pci_dev_dump: hdr_type=%u irq(pre-MSI)=%u\n",
              pdev->hdr_type, pdev->irq);

    nvec = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_MSI | PCI_IRQ_LEGACY);
    if (nvec < 0) {
        dev_err(&pdev->dev, "ep_pci_dev_dump: irq vector alloc failed\n");
        pci_disable_device(pdev);
        return nvec;
    }

    dev_info(&pdev->dev, "ep_pci_dev_dump: msi_enabled=%d final irq=%d\n",
              pdev->msi_enabled, pci_irq_vector(pdev, 0));

    return 0;
}

static void ep_pci_dev_dump_remove(struct pci_dev *pdev)
{
    pci_free_irq_vectors(pdev);
    pci_disable_device(pdev);
    dev_info(&pdev->dev, "ep_pci_dev_dump: removed\n");
}

static const struct pci_device_id ep_pci_dev_dump_ids[] = {
    { PCI_DEVICE(EP_VENDOR_ID, EP_DEVICE_ID) },
    { 0, }
};
MODULE_DEVICE_TABLE(pci, ep_pci_dev_dump_ids);

static struct pci_driver ep_pci_dev_dump_driver = {
    .name     = "ep_pci_dev_dump",
    .id_table = ep_pci_dev_dump_ids,
    .probe    = ep_pci_dev_dump_probe,
    .remove   = ep_pci_dev_dump_remove,
};

module_pci_driver(ep_pci_dev_dump_driver);
MODULE_LICENSE("GPL");
MODULE_DESCRIPTION("EmbeddedPathashala - dump struct pci_dev fields");

Build it with a minimal Kbuild file against your running kernel headers:

obj-m += ep_pci_dev_dump.o

all:
	make -C /lib/modules/$(shell uname -r)/build M=$(PWD) modules

clean:
	make -C /lib/modules/$(shell uname -r)/build M=$(PWD) clean

$ make
$ sudo insmod ep_pci_dev_dump.ko
$ dmesg | tail -n 6

Expected output on a QEMU guest booted with -device edu:

ep_pci_dev_dump: vendor=0x1234 device=0x11e8
ep_pci_dev_dump: class=0x00ff00 revision=0x10
ep_pci_dev_dump: hdr_type=0 irq(pre-MSI)=11
ep_pci_dev_dump: msi_enabled=1 final irq=27

Notice how irq jumps from the legacy pre-assigned value to a fresh MSI vector once pci_alloc_irq_vectors() succeeds — exactly the behavior we described above, now confirmed on a live system rather than taken on faith.

Legacy INTx vs MSI/MSI-X: A Quick Comparison

Real-World Use Cases

Understanding these Linux kernel PCI data structures is not academic — it directly shapes how you write drivers for NVMe SSDs, GPU and display controllers, Wi-Fi/Bluetooth combo chips on M.2 modules, and embedded PCIe accelerators found in automotive and industrial SoCs. Whenever you debug a driver that never receives interrupts, or a device that shows the wrong class code in lspci, you are debugging exactly the fields covered in this lecture.

Common Mistakes and Troubleshooting

• Reading pdev->irq before calling pci_alloc_irq_vectors() and assuming it is the final MSI vector.
• Forgetting to call pci_enable_device() before touching BARs or IRQs — the device stays inaccessible until this is done.
• Not calling pci_free_irq_vectors() in remove(), leaking allocated MSI vectors on module unload.
• Assuming every device supports MSI-X; always check the return value of pci_alloc_irq_vectors() and fall back to legacy INTx via PCI_IRQ_LEGACY.
• Confusing class (24-bit, includes prog-if) with the base class byte alone when matching device types.

Best Practices

• Always request MSI/MSI-X first and let pci_alloc_irq_vectors() fall back to legacy INTx automatically via the flags argument.
• Use pci_irq_vector() rather than manual arithmetic on pdev->irq for every vector index.
• Set an appropriate dma_mask early in probe() if your device performs DMA — this affects buffer allocation later in the driver’s life.
• Release resources in the reverse order you acquired them: free IRQ vectors, then disable the device, mirroring the demo above.
• For security, never trust configuration-space values from an unverified device blindly when building driver logic that affects system stability — validate ranges before using them as array indices or loop bounds.

Interview Questions

Summary and Key Takeaways

In this lecture of our free linux kernel development course we broke the Linux PCI software stack into its host controller, PCI core, and driver layers, then examined struct pci_dev field by field on a modern kernel, paying special attention to how the irq field behaves differently under legacy INTx and MSI/MSI-X. We closed with an original ep_pci_dev_dump driver that proves these behaviors on a live QEMU edu device rather than just describing them. Mastering these Linux kernel PCI data structures is a prerequisite for every advanced PCIe topic we cover later in this series, including DMA-capable endpoint drivers and PCIe power management.

Frequently Asked Questions

PREV_LEC  |  NEXT_LEC