table of contents
PCI(9) | Kernel Developer's Manual | PCI(9) |
NAME¶
pci
,
pci_alloc_msi
,
pci_alloc_msix
,
pci_disable_busmaster
,
pci_disable_io
,
pci_enable_busmaster
,
pci_enable_io
,
pci_find_bsf
,
pci_find_cap
,
pci_find_dbsf
,
pci_find_device
,
pci_find_extcap
,
pci_find_htcap
,
pci_get_max_read_req
,
pci_get_powerstate
,
pci_get_vpd_ident
,
pci_get_vpd_readonly
,
pci_msi_count
,
pci_msix_count
,
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
—
PCI bus interface
SYNOPSIS¶
#include
<sys/bus.h>
#include
<dev/pci/pcireg.h>
#include
<dev/pci/pcivar.h>
int
pci_alloc_msi
(device_t
dev, int
*count);
int
pci_alloc_msix
(device_t
dev, int
*count);
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);
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_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);
int
pci_msi_count
(device_t
dev);
int
pci_msix_count
(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);
DESCRIPTION¶
Thepci
set of functions are used for
managing PCI devices. The functions are split into several groups: raw
configuration access, locating devices, device information, device
configuration, and message signaled interrupts.
Raw Configuration Access¶
Thepci_read_config
() function is used to
read 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 is used to
write the value val to the PCI configuration
space of the device dev, at offset
reg, 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.
Locating Devices¶
Thepci_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. Note that in case the system has
multiple PCI domains, the pci_find_bsf
()
function only searches the first one. Actually, it is equivalent to:
pci_find_dbsf(0, bus, slot, func);
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.
Device Information¶
Thepci_find_cap
() function is used to locate
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_extcap
() function is used to
locate 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_htcap
() function is used to
locate 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_get_vpd_ident
() function is used to
fetch 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.
The pci_get_vpd_readonly
() function is used
to fetch the value of a single VPD read-only keyword for the device
dev. The keyword to fetch is identified by
the two character string kw. If the device
supports VPD and provides a read-only value for the requested keyword, then
*vptr is set to point at a read-only,
null-terminated copy of the value, and
pci_get_vpd_readonly
() returns zero. If the
device does not support VPD or does not provide the requested keyword, then
pci_get_vpd_readonly
() returns an error.
Device Configuration¶
Thepci_enable_busmaster
() function enables
PCI bus mastering for the device dev, by
setting the PCIM_CMD_BUSMASTEREN
bit in the
PCIR_COMMAND
register. The
pci_disable_busmaster
() function clears
this bit.
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_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. Busses 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
. Busses 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.
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_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.
Message Signaled Interrupts¶
Message Signaled Interrupts (MSI) and Enhanced Message Signaled Interrupts (MSI-X) are PCI capabilities that provide an alternate method for PCI devices to signal interrupts. The legacy INTx interrupt is available to PCI devices as aSYS_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 must 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. A driver is
not allowed 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. A driver is only
allowed to use either MSI or MSI-X, but not both.
The pci_msi_count
() function returns the
maximum number of MSI messages supported by the device
dev. If the device does not support MSI, then
pci_msi_count
() returns zero.
The pci_alloc_msi
() function attempts to
allocate *count MSI messages for the device
dev. The
pci_alloc_msi
() 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 messages. On success,
*count is set to the number of messages
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
() is not able to allocate any
messages, it returns an error. Note that MSI only supports message counts that
are powers of two; requests to allocate a non-power of two count of messages
will fail.
The pci_release_msi
() function is used to
release any allocated MSI or MSI-X messages back to the system. If any MSI or
MSI-X SYS_RES_IRQ
resources are allocated
by the driver or have a configured interrupt handler, this function will fail
with EBUSY
. The
pci_release_msi
() function returns zero on
success and an error on failure.
The pci_msix_count
() function returns the
maximum number of MSI-X messages supported by the device
dev. If the device does not support MSI-X,
then pci_msix_count
() returns zero.
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 indicies. 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 pci_pending_msix
() function examines the
dev device's Pending Bit Array (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.
IMPLEMENTATION NOTES¶
The pci_addr_t type varies according to the size of the PCI bus address space on the target architecture.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), rman(9) NewBus, FreeBSD Developers' Handbook, http://www.FreeBSD.org/doc/en_US.ISO8859-1/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⟩ andJohn Baldwin ⟨jhb@FreeBSD.org⟩.
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. This should be taken note of when working with the kernel PCI code.March 5, 2012 | Debian |