PCI(9)

🌸 NAME 🌸

okay bestie, welcome to PCI(9) from the Kernel Developer's Manual — this is the whole PCI bus interface crew, and yes, it's a lot of names, but we're gonna get through them together. 💖

pci, is_pci_device, pci_alloc_msi, pci_alloc_msix, pci_clear_pme, pci_disable_busmaster, pci_disable_io, pci_enable_busmaster, pci_enable_io, pci_enable_pme, pci_find_bsf, pci_find_cap, pci_find_dbsf, pci_find_device, pci_find_extcap, pci_find_htcap, pci_find_next_cap, pci_find_next_extcap, pci_find_next_htcap, pci_find_pcie_root_port, pci_get_id, pci_get_max_payload, pci_get_max_read_req, pci_get_powerstate, pci_get_vpd_ident, pci_get_vpd_readonly, pci_has_pm, pci_iov_attach, pci_iov_attach_name, pci_iov_detach, pci_msi_count, pci_msix_count, pci_msix_pba_bar, pci_msix_table_bar, pci_pending_msix, pci_read_config, pci_release_msi, pci_remap_msix, pci_restore_state, pci_save_state, pci_set_max_read_req, pci_set_powerstate, pci_write_config, pcie_adjust_config, pcie_flr, pcie_get_max_completion_timeout, pcie_read_config, pcie_wait_for_pending_transactions, pcie_write_config — PCI bus interface

---

✨ SYNOPSIS ✨

       #include <sys/bus.h>
       #include <dev/pci/pcireg.h>
       #include <dev/pci/pcivar.h>

       bool
       is_pci_device(device_t dev);

       int
       pci_alloc_msi(device_t dev, int *count);

       int
       pci_alloc_msix(device_t dev, int *count);

       void
       pci_clear_pme(device_t dev);

       int
       pci_disable_busmaster(device_t dev);

       int
       pci_disable_io(device_t dev, int space);

       int
       pci_enable_busmaster(device_t dev);

       int
       pci_enable_io(device_t dev, int space);

       void
       pci_enable_pme(device_t dev);

       device_t
       pci_find_bsf(uint8_t bus, uint8_t slot, uint8_t func);

       int
       pci_find_cap(device_t dev, int capability, int *capreg);

       device_t
       pci_find_dbsf(uint32_t domain, uint8_t bus, uint8_t slot, uint8_t func);

       device_t
       pci_find_device(uint16_t vendor, uint16_t device);

       int
       pci_find_extcap(device_t dev, int capability, int *capreg);

       int
       pci_find_htcap(device_t dev, int capability, int *capreg);

       int
       pci_find_next_cap(device_t dev, int capability, int start, int *capreg);

       int
       pci_find_next_extcap(device_t dev, int capability, int start,
           int *capreg);

       int
       pci_find_next_htcap(device_t dev, int capability, int start,
           int *capreg);

       device_t
       pci_find_pcie_root_port(device_t dev);

       int
       pci_get_id(device_t dev, enum pci_id_type type, uintptr_t *id);

       int
       pci_get_max_payload(device_t dev);

       int
       pci_get_max_read_req(device_t dev);

       int
       pci_get_powerstate(device_t dev);

       int
       pci_get_vpd_ident(device_t dev, const char **identptr);

       int
       pci_get_vpd_readonly(device_t dev, const char *kw, const char **vptr);

       bool
       pci_has_pm(device_t dev);

       int
       pci_msi_count(device_t dev);

       int
       pci_msix_count(device_t dev);

       int
       pci_msix_pba_bar(device_t dev);

       int
       pci_msix_table_bar(device_t dev);

       int
       pci_pending_msix(device_t dev, u_int index);

       uint32_t
       pci_read_config(device_t dev, int reg, int width);

       int
       pci_release_msi(device_t dev);

       int
       pci_remap_msix(device_t dev, int count, const u_int *vectors);

       void
       pci_restore_state(device_t dev);

       void
       pci_save_state(device_t dev);

       int
       pci_set_max_read_req(device_t dev, int size);

       int
       pci_set_powerstate(device_t dev, int state);

       void
       pci_write_config(device_t dev, int reg, uint32_t val, int width);

       uint32_t
       pcie_adjust_config(device_t dev, int reg, uint32_t mask, uint32_t val,
           int width);

       bool
       pcie_flr(device_t dev, u_int max_delay, bool force);

       int
       pcie_get_max_completion_timeout(device_t dev);

       uint32_t
       pcie_read_config(device_t dev, int reg, int width);

       bool
       pcie_wait_for_pending_transactions(device_t dev, u_int max_delay);

       void
       pcie_write_config(device_t dev, int reg, uint32_t val, int width);

       void
       pci_event_fn(void *arg, device_t dev);

       EVENTHANDLER_REGISTER(pci_add_device, pci_event_fn);

       EVENTHANDLER_DEREGISTER(pci_delete_resource, pci_event_fn);

       #include <dev/pci/pci_iov.h>

       int
       pci_iov_attach(device_t dev, nvlist_t *pf_schema, nvlist_t *vf_schema);

       int
       pci_iov_attach_name(device_t dev, nvlist_t *pf_schema,
           nvlist_t *vf_schema, const char *fmt, ...);

       int
       pci_iov_detach(device_t dev);

