Manual Pages  — PCI

The pci_enable_io() function enables memory or I/O port address decoding for the device dev, by setting the PCIM_CMD_MEMEN or PCIM_CMD_PORTEN bit in the PCIR_COMMAND register appropriately. The pci_disable_io() function clears the appropriate bit. The space argument specifies which resource is affected; this can be either SYS_RES_MEMORY or SYS_RES_IOPORT as appropriate. Device drivers should generally not use these routines directly. The PCI bus will enable decoding automatically when a SYS_RES_MEMORY or SYS_RES_IOPORT resource is activated via bus_alloc_resource(9) or bus_activate_resource(9).

The pci_get_max_payload() function returns the current maximum TLP payload size in bytes for a PCI-express device. If the dev device is not a PCI-express device, pci_get_max_payload() returns zero.

The pci_get_max_read_req() function returns the current maximum read request size in bytes for a PCI-express device. If the dev device is not a PCI-express device, pci_get_max_read_req() returns zero.

The pci_set_max_read_req() sets the PCI-express maximum read request size for dev. The requested size may be adjusted, and pci_set_max_read_req() returns the actual size set in bytes. If the dev device is not a PCI-express device, pci_set_max_read_req() returns zero.

The pci_get_powerstate() function returns the current power state of the device dev. If the device does not support power management capabilities, then the default state of PCI_POWERSTATE_D0 is returned. The following power states are defined by PCI:

PCI_POWERSTATE_D0	State in which device is on and running. It is receiving full power from the system and delivering full functionality to the user.
PCI_POWERSTATE_D1	Class-specific low-power state in which device context may or may not be lost. Buses in this state cannot do anything to the bus, to force devices to lose context.
PCI_POWERSTATE_D2	Class-specific low-power state in which device context may or may not be lost. Attains greater power savings than PCI_POWERSTATE_D1. Buses in this state can cause devices to lose some context. Devices must be prepared for the bus to be in this state or higher.
PCI_POWERSTATE_D3	State in which the device is off and not running. Device context is lost, and power from the device can be removed.
PCI_POWERSTATE_UNKNOWN
	State of the device is unknown.

The pci_set_powerstate() function is used to transition the device dev to the PCI power state state. If the device does not support power management capabilities or it does not support the specific power state state, then the function will fail with EOPNOTSUPP.

The pci_iov_attach() function is used to advertise that the given device (and associated device driver) supports PCI Single-Root I/O Virtualization (SR-IOV). A driver that supports SR-IOV must implement the PCI_IOV_INIT(9), PCI_IOV_ADD_VF(9) and PCI_IOV_UNINIT(9) methods. This function should be called during the DEVICE_ATTACH(9) method. If this function returns an error, it is recommended that the device driver still successfully attaches, but runs with SR-IOV disabled. The pf_schema and vf_schema parameters are used to 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 details on how to construct the schema. If either the pf_schema or vf_schema is invalid or specifies parameter names that conflict with parameter names that are already in use, pci_iov_attach() will return an error and SR-IOV will not be available on the PF device. If a driver does not accept configuration parameters for either the PF device or the VF devices, the driver must pass an empty schema for that device. The SR-IOV infrastructure takes ownership of the pf_schema and vf_schema and is responsible for freeing them. The driver must never free the schemas itself.

The pci_iov_attach_name() function is a variant of pci_iov_attach() that allows the name of the associated character device in /dev/iov to be specified by fmt. The pci_iov_attach() function uses the name of dev as the device name.

The pci_iov_detach() function is used to advise 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 must 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, as detaching the PF driver while VF devices are active would cause system instability. 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.

The pci_save_state() and pci_restore_state() functions can be used by a device driver to save and restore standard PCI config registers. The pci_save_state() function must be invoked while the device has valid state before pci_restore_state() can be used. 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 are restored.

The pcie_flr() function requests a Function Level Reset (FLR) of dev. If dev is not a PCI-express device or does not support Function Level Resets via the PCI-express device control register, false is returned. Pending transactions are drained by disabling busmastering and calling pcie_wait_for_pending_transactions() before resetting the device. The max_delay argument specifies the maximum timeout to wait for pending transactions as described for pcie_wait_for_pending_transactions(). If pcie_wait_for_pending_transactions() fails with a timeout and force is false, busmastering is re-enabled and false is returned. If pcie_wait_for_pending_transactions() fails with a timeout and force is true, the device is reset despite the timeout. After the reset has been requested, pcie_flr sleeps for at least 100 milliseconds before returning true. Note that pcie_flr does not save and restore any state around the reset. The caller should save and restore state as needed.

The pci_msix_pba_bar() function returns the offset in configuration space of the Base Address Register (BAR) containing the MSI-X Pending Bit Array (PBA) 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. If the device does not support MSI-X, then pci_msix_pba_bar() returns -1.

The pci_msix_table_bar() function 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. If the device does not support MSI-X, then pci_msix_table_bar() returns -1.

The pci_alloc_msix() function attempts to allocate *count MSI-X messages for the device dev. The pci_alloc_msix() function 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 two identifies the second index in the table, etc. The pci_alloc_msix() function assigns the *count messages allocated to the first *count table indices. If pci_alloc_msix() is not able to allocate any messages, it returns an error. Unlike MSI, MSI-X does not require message counts that are powers of two.

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(). Note that the vector table and PBA may be stored in the same BAR or in different BARs.

The pci_pending_msix() function 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. Passing an invalid index to this function will result in undefined behavior.

As mentioned 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. The pci_remap_msix() function 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 to indicate that 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.

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 that 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. Note that 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. The pci_remap_msix() function will fail if this condition is not met.

FreeBSD Developers' Handbook, NewBus,

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