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 Management PCI_CAP_ID_AGP Accelerated Graphics Port PCI_CAP_ID_VPD Vital Product Data PCI_CAP_ID_SLOTID Slot Identification PCI_CAP_ID_MSI Message Signalled Interrupts PCI_CAP_ID_CHSWP CompactPCI HotSwap PCI_CAP_ID_PCIX PCI-X PCI_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 Reporting PCI_EXT_CAP_ID_VC Virtual Channel PCI_EXT_CAP_ID_DSN Device Serial Number PCI_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 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_io(struct pci_dev *dev)¶: Initialize a device for use with IO 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 I/O resources. Wake up the device if it was suspended. Beware, this function can fail.

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).

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 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.

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.

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.

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);

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

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 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 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

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.

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.

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 ids
unsigned int device: PCI device id to match, or PCI_ANY_ID to match all device ids
unsigned int ss_vendor: PCI subsystem vendor id to match, or PCI_ANY_ID to match all vendor ids
unsigned int ss_device: PCI subsystem device id to match, or PCI_ANY_ID to match all device ids
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 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 ids
unsigned int device: PCI device id to match, or PCI_ANY_ID to match all device ids
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 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.

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.

void pci_msi_mask_irq(struct irq_data *data)¶: Generic IRQ chip callback to mask PCI/MSI interrupts

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_msix_vec_count(struct pci_dev *dev)¶: return the number of device’s MSI-X table entries

Parameters

struct pci_dev *dev: pointer to the pci_dev data structure of MSI-X device function This function returns the number of device’s MSI-X table entries and therefore the number of MSI-X vectors device is capable of sending. It returns a negative errno if the device is not capable of sending MSI-X interrupts.

int pci_msi_enabled(void)¶: is MSI enabled?

Parameters

void: no arguments

Description

Returns true if MSI has not been disabled by the command-line option pci=nomsi.

int pci_enable_msix_range(struct pci_dev *dev, struct msix_entry *entries, int minvec, int maxvec)¶: configure device’s MSI-X capability structure

Parameters

struct pci_dev *dev: pointer to the pci_dev data structure of MSI-X device function
struct msix_entry *entries: pointer to an array of MSI-X entries
int minvec: minimum number of MSI-X IRQs requested
int maxvec: maximum number of MSI-X IRQs requested

Description

Setup the MSI-X capability structure of device function with a maximum possible number of interrupts in the range between minvec and maxvec upon its software driver call to request for MSI-X mode enabled on its hardware device function. It returns a negative errno if an error occurs. If it succeeds, it returns the actual number of interrupts allocated and indicates the successful configuration of MSI-X capability structure with new allocated MSI-X interrupts.

int pci_alloc_irq_vectors_affinity(struct pci_dev *dev, unsigned int min_vecs, unsigned int max_vecs, unsigned int flags, struct irq_affinity *affd)¶: allocate multiple IRQs for a device

Parameters

struct pci_dev *dev: PCI device to operate on
unsigned int min_vecs: minimum number of vectors required (must be >= 1)
unsigned int max_vecs: maximum (desired) number of vectors
unsigned int flags: flags or quirks for the allocation
struct irq_affinity *affd: optional description of the affinity requirements

Description

Allocate up to max_vecs interrupt vectors for dev, using MSI-X or MSI vectors if available, and fall back to a single legacy vector if neither is available. Return the number of vectors allocated, (which might be smaller than max_vecs) if successful, or a negative error code on error. If less than min_vecs interrupt vectors are available for dev the function will fail with -ENOSPC.

To get the Linux IRQ number used for a vector that can be passed to request_irq() use the pci_irq_vector() helper.

void pci_free_irq_vectors(struct pci_dev *dev)¶: free previously allocated IRQs for a device

Parameters

struct pci_dev *dev: PCI device to operate on

Description

Undoes the allocations and enabling in pci_alloc_irq_vectors().

int pci_irq_vector(struct pci_dev *dev, unsigned int nr)¶: return Linux IRQ number of a device vector

Parameters

struct pci_dev *dev: PCI device to operate on
unsigned int nr: device-relative interrupt vector index (0-based).

const struct cpumask *pci_irq_get_affinity(struct pci_dev *dev, int nr)¶: return the affinity of a particular MSI vector

Parameters

struct pci_dev *dev: PCI device to operate on
int nr: device-relative interrupt vector index (0-based).

struct irq_domain *pci_msi_create_irq_domain(struct fwnode_handle *fwnode, struct msi_domain_info *info, struct irq_domain *parent)¶: Create a MSI interrupt domain

Parameters

struct fwnode_handle *fwnode: Optional fwnode of the interrupt controller
struct msi_domain_info *info: MSI domain info
struct irq_domain *parent: Parent irq domain

Description

Updates the domain and chip ops and creates a MSI interrupt domain.

Return

A domain pointer or NULL in case of failure.

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.

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.

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

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 register
struct 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 initialize
struct 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.