---

🎀 DESCRIPTION 🎀

okay so the pci set of functions is literally all about managing PCI devices. 💅 They split into several groups: raw configuration access, locating devices, device information, device configuration, and message signaled interrupts. We're doing this in order, bestie, no skipping.

The is_pci_device() function is your little vibe check for whether dev is a PCI device. 🦋

🔧 Raw Configuration Access 🔧

The pci_read_config() function reads data from the PCI configuration space of the device dev, at offset reg, with width specifying the size of the access. 📖

The pci_write_config() function writes the value val to the PCI configuration space of the device dev, at offset reg, with width specifying the size of the access. ✍️

The pcie_adjust_config() function modifies the value of a register in the PCI-express capability register set of device dev. The offset reg specifies a relative offset in the register set with width specifying the size of the access. The new value of the register is computed by modifying bits set in mask to the value in val. Any bits not specified in mask are preserved. The previous value of the register is returned. 🎀

The pcie_read_config() function reads the value of a register in the PCI-express capability register set of device dev. The offset reg specifies a relative offset in the register set with width specifying the size of the access. 👀

The pcie_write_config() function writes the value val to a register in the PCI-express capability register set of device dev. The offset reg specifies a relative offset in the register set with width specifying the size of the access. 💌

NOTE: Device drivers should only use these functions for functionality that is not available via another pci() function. bestie, that's a real one — don't reach for the raw stuff when a nicer pci() function already exists. 🫶

🦋 Locating Devices 🦋

The pci_find_bsf() function looks up the device_t of a PCI device, given its bus, slot, and func. The slot number actually refers to the number of the device on the bus, which does not necessarily indicate its geographic location in terms of a physical slot. Also note: if the system has multiple PCI domains, pci_find_bsf() only searches the first one. 👑 Actually, it is equivalent to:

pci_find_dbsf(0, bus, slot, func);

The pci_find_dbsf() function looks up the device_t of a PCI device, given its domain, bus, slot, and func. The slot number actually refers to the number of the device on the bus, which does not necessarily indicate its geographic location in terms of a physical slot. 🗺️

The pci_find_device() function looks up the device_t of a PCI device, given its vendor and device IDs. Note that there can be multiple matches for this search; this function only returns the first matching device. so like, not all of them, just the first one it finds. 💀

💜 Device Information 💜

