FreeBSD pciconf: Separate PCI Identity, Driver Binding, and Resources

A device being visible on the PCI bus does not mean FreeBSD has attached a usable driver. Conversely, a driver name in a device list does not prove the device works at the application layer. pciconf(8) is useful because it exposes several different layers of evidence: the selector identifying a bus function, numeric vendor and device IDs, a name supplied by an identification database, the attached driver, and resource information. Keep those layers separate while troubleshooting.

Capture a read-only baseline

On the affected host, start with the release and a complete PCI listing:

freebsd-version -kru
pciconf -lv
pciconf -lcv

The -l mode lists PCI devices; -v adds human-readable vendor and device information; -c lists PCI capabilities. Save the full output before filtering it for a specific device. A description may be absent or misleading if the local identification database does not know an ID. The numeric vendor and device fields are stronger evidence for matching a hardware revision to driver documentation than a marketing name alone.

The selector has the form of a PCI domain, bus, slot, and function. Record the complete selector from the host where the problem occurs. The selector is an address in the current bus topology, not a permanent asset identifier: firmware settings, hardware moves, or different virtualization layouts can change it. Correlate the selector with numeric IDs and the boot log before claiming that two listings refer to the same physical card.

The manual’s list mode offers additional views. -b includes base address register information, while -B expands bridge decoding-window information. These are useful when a driver reports a resource-allocation conflict, but they are not a substitute for a driver log: the presence of a BAR only says that a PCI function exposes a resource. It does not demonstrate that the driver mapped it, initialized the chip, or brought up the service behind it. Capture resource views only when relevant to the incident; they can be noisy and platform-specific.

When comparing two hosts, prefer a small comparison table keyed by numeric vendor, device, subsystem, revision, and PCI class values. A differently worded vendor string is weak evidence of a hardware difference. Conversely, a matching broad product name can conceal a different revision or subsystem design. Keep the raw pciconf line alongside any interpretation so a later reader can re-evaluate the mapping.

Interpret driver binding cautiously

In pciconf -l output, an attached device is identified by a driver name and unit number; an unclaimed function is identified by a PCI selector. Thus none is a useful prompt to investigate binding, not proof that FreeBSD lacks a suitable driver. The FreeBSD Handbook uses pciconf -lv when identifying network hardware and then checks whether a module is needed. Driver matching, firmware availability, and a working network interface are separate checks.

For a network adapter, continue with ifconfig -a and the boot log. For a storage controller, use the storage subsystem’s inventory and error reports. Do not treat pciconf as a health test or infer link state, throughput, or firmware correctness from its device listing.

A practical triage order is: first confirm the function is enumerated; next confirm the numeric IDs and class; then confirm a driver has attached; then inspect driver-specific diagnostics; finally test the application’s actual operation. The failure location changes the next action. A missing function suggests firmware, slot, passthrough, or hardware investigation. A visible but unbound function suggests driver matching or support. An attached driver with no usable interface calls for firmware, configuration, or runtime-error evidence. Skipping directly from “visible” to “hardware works” loses that distinction.

Do not automatically load a module just because a none entry appears. FreeBSD can list PCI bridge functions and other components that do not correspond to a user-facing interface, and loading an unrelated module may not change the binding. Match the exact IDs to the driver manual, inspect dmesg, and make changes in a maintenance window if the device is part of the boot path or remote access path.

Know where observation becomes intervention

The pciconf manual also documents configuration-space reads and writes. A targeted -r read is not the same as the routine list modes: the manual warns that reading registers can trigger failures on badly designed PCI devices. A -w operation changes configuration space; BAR access and reset-related operations can affect live hardware. Do not put such commands into a generic inventory script or paste an offset from another model’s runbook into production.

If a driver change is proposed, first preserve the baseline, identify the exact device and host, check the release-specific driver and firmware documentation, and arrange a rollback path. After the change, compare the PCI listing, boot messages, device node or interface inventory, and a real workload test. A changed driver label is only one part of the result.

For reproducible evidence, include the command, FreeBSD release, capture time, and whether the listing was taken on bare metal, in a VM, or inside a host configuring passthrough. Redact serial numbers or asset-identifying VPD before sharing logs outside the team. If the target is a removable or hot-pluggable device, take a second listing after the event and compare the entire function set, not just the line that first looked suspicious.

This distinction matters especially for PCI passthrough: the host must not simultaneously own a device that a guest is expected to control. Treat the PCI identity and host binding evidence here as input to a separate passthrough plan, not as authorization to detach a device on a running system.

Related:

Sources:

Capture a read-only baseline

Interpret driver binding cautiously

Know where observation becomes intervention

Comments