PCI Support Library¶
-
unsigned char pci_bus_max_busnr(struct pci_bus *bus)¶
returns maximum PCI bus number of given bus’ children
Parameters
struct pci_bus *bus
pointer to PCI bus structure to search
Description
Given a PCI bus, returns the highest PCI bus number present in the set including the given PCI bus and its list of child PCI buses.
-
int pci_status_get_and_clear_errors(struct pci_dev *pdev)¶
return and clear error bits in PCI_STATUS
Parameters
struct pci_dev *pdev
the PCI device
Description
Returns error bits set in PCI_STATUS and clears them.
-
u8 pci_find_capability(struct pci_dev *dev, int cap)¶
query for devices’ capabilities
Parameters
struct pci_dev *dev
PCI device to query
int cap
capability code
Description
Tell if a device supports a given PCI capability. Returns the address of the requested capability structure within the device’s PCI configuration space or 0 in case the device does not support it. Possible values for cap include:
PCI_CAP_ID_PM
Power ManagementPCI_CAP_ID_AGP
Accelerated Graphics PortPCI_CAP_ID_VPD
Vital Product DataPCI_CAP_ID_SLOTID
Slot IdentificationPCI_CAP_ID_MSI
Message Signalled InterruptsPCI_CAP_ID_CHSWP
CompactPCI HotSwapPCI_CAP_ID_PCIX
PCI-XPCI_CAP_ID_EXP
PCI Express
-
u8 pci_bus_find_capability(struct pci_bus *bus, unsigned int devfn, int cap)¶
query for devices’ capabilities
Parameters
struct pci_bus *bus
the PCI bus to query
unsigned int devfn
PCI device to query
int cap
capability code
Description
Like pci_find_capability()
but works for PCI devices that do not have a
pci_dev structure set up yet.
Returns the address of the requested capability structure within the device’s PCI configuration space or 0 in case the device does not support it.
-
u16 pci_find_next_ext_capability(struct pci_dev *dev, u16 start, int cap)¶
Find an extended capability
Parameters
struct pci_dev *dev
PCI device to query
u16 start
address at which to start looking (0 to start at beginning of list)
int cap
capability code
Description
Returns the address of the next matching extended capability structure within the device’s PCI configuration space or 0 if the device does not support it. Some capabilities can occur several times, e.g., the vendor-specific capability, and this provides a way to find them all.
-
u16 pci_find_ext_capability(struct pci_dev *dev, int cap)¶
Find an extended capability
Parameters
struct pci_dev *dev
PCI device to query
int cap
capability code
Description
Returns the address of the requested extended capability structure within the device’s PCI configuration space or 0 if the device does not support it. Possible values for cap include:
PCI_EXT_CAP_ID_ERR
Advanced Error ReportingPCI_EXT_CAP_ID_VC
Virtual ChannelPCI_EXT_CAP_ID_DSN
Device Serial NumberPCI_EXT_CAP_ID_PWR
Power Budgeting
-
u64 pci_get_dsn(struct pci_dev *dev)¶
Read and return the 8-byte Device Serial Number
Parameters
struct pci_dev *dev
PCI device to query
Description
Looks up the PCI_EXT_CAP_ID_DSN and reads the 8 bytes of the Device Serial Number.
Returns the DSN, or zero if the capability does not exist.
-
u8 pci_find_next_ht_capability(struct pci_dev *dev, u8 pos, int ht_cap)¶
query a device’s HyperTransport capabilities
Parameters
struct pci_dev *dev
PCI device to query
u8 pos
Position from which to continue searching
int ht_cap
HyperTransport capability code
Description
To be used in conjunction with pci_find_ht_capability()
to search for
all capabilities matching ht_cap. pos should always be a value returned
from pci_find_ht_capability()
.
NB. To be 100% safe against broken PCI devices, the caller should take steps to avoid an infinite loop.
-
u8 pci_find_ht_capability(struct pci_dev *dev, int ht_cap)¶
query a device’s HyperTransport capabilities
Parameters
struct pci_dev *dev
PCI device to query
int ht_cap
HyperTransport capability code
Description
Tell if a device supports a given HyperTransport capability. Returns an address within the device’s PCI configuration space or 0 in case the device does not support the request capability. The address points to the PCI capability, of type PCI_CAP_ID_HT, which has a HyperTransport capability matching ht_cap.
-
u16 pci_find_vsec_capability(struct pci_dev *dev, u16 vendor, int cap)¶
Find a vendor-specific extended capability
Parameters
struct pci_dev *dev
PCI device to query
u16 vendor
Vendor ID for which capability is defined
int cap
Vendor-specific capability ID
Description
If dev has Vendor ID vendor, search for a VSEC capability with VSEC ID cap. If found, return the capability offset in config space; otherwise return 0.
-
u16 pci_find_dvsec_capability(struct pci_dev *dev, u16 vendor, u16 dvsec)¶
Find DVSEC for vendor
Parameters
struct pci_dev *dev
PCI device to query
u16 vendor
Vendor ID to match for the DVSEC
u16 dvsec
Designated Vendor-specific capability ID
Description
If DVSEC has Vendor ID vendor and DVSEC ID dvsec return the capability offset in config space; otherwise return 0.
-
struct resource *pci_find_parent_resource(const struct pci_dev *dev, struct resource *res)¶
return resource region of parent bus of given region
Parameters
const struct pci_dev *dev
PCI device structure contains resources to be searched
struct resource *res
child resource record for which parent is sought
Description
For given resource region of given device, return the resource region of parent bus the given region is contained in.
-
struct resource *pci_find_resource(struct pci_dev *dev, struct resource *res)¶
Return matching PCI device resource
Parameters
struct pci_dev *dev
PCI device to query
struct resource *res
Resource to look for
Description
Goes over standard PCI resources (BARs) and checks if the given resource
is partially or fully contained in any of them. In that case the
matching resource is returned, NULL
otherwise.
-
int pcie_read_tlp_log(struct pci_dev *dev, int where, struct pcie_tlp_log *tlp_log)¶
read TLP Header Log
Parameters
struct pci_dev *dev
PCIe device
int where
PCI Config offset of TLP Header Log
struct pcie_tlp_log *tlp_log
TLP Log structure to fill
Description
Fill tlp_log from TLP Header Log registers, e.g., AER or DPC.
Return
0 on success and filled TLP Log structure, <0 on error.
-
int pci_platform_power_transition(struct pci_dev *dev, pci_power_t state)¶
Use platform to change device power state
Parameters
struct pci_dev *dev
PCI device to handle.
pci_power_t state
State to put the device into.
-
int pci_set_power_state(struct pci_dev *dev, pci_power_t state)¶
Set the power state of a PCI device
Parameters
struct pci_dev *dev
PCI device to handle.
pci_power_t state
PCI power state (D0, D1, D2, D3hot) to put the device into.
Description
Transition a device to a new power state, using the platform firmware and/or the device’s PCI PM registers.
RETURN VALUE: -EINVAL if the requested state is invalid. -EIO if device does not support PCI PM or its PM capabilities register has a wrong version, or device doesn’t support the requested state. 0 if the transition is to D1 or D2 but D1 and D2 are not supported. 0 if device already is in the requested state. 0 if the transition is to D3 but D3 is not supported. 0 if device’s power state has been successfully changed.
-
int pci_save_state(struct pci_dev *dev)¶
save the PCI configuration space of a device before suspending
Parameters
struct pci_dev *dev
PCI device that we’re dealing with
-
void pci_restore_state(struct pci_dev *dev)¶
Restore the saved state of a PCI device
Parameters
struct pci_dev *dev
PCI device that we’re dealing with
-
struct pci_saved_state *pci_store_saved_state(struct pci_dev *dev)¶
Allocate and return an opaque struct containing the device saved state.
Parameters
struct pci_dev *dev
PCI device that we’re dealing with
Description
Return NULL if no state or error.
-
int pci_load_saved_state(struct pci_dev *dev, struct pci_saved_state *state)¶
Reload the provided save state into struct pci_dev.
Parameters
struct pci_dev *dev
PCI device that we’re dealing with
struct pci_saved_state *state
Saved state returned from
pci_store_saved_state()
-
int pci_load_and_free_saved_state(struct pci_dev *dev, struct pci_saved_state **state)¶
Reload the save state pointed to by state, and free the memory allocated for it.
Parameters
struct pci_dev *dev
PCI device that we’re dealing with
struct pci_saved_state **state
Pointer to saved state returned from
pci_store_saved_state()
-
int pci_reenable_device(struct pci_dev *dev)¶
Resume abandoned device
Parameters
struct pci_dev *dev
PCI device to be resumed
NOTE
This function is a backend of pci_default_resume() and is not supposed to be called by normal code, write proper resume handler and use it instead.
-
int pci_enable_device_mem(struct pci_dev *dev)¶
Initialize a device for use with Memory space
Parameters
struct pci_dev *dev
PCI device to be initialized
Description
Initialize device before it’s used by a driver. Ask low-level code to enable Memory resources. Wake up the device if it was suspended. Beware, this function can fail.
-
int pci_enable_device(struct pci_dev *dev)¶
Initialize device before it’s used by a driver.
Parameters
struct pci_dev *dev
PCI device to be initialized
Description
Initialize device before it’s used by a driver. Ask low-level code to enable I/O and memory. Wake up the device if it was suspended. Beware, this function can fail.
Note we don’t actually enable the device many times if we call this function repeatedly (we just increment the count).
-
void pci_disable_device(struct pci_dev *dev)¶
Disable PCI device after use
Parameters
struct pci_dev *dev
PCI device to be disabled
Description
Signal to the system that the PCI device is not in use by the system anymore. This only involves disabling PCI bus-mastering, if active.
Note we don’t actually disable the device until all callers of
pci_enable_device()
have called pci_disable_device()
.
-
int pci_set_pcie_reset_state(struct pci_dev *dev, enum pcie_reset_state state)¶
set reset state for device dev
Parameters
struct pci_dev *dev
the PCIe device reset
enum pcie_reset_state state
Reset state to enter into
Description
Sets the PCI reset state for the device.
-
bool pci_pme_capable(struct pci_dev *dev, pci_power_t state)¶
check the capability of PCI device to generate PME#
Parameters
struct pci_dev *dev
PCI device to handle.
pci_power_t state
PCI state from which device will issue PME#.
-
void pci_pme_active(struct pci_dev *dev, bool enable)¶
enable or disable PCI device’s PME# function
Parameters
struct pci_dev *dev
PCI device to handle.
bool enable
‘true’ to enable PME# generation; ‘false’ to disable it.
Description
The caller must verify that the device is capable of generating PME# before calling this function with enable equal to ‘true’.
-
int pci_enable_wake(struct pci_dev *pci_dev, pci_power_t state, bool enable)¶
change wakeup settings for a PCI device
Parameters
struct pci_dev *pci_dev
Target device
pci_power_t state
PCI state from which device will issue wakeup events
bool enable
Whether or not to enable event generation
Description
If enable is set, check device_may_wakeup() for the device before calling __pci_enable_wake() for it.
-
int pci_wake_from_d3(struct pci_dev *dev, bool enable)¶
enable/disable device to wake up from D3_hot or D3_cold
Parameters
struct pci_dev *dev
PCI device to prepare
bool enable
True to enable wake-up event generation; false to disable
Description
Many drivers want the device to wake up the system from D3_hot or D3_cold
and this function allows them to set that up cleanly - pci_enable_wake()
should not be called twice in a row to enable wake-up due to PCI PM vs ACPI
ordering constraints.
This function only returns error code if the device is not allowed to wake up the system from sleep or it is not capable of generating PME# from both D3_hot and D3_cold and the platform is unable to enable wake-up power for it.
-
int pci_prepare_to_sleep(struct pci_dev *dev)¶
prepare PCI device for system-wide transition into a sleep state
Parameters
struct pci_dev *dev
Device to handle.
Description
Choose the power state appropriate for the device depending on whether it can wake up the system and/or is power manageable by the platform (PCI_D3hot is the default) and put the device into that state.
-
int pci_back_from_sleep(struct pci_dev *dev)¶
turn PCI device on during system-wide transition into working state
Parameters
struct pci_dev *dev
Device to handle.
Description
Disable device’s system wake-up capability and put it into D0.
-
bool pci_dev_run_wake(struct pci_dev *dev)¶
Check if device can generate run-time wake-up events.
Parameters
struct pci_dev *dev
Device to check.
Description
Return true if the device itself is capable of generating wake-up events (through the platform or using the native PCIe PME) or if the device supports PME and one of its upstream bridges can generate wake-up events.
-
pci_power_t pci_choose_state(struct pci_dev *dev, pm_message_t state)¶
Choose the power state of a PCI device.
Parameters
struct pci_dev *dev
Target PCI device.
pm_message_t state
Target state for the whole system.
Description
Returns PCI power state suitable for dev and state.
-
void pci_d3cold_enable(struct pci_dev *dev)¶
Enable D3cold for device
Parameters
struct pci_dev *dev
PCI device to handle
Description
This function can be used in drivers to enable D3cold from the device they handle. It also updates upstream PCI bridge PM capabilities accordingly.
-
void pci_d3cold_disable(struct pci_dev *dev)¶
Disable D3cold for device
Parameters
struct pci_dev *dev
PCI device to handle
Description
This function can be used in drivers to disable D3cold from the device they handle. It also updates upstream PCI bridge PM capabilities accordingly.
-
u32 pci_rebar_get_possible_sizes(struct pci_dev *pdev, int bar)¶
get possible sizes for BAR
Parameters
struct pci_dev *pdev
PCI device
int bar
BAR to query
Description
Get the possible sizes of a resizable BAR as bitmask defined in the spec (bit 0=1MB, bit 19=512GB). Returns 0 if BAR isn’t resizable.
-
int pci_enable_atomic_ops_to_root(struct pci_dev *dev, u32 cap_mask)¶
enable AtomicOp requests to root port
Parameters
struct pci_dev *dev
the PCI device
u32 cap_mask
mask of desired AtomicOp sizes, including one or more of: PCI_EXP_DEVCAP2_ATOMIC_COMP32 PCI_EXP_DEVCAP2_ATOMIC_COMP64 PCI_EXP_DEVCAP2_ATOMIC_COMP128
Description
Return 0 if all upstream bridges support AtomicOp routing, egress blocking is disabled on all upstream ports, and the root port supports the requested completion capabilities (32-bit, 64-bit and/or 128-bit AtomicOp completion), or negative otherwise.
-
void pci_release_region(struct pci_dev *pdev, int bar)¶
Release a PCI bar
Parameters
struct pci_dev *pdev
PCI device whose resources were previously reserved by
pci_request_region()
int bar
BAR to release
Description
Releases the PCI I/O and memory resources previously reserved by a
successful call to pci_request_region()
. Call this function only
after all use of the PCI regions has ceased.
-
int pci_request_region(struct pci_dev *pdev, int bar, const char *res_name)¶
Reserve PCI I/O and memory resource
Parameters
struct pci_dev *pdev
PCI device whose resources are to be reserved
int bar
BAR to be reserved
const char *res_name
Name to be associated with resource
Description
Mark the PCI region associated with PCI device pdev BAR bar as being reserved by owner res_name. Do not access any address inside the PCI regions unless this call returns successfully.
Returns 0 on success, or EBUSY
on error. A warning
message is also printed on failure.
-
void pci_release_selected_regions(struct pci_dev *pdev, int bars)¶
Release selected PCI I/O and memory resources
Parameters
struct pci_dev *pdev
PCI device whose resources were previously reserved
int bars
Bitmask of BARs to be released
Description
Release selected PCI I/O and memory resources previously reserved. Call this function only after all use of the PCI regions has ceased.
-
int pci_request_selected_regions(struct pci_dev *pdev, int bars, const char *res_name)¶
Reserve selected PCI I/O and memory resources
Parameters
struct pci_dev *pdev
PCI device whose resources are to be reserved
int bars
Bitmask of BARs to be requested
const char *res_name
Name to be associated with resource
-
void pci_release_regions(struct pci_dev *pdev)¶
Release reserved PCI I/O and memory resources
Parameters
struct pci_dev *pdev
PCI device whose resources were previously reserved by
pci_request_regions()
Description
Releases all PCI I/O and memory resources previously reserved by a
successful call to pci_request_regions()
. Call this function only
after all use of the PCI regions has ceased.
-
int pci_request_regions(struct pci_dev *pdev, const char *res_name)¶
Reserve PCI I/O and memory resources
Parameters
struct pci_dev *pdev
PCI device whose resources are to be reserved
const char *res_name
Name to be associated with resource.
Description
Mark all PCI regions associated with PCI device pdev as being reserved by owner res_name. Do not access any address inside the PCI regions unless this call returns successfully.
Returns 0 on success, or EBUSY
on error. A warning
message is also printed on failure.
-
int pci_request_regions_exclusive(struct pci_dev *pdev, const char *res_name)¶
Reserve PCI I/O and memory resources
Parameters
struct pci_dev *pdev
PCI device whose resources are to be reserved
const char *res_name
Name to be associated with resource.
Description
Mark all PCI regions associated with PCI device pdev as being reserved by owner res_name. Do not access any address inside the PCI regions unless this call returns successfully.
pci_request_regions_exclusive()
will mark the region so that /dev/mem
and the sysfs MMIO access will not be allowed.
Returns 0 on success, or EBUSY
on error. A warning message is also
printed on failure.
-
int pci_remap_iospace(const struct resource *res, phys_addr_t phys_addr)¶
Remap the memory mapped I/O space
Parameters
const struct resource *res
Resource describing the I/O space
phys_addr_t phys_addr
physical address of range to be mapped
Description
Remap the memory mapped I/O space described by the res and the CPU physical address phys_addr into virtual address space. Only architectures that have memory mapped IO functions defined (and the PCI_IOBASE value defined) should call this function.
-
void pci_unmap_iospace(struct resource *res)¶
Unmap the memory mapped I/O space
Parameters
struct resource *res
resource to be unmapped
Description
Unmap the CPU virtual address res from virtual address space. Only architectures that have memory mapped IO functions defined (and the PCI_IOBASE value defined) should call this function.
-
void pci_set_master(struct pci_dev *dev)¶
enables bus-mastering for device dev
Parameters
struct pci_dev *dev
the PCI device to enable
Description
Enables bus-mastering on the device and calls pcibios_set_master() to do the needed arch specific settings.
-
void pci_clear_master(struct pci_dev *dev)¶
disables bus-mastering for device dev
Parameters
struct pci_dev *dev
the PCI device to disable
-
int pci_set_cacheline_size(struct pci_dev *dev)¶
ensure the CACHE_LINE_SIZE register is programmed
Parameters
struct pci_dev *dev
the PCI device for which MWI is to be enabled
Description
Helper function for pci_set_mwi. Originally copied from drivers/net/acenic.c. Copyright 1998-2001 by Jes Sorensen, <jes**trained**-monkey.org>.
Return
An appropriate -ERRNO error value on error, or zero for success.
-
int pci_set_mwi(struct pci_dev *dev)¶
enables memory-write-invalidate PCI transaction
Parameters
struct pci_dev *dev
the PCI device for which MWI is enabled
Description
Enables the Memory-Write-Invalidate transaction in PCI_COMMAND
.
Return
An appropriate -ERRNO error value on error, or zero for success.
-
int pci_try_set_mwi(struct pci_dev *dev)¶
enables memory-write-invalidate PCI transaction
Parameters
struct pci_dev *dev
the PCI device for which MWI is enabled
Description
Enables the Memory-Write-Invalidate transaction in PCI_COMMAND
.
Callers are not required to check the return value.
Return
An appropriate -ERRNO error value on error, or zero for success.
-
void pci_clear_mwi(struct pci_dev *dev)¶
disables Memory-Write-Invalidate for device dev
Parameters
struct pci_dev *dev
the PCI device to disable
Description
Disables PCI Memory-Write-Invalidate transaction on the device
-
void pci_intx(struct pci_dev *pdev, int enable)¶
enables/disables PCI INTx for device dev
Parameters
struct pci_dev *pdev
the PCI device to operate on
int enable
boolean: whether to enable or disable PCI INTx
Description
Enables/disables PCI INTx for device pdev
-
int pci_wait_for_pending_transaction(struct pci_dev *dev)¶
wait for pending transaction
Parameters
struct pci_dev *dev
the PCI device to operate on
Description
Return 0 if transaction is pending 1 otherwise.
-
int pcie_flr(struct pci_dev *dev)¶
initiate a PCIe function level reset
Parameters
struct pci_dev *dev
device to reset
Description
Initiate a function level reset unconditionally on dev without checking any flags and DEVCAP
-
int pcie_reset_flr(struct pci_dev *dev, bool probe)¶
initiate a PCIe function level reset
Parameters
struct pci_dev *dev
device to reset
bool probe
if true, return 0 if device can be reset this way
Description
Initiate a function level reset on dev.
-
int pci_bridge_secondary_bus_reset(struct pci_dev *dev)¶
Reset the secondary bus on a PCI bridge.
Parameters
struct pci_dev *dev
Bridge device
Description
Use the bridge control register to assert reset on the secondary bus. Devices on the secondary bus are left in power-on state.
-
int __pci_reset_function_locked(struct pci_dev *dev)¶
reset a PCI device function while holding the dev mutex lock.
Parameters
struct pci_dev *dev
PCI device to reset
Description
Some devices allow an individual function to be reset without affecting other functions in the same device. The PCI device must be responsive to PCI config space in order to use this function.
The device function is presumed to be unused and the caller is holding the device mutex lock when this function is called.
Resetting the device will make the contents of PCI configuration space random, so any caller of this must be prepared to reinitialise the device including MSI, bus mastering, BARs, decoding IO and memory spaces, etc.
Returns 0 if the device function was successfully reset or negative if the device doesn’t support resetting a single function.
-
int pci_reset_function(struct pci_dev *dev)¶
quiesce and reset a PCI device function
Parameters
struct pci_dev *dev
PCI device to reset
Description
Some devices allow an individual function to be reset without affecting other functions in the same device. The PCI device must be responsive to PCI config space in order to use this function.
This function does not just reset the PCI portion of a device, but
clears all the state associated with the device. This function differs
from __pci_reset_function_locked()
in that it saves and restores device state
over the reset and takes the PCI device lock.
Returns 0 if the device function was successfully reset or negative if the device doesn’t support resetting a single function.
-
int pci_reset_function_locked(struct pci_dev *dev)¶
quiesce and reset a PCI device function
Parameters
struct pci_dev *dev
PCI device to reset
Description
Some devices allow an individual function to be reset without affecting other functions in the same device. The PCI device must be responsive to PCI config space in order to use this function.
This function does not just reset the PCI portion of a device, but
clears all the state associated with the device. This function differs
from __pci_reset_function_locked()
in that it saves and restores device state
over the reset. It also differs from pci_reset_function()
in that it
requires the PCI device lock to be held.
Returns 0 if the device function was successfully reset or negative if the device doesn’t support resetting a single function.
-
int pci_try_reset_function(struct pci_dev *dev)¶
quiesce and reset a PCI device function
Parameters
struct pci_dev *dev
PCI device to reset
Description
Same as above, except return -EAGAIN if unable to lock device.
-
int pci_probe_reset_slot(struct pci_slot *slot)¶
probe whether a PCI slot can be reset
Parameters
struct pci_slot *slot
PCI slot to probe
Description
Return 0 if slot can be reset, negative if a slot reset is not supported.
-
int pci_probe_reset_bus(struct pci_bus *bus)¶
probe whether a PCI bus can be reset
Parameters
struct pci_bus *bus
PCI bus to probe
Description
Return 0 if bus can be reset, negative if a bus reset is not supported.
-
int pci_reset_bus(struct pci_dev *pdev)¶
Try to reset a PCI bus
Parameters
struct pci_dev *pdev
top level PCI device to reset via slot/bus
Description
Same as above except return -EAGAIN if the bus cannot be locked
-
int pcix_get_max_mmrbc(struct pci_dev *dev)¶
get PCI-X maximum designed memory read byte count
Parameters
struct pci_dev *dev
PCI device to query
Description
Returns mmrbc: maximum designed memory read count in bytes or appropriate error value.
-
int pcix_get_mmrbc(struct pci_dev *dev)¶
get PCI-X maximum memory read byte count
Parameters
struct pci_dev *dev
PCI device to query
Description
Returns mmrbc: maximum memory read count in bytes or appropriate error value.
-
int pcix_set_mmrbc(struct pci_dev *dev, int mmrbc)¶
set PCI-X maximum memory read byte count
Parameters
struct pci_dev *dev
PCI device to query
int mmrbc
maximum memory read count in bytes valid values are 512, 1024, 2048, 4096
Description
If possible sets maximum memory read byte count, some bridges have errata that prevent this.
-
int pcie_get_readrq(struct pci_dev *dev)¶
get PCI Express read request size
Parameters
struct pci_dev *dev
PCI device to query
Description
Returns maximum memory read request in bytes or appropriate error value.
-
int pcie_set_readrq(struct pci_dev *dev, int rq)¶
set PCI Express maximum memory read request
Parameters
struct pci_dev *dev
PCI device to query
int rq
maximum memory read count in bytes valid values are 128, 256, 512, 1024, 2048, 4096
Description
If possible sets maximum memory read request in bytes
-
int pcie_get_mps(struct pci_dev *dev)¶
get PCI Express maximum payload size
Parameters
struct pci_dev *dev
PCI device to query
Description
Returns maximum payload size in bytes
-
int pcie_set_mps(struct pci_dev *dev, int mps)¶
set PCI Express maximum payload size
Parameters
struct pci_dev *dev
PCI device to query
int mps
maximum payload size in bytes valid values are 128, 256, 512, 1024, 2048, 4096
Description
If possible sets maximum payload size
-
u32 pcie_bandwidth_available(struct pci_dev *dev, struct pci_dev **limiting_dev, enum pci_bus_speed *speed, enum pcie_link_width *width)¶
determine minimum link settings of a PCIe device and its bandwidth limitation
Parameters
struct pci_dev *dev
PCI device to query
struct pci_dev **limiting_dev
storage for device causing the bandwidth limitation
enum pci_bus_speed *speed
storage for speed of limiting device
enum pcie_link_width *width
storage for width of limiting device
Description
Walk up the PCI device chain and find the point where the minimum bandwidth is available. Return the bandwidth available there and (if limiting_dev, speed, and width pointers are supplied) information about that point. The bandwidth returned is in Mb/s, i.e., megabits/second of raw bandwidth.
-
enum pci_bus_speed pcie_get_speed_cap(struct pci_dev *dev)¶
query for the PCI device’s link speed capability
Parameters
struct pci_dev *dev
PCI device to query
Description
Query the PCI device speed capability. Return the maximum link speed supported by the device.
-
enum pcie_link_width pcie_get_width_cap(struct pci_dev *dev)¶
query for the PCI device’s link width capability
Parameters
struct pci_dev *dev
PCI device to query
Description
Query the PCI device width capability. Return the maximum link width supported by the device.
-
void pcie_print_link_status(struct pci_dev *dev)¶
Report the PCI device’s link speed and width
Parameters
struct pci_dev *dev
PCI device to query
Description
Report the available bandwidth at the device.
-
int pci_select_bars(struct pci_dev *dev, unsigned long flags)¶
Make BAR mask from the type of resource
Parameters
struct pci_dev *dev
the PCI device for which BAR mask is made
unsigned long flags
resource type mask to be selected
Description
This helper routine makes bar mask from the type of resource.
-
void __iomem *pci_iomap_range(struct pci_dev *dev, int bar, unsigned long offset, unsigned long maxlen)¶
create a virtual mapping cookie for a PCI BAR
Parameters
struct pci_dev *dev
PCI device that owns the BAR
int bar
BAR number
unsigned long offset
map memory at the given offset in BAR
unsigned long maxlen
max length of the memory to map
Description
Using this function you will get a __iomem address to your device BAR. You can access it using ioread*() and iowrite*(). These functions hide the details if this is a MMIO or PIO address space and will just do what you expect from them in the correct way.
maxlen specifies the maximum length to map. If you want to get access to
the complete BAR from offset to the end, pass 0
here.
-
void __iomem *pci_iomap_wc_range(struct pci_dev *dev, int bar, unsigned long offset, unsigned long maxlen)¶
create a virtual WC mapping cookie for a PCI BAR
Parameters
struct pci_dev *dev
PCI device that owns the BAR
int bar
BAR number
unsigned long offset
map memory at the given offset in BAR
unsigned long maxlen
max length of the memory to map
Description
Using this function you will get a __iomem address to your device BAR. You can access it using ioread*() and iowrite*(). These functions hide the details if this is a MMIO or PIO address space and will just do what you expect from them in the correct way. When possible write combining is used.
maxlen specifies the maximum length to map. If you want to get access to
the complete BAR from offset to the end, pass 0
here.
-
void __iomem *pci_iomap(struct pci_dev *dev, int bar, unsigned long maxlen)¶
create a virtual mapping cookie for a PCI BAR
Parameters
struct pci_dev *dev
PCI device that owns the BAR
int bar
BAR number
unsigned long maxlen
length of the memory to map
Description
Using this function you will get a __iomem address to your device BAR. You can access it using ioread*() and iowrite*(). These functions hide the details if this is a MMIO or PIO address space and will just do what you expect from them in the correct way.
maxlen specifies the maximum length to map. If you want to get access to
the complete BAR without checking for its length first, pass 0
here.
-
void __iomem *pci_iomap_wc(struct pci_dev *dev, int bar, unsigned long maxlen)¶
create a virtual WC mapping cookie for a PCI BAR
Parameters
struct pci_dev *dev
PCI device that owns the BAR
int bar
BAR number
unsigned long maxlen
length of the memory to map
Description
Using this function you will get a __iomem address to your device BAR. You can access it using ioread*() and iowrite*(). These functions hide the details if this is a MMIO or PIO address space and will just do what you expect from them in the correct way. When possible write combining is used.
maxlen specifies the maximum length to map. If you want to get access to
the complete BAR without checking for its length first, pass 0
here.
-
int devm_pci_remap_iospace(struct device *dev, const struct resource *res, phys_addr_t phys_addr)¶
Managed
pci_remap_iospace()
Parameters
struct device *dev
Generic device to remap IO address for
const struct resource *res
Resource describing the I/O space
phys_addr_t phys_addr
physical address of range to be mapped
Description
Managed pci_remap_iospace()
. Map is automatically unmapped on driver
detach.
-
void __iomem *devm_pci_remap_cfgspace(struct device *dev, resource_size_t offset, resource_size_t size)¶
Managed pci_remap_cfgspace()
Parameters
struct device *dev
Generic device to remap IO address for
resource_size_t offset
Resource address to map
resource_size_t size
Size of map
Description
Managed pci_remap_cfgspace(). Map is automatically unmapped on driver detach.
-
void __iomem *devm_pci_remap_cfg_resource(struct device *dev, struct resource *res)¶
check, request region and ioremap cfg resource
Parameters
struct device *dev
generic device to handle the resource for
struct resource *res
configuration space resource to be handled
Description
Checks that a resource is a valid memory region, requests the memory region and ioremaps with pci_remap_cfgspace() API that ensures the proper PCI configuration space memory attributes are guaranteed.
All operations are managed and will be undone on driver detach.
Returns a pointer to the remapped memory or an ERR_PTR()
encoded error code
on failure. Usage example:
res = platform_get_resource(pdev, IORESOURCE_MEM, 0);
base = devm_pci_remap_cfg_resource(&pdev->dev, res);
if (IS_ERR(base))
return PTR_ERR(base);
-
int pcim_set_mwi(struct pci_dev *dev)¶
a device-managed
pci_set_mwi()
Parameters
struct pci_dev *dev
the PCI device for which MWI is enabled
Description
Managed pci_set_mwi()
.
Return
An appropriate -ERRNO error value on error, or zero for success.
-
int pcim_enable_device(struct pci_dev *pdev)¶
Managed
pci_enable_device()
Parameters
struct pci_dev *pdev
PCI device to be initialized
Description
Managed pci_enable_device()
.
-
void pcim_pin_device(struct pci_dev *pdev)¶
Pin managed PCI device
Parameters
struct pci_dev *pdev
PCI device to pin
Description
Pin managed PCI device pdev. Pinned device won’t be disabled on
driver detach. pdev must have been enabled with
pcim_enable_device()
.
-
void __iomem *const *pcim_iomap_table(struct pci_dev *pdev)¶
access iomap allocation table
Parameters
struct pci_dev *pdev
PCI device to access iomap table for
Description
Access iomap allocation table for dev. If iomap table doesn’t exist and pdev is managed, it will be allocated. All iomaps recorded in the iomap table are automatically unmapped on driver detach.
This function might sleep when the table is first allocated but can be safely called without context and guaranteed to succeed once allocated.
-
void __iomem *pcim_iomap(struct pci_dev *pdev, int bar, unsigned long maxlen)¶
Managed
pcim_iomap()
Parameters
struct pci_dev *pdev
PCI device to iomap for
int bar
BAR to iomap
unsigned long maxlen
Maximum length of iomap
Description
Managed pci_iomap()
. Map is automatically unmapped on driver
detach.
-
void pcim_iounmap(struct pci_dev *pdev, void __iomem *addr)¶
Managed pci_iounmap()
Parameters
struct pci_dev *pdev
PCI device to iounmap for
void __iomem *addr
Address to unmap
Description
Managed pci_iounmap(). addr must have been mapped using pcim_iomap()
.
-
int pcim_iomap_regions(struct pci_dev *pdev, int mask, const char *name)¶
Request and iomap PCI BARs
Parameters
struct pci_dev *pdev
PCI device to map IO resources for
int mask
Mask of BARs to request and iomap
const char *name
Name used when requesting regions
Description
Request and iomap regions specified by mask.
-
int pcim_iomap_regions_request_all(struct pci_dev *pdev, int mask, const char *name)¶
Request all BARs and iomap specified ones
Parameters
struct pci_dev *pdev
PCI device to map IO resources for
int mask
Mask of BARs to iomap
const char *name
Name used when requesting regions
Description
Request all PCI BARs and iomap regions specified by mask.
-
void pcim_iounmap_regions(struct pci_dev *pdev, int mask)¶
Unmap and release PCI BARs
Parameters
struct pci_dev *pdev
PCI device to map IO resources for
int mask
Mask of BARs to unmap and release
Description
Unmap and release regions specified by mask.
-
int pci_add_dynid(struct pci_driver *drv, unsigned int vendor, unsigned int device, unsigned int subvendor, unsigned int subdevice, unsigned int class, unsigned int class_mask, unsigned long driver_data)¶
add a new PCI device ID to this driver and re-probe devices
Parameters
struct pci_driver *drv
target pci driver
unsigned int vendor
PCI vendor ID
unsigned int device
PCI device ID
unsigned int subvendor
PCI subvendor ID
unsigned int subdevice
PCI subdevice ID
unsigned int class
PCI class
unsigned int class_mask
PCI class mask
unsigned long driver_data
private driver data
Description
Adds a new dynamic pci device ID to this driver and causes the driver to probe for all devices again. drv must have been registered prior to calling this function.
Context
Does GFP_KERNEL allocation.
Return
0 on success, -errno on failure.
-
const struct pci_device_id *pci_match_id(const struct pci_device_id *ids, struct pci_dev *dev)¶
See if a PCI device matches a given pci_id table
Parameters
const struct pci_device_id *ids
array of PCI device ID structures to search in
struct pci_dev *dev
the PCI device structure to match against.
Description
Used by a driver to check whether a PCI device is in its list of
supported devices. Returns the matching pci_device_id structure or
NULL
if there is no match.
Deprecated; don’t use this as it will not catch any dynamic IDs that a driver might want to check for.
-
int __pci_register_driver(struct pci_driver *drv, struct module *owner, const char *mod_name)¶
register a new pci driver
Parameters
struct pci_driver *drv
the driver structure to register
struct module *owner
owner module of drv
const char *mod_name
module name string
Description
Adds the driver structure to the list of registered drivers. Returns a negative value on error, otherwise 0. If no error occurred, the driver remains registered even if no device was claimed during registration.
-
void pci_unregister_driver(struct pci_driver *drv)¶
unregister a pci driver
Parameters
struct pci_driver *drv
the driver structure to unregister
Description
Deletes the driver structure from the list of registered PCI drivers, gives it a chance to clean up by calling its remove() function for each device it was responsible for, and marks those devices as driverless.
-
struct pci_driver *pci_dev_driver(const struct pci_dev *dev)¶
get the pci_driver of a device
Parameters
const struct pci_dev *dev
the device to query
Description
Returns the appropriate pci_driver structure or NULL
if there is no
registered driver for the device.
-
struct pci_dev *pci_dev_get(struct pci_dev *dev)¶
increments the reference count of the pci device structure
Parameters
struct pci_dev *dev
the device being referenced
Description
Each live reference to a device should be refcounted.
Drivers for PCI devices should normally record such references in
their probe() methods, when they bind to a device, and release
them by calling pci_dev_put()
, in their disconnect() methods.
A pointer to the device with the incremented reference counter is returned.
-
void pci_dev_put(struct pci_dev *dev)¶
release a use of the pci device structure
Parameters
struct pci_dev *dev
device that’s been disconnected
Description
Must be called when a user of a device is finished with it. When the last user of the device calls this function, the memory of the device is freed.
-
void pci_stop_and_remove_bus_device(struct pci_dev *dev)¶
remove a PCI device and any children
Parameters
struct pci_dev *dev
the device to remove
Description
Remove a PCI device from the device lists, informing the drivers that the device has been removed. We also remove any subordinate buses and children in a depth-first manner.
For each device we remove, delete the device structure from the device lists, remove the /proc entry, and notify userspace (/sbin/hotplug).
-
struct pci_bus *pci_find_bus(int domain, int busnr)¶
locate PCI bus from a given domain and bus number
Parameters
int domain
number of PCI domain to search
int busnr
number of desired PCI bus
Description
Given a PCI bus number and domain number, the desired PCI bus is located
in the global list of PCI buses. If the bus is found, a pointer to its
data structure is returned. If no bus is found, NULL
is returned.
-
struct pci_bus *pci_find_next_bus(const struct pci_bus *from)¶
begin or continue searching for a PCI bus
Parameters
const struct pci_bus *from
Previous PCI bus found, or
NULL
for new search.
Description
Iterates through the list of known PCI buses. A new search is
initiated by passing NULL
as the from argument. Otherwise if
from is not NULL
, searches continue from next device on the
global list.
-
struct pci_dev *pci_get_slot(struct pci_bus *bus, unsigned int devfn)¶
locate PCI device for a given PCI slot
Parameters
struct pci_bus *bus
PCI bus on which desired PCI device resides
unsigned int devfn
encodes number of PCI slot in which the desired PCI device resides and the logical device number within that slot in case of multi-function devices.
Description
Given a PCI bus and slot/function number, the desired PCI device
is located in the list of PCI devices.
If the device is found, its reference count is increased and this
function returns a pointer to its data structure. The caller must
decrement the reference count by calling pci_dev_put()
.
If no device is found, NULL
is returned.
-
struct pci_dev *pci_get_domain_bus_and_slot(int domain, unsigned int bus, unsigned int devfn)¶
locate PCI device for a given PCI domain (segment), bus, and slot
Parameters
int domain
PCI domain/segment on which the PCI device resides.
unsigned int bus
PCI bus on which desired PCI device resides
unsigned int devfn
encodes number of PCI slot in which the desired PCI device resides and the logical device number within that slot in case of multi-function devices.
Description
Given a PCI domain, bus, and slot/function number, the desired PCI
device is located in the list of PCI devices. If the device is
found, its reference count is increased and this function returns a
pointer to its data structure. The caller must decrement the
reference count by calling pci_dev_put()
. If no device is found,
NULL
is returned.
-
struct pci_dev *pci_get_subsys(unsigned int vendor, unsigned int device, unsigned int ss_vendor, unsigned int ss_device, struct pci_dev *from)¶
begin or continue searching for a PCI device by vendor/subvendor/device/subdevice id
Parameters
unsigned int vendor
PCI vendor id to match, or
PCI_ANY_ID
to match all vendor idsunsigned int device
PCI device id to match, or
PCI_ANY_ID
to match all device idsunsigned int ss_vendor
PCI subsystem vendor id to match, or
PCI_ANY_ID
to match all vendor idsunsigned int ss_device
PCI subsystem device id to match, or
PCI_ANY_ID
to match all device idsstruct pci_dev *from
Previous PCI device found in search, or
NULL
for new search.
Description
Iterates through the list of known PCI devices. If a PCI device is found
with a matching vendor, device, ss_vendor and ss_device, a pointer to its
device structure is returned, and the reference count to the device is
incremented. Otherwise, NULL
is returned. A new search is initiated by
passing NULL
as the from argument. Otherwise if from is not NULL
,
searches continue from next device on the global list.
The reference count for from is always decremented if it is not NULL
.
-
struct pci_dev *pci_get_device(unsigned int vendor, unsigned int device, struct pci_dev *from)¶
begin or continue searching for a PCI device by vendor/device id
Parameters
unsigned int vendor
PCI vendor id to match, or
PCI_ANY_ID
to match all vendor idsunsigned int device
PCI device id to match, or
PCI_ANY_ID
to match all device idsstruct pci_dev *from
Previous PCI device found in search, or
NULL
for new search.
Description
Iterates through the list of known PCI devices. If a PCI device is
found with a matching vendor and device, the reference count to the
device is incremented and a pointer to its device structure is returned.
Otherwise, NULL
is returned. A new search is initiated by passing NULL
as the from argument. Otherwise if from is not NULL
, searches continue
from next device on the global list. The reference count for from is
always decremented if it is not NULL
.
-
struct pci_dev *pci_get_class(unsigned int class, struct pci_dev *from)¶
begin or continue searching for a PCI device by class
Parameters
unsigned int class
search for a PCI device with this class designation
struct pci_dev *from
Previous PCI device found in search, or
NULL
for new search.
Description
Iterates through the list of known PCI devices. If a PCI device is
found with a matching class, the reference count to the device is
incremented and a pointer to its device structure is returned.
Otherwise, NULL
is returned.
A new search is initiated by passing NULL
as the from argument.
Otherwise if from is not NULL
, searches continue from next device
on the global list. The reference count for from is always decremented
if it is not NULL
.
-
struct pci_dev *pci_get_base_class(unsigned int class, struct pci_dev *from)¶
searching for a PCI device by matching against the base class code only
Parameters
unsigned int class
search for a PCI device with this base class code
struct pci_dev *from
Previous PCI device found in search, or
NULL
for new search.
Description
Iterates through the list of known PCI devices. If a PCI device is found
with a matching base class code, the reference count to the device is
incremented. See pci_match_one_device() to figure out how does this works.
A new search is initiated by passing NULL
as the from argument.
Otherwise if from is not NULL
, searches continue from next device on the
global list. The reference count for from is always decremented if it is
not NULL
.
Return
A pointer to a matched PCI device, NULL
Otherwise.
-
int pci_dev_present(const struct pci_device_id *ids)¶
Returns 1 if device matching the device list is present, 0 if not.
Parameters
const struct pci_device_id *ids
A pointer to a null terminated list of
struct pci_device_id
structures that describe the type of PCI device the caller is trying to find.
Description
Obvious fact: You do not have a reference to any device that might be found by this function, so if that device is removed from the system right after this function is finished, the value will be stale. Use this function to find devices that are usually built into a system, or for a general hint as to if another device happens to be present at this specific moment in time.
Parameters
struct irq_data *data
pointer to irqdata associated to that interrupt
-
void pci_msi_unmask_irq(struct irq_data *data)¶
Generic IRQ chip callback to unmask PCI/MSI interrupts
Parameters
struct irq_data *data
pointer to irqdata associated to that interrupt
-
int pci_msi_vec_count(struct pci_dev *dev)¶
Return the number of MSI vectors a device can send
Parameters
struct pci_dev *dev
device to report about
Description
This function returns the number of MSI vectors a device requested via Multiple Message Capable register. It returns a negative errno if the device is not capable sending MSI interrupts. Otherwise, the call succeeds and returns a power of two, up to a maximum of 2^5 (32), according to the MSI specification.
-
int pci_bus_alloc_resource(struct pci_bus *bus, struct resource *res, resource_size_t size, resource_size_t align, resource_size_t min, unsigned long type_mask, resource_size_t (*alignf)(void*, const struct resource*, resource_size_t, resource_size_t), void *alignf_data)¶
allocate a resource from a parent bus
Parameters
struct pci_bus *bus
PCI bus
struct resource *res
resource to allocate
resource_size_t size
size of resource to allocate
resource_size_t align
alignment of resource to allocate
resource_size_t min
minimum /proc/iomem address to allocate
unsigned long type_mask
IORESOURCE_* type flags
resource_size_t (*alignf)(void *, const struct resource *, resource_size_t, resource_size_t)
resource alignment function
void *alignf_data
data argument for resource alignment function
Description
Given the PCI bus a device resides on, the size, minimum address, alignment and type, try to find an acceptable resource allocation for a specific device resource.
-
void pci_bus_add_device(struct pci_dev *dev)¶
start driver for a single device
Parameters
struct pci_dev *dev
device to add
Description
This adds add sysfs entries and start device drivers
-
void pci_bus_add_devices(const struct pci_bus *bus)¶
start driver for PCI devices
Parameters
const struct pci_bus *bus
bus to check for new devices
Description
Start driver for PCI devices and add some sysfs entries.
-
void pci_walk_bus(struct pci_bus *top, int (*cb)(struct pci_dev*, void*), void *userdata)¶
walk devices on/under bus, calling callback.
Parameters
struct pci_bus *top
bus whose devices should be walked
int (*cb)(struct pci_dev *, void *)
callback to be called for each device found
void *userdata
arbitrary pointer to be passed to callback
Walk the given bus, including any bridged devices on buses under this bus. Call the provided callback on each device found.
We check the return of cb each time. If it returns anything other than 0, we break out.
-
struct pci_ops *pci_bus_set_ops(struct pci_bus *bus, struct pci_ops *ops)¶
Set raw operations of pci bus
Parameters
struct pci_bus *bus
pci bus struct
struct pci_ops *ops
new raw operations
Description
Return previous raw operations
-
void pci_cfg_access_lock(struct pci_dev *dev)¶
Lock PCI config reads/writes
Parameters
struct pci_dev *dev
pci device struct
Description
When access is locked, any userspace reads or writes to config
space and concurrent lock requests will sleep until access is
allowed via pci_cfg_access_unlock()
again.
-
bool pci_cfg_access_trylock(struct pci_dev *dev)¶
try to lock PCI config reads/writes
Parameters
struct pci_dev *dev
pci device struct
Description
Same as pci_cfg_access_lock, but will return 0 if access is already locked, 1 otherwise. This function can be used from atomic contexts.
-
void pci_cfg_access_unlock(struct pci_dev *dev)¶
Unlock PCI config reads/writes
Parameters
struct pci_dev *dev
pci device struct
Description
This function allows PCI config accesses to resume.
-
int pci_request_irq(struct pci_dev *dev, unsigned int nr, irq_handler_t handler, irq_handler_t thread_fn, void *dev_id, const char *fmt, ...)¶
allocate an interrupt line for a PCI device
Parameters
struct pci_dev *dev
PCI device to operate on
unsigned int nr
device-relative interrupt vector index (0-based).
irq_handler_t handler
Function to be called when the IRQ occurs. Primary handler for threaded interrupts. If NULL and thread_fn != NULL the default primary handler is installed.
irq_handler_t thread_fn
Function called from the IRQ handler thread If NULL, no IRQ thread is created
void *dev_id
Cookie passed back to the handler function
const char *fmt
Printf-like format string naming the handler
...
variable arguments
Description
This call allocates interrupt resources and enables the interrupt line and IRQ handling. From the point this call is made handler and thread_fn may be invoked. All interrupts requested using this function might be shared.
dev_id must not be NULL and must be globally unique.
-
void pci_free_irq(struct pci_dev *dev, unsigned int nr, void *dev_id)¶
free an interrupt allocated with pci_request_irq
Parameters
struct pci_dev *dev
PCI device to operate on
unsigned int nr
device-relative interrupt vector index (0-based).
void *dev_id
Device identity to free
Description
Remove an interrupt handler. The handler is removed and if the interrupt line is no longer in use by any driver it is disabled. The caller must ensure the interrupt is disabled on the device before calling this function. The function does not return until any executing interrupts for this IRQ have completed.
This function must not be called from interrupt context.
-
u8 pci_common_swizzle(struct pci_dev *dev, u8 *pinp)¶
swizzle INTx all the way to root bridge
Parameters
struct pci_dev *dev
the PCI device
u8 *pinp
pointer to the INTx pin value (1=INTA, 2=INTB, 3=INTD, 4=INTD)
Description
Perform INTx swizzling for a device. This traverses through all PCI-to-PCI bridges all the way up to a PCI root bus.
-
bool pci_check_and_mask_intx(struct pci_dev *dev)¶
mask INTx on pending interrupt
Parameters
struct pci_dev *dev
the PCI device to operate on
Description
Check if the device dev has its INTx line asserted, mask it and return true in that case. False is returned if no interrupt was pending.
-
bool pci_check_and_unmask_intx(struct pci_dev *dev)¶
unmask INTx if no interrupt is pending
Parameters
struct pci_dev *dev
the PCI device to operate on
Description
Check if the device dev has its INTx line asserted, unmask it if not and return true. False is returned and the mask remains active if there was still an interrupt pending.
-
bool pcie_relaxed_ordering_enabled(struct pci_dev *dev)¶
Probe for PCIe relaxed ordering enable
Parameters
struct pci_dev *dev
PCI device to query
Description
Returns true if the device has enabled relaxed ordering attribute.
-
int pci_scan_slot(struct pci_bus *bus, int devfn)¶
Scan a PCI slot on a bus for devices
Parameters
struct pci_bus *bus
PCI bus to scan
int devfn
slot number to scan (must have zero function)
Description
Scan a PCI slot on the specified PCI bus for devices, adding discovered devices to the bus->devices list. New devices will not have is_added set.
Returns the number of new devices found.
-
unsigned int pci_scan_child_bus(struct pci_bus *bus)¶
Scan devices below a bus
Parameters
struct pci_bus *bus
Bus to scan for devices
Description
Scans devices below bus including subordinate buses. Returns new subordinate number including all the found devices.
-
unsigned int pci_rescan_bus(struct pci_bus *bus)¶
Scan a PCI bus for devices
Parameters
struct pci_bus *bus
PCI bus to scan
Description
Scan a PCI bus and child buses for new devices, add them, and enable them.
Returns the max number of subordinate bus discovered.
-
struct pci_slot *pci_create_slot(struct pci_bus *parent, int slot_nr, const char *name, struct hotplug_slot *hotplug)¶
create or increment refcount for physical PCI slot
Parameters
struct pci_bus *parent
struct pci_bus of parent bridge
int slot_nr
PCI_SLOT(pci_dev->devfn) or -1 for placeholder
const char *name
user visible string presented in /sys/bus/pci/slots/<name>
struct hotplug_slot *hotplug
set if caller is hotplug driver, NULL otherwise
Description
PCI slots have first class attributes such as address, speed, width,
and a struct pci_slot
is used to manage them. This interface will
either return a new struct pci_slot
to the caller, or if the pci_slot
already exists, its refcount will be incremented.
Slots are uniquely identified by a pci_bus, slot_nr tuple.
There are known platforms with broken firmware that assign the same name to multiple slots. Workaround these broken platforms by renaming the slots on behalf of the caller. If firmware assigns name N to multiple slots:
The first slot is assigned N The second slot is assigned N-1 The third slot is assigned N-2 etc.
Placeholder slots: In most cases, pci_bus, slot_nr will be sufficient to uniquely identify a slot. There is one notable exception - pSeries (rpaphp), where the slot_nr cannot be determined until a device is actually inserted into the slot. In this scenario, the caller may pass -1 for slot_nr.
The following semantics are imposed when the caller passes slot_nr ==
-1. First, we no longer check for an existing struct
pci_slot, as there
may be many slots with slot_nr of -1. The other change in semantics is
user-visible, which is the ‘address’ parameter presented in sysfs will
consist solely of a dddd:bb tuple, where dddd is the PCI domain of the
struct
pci_bus and bb is the bus number. In other words, the devfn of
the ‘placeholder’ slot will not be displayed.
-
void pci_destroy_slot(struct pci_slot *slot)¶
decrement refcount for physical PCI slot
Parameters
struct pci_slot *slot
struct pci_slot to decrement
Description
struct
pci_slot is refcounted, so destroying them is really easy; we
just call kobject_put on its kobj and let our release methods do the
rest.
-
void pci_hp_create_module_link(struct pci_slot *pci_slot)¶
create symbolic link to hotplug driver module
Parameters
struct pci_slot *pci_slot
struct pci_slot
Description
Helper function for pci_hotplug_core.c to create symbolic link to the hotplug driver module.
-
void pci_hp_remove_module_link(struct pci_slot *pci_slot)¶
remove symbolic link to the hotplug driver module.
Parameters
struct pci_slot *pci_slot
struct pci_slot
Description
Helper function for pci_hotplug_core.c to remove symbolic link to the hotplug driver module.
-
int pci_enable_rom(struct pci_dev *pdev)¶
enable ROM decoding for a PCI device
Parameters
struct pci_dev *pdev
PCI device to enable
Description
Enable ROM decoding on dev. This involves simply turning on the last bit of the PCI ROM BAR. Note that some cards may share address decoders between the ROM and other resources, so enabling it may disable access to MMIO registers or other card memory.
-
void pci_disable_rom(struct pci_dev *pdev)¶
disable ROM decoding for a PCI device
Parameters
struct pci_dev *pdev
PCI device to disable
Description
Disable ROM decoding on a PCI device by turning off the last bit in the ROM BAR.
-
void __iomem *pci_map_rom(struct pci_dev *pdev, size_t *size)¶
map a PCI ROM to kernel space
Parameters
struct pci_dev *pdev
pointer to pci device struct
size_t *size
pointer to receive size of pci window over ROM
Return
kernel virtual pointer to image of ROM
Description
Map a PCI ROM into kernel space. If ROM is boot video ROM, the shadow BIOS copy will be returned instead of the actual ROM.
-
void pci_unmap_rom(struct pci_dev *pdev, void __iomem *rom)¶
unmap the ROM from kernel space
Parameters
struct pci_dev *pdev
pointer to pci device struct
void __iomem *rom
virtual address of the previous mapping
Description
Remove a mapping of a previously mapped ROM
-
void *pci_iov_get_pf_drvdata(struct pci_dev *dev, struct pci_driver *pf_driver)¶
Return the drvdata of a PF
Parameters
struct pci_dev *dev
VF pci_dev
struct pci_driver *pf_driver
Device driver required to own the PF
Description
This must be called from a context that ensures that a VF driver is attached. The value returned is invalid once the VF driver completes its remove() callback.
Locking is achieved by the driver core. A VF driver cannot be probed until
pci_enable_sriov()
is called and pci_disable_sriov()
does not return until
all VF drivers have completed their remove().
The PF driver must call pci_disable_sriov()
before it begins to destroy the
drvdata.
-
int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn)¶
enable the SR-IOV capability
Parameters
struct pci_dev *dev
the PCI device
int nr_virtfn
number of virtual functions to enable
Description
Returns 0 on success, or negative on failure.
-
void pci_disable_sriov(struct pci_dev *dev)¶
disable the SR-IOV capability
Parameters
struct pci_dev *dev
the PCI device
-
int pci_num_vf(struct pci_dev *dev)¶
return number of VFs associated with a PF device_release_driver
Parameters
struct pci_dev *dev
the PCI device
Description
Returns number of VFs, or 0 if SR-IOV is not enabled.
-
int pci_vfs_assigned(struct pci_dev *dev)¶
returns number of VFs are assigned to a guest
Parameters
struct pci_dev *dev
the PCI device
Description
Returns number of VFs belonging to this device that are assigned to a guest. If device is not a physical function returns 0.
-
int pci_sriov_set_totalvfs(struct pci_dev *dev, u16 numvfs)¶
reduce the TotalVFs available
Parameters
struct pci_dev *dev
the PCI PF device
u16 numvfs
number that should be used for TotalVFs supported
Description
Should be called from PF driver’s probe routine with device’s mutex held.
Returns 0 if PF is an SRIOV-capable device and value of numvfs valid. If not a PF return -ENOSYS; if numvfs is invalid return -EINVAL; if VFs already enabled, return -EBUSY.
-
int pci_sriov_get_totalvfs(struct pci_dev *dev)¶
get total VFs supported on this device
Parameters
struct pci_dev *dev
the PCI PF device
Description
For a PCIe device with SRIOV support, return the PCIe SRIOV capability value of TotalVFs or the value of driver_max_VFs if the driver reduced it. Otherwise 0.
-
int pci_sriov_configure_simple(struct pci_dev *dev, int nr_virtfn)¶
helper to configure SR-IOV
Parameters
struct pci_dev *dev
the PCI device
int nr_virtfn
number of virtual functions to enable, 0 to disable
Description
Enable or disable SR-IOV for devices that don’t require any PF setup before enabling SR-IOV. Return value is negative on error, or number of VFs allocated on success.
-
ssize_t pci_read_legacy_io(struct file *filp, struct kobject *kobj, struct bin_attribute *bin_attr, char *buf, loff_t off, size_t count)¶
read byte(s) from legacy I/O port space
Parameters
struct file *filp
open sysfs file
struct kobject *kobj
kobject corresponding to file to read from
struct bin_attribute *bin_attr
struct bin_attribute for this file
char *buf
buffer to store results
loff_t off
offset into legacy I/O port space
size_t count
number of bytes to read
Description
Reads 1, 2, or 4 bytes from legacy I/O port space using an arch specific callback routine (pci_legacy_read).
-
ssize_t pci_write_legacy_io(struct file *filp, struct kobject *kobj, struct bin_attribute *bin_attr, char *buf, loff_t off, size_t count)¶
write byte(s) to legacy I/O port space
Parameters
struct file *filp
open sysfs file
struct kobject *kobj
kobject corresponding to file to read from
struct bin_attribute *bin_attr
struct bin_attribute for this file
char *buf
buffer containing value to be written
loff_t off
offset into legacy I/O port space
size_t count
number of bytes to write
Description
Writes 1, 2, or 4 bytes from legacy I/O port space using an arch specific callback routine (pci_legacy_write).
-
int pci_mmap_legacy_mem(struct file *filp, struct kobject *kobj, struct bin_attribute *attr, struct vm_area_struct *vma)¶
map legacy PCI memory into user memory space
Parameters
struct file *filp
open sysfs file
struct kobject *kobj
kobject corresponding to device to be mapped
struct bin_attribute *attr
struct bin_attribute for this file
struct vm_area_struct *vma
struct vm_area_struct passed to mmap
Description
Uses an arch specific callback, pci_mmap_legacy_mem_page_range, to mmap legacy memory space (first meg of bus space) into application virtual memory space.
-
int pci_mmap_legacy_io(struct file *filp, struct kobject *kobj, struct bin_attribute *attr, struct vm_area_struct *vma)¶
map legacy PCI IO into user memory space
Parameters
struct file *filp
open sysfs file
struct kobject *kobj
kobject corresponding to device to be mapped
struct bin_attribute *attr
struct bin_attribute for this file
struct vm_area_struct *vma
struct vm_area_struct passed to mmap
Description
Uses an arch specific callback, pci_mmap_legacy_io_page_range, to mmap legacy IO space (first meg of bus space) into application virtual memory space. Returns -ENOSYS if the operation isn’t supported
-
void pci_adjust_legacy_attr(struct pci_bus *b, enum pci_mmap_state mmap_type)¶
adjustment of legacy file attributes
Parameters
struct pci_bus *b
bus to create files under
enum pci_mmap_state mmap_type
I/O port or memory
Description
Stub implementation. Can be overridden by arch if necessary.
-
void pci_create_legacy_files(struct pci_bus *b)¶
create legacy I/O port and memory files
Parameters
struct pci_bus *b
bus to create files under
Description
Some platforms allow access to legacy I/O port and ISA memory space on a per-bus basis. This routine creates the files and ties them into their associated read, write and mmap files from pci-sysfs.c
On error unwind, but don’t propagate the error to the caller as it is ok to set up the PCI bus without these files.
-
int pci_mmap_resource(struct kobject *kobj, struct bin_attribute *attr, struct vm_area_struct *vma, int write_combine)¶
map a PCI resource into user memory space
Parameters
struct kobject *kobj
kobject for mapping
struct bin_attribute *attr
struct bin_attribute for the file being mapped
struct vm_area_struct *vma
struct vm_area_struct passed into the mmap
int write_combine
1 for write_combine mapping
Description
Use the regular PCI mapping routines to map a PCI resource into userspace.
-
void pci_remove_resource_files(struct pci_dev *pdev)¶
cleanup resource files
Parameters
struct pci_dev *pdev
dev to cleanup
Description
If we created resource files for pdev, remove them from sysfs and free their resources.
-
int pci_create_resource_files(struct pci_dev *pdev)¶
create resource files in sysfs for dev
Parameters
struct pci_dev *pdev
dev in question
Description
Walk the resources in pdev creating files for each resource available.
-
ssize_t pci_write_rom(struct file *filp, struct kobject *kobj, struct bin_attribute *bin_attr, char *buf, loff_t off, size_t count)¶
used to enable access to the PCI ROM display
Parameters
struct file *filp
sysfs file
struct kobject *kobj
kernel object handle
struct bin_attribute *bin_attr
struct bin_attribute for this file
char *buf
user input
loff_t off
file offset
size_t count
number of byte in input
Description
writing anything except 0 enables it
-
ssize_t pci_read_rom(struct file *filp, struct kobject *kobj, struct bin_attribute *bin_attr, char *buf, loff_t off, size_t count)¶
read a PCI ROM
Parameters
struct file *filp
sysfs file
struct kobject *kobj
kernel object handle
struct bin_attribute *bin_attr
struct bin_attribute for this file
char *buf
where to put the data we read from the ROM
loff_t off
file offset
size_t count
number of bytes to read
Description
Put count bytes starting at off into buf from the ROM in the PCI device corresponding to kobj.
-
void pci_remove_sysfs_dev_files(struct pci_dev *pdev)¶
cleanup PCI specific sysfs files
Parameters
struct pci_dev *pdev
device whose entries we should free
Description
Cleanup when pdev is removed from sysfs.
PCI Hotplug Support Library¶
-
int __pci_hp_register(struct hotplug_slot *slot, struct pci_bus *bus, int devnr, const char *name, struct module *owner, const char *mod_name)¶
register a hotplug_slot with the PCI hotplug subsystem
Parameters
struct hotplug_slot *slot
pointer to the
struct hotplug_slot
to registerstruct pci_bus *bus
bus this slot is on
int devnr
device number
const char *name
name registered with kobject core
struct module *owner
caller module owner
const char *mod_name
caller module name
Description
Prepares a hotplug slot for in-kernel use and immediately publishes it to
user space in one go. Drivers may alternatively carry out the two steps
separately by invoking pci_hp_initialize() and pci_hp_add()
.
Returns 0 if successful, anything else for an error.
-
int __pci_hp_initialize(struct hotplug_slot *slot, struct pci_bus *bus, int devnr, const char *name, struct module *owner, const char *mod_name)¶
prepare hotplug slot for in-kernel use
Parameters
struct hotplug_slot *slot
pointer to the
struct hotplug_slot
to initializestruct pci_bus *bus
bus this slot is on
int devnr
slot number
const char *name
name registered with kobject core
struct module *owner
caller module owner
const char *mod_name
caller module name
Description
Allocate and fill in a PCI slot for use by a hotplug driver. Once this has been called, the driver may invoke hotplug_slot_name() to get the slot’s unique name. The driver must be prepared to handle a ->reset_slot callback from this point on.
Returns 0 on success or a negative int on error.
-
int pci_hp_add(struct hotplug_slot *slot)¶
publish hotplug slot to user space
Parameters
struct hotplug_slot *slot
pointer to the
struct hotplug_slot
to publish
Description
Make a hotplug slot’s sysfs interface available and inform user space of its
addition by sending a uevent. The hotplug driver must be prepared to handle
all struct hotplug_slot_ops
callbacks from this point on.
Returns 0 on success or a negative int on error.
-
void pci_hp_deregister(struct hotplug_slot *slot)¶
deregister a hotplug_slot with the PCI hotplug subsystem
Parameters
struct hotplug_slot *slot
pointer to the
struct hotplug_slot
to deregister
Description
The slot must have been registered with the pci hotplug subsystem previously with a call to pci_hp_register().
Returns 0 if successful, anything else for an error.
-
void pci_hp_del(struct hotplug_slot *slot)¶
unpublish hotplug slot from user space
Parameters
struct hotplug_slot *slot
pointer to the
struct hotplug_slot
to unpublish
Description
Remove a hotplug slot’s sysfs interface.
Returns 0 on success or a negative int on error.
-
void pci_hp_destroy(struct hotplug_slot *slot)¶
remove hotplug slot from in-kernel use
Parameters
struct hotplug_slot *slot
pointer to the
struct hotplug_slot
to destroy
Description
Destroy a PCI slot used by a hotplug driver. Once this has been called, the driver may no longer invoke hotplug_slot_name() to get the slot’s unique name. The driver no longer needs to handle a ->reset_slot callback from this point on.
Returns 0 on success or a negative int on error.