The pci_find_cap() function locates the first instance of a PCI capability register set for the device dev. The capability to locate is specified by ID via capability. Constant macros of the form PCIY_xxx for standard capability IDs are defined in <dev/pci/pcireg.h>. If the capability is found, then *capreg is set to the offset in configuration space of the capability register set, and pci_find_cap() returns zero. If the capability is not found or the device does not support capabilities, pci_find_cap() returns an error. 🧚

The pci_find_next_cap() function locates the next instance of a PCI capability register set for the device dev. The start should be the *capreg returned by a prior pci_find_cap() or pci_find_next_cap(). When no more instances are located pci_find_next_cap() returns an error. 🔥

The pci_has_pm() function returns true if dev supports power management. ⚡

The pci_find_extcap() function locates the first instance of a PCI-express extended capability register set for the device dev. The extended capability to locate is specified by ID via capability. Constant macros of the form PCIZ_xxx for standard extended capability IDs are defined in <dev/pci/pcireg.h>. If the extended capability is found, then *capreg is set to the offset in configuration space of the extended capability register set, and pci_find_extcap() returns zero. If the extended capability is not found or the device is not a PCI-express device, pci_find_extcap() returns an error. 🌈

The pci_find_next_extcap() function locates the next instance of a PCI-express extended capability register set for the device dev. The start should be the *capreg returned by a prior pci_find_extcap() or pci_find_next_extcap(). When no more instances are located pci_find_next_extcap() returns an error. ✨

The pci_find_htcap() function locates the first instance of a HyperTransport capability register set for the device dev. The capability to locate is specified by type via capability. Constant macros of the form PCIM_HTCAP_xxx for standard HyperTransport capability types are defined in <dev/pci/pcireg.h>. If the capability is found, then *capreg is set to the offset in configuration space of the capability register set, and pci_find_htcap() returns zero. If the capability is not found or the device is not a HyperTransport device, pci_find_htcap() returns an error. 🦋

The pci_find_next_htcap() function locates the next instance of a HyperTransport capability register set for the device dev. The start should be the *capreg returned by a prior pci_find_htcap() or pci_find_next_htcap(). When no more instances are located pci_find_next_htcap() returns an error. 🌸

The pci_find_pcie_root_port() function walks up the PCI device hierarchy to locate the PCI-express root port upstream of dev. If a root port is not found, pci_find_pcie_root_port() returns NULL. 🎀

The pci_get_id() function reads an identifier from a device. The type flag is used to specify which identifier to read. The following flags are supported:

• PCI_ID_RID — Read the routing identifier for the device.
• PCI_ID_MSI — Read the MSI routing ID. This is needed by some interrupt controllers to route MSI and MSI-X interrupts. 👑

The pci_get_vpd_ident() function fetches a device's Vital Product Data (VPD) identifier string. If the device dev supports VPD and provides an identifier string, then *identptr is set to point at a read-only, null-terminated copy of the identifier string, and pci_get_vpd_ident() returns zero. If the device does not support VPD or does not provide an identifier string, then pci_get_vpd_ident() returns an error. 💖

So pci_get_vpd_readonly() is your girl for grabbing the value of one single VPD read-only keyword off the device dev — the keyword you want is named by that two-character string kw 💖 If the device actually supports VPD and has a read-only value for the keyword you asked for, then *vptr gets pointed at a read-only, null-terminated copy of that value, and the function returns zero. Slay. But if the device doesn't do VPD, or just doesn't have that keyword? It returns an error. No value for you, bestie 😭

Then there's pcie_get_max_completion_timeout() — it hands you the maximum completion timeout configured for dev, measured in microseconds ⏱️ And heads up: if dev is not a PCI-express device at all, it just returns zero. Also, when completion timeouts are disabled for dev, it still returns the maximum timeout that <emphasis>would</emphasis> be used if timeouts were enabled. Iconic of it tbh.

