What You Will Learn

Prerequisites

From pci_dev to pci_driver: Why Matching Matters

A PCI bus can be enumerated with dozens of devices sitting on it, each described internally by its own struct pci_dev. But a struct pci_dev by itself does not run any code — it is just data. What actually makes a device usable is a driver being bound to it. The PCI core’s job during boot, and again every time a device is hot-plugged, is to walk every registered PCI driver and ask a simple question for each one: “does any entry in your ID table describe this device?” This entire process is called device-driver matching, and it is what this lecture is really about.

This matching is not PCI-specific magic — it is built on the generic Linux driver model. Every bus type (PCI, USB, I2C, platform, and so on) implements a match() callback that the driver core calls whenever a new device or a new driver appears on that bus. For PCI, this callback is pci_bus_match(), and it compares the device’s vendor/device/class/subsystem fields against every entry of every registered driver’s id_table.

struct pci_device_id Explained

Every PCI driver ships a small, statically declared array that lists exactly which devices it is willing to handle. Each entry in that array is a struct pci_device_id. As of the current mainline kernel, the structure looks like this:

struct pci_device_id {
    __u32 vendor, device;      /* Vendor and Device ID or PCI_ANY_ID */
    __u32 subvendor, subdevice;/* Subsystem ID or PCI_ANY_ID */
    __u32 class, class_mask;   /* (class,subclass,prog-if) triplet */
    kernel_ulong_t driver_data;/* Private data passed to the driver */
    __u32 override_only;       /* Match only via driver_override, not auto-probe */
};

Here is what each field really does:

The ID-Matching Macros

Filling every field by hand for every entry is tedious and error-prone, so <linux/pci_ids.h> and <linux/mod_devicetable.h> provide macros that build a correctly-formed struct pci_device_id for the common cases:

/* Match one exact vendor:device pair, ignore subsystem and class */
PCI_DEVICE(vend, dev)

/* Match an exact vendor:device pair with a driver_data payload */
PCI_VDEVICE(vendor, device)

/* Match every device belonging to a PCI class, ignore vendor/device */
PCI_DEVICE_CLASS(dev_class, dev_class_mask)

/* Match a vendor:device pair AND a specific subsystem vendor:device */
PCI_DEVICE_SUB(vend, dev, subvend, subdev)

Any field left unspecified by these macros is automatically set to PCI_ANY_ID, a wildcard value telling the matching code “accept anything here.” Every ID table must end with a zero-filled sentinel entry — this is how the kernel knows where the array ends, since there is no length field alongside it.

Comparing the Matching Strategies

Exporting the ID Table to Userspace

A compiled driver’s ID table only matters to the kernel — but the hotplug system (udev) also needs to know, from userspace, which module to load for a newly appeared device, before that module is even loaded. This is solved with a single macro:

MODULE_DEVICE_TABLE(pci, my_pci_tbl);

This macro drops the entire ID table into a special ELF section inside the compiled .ko file. When the module is installed, depmod scans every module for this section and builds a plain-text table called modules.alias under /lib/modules/<kernel-version>/. From then on, whenever the kernel detects a new PCI device and emits a hotplug uevent, udev looks the device’s modalias string up in that table to find the correct module — without ever having to load every PCI driver on the system just to test-fit it.

struct pci_driver — The Registration Structure

Once the kernel finds a matching ID table, it needs to know which functions to call. That contract is struct pci_driver. The fields a typical modern driver actually fills in are:

struct pci_driver {
    const char *name;
    const struct pci_device_id *id_table;
    int  (*probe)(struct pci_dev *dev, const struct pci_device_id *id);
    void (*remove)(struct pci_dev *dev);
    void (*shutdown)(struct pci_dev *dev);
    const struct pci_error_handlers *err_handler;
    struct device_driver driver;   /* holds ->pm for power management */
};

Registering the Driver

A filled-in struct pci_driver is registered and unregistered with:

int  pci_register_driver(struct pci_driver *drv);
void pci_unregister_driver(struct pci_driver *drv);