pcie_wait_for_pending_transactions() is the patient one — it waits for any pending transactions started by dev to finish, checking by polling the transactions pending flag in the PCI-express device status register 👀 It returns true once that transaction pending flag is clear. But if transactions are still pending after max_delay milliseconds, it returns false. If max_delay is zero, it does a single check — otherwise it may sleep while polling that flag. And if dev isn't a PCI-express device at all? It returns true. Respectfully, sure 💅

🛠️ Device Configuration 🛠️

pci_enable_busmaster() turns on PCI bus mastering for dev by setting the PCIM_CMD_BUSMASTEREN bit in the PCIR_COMMAND register. And pci_disable_busmaster() clears that bit. Flip it on, flip it off 🎀

pci_enable_io() enables memory or I/O port address decoding for dev by setting the PCIM_CMD_MEMEN or PCIM_CMD_PORTEN bit in the PCIR_COMMAND register — whichever is appropriate. pci_disable_io() clears that appropriate bit. The space argument tells it which resource is affected, and it can be either SYS_RES_MEMORY or SYS_RES_IOPORT as appropriate.

⚠️ Real talk: device drivers should <emphasis>generally not</emphasis> use these routines directly, okay? The PCI bus enables decoding automatically when a SYS_RES_MEMORY or SYS_RES_IOPORT resource is activated via bus_alloc_resource(9) or bus_activate_resource(9). Let the bus do her thing 💅

pci_get_max_payload() returns the current maximum TLP payload size in bytes for a PCI-express device. If dev isn't PCI-express, it returns zero. Simple as that 🦋

pci_get_max_read_req() returns the current maximum read request size in bytes for a PCI-express device — and again, if dev isn't PCI-express, zero.

pci_set_max_read_req() sets the PCI-express maximum read request size for dev. Heads up though: the requested size <emphasis>may be adjusted</emphasis>, and the function returns the actual size that got set, in bytes. If dev isn't a PCI-express device, it returns zero. So like, don't assume you got exactly what you asked for, bestie 🙈

pci_get_powerstate() returns the current power state of dev. If the device doesn't support power management capabilities, then you get the default state PCI_POWERSTATE_D0 back. These are the power states PCI defines:

• PCI_POWERSTATE_D0 — the state where the device is <emphasis>on and running</emphasis> ✨ It's getting full power from the system and delivering full functionality to the user. Main character energy fr.
• PCI_POWERSTATE_D1 — a class-specific low-power state where device context may or may not be lost. Buses in this state can't do anything to the bus, so they can't force devices to lose context.
• PCI_POWERSTATE_D2 — another class-specific low-power state where device context may or may not be lost. This one gets greater power savings than PCI_POWERSTATE_D1 🔋 But buses in this state <emphasis>can</emphasis> cause devices to lose some context, so devices must be prepared for the bus to be in this state or higher.
• PCI_POWERSTATE_D3 — the device is off and not running. Device context is lost, and power from the device can be removed 💀
• PCI_POWERSTATE_UNKNOWN — the state of the device is unknown. Mysterious. We don't know her.

pci_set_powerstate() is what you use to transition dev to the PCI power state state. But if the device doesn't support power management capabilities, or it doesn't support that specific power state state, then the function fails with EOPNOTSUPP 😤

pci_clear_pme() is the one that clears any pending PME# signal and disables generation of power management events.

pci_enable_pme() enables generation of power management events <emphasis>before</emphasis> you suspend a device. Get it set up first, then snooze 😴

pci_iov_attach() is how you advertise that a given device (plus its associated device driver) supports PCI Single-Root I/O Virtualization, aka SR-IOV 👑 A driver that supports SR-IOV <emphasis>must</emphasis> implement the PCI_IOV_INIT(9), PCI_IOV_ADD_VF(9) and PCI_IOV_UNINIT(9) methods — no skipping, it's required, periodt. This function should be called during the DEVICE_ATTACH(9) method.

If this function returns an error, the recommendation is that the device driver should <emphasis>still</emphasis> successfully attach, but just run with SR-IOV disabled. Basically: don't let the SR-IOV thing ruin the whole attach, bestie 🫶

The pf_schema and vf_schema parameters define what device-specific configuration parameters the device driver accepts when SR-IOV is enabled — for the Physical Function (PF) and for individual Virtual Functions (VFs) respectively. See pci_iov_schema(9) for the deets on how to construct the schema 📝 If either pf_schema or vf_schema is invalid, or specifies parameter names that conflict with parameter names already in use, then pci_iov_attach() returns an error and SR-IOV won't be available on the PF device. Rough.

And if a driver doesn't accept configuration parameters for either the PF device or the VF devices, the driver must pass an <emphasis>empty</emphasis> schema for that device. Empty is valid, okay?

🚨 Important ownership tea: the SR-IOV infrastructure takes ownership of the pf_schema and vf_schema and is responsible for freeing them. The driver must <emphasis>never</emphasis> free the schemas itself. Do not touch. Hands off. 💀

pci_iov_attach_name() is a variant of pci_iov_attach() that lets you specify the name of the associated character device in /dev/iov via fmt. Plain pci_iov_attach() just uses the name of dev as the device name. Cute either way 🎀

pci_iov_detach() advises the SR-IOV infrastructure that the driver for the given device is attempting to detach and that all SR-IOV resources for the device must be released. This function <emphasis>must</emphasis> be called during the DEVICE_DETACH(9) method if pci_iov_attach() was successfully called on the device and pci_iov_detach() has not subsequently been called on the device and returned no error.

If this function returns an error, the DEVICE_DETACH(9) method must fail and return an error — because detaching the PF driver while VF devices are active would cause system instability 😱 Not cute. Not the vibe. Do not do it.

Good news though: this function is safe to call and will always succeed if pci_iov_attach() previously failed with an error on the given device, or if pci_iov_attach() was never called on the device at all. So no stress there 💖

pci_save_state() and pci_restore_state() are the save-and-restore duo a device driver can use for standard PCI config registers 💾 pci_save_state() <emphasis>must</emphasis> be invoked while the device has valid state before pci_restore_state() can be used — order matters, bestie. And if the device is not in the fully-powered state (PCI_POWERSTATE_D0) when pci_restore_state() is invoked, then the device will be transitioned to PCI_POWERSTATE_D0 before any config registers get restored. It handles that for you ✨

pcie_flr() requests a Function Level Reset (FLR) of dev 🔄 If dev isn't a PCI-express device, or doesn't support Function Level Resets via the PCI-express device control register, then false is returned. Pending transactions get drained by disabling busmastering and calling pcie_wait_for_pending_transactions() <emphasis>before</emphasis> resetting the device. The max_delay argument is the maximum timeout to wait for pending transactions, exactly as described for pcie_wait_for_pending_transactions().

If pcie_wait_for_pending_transactions() fails with a timeout and force is false, busmastering gets re-enabled and false is returned. But if pcie_wait_for_pending_transactions() fails with a timeout and force is true, the device gets reset <emphasis>despite</emphasis> the timeout 😤 After the reset has been requested, pcie_flr sleeps for at least 100 milliseconds before returning true — beauty rest, she's earned it 💅

⚠️ Note that pcie_flr does <emphasis>not</emphasis> save and restore any state around the reset. The caller should save and restore state as needed. That's on you, bestie, not her 🙈

💌 Message Signaled Interrupts 💌

Message Signaled Interrupts (MSI) and Enhanced Message Signaled Interrupts (MSI-X) are PCI capabilities that give PCI devices an alternate method for signaling interrupts ⚡ The legacy INTx interrupt is available to PCI devices as a SYS_RES_IRQ resource with a resource ID of zero. MSI and MSI-X interrupts are available to PCI devices as one or more SYS_RES_IRQ resources with resource IDs greater than zero.