Since nearly every PCI driver’s module_init()/module_exit() pair does nothing but call these two functions, the kernel provides a shortcut macro that generates both for you:

module_pci_driver(my_pci_driver);

Hands-On: An Original PCI ID-Matching Driver

Let’s put all of this together in a small, original driver — ep_pci_id_driver — targeting QEMU’s built-in edu educational PCI device (vendor 0x1234, device 0x11e8), the same test device used earlier in this series. This driver does nothing more than prove that matching and registration work correctly, which is exactly what you want when first learning this API.

#include <linux/module.h>
#include <linux/pci.h>
#include <linux/kernel.h>

#define EP_EDU_VENDOR_ID  0x1234
#define EP_EDU_DEVICE_ID  0x11e8

static const struct pci_device_id ep_pci_id_tbl[] = {
    { PCI_DEVICE(EP_EDU_VENDOR_ID, EP_EDU_DEVICE_ID) },
    { 0, }
};
MODULE_DEVICE_TABLE(pci, ep_pci_id_tbl);

static int ep_pci_id_probe(struct pci_dev *pdev,
                            const struct pci_device_id *id)
{
    dev_info(&pdev->dev,
             "ep_pci_id_driver: matched vendor=0x%04x device=0x%04x\n",
             pdev->vendor, pdev->device);
    return 0;
}

static void ep_pci_id_remove(struct pci_dev *pdev)
{
    dev_info(&pdev->dev, "ep_pci_id_driver: device removed\n");
}

static struct pci_driver ep_pci_id_driver = {
    .name     = "ep_pci_id_driver",
    .id_table = ep_pci_id_tbl,
    .probe    = ep_pci_id_probe,
    .remove   = ep_pci_id_remove,
};

module_pci_driver(ep_pci_id_driver);

MODULE_LICENSE("GPL");
MODULE_AUTHOR("EmbeddedPathashala");
MODULE_DESCRIPTION("EmbeddedPathashala PCI ID matching demo driver");

A minimal Makefile to build it against your running kernel headers:

obj-m += ep_pci_id_driver.o

KDIR := /lib/modules/$(shell uname -r)/build

all:
	make -C $(KDIR) M=$(PWD) modules

clean:
	make -C $(KDIR) M=$(PWD) clean

Building and Testing on QEMU

Boot the VM with the edu device attached (-device edu on the QEMU command line), then build and load the module:

$ make
$ sudo insmod ep_pci_id_driver.ko
$ dmesg | tail -n 3
[   41.208813] ep_pci_id_driver: probe of 0000:00:03.0
[   41.208820] ep_pci_id_driver: matched vendor=0x1234 device=0x11e8
$ lsmod | grep ep_pci_id_driver
ep_pci_id_driver       16384  0

Confirm that MODULE_DEVICE_TABLE did its job and depmod correctly exported the alias:

$ modinfo ep_pci_id_driver.ko | grep alias
alias:          pci:v00001234d000011E8sv*sd*bc*sc*i*

$ sudo rmmod ep_pci_id_driver
$ dmesg | tail -n 1
[   58.114402] ep_pci_id_driver: device removed

That single alias: line is exactly what gets written into modules.alias — it is the same string udev matches against a device’s own modalias when it decides which module to auto-load.

Common Mistakes and Troubleshooting

Best Practices

Summary and Key Takeaways

PCI driver registration boils down to two data structures working together: struct pci_device_id tells the kernel which devices you support, and struct pci_driver tells it which functions to call once a match is found. MODULE_DEVICE_TABLE() is the bridge that lets this same information drive userspace hotplug loading through depmod and modules.alias. Everything else — pci_register_driver(), module_pci_driver(), probe/remove — exists to plug your driver cleanly into that matching pipeline. With this piece in place, the PCI series is ready to move from “getting probed” to actually talking to device hardware: BARs, MMIO, and interrupts, most of which this course has already begun covering.

Frequently Asked Questions