A driver <emphasis>must</emphasis> ask the PCI bus to allocate MSI or MSI-X interrupts using pci_alloc_msi() or pci_alloc_msix() before it can use MSI or MSI-X SYS_RES_IRQ resources. No allocation, no resources. That's the rule 📋

Also, a driver is <emphasis>not allowed</emphasis> to use the legacy INTx SYS_RES_IRQ resource if MSI or MSI-X interrupts have been allocated — and attempts to allocate MSI or MSI-X interrupts will fail if the driver is currently using the legacy INTx SYS_RES_IRQ resource. It goes both ways 😭 And a driver is only allowed to use <emphasis>either</emphasis> MSI <emphasis>or</emphasis> MSI-X, but not both. Pick one. Commit. 💅

pci_msi_count() returns the maximum number of MSI messages supported by the device dev. If the device doesn't support MSI, then pci_msi_count() returns zero.

pci_alloc_msi() attempts to allocate *count MSI messages for the device dev. Now, it may allocate <emphasis>fewer</emphasis> messages than you requested for various reasons — including asking for more messages than dev supports, or if the system has a shortage of available MSI messages 🍓 On success, *count is set to the number of messages actually allocated and pci_alloc_msi() returns zero.

The SYS_RES_IRQ resources for the allocated messages will be available at consecutive resource IDs beginning with one. If pci_alloc_msi() isn't able to allocate <emphasis>any</emphasis> messages, it returns an error.

💀 Heads up: MSI only supports message counts that are powers of two. So requests to allocate a non-power of two count of messages will fail. Math is math, bestie.

• pci_release_msi() — this is the "okay we're done here, give the messages back" function 💅 it releases any allocated MSI or MSI-X messages back to the system. But heads up, bestie: if any MSI or MSI-X SYS_RES_IRQ resources are still allocated by the driver, or if one of them has a configured interrupt handler, this function fails with EBUSY 😭. It returns zero on success and an error on failure, no cap.
• pci_msix_count() — returns the maximum number of MSI-X messages supported by the device dev. If the device doesn't support MSI-X at all, then pci_msix_count() just returns zero, that's it, that's the whole vibe.
• pci_msix_pba_bar() — returns the offset in configuration space of the Base Address Register (BAR) containing the MSI-X Pending Bit Array (PBA) for device dev. You can take that returned value and use it as the resource ID with bus_alloc_resource(9) and bus_release_resource(9) to allocate the BAR — iconic little handoff 🫶. If the device does not support MSI-X, then pci_msix_pba_bar() returns -1.
• pci_msix_table_bar() — same energy, different BAR ✨ it returns the offset in configuration space of the BAR containing the MSI-X vector table for device dev. The returned value can be used as the resource ID with bus_alloc_resource(9) and bus_release_resource(9) to allocate the BAR. And if the device does not support MSI-X, then pci_msix_table_bar() returns -1.
• pci_alloc_msix() — this one attempts to allocate *count MSI-X messages for the device dev 🔥. Note "attempts" — it may allocate fewer messages than requested for various reasons, including requests for more messages than the device dev supports, or if the system has a shortage of available MSI-X messages. On success, *count is set to the number of messages allocated and pci_alloc_msix() returns zero.

For MSI-X messages, the resource ID for each SYS_RES_IRQ resource identifies the index in the MSI-X table of the corresponding message. A resource ID of one maps to the first index of the MSI-X table; a resource ID of two identifies the second index in the table, etc. So pci_alloc_msix() assigns the *count messages allocated to the first *count table indices. If pci_alloc_msix() is not able to allocate any messages at all, it returns an error. And unlike MSI, MSI-X does not require message counts that are powers of two — no power-of-two gatekeeping here, we love to see it 🎀.

⚠️ Okay this next bit is important, write it on your hand: the BARs containing the MSI-X vector table and PBA must be allocated via bus_alloc_resource(9) before calling pci_alloc_msix() and must not be released until after calling pci_release_msi(). Also note that the vector table and PBA may be stored in the same BAR or in different BARs — either is valid, so don't assume.

• pci_pending_msix() — examines the dev device's PBA to determine the pending status of the MSI-X message at table index index. If the indicated message is pending, this function returns a non-zero value; otherwise, it returns zero. 💀 And passing an invalid index to this function will result in undefined behavior — so like, don't.
• pci_remap_msix() — as mentioned up in the description of pci_alloc_msix(), MSI-X messages are initially assigned to the first N table entries. A driver may use a different distribution of available messages to table entries via the pci_remap_msix() function ✨. Note that this function must be called after a successful call to pci_alloc_msix() but before any of the SYS_RES_IRQ resources are allocated. pci_remap_msix() returns zero on success, or an error on failure.

The vectors array should contain count message vectors. The array maps directly to the MSI-X table in that the first entry in the array specifies the message used for the first entry in the MSI-X table, the second entry in the array corresponds to the second entry in the MSI-X table, etc. The vector value in each array index can either be zero — meaning no message should be assigned to the corresponding MSI-X table entry — or it can be a number from one to N (where N is the count returned from the previous call to pci_alloc_msix()) to indicate which of the allocated messages should be assigned to the corresponding MSI-X table entry. Simple as 🍓.

If pci_remap_msix() succeeds, each MSI-X table entry with a non-zero vector will have an associated SYS_RES_IRQ resource whose resource ID corresponds to the table index as described above for pci_alloc_msix(). MSI-X table entries with a vector of zero will not have an associated SYS_RES_IRQ resource. Additionally, if any of the original messages allocated by pci_alloc_msix() are not used in the new distribution of messages in the MSI-X table, they will be released automatically — free real estate, no cleanup needed 🧚.

😭 One catch though: if a driver wishes to use fewer messages than were allocated by pci_alloc_msix(), the driver must use a single, contiguous range of messages beginning with one in the new distribution. pci_remap_msix() will fail if this condition is not met. Contiguous or nothing, bestie.

🦋 Device Events 🦋

The pci_add_device event handler is invoked every time a new PCI device is added to the system. And yes, that includes the creation of Virtual Functions via SR-IOV 👑

The pci_delete_device event handler is invoked every time a PCI device is removed from the system.

Both event handlers pass the device_t object of the relevant PCI device as dev to each callback function. Both event handlers are invoked while dev is unattached but with valid instance variables — like, it's not hooked up to a driver yet but it's still fully itself, yk? 🫶

---

👀 SEE ALSO 👀

pci(4), pciconf(8), bus_alloc_resource(9), bus_dma(9), bus_release_resource(9), bus_setup_intr(9), bus_teardown_intr(9), devclass(9), device(9), driver(9), eventhandler(9), rman(9)

"NewBus", FreeBSD Developers' Handbook, https://docs.freebsd.org/en/books/developers-handbook/.

Shanley and Anderson, PCI System Architecture, Addison-Wesley, 2nd Edition, ISBN 0-201-30974-2.

💖 AUTHORS 💖

This manual page was written by Bruce M Simpson <bms@FreeBSD.org> and John Baldwin <jhb@FreeBSD.org>. Legends, honestly 🎀

💀 BUGS 💀

The kernel PCI code has a number of references to "slot numbers". These do not refer to the geographic location of PCI devices, but to the device number assigned by the combination of the PCI IDSEL mechanism and the platform firmware. So like, do not read "slot" as "physical hole in the machine", bestie 🙈 — this should be taken note of when working with the kernel PCI code.

The PCI bus driver should allocate the MSI-X vector table and PBA internally as necessary rather than requiring the caller to do so. That's the wishlist, anyway ✨

---

and that's the whole page, bestie — you ate it 💅✨

This one's from Debian, dated May 18, 2026, and it lives at PCI(9) — go forth and slay your MSI-X allocations 🦋💜