PCI Support Library¶

unsigned charpci_bus_max_busnr(struct pci_bus * bus)¶

returns maximum PCI bus number of given bus’ children

Parameters

structpci_bus*bus

pointer to PCI bus structure to search

Description

Given a PCI bus, returns the highest PCI bus number present in the setincluding the given PCI bus and its list of child PCI buses.

intpci_status_get_and_clear_errors(struct pci_dev * pdev)¶

return and clear error bits in PCI_STATUS

Parameters

structpci_dev*pdev

the PCI device

Description

Returns error bits set in PCI_STATUS and clears them.

intpci_find_capability(struct pci_dev * dev, int cap)¶

query for devices’ capabilities

Parameters

structpci_dev*dev

PCI device to query

intcap

capability code

Description

Tell if a device supports a given PCI capability.Returns the address of the requested capability structure within thedevice’s PCI configuration space or 0 in case the device does notsupport it. Possible values forcap 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

intpci_bus_find_capability(struct pci_bus * bus, unsigned int devfn, int cap)¶

query for devices’ capabilities

Parameters

structpci_bus*bus

the PCI bus to query

unsignedintdevfn

PCI device to query

intcap

capability code

Description

Likepci_find_capability() but works for PCI devices that do not have apci_dev structure set up yet.

Returns the address of the requested capability structure within thedevice’s PCI configuration space or 0 in case the device does notsupport it.

intpci_find_next_ext_capability(struct pci_dev * dev, int start, int cap)¶

Find an extended capability

Parameters

structpci_dev*dev

PCI device to query

intstart

address at which to start looking (0 to start at beginning of list)

intcap

capability code

Description

Returns the address of the next matching extended capability structurewithin the device’s PCI configuration space or 0 if the device doesnot support it. Some capabilities can occur several times, e.g., thevendor-specific capability, and this provides a way to find them all.

intpci_find_ext_capability(struct pci_dev * dev, int cap)¶

Find an extended capability

Parameters

structpci_dev*dev

PCI device to query

intcap

capability code

Description

Returns the address of the requested extended capability structurewithin the device’s PCI configuration space or 0 if the device doesnot support it. Possible values forcap 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

u64pci_get_dsn(struct pci_dev * dev)¶

Read and return the 8-byte Device Serial Number

Parameters

structpci_dev*dev

PCI device to query

Description

Looks up the PCI_EXT_CAP_ID_DSN and reads the 8 bytes of the Device SerialNumber.

Returns the DSN, or zero if the capability does not exist.

intpci_find_next_ht_capability(struct pci_dev * dev, int pos, int ht_cap)¶

query a device’s Hypertransport capabilities

Parameters

structpci_dev*dev

PCI device to query

intpos

Position from which to continue searching

intht_cap

Hypertransport capability code

Description

To be used in conjunction withpci_find_ht_capability() to search forall capabilities matchinght_cap.pos should always be a value returnedfrompci_find_ht_capability().

NB. To be 100% safe against broken PCI devices, the caller should takesteps to avoid an infinite loop.

intpci_find_ht_capability(struct pci_dev * dev, int ht_cap)¶

query a device’s Hypertransport capabilities

Parameters

structpci_dev*dev

PCI device to query

intht_cap

Hypertransport capability code

Description

Tell if a device supports a given Hypertransport capability.Returns an address within the device’s PCI configuration spaceor 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 matchinght_cap.

struct resource *pci_find_parent_resource(const struct pci_dev * dev, struct resource * res)¶

return resource region of parent bus of given region

Parameters

conststructpci_dev*dev

PCI device structure contains resources to be searched

structresource*res

child resource record for which parent is sought

Description

For given resource region of given device, return the resource region ofparent 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

structpci_dev*dev

PCI device to query

structresource*res

Resource to look for

Description

Goes over standard PCI resources (BARs) and checks if the given resourceis partially or fully contained in any of them. In that case thematching resource is returned,NULL otherwise.

intpci_platform_power_transition(struct pci_dev * dev, pci_power_t state)¶

Use platform to change device power state

Parameters

structpci_dev*dev

PCI device to handle.

pci_power_tstate

State to put the device into.

intpci_set_power_state(struct pci_dev * dev, pci_power_t state)¶

Set the power state of a PCI device

Parameters

structpci_dev*dev

PCI device to handle.

pci_power_tstate

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/orthe 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 awrong 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.

pci_power_tpci_choose_state(struct pci_dev * dev, pm_message_t state)¶

Choose the power state of a PCI device

Parameters

structpci_dev*dev

PCI device to be suspended

pm_message_tstate

target sleep state for the whole system. This is the valuethat is passed to suspend() function.

Description

Returns PCI power state suitable for given device and given systemmessage.

intpci_save_state(struct pci_dev * dev)¶

save the PCI configuration space of a device before suspending

Parameters

structpci_dev*dev

PCI device that we’re dealing with

voidpci_restore_state(struct pci_dev * dev)¶

Restore the saved state of a PCI device

Parameters

structpci_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

structpci_dev*dev

PCI device that we’re dealing with

Description

Return NULL if no state or error.

intpci_load_saved_state(struct pci_dev * dev, struct pci_saved_state * state)¶

Reload the provided save state into struct pci_dev.

Parameters

structpci_dev*dev

PCI device that we’re dealing with

structpci_saved_state*state

Saved state returned frompci_store_saved_state()

intpci_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

structpci_dev*dev

PCI device that we’re dealing with

structpci_saved_state**state

Pointer to saved state returned frompci_store_saved_state()

intpci_reenable_device(struct pci_dev * dev)¶

Resume abandoned device

Parameters

structpci_dev*dev

PCI device to be resumed

NOTE

This function is a backend of pci_default_resume() and is not supposedto be called by normal code, write proper resume handler and use it instead.

intpci_enable_device_io(struct pci_dev * dev)¶

Initialize a device for use with IO space

Parameters

structpci_dev*dev

PCI device to be initialized

Description

Initialize device before it’s used by a driver. Ask low-level codeto enable I/O resources. Wake up the device if it was suspended.Beware, this function can fail.

intpci_enable_device_mem(struct pci_dev * dev)¶

Initialize a device for use with Memory space

Parameters

structpci_dev*dev

PCI device to be initialized

Description

Initialize device before it’s used by a driver. Ask low-level codeto enable Memory resources. Wake up the device if it was suspended.Beware, this function can fail.

intpci_enable_device(struct pci_dev * dev)¶

Initialize device before it’s used by a driver.

Parameters

structpci_dev*dev

PCI device to be initialized

Description

Initialize device before it’s used by a driver. Ask low-level codeto 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 callthis function repeatedly (we just increment the count).

intpcim_enable_device(struct pci_dev * pdev)¶

Managedpci_enable_device()

Parameters

structpci_dev*pdev

PCI device to be initialized

Description

Managedpci_enable_device().

voidpcim_pin_device(struct pci_dev * pdev)¶

Pin managed PCI device

Parameters

structpci_dev*pdev

PCI device to pin

Description

Pin managed PCI devicepdev. Pinned device won’t be disabled ondriver detach.pdev must have been enabled withpcim_enable_device().

voidpci_disable_device(struct pci_dev * dev)¶

Disable PCI device after use

Parameters

structpci_dev*dev

PCI device to be disabled

Description

Signal to the system that the PCI device is not in use by the systemanymore. This only involves disabling PCI bus-mastering, if active.

Note we don’t actually disable the device until all callers ofpci_enable_device() have calledpci_disable_device().

intpci_set_pcie_reset_state(struct pci_dev * dev, enum pcie_reset_state state)¶

set reset state for device dev

Parameters

structpci_dev*dev

the PCIe device reset

enumpcie_reset_statestate

Reset state to enter into

Description

Sets the PCI reset state for the device.

boolpci_pme_capable(struct pci_dev * dev, pci_power_t state)¶

check the capability of PCI device to generate PME#

Parameters

structpci_dev*dev

PCI device to handle.

pci_power_tstate

PCI state from which device will issue PME#.

voidpci_pme_active(struct pci_dev * dev, bool enable)¶

enable or disable PCI device’s PME# function

Parameters

structpci_dev*dev

PCI device to handle.

boolenable

‘true’ to enable PME# generation; ‘false’ to disable it.

Description

The caller must verify that the device is capable of generating PME# beforecalling this function withenable equal to ‘true’.

intpci_enable_wake(struct pci_dev * pci_dev, pci_power_t state, bool enable)¶

change wakeup settings for a PCI device

Parameters

structpci_dev*pci_dev

Target device

pci_power_tstate

PCI state from which device will issue wakeup events

boolenable

Whether or not to enable event generation

Description

Ifenable is set, check device_may_wakeup() for the device before calling__pci_enable_wake() for it.

intpci_wake_from_d3(struct pci_dev * dev, bool enable)¶

enable/disable device to wake up from D3_hot or D3_cold

Parameters

structpci_dev*dev

PCI device to prepare

boolenable

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_coldand 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 ACPIordering constraints.

This function only returns error code if the device is not allowed to wakeup the system from sleep or it is not capable of generating PME# from bothD3_hot and D3_cold and the platform is unable to enable wake-up power for it.

intpci_prepare_to_sleep(struct pci_dev * dev)¶

prepare PCI device for system-wide transition into a sleep state

Parameters

structpci_dev*dev

Device to handle.

Description

Choose the power state appropriate for the device depending on whetherit 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.

intpci_back_from_sleep(struct pci_dev * dev)¶

turn PCI device on during system-wide transition into working state

Parameters

structpci_dev*dev

Device to handle.

Description

Disable device’s system wake-up capability and put it into D0.

boolpci_dev_run_wake(struct pci_dev * dev)¶

Check if device can generate run-time wake-up events.

Parameters

structpci_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 supportsPME and one of its upstream bridges can generate wake-up events.

voidpci_d3cold_enable(struct pci_dev * dev)¶

Enable D3cold for device

Parameters

structpci_dev*dev

PCI device to handle

Description

This function can be used in drivers to enable D3cold from the devicethey handle. It also updates upstream PCI bridge PM capabilitiesaccordingly.

voidpci_d3cold_disable(struct pci_dev * dev)¶

Disable D3cold for device

Parameters

structpci_dev*dev

PCI device to handle

Description

This function can be used in drivers to disable D3cold from the devicethey handle. It also updates upstream PCI bridge PM capabilitiesaccordingly.

intpci_enable_atomic_ops_to_root(struct pci_dev * dev, u32 cap_mask)¶

enable AtomicOp requests to root port

Parameters

structpci_dev*dev

the PCI device

u32cap_mask

mask of desired AtomicOp sizes, including one or more of:PCI_EXP_DEVCAP2_ATOMIC_COMP32PCI_EXP_DEVCAP2_ATOMIC_COMP64PCI_EXP_DEVCAP2_ATOMIC_COMP128

Description

Return 0 if all upstream bridges support AtomicOp routing, egressblocking is disabled on all upstream ports, and the root port supportsthe requested completion capabilities (32-bit, 64-bit and/or 128-bitAtomicOp completion), or negative otherwise.

u8pci_common_swizzle(struct pci_dev * dev, u8 * pinp)¶

swizzle INTx all the way to root bridge

Parameters

structpci_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-PCIbridges all the way up to a PCI root bus.

voidpci_release_region(struct pci_dev * pdev, int bar)¶

Release a PCI bar

Parameters

structpci_dev*pdev

PCI device whose resources were previously reserved bypci_request_region()

intbar

BAR to release

Description

Releases the PCI I/O and memory resources previously reserved by asuccessful call topci_request_region(). Call this function onlyafter all use of the PCI regions has ceased.

intpci_request_region(struct pci_dev * pdev, int bar, const char * res_name)¶

Reserve PCI I/O and memory resource

Parameters

structpci_dev*pdev

PCI device whose resources are to be reserved

intbar

BAR to be reserved

constchar*res_name

Name to be associated with resource

Description

Mark the PCI region associated with PCI devicepdev BARbar asbeing reserved by ownerres_name. Do not access anyaddress inside the PCI regions unless this call returnssuccessfully.

Returns 0 on success, orEBUSY on error. A warningmessage is also printed on failure.

voidpci_release_selected_regions(struct pci_dev * pdev, int bars)¶

Release selected PCI I/O and memory resources

Parameters

structpci_dev*pdev

PCI device whose resources were previously reserved

intbars

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.

intpci_request_selected_regions(struct pci_dev * pdev, int bars, const char * res_name)¶

Reserve selected PCI I/O and memory resources

Parameters

structpci_dev*pdev

PCI device whose resources are to be reserved

intbars

Bitmask of BARs to be requested

constchar*res_name

Name to be associated with resource

voidpci_release_regions(struct pci_dev * pdev)¶

Release reserved PCI I/O and memory resources

Parameters

structpci_dev*pdev

PCI device whose resources were previously reserved bypci_request_regions()

Description

Releases all PCI I/O and memory resources previously reserved by asuccessful call topci_request_regions(). Call this function onlyafter all use of the PCI regions has ceased.

intpci_request_regions(struct pci_dev * pdev, const char * res_name)¶

Reserve PCI I/O and memory resources

Parameters

structpci_dev*pdev

PCI device whose resources are to be reserved

constchar*res_name

Name to be associated with resource.

Description

Mark all PCI regions associated with PCI devicepdev asbeing reserved by ownerres_name. Do not access anyaddress inside the PCI regions unless this call returnssuccessfully.

Returns 0 on success, orEBUSY on error. A warningmessage is also printed on failure.

intpci_request_regions_exclusive(struct pci_dev * pdev, const char * res_name)¶

Reserve PCI I/O and memory resources

Parameters

structpci_dev*pdev

PCI device whose resources are to be reserved

constchar*res_name

Name to be associated with resource.

Description

Mark all PCI regions associated with PCI devicepdev as being reservedby ownerres_name. Do not access any address inside the PCI regionsunless this call returns successfully.

pci_request_regions_exclusive() will mark the region so that /dev/memand the sysfs MMIO access will not be allowed.

Returns 0 on success, orEBUSY on error. A warning message is alsoprinted on failure.

intpci_remap_iospace(const struct resource * res, phys_addr_t phys_addr)¶

Remap the memory mapped I/O space

Parameters

conststructresource*res

Resource describing the I/O space

phys_addr_tphys_addr

physical address of range to be mapped

Description

Remap the memory mapped I/O space described by theres and the CPUphysical addressphys_addr into virtual address space. Onlyarchitectures that have memory mapped IO functions defined (and thePCI_IOBASE value defined) should call this function.

voidpci_unmap_iospace(struct resource * res)¶

Unmap the memory mapped I/O space

Parameters

structresource*res

resource to be unmapped

Description

Unmap the CPU virtual addressres from virtual address space. Onlyarchitectures that have memory mapped IO functions defined (and thePCI_IOBASE value defined) should call this function.

intdevm_pci_remap_iospace(structdevice * dev, const struct resource * res, phys_addr_t phys_addr)¶

Managedpci_remap_iospace()

Parameters

structdevice*dev

Generic device to remap IO address for

conststructresource*res

Resource describing the I/O space

phys_addr_tphys_addr

physical address of range to be mapped

Description

Managedpci_remap_iospace(). Map is automatically unmapped on driverdetach.

void __iomem *devm_pci_remap_cfgspace(structdevice * dev, resource_size_t offset, resource_size_t size)¶

Managed pci_remap_cfgspace()

Parameters

structdevice*dev

Generic device to remap IO address for

resource_size_toffset

Resource address to map

resource_size_tsize

Size of map

Description

Managed pci_remap_cfgspace(). Map is automatically unmapped on driverdetach.

void __iomem *devm_pci_remap_cfg_resource(structdevice * dev, struct resource * res)¶

check, request region and ioremap cfg resource

Parameters

structdevice*dev

generic device to handle the resource for

structresource*res

configuration space resource to be handled

Description

Checks that a resource is a valid memory region, requests the memoryregion and ioremaps with pci_remap_cfgspace() API that ensures theproper 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 codeon 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);

voidpci_set_master(struct pci_dev * dev)¶

enables bus-mastering for device dev

Parameters

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

voidpci_clear_master(struct pci_dev * dev)¶

disables bus-mastering for device dev

Parameters

structpci_dev*dev

the PCI device to disable

intpci_set_cacheline_size(struct pci_dev * dev)¶

ensure the CACHE_LINE_SIZE register is programmed

Parameters

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

intpci_set_mwi(struct pci_dev * dev)¶

enables memory-write-invalidate PCI transaction

Parameters

structpci_dev*dev

the PCI device for which MWI is enabled

Description

Enables the Memory-Write-Invalidate transaction inPCI_COMMAND.

Return

An appropriate -ERRNO error value on error, or zero for success.

intpcim_set_mwi(struct pci_dev * dev)¶

a device-managedpci_set_mwi()

Parameters

structpci_dev*dev

the PCI device for which MWI is enabled

Description

Managedpci_set_mwi().

Return

An appropriate -ERRNO error value on error, or zero for success.

intpci_try_set_mwi(struct pci_dev * dev)¶

enables memory-write-invalidate PCI transaction

Parameters

structpci_dev*dev

the PCI device for which MWI is enabled

Description

Enables the Memory-Write-Invalidate transaction inPCI_COMMAND.Callers are not required to check the return value.

Return

An appropriate -ERRNO error value on error, or zero for success.

voidpci_clear_mwi(struct pci_dev * dev)¶

disables Memory-Write-Invalidate for device dev

Parameters

structpci_dev*dev

the PCI device to disable

Description

Disables PCI Memory-Write-Invalidate transaction on the device

voidpci_intx(struct pci_dev * pdev, int enable)¶

enables/disables PCI INTx for device dev

Parameters

structpci_dev*pdev

the PCI device to operate on

intenable

boolean: whether to enable or disable PCI INTx

Description

Enables/disables PCI INTx for devicepdev

boolpci_check_and_mask_intx(struct pci_dev * dev)¶

mask INTx on pending interrupt

Parameters

structpci_dev*dev

the PCI device to operate on

Description

Check if the device dev has its INTx line asserted, mask it and returntrue in that case. False is returned if no interrupt was pending.

boolpci_check_and_unmask_intx(struct pci_dev * dev)¶

unmask INTx if no interrupt is pending

Parameters

structpci_dev*dev

the PCI device to operate on

Description

Check if the device dev has its INTx line asserted, unmask it if not andreturn true. False is returned and the mask remains active if there wasstill an interrupt pending.

intpci_wait_for_pending_transaction(struct pci_dev * dev)¶

wait for pending transaction

Parameters

structpci_dev*dev

the PCI device to operate on

Description

Return 0 if transaction is pending 1 otherwise.

boolpcie_has_flr(struct pci_dev * dev)¶

check if a device supports function level resets

Parameters

structpci_dev*dev

device to check

Description

Returns true if the device advertises support for PCIe function levelresets.

intpcie_flr(struct pci_dev * dev)¶

initiate a PCIe function level reset

Parameters

structpci_dev*dev

device to reset

Description

Initiate a function level reset ondev. The caller should ensure thedevice supports FLR before calling this function, e.g. by using thepcie_has_flr() helper.

intpci_bridge_secondary_bus_reset(struct pci_dev * dev)¶

Reset the secondary bus on a PCI bridge.

Parameters

structpci_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 thedev mutex lock.

Parameters

structpci_dev*dev

PCI device to reset

Description

Some devices allow an individual function to be reset without affectingother functions in the same device. The PCI device must be responsiveto PCI config space in order to use this function.

The device function is presumed to be unused and the caller is holdingthe device mutex lock when this function is called.

Resetting the device will make the contents of PCI configuration spacerandom, so any caller of this must be prepared to reinitialise thedevice including MSI, bus mastering, BARs, decoding IO and memory spaces,etc.

Returns 0 if the device function was successfully reset or negative if thedevice doesn’t support resetting a single function.

intpci_reset_function(struct pci_dev * dev)¶

quiesce and reset a PCI device function

Parameters

structpci_dev*dev

PCI device to reset

Description

Some devices allow an individual function to be reset without affectingother functions in the same device. The PCI device must be responsiveto PCI config space in order to use this function.

This function does not just reset the PCI portion of a device, butclears all the state associated with the device. This function differsfrom__pci_reset_function_locked() in that it saves and restores device stateover the reset and takes the PCI device lock.

Returns 0 if the device function was successfully reset or negative if thedevice doesn’t support resetting a single function.

intpci_reset_function_locked(struct pci_dev * dev)¶

quiesce and reset a PCI device function

Parameters

structpci_dev*dev

PCI device to reset

Description

Some devices allow an individual function to be reset without affectingother functions in the same device. The PCI device must be responsiveto PCI config space in order to use this function.

This function does not just reset the PCI portion of a device, butclears all the state associated with the device. This function differsfrom__pci_reset_function_locked() in that it saves and restores device stateover the reset. It also differs frompci_reset_function() in that itrequires the PCI device lock to be held.

Returns 0 if the device function was successfully reset or negative if thedevice doesn’t support resetting a single function.

intpci_try_reset_function(struct pci_dev * dev)¶

quiesce and reset a PCI device function

Parameters

structpci_dev*dev

PCI device to reset

Description

Same as above, except return -EAGAIN if unable to lock device.

intpci_probe_reset_slot(struct pci_slot * slot)¶

probe whether a PCI slot can be reset

Parameters

structpci_slot*slot

PCI slot to probe

Description

Return 0 if slot can be reset, negative if a slot reset is not supported.

intpci_probe_reset_bus(struct pci_bus * bus)¶

probe whether a PCI bus can be reset

Parameters

structpci_bus*bus

PCI bus to probe

Description

Return 0 if bus can be reset, negative if a bus reset is not supported.

intpci_reset_bus(struct pci_dev * pdev)¶

Try to reset a PCI bus

Parameters

structpci_dev*pdev

top level PCI device to reset via slot/bus

Description

Same as above except return -EAGAIN if the bus cannot be locked

intpcix_get_max_mmrbc(struct pci_dev * dev)¶

get PCI-X maximum designed memory read byte count

Parameters

structpci_dev*dev

PCI device to query

Description

Returns mmrbc: maximum designed memory read count in bytes orappropriate error value.

intpcix_get_mmrbc(struct pci_dev * dev)¶

get PCI-X maximum memory read byte count

Parameters

structpci_dev*dev

PCI device to query

Description

Returns mmrbc: maximum memory read count in bytes or appropriate errorvalue.

intpcix_set_mmrbc(struct pci_dev * dev, int mmrbc)¶

set PCI-X maximum memory read byte count

Parameters

structpci_dev*dev

PCI device to query

intmmrbc

maximum memory read count in bytesvalid values are 512, 1024, 2048, 4096

Description

If possible sets maximum memory read byte count, some bridges have erratathat prevent this.

intpcie_get_readrq(struct pci_dev * dev)¶

get PCI Express read request size

Parameters

structpci_dev*dev

PCI device to query

Description

Returns maximum memory read request in bytes or appropriate error value.

intpcie_set_readrq(struct pci_dev * dev, int rq)¶

set PCI Express maximum memory read request

Parameters

structpci_dev*dev

PCI device to query

intrq

maximum memory read count in bytesvalid values are 128, 256, 512, 1024, 2048, 4096

Description

If possible sets maximum memory read request in bytes

intpcie_get_mps(struct pci_dev * dev)¶

get PCI Express maximum payload size

Parameters

structpci_dev*dev

PCI device to query

Description

Returns maximum payload size in bytes

intpcie_set_mps(struct pci_dev * dev, int mps)¶

set PCI Express maximum payload size

Parameters

structpci_dev*dev

PCI device to query

intmps

maximum payload size in bytesvalid values are 128, 256, 512, 1024, 2048, 4096

Description

If possible sets maximum payload size

u32pcie_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

structpci_dev*dev

PCI device to query

structpci_dev**limiting_dev

storage for device causing the bandwidth limitation

enumpci_bus_speed*speed

storage for speed of limiting device

enumpcie_link_width*width

storage for width of limiting device

Description

Walk up the PCI device chain and find the point where the minimumbandwidth is available. Return the bandwidth available there and (iflimiting_dev, speed, and width pointers are supplied) information aboutthat point. The bandwidth returned is in Mb/s, i.e., megabits/second ofraw bandwidth.

enum pci_bus_speedpcie_get_speed_cap(struct pci_dev * dev)¶

query for the PCI device’s link speed capability

Parameters

structpci_dev*dev

PCI device to query

Description

Query the PCI device speed capability. Return the maximum link speedsupported by the device.

enum pcie_link_widthpcie_get_width_cap(struct pci_dev * dev)¶

query for the PCI device’s link width capability

Parameters

structpci_dev*dev

PCI device to query

Description

Query the PCI device width capability. Return the maximum link widthsupported by the device.

voidpcie_print_link_status(struct pci_dev * dev)¶

Report the PCI device’s link speed and width

Parameters

structpci_dev*dev

PCI device to query

Description

Report the available bandwidth at the device.

intpci_select_bars(struct pci_dev * dev, unsigned long flags)¶

Make BAR mask from the type of resource

Parameters

structpci_dev*dev

the PCI device for which BAR mask is made

unsignedlongflags

resource type mask to be selected

Description

This helper routine makes bar mask from the type of resource.

intpci_add_dynid(structpci_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

structpci_driver*drv

target pci driver

unsignedintvendor

PCI vendor ID

unsignedintdevice

PCI device ID

unsignedintsubvendor

PCI subvendor ID

unsignedintsubdevice

PCI subdevice ID

unsignedintclass

PCI class

unsignedintclass_mask

PCI class mask

unsignedlongdriver_data

private driver data

Description

Adds a new dynamic pci device ID to this driver and causes thedriver to probe for all devices again.drv must have beenregistered prior to calling this function.

Context

Does GFP_KERNEL allocation.

Return

0 on success, -errno on failure.

const structpci_device_id *pci_match_id(const structpci_device_id * ids, struct pci_dev * dev)¶

See if a pci device matches a given pci_id table

Parameters

conststructpci_device_id*ids

array of PCI device id structures to search in

structpci_dev*dev

the PCI device structure to match against.

Description

Used by a driver to check whether a PCI device present in thesystem is in its list of supported devices. Returns the matchingpci_device_id structure orNULL if there is no match.

Deprecated, don’t use this as it will not catch any dynamic idsthat a driver might want to check for.

int__pci_register_driver(structpci_driver * drv, struct module * owner, const char * mod_name)¶

register a new pci driver

Parameters

structpci_driver*drv

the driver structure to register

structmodule*owner

owner module of drv

constchar*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 ifno device was claimed during registration.

voidpci_unregister_driver(structpci_driver * drv)¶

unregister a pci driver

Parameters

structpci_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 foreach device it was responsible for, and marks those devices asdriverless.

structpci_driver *pci_dev_driver(const struct pci_dev * dev)¶

get the pci_driver of a device

Parameters

conststructpci_dev*dev

the device to query

Description

Returns the appropriate pci_driver structure orNULL if there is noregistered driver for the device.

struct pci_dev *pci_dev_get(struct pci_dev * dev)¶

increments the reference count of the pci device structure

Parameters

structpci_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 intheir probe() methods, when they bind to a device, and releasethem by callingpci_dev_put(), in their disconnect() methods.

A pointer to the device with the incremented reference counter is returned.

voidpci_dev_put(struct pci_dev * dev)¶

release a use of the pci device structure

Parameters

structpci_dev*dev

device that’s been disconnected

Description

Must be called when a user of a device is finished with it. When the lastuser of the device calls this function, the memory of the device is freed.

voidpci_stop_and_remove_bus_device(struct pci_dev * dev)¶

remove a PCI device and any children

Parameters

structpci_dev*dev

the device to remove

Description

Remove a PCI device from the device lists, informing the driversthat the device has been removed. We also remove any subordinatebuses and children in a depth-first manner.

For each device we remove, delete the device structure from thedevice 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

intdomain

number of PCI domain to search

intbusnr

number of desired PCI bus

Description

Given a PCI bus number and domain number, the desired PCI bus is locatedin the global list of PCI buses. If the bus is found, a pointer to itsdata 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

conststructpci_bus*from

Previous PCI bus found, orNULL for new search.

Description

Iterates through the list of known PCI buses. A new search isinitiated by passingNULL as thefrom argument. Otherwise iffrom is notNULL, searches continue from next device on theglobal list.

struct pci_dev *pci_get_slot(struct pci_bus * bus, unsigned int devfn)¶

locate PCI device for a given PCI slot

Parameters

structpci_bus*bus

PCI bus on which desired PCI device resides

unsignedintdevfn

encodes number of PCI slot in which the desired PCIdevice resides and the logical device number within that slotin case of multi-function devices.

Description

Given a PCI bus and slot/function number, the desired PCI deviceis located in the list of PCI devices.If the device is found, its reference count is increased and thisfunction returns a pointer to its data structure. The caller mustdecrement the reference count by callingpci_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

intdomain

PCI domain/segment on which the PCI device resides.

unsignedintbus

PCI bus on which desired PCI device resides

unsignedintdevfn

encodes number of PCI slot in which the desired PCI deviceresides and the logical device number within that slot in case ofmulti-function devices.

Description

Given a PCI domain, bus, and slot/function number, the desired PCIdevice is located in the list of PCI devices. If the device isfound, its reference count is increased and this function returns apointer to its data structure. The caller must decrement thereference count by callingpci_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

unsignedintvendor

PCI vendor id to match, orPCI_ANY_ID to match all vendor ids

unsignedintdevice

PCI device id to match, orPCI_ANY_ID to match all device ids

unsignedintss_vendor

PCI subsystem vendor id to match, orPCI_ANY_ID to match all vendor ids

unsignedintss_device

PCI subsystem device id to match, orPCI_ANY_ID to match all device ids

structpci_dev*from

Previous PCI device found in search, orNULL for new search.

Description

Iterates through the list of known PCI devices. If a PCI device is foundwith a matchingvendor,device,ss_vendor andss_device, a pointer to itsdevice structure is returned, and the reference count to the device isincremented. Otherwise,NULL is returned. A new search is initiated bypassingNULL as thefrom argument. Otherwise iffrom is notNULL,searches continue from next device on the global list.The reference count forfrom is always decremented if it is notNULL.

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

unsignedintvendor

PCI vendor id to match, orPCI_ANY_ID to match all vendor ids

unsignedintdevice

PCI device id to match, orPCI_ANY_ID to match all device ids

structpci_dev*from

Previous PCI device found in search, orNULL for new search.

Description

Iterates through the list of known PCI devices. If a PCI device isfound with a matchingvendor anddevice, the reference count to thedevice is incremented and a pointer to its device structure is returned.Otherwise,NULL is returned. A new search is initiated by passingNULLas thefrom argument. Otherwise iffrom is notNULL, searches continuefrom next device on the global list. The reference count forfrom isalways decremented if it is notNULL.

struct pci_dev *pci_get_class(unsigned int class, struct pci_dev * from)¶

begin or continue searching for a PCI device by class

Parameters

unsignedintclass

search for a PCI device with this class designation

structpci_dev*from

Previous PCI device found in search, orNULL for new search.

Description

Iterates through the list of known PCI devices. If a PCI device isfound with a matchingclass, the reference count to the device isincremented and a pointer to its device structure is returned.Otherwise,NULL is returned.A new search is initiated by passingNULL as thefrom argument.Otherwise iffrom is notNULL, searches continue from next deviceon the global list. The reference count forfrom is always decrementedif it is notNULL.

intpci_dev_present(const structpci_device_id * ids)¶

Returns 1 if device matching the device list is present, 0 if not.

Parameters

conststructpci_device_id*ids

A pointer to a null terminated list of struct pci_device_id structuresthat 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 foundby this function, so if that device is removed from the system right afterthis function is finished, the value will be stale. Use this function tofind devices that are usually built into a system, or for a general hint asto if another device happens to be present at this specific moment in time.

voidpci_msi_mask_irq(structirq_data * data)¶

Generic IRQ chip callback to mask PCI/MSI interrupts

Parameters

structirq_data*data

pointer to irqdata associated to that interrupt

voidpci_msi_unmask_irq(structirq_data * data)¶

Generic IRQ chip callback to unmask PCI/MSI interrupts

Parameters

structirq_data*data

pointer to irqdata associated to that interrupt

intpci_msi_vec_count(struct pci_dev * dev)¶

Return the number of MSI vectors a device can send

Parameters

structpci_dev*dev

device to report about

Description

This function returns the number of MSI vectors a device requested viaMultiple Message Capable register. It returns a negative errno if thedevice is not capable sending MSI interrupts. Otherwise, the call succeedsand returns a power of two, up to a maximum of 2^5 (32), according to theMSI specification.

intpci_msix_vec_count(struct pci_dev * dev)¶

return the number of device’s MSI-X table entries

Parameters

structpci_dev*dev

pointer to the pci_dev data structure of MSI-X device functionThis function returns the number of device’s MSI-X table entries andtherefore 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-Xinterrupts.

intpci_msi_enabled(void)¶

is MSI enabled?

Parameters

void

no arguments

Description

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

intpci_enable_msix_range(struct pci_dev * dev, struct msix_entry * entries, int minvec, int maxvec)¶

configure device’s MSI-X capability structure

Parameters

structpci_dev*dev

pointer to the pci_dev data structure of MSI-X device function

structmsix_entry*entries

pointer to an array of MSI-X entries

intminvec

minimum number of MSI-X IRQs requested

intmaxvec

maximum number of MSI-X IRQs requested

Description

Setup the MSI-X capability structure of device function with a maximumpossible number of interrupts in the range betweenminvec andmaxvecupon its software driver call to request for MSI-X mode enabled on itshardware device function. It returns a negative errno if an error occurs.If it succeeds, it returns the actual number of interrupts allocated andindicates the successful configuration of MSI-X capability structurewith new allocated MSI-X interrupts.

intpci_alloc_irq_vectors_affinity(struct pci_dev * dev, unsigned int min_vecs, unsigned int max_vecs, unsigned int flags, structirq_affinity * affd)¶

allocate multiple IRQs for a device

Parameters

structpci_dev*dev

PCI device to operate on

unsignedintmin_vecs

minimum number of vectors required (must be >= 1)

unsignedintmax_vecs

maximum (desired) number of vectors

unsignedintflags

flags or quirks for the allocation

structirq_affinity*affd

optional description of the affinity requirements

Description

Allocate up tomax_vecs interrupt vectors fordev, using MSI-X or MSIvectors if available, and fall back to a single legacy vectorif neither is available. Return the number of vectors allocated,(which might be smaller thanmax_vecs) if successful, or a negativeerror code on error. If less thanmin_vecs interrupt vectors areavailable fordev the function will fail with -ENOSPC.

To get the Linux IRQ number used for a vector that can be passed torequest_irq() use thepci_irq_vector() helper.

voidpci_free_irq_vectors(struct pci_dev * dev)¶

free previously allocated IRQs for a device

Parameters

structpci_dev*dev

PCI device to operate on

Description

Undoes the allocations and enabling in pci_alloc_irq_vectors().

intpci_irq_vector(struct pci_dev * dev, unsigned int nr)¶

return Linux IRQ number of a device vector

Parameters

structpci_dev*dev

PCI device to operate on

unsignedintnr

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

structpci_dev*dev

PCI device to operate on

intnr

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

structfwnode_handle*fwnode

Optional fwnode of the interrupt controller

structmsi_domain_info*info

MSI domain info

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

intpci_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

structpci_bus*bus

PCI bus

structresource*res

resource to allocate

resource_size_tsize

size of resource to allocate

resource_size_talign

alignment of resource to allocate

resource_size_tmin

minimum /proc/iomem address to allocate

unsignedlongtype_mask

IORESOURCE_* type flags

resource_size_t(*)(void*,conststructresource*,resource_size_t,resource_size_t)alignf

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 allocationfor a specific device resource.

voidpci_bus_add_device(struct pci_dev * dev)¶

start driver for a single device

Parameters

structpci_dev*dev

device to add

Description

This adds add sysfs entries and start device drivers

voidpci_bus_add_devices(const struct pci_bus * bus)¶

start driver for PCI devices

Parameters

conststructpci_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

structpci_bus*bus

pci bus struct

structpci_ops*ops

new raw operations

Description

Return previous raw operations

voidpci_cfg_access_lock(struct pci_dev * dev)¶

Lock PCI config reads/writes

Parameters

structpci_dev*dev

pci device struct

Description

When access is locked, any userspace reads or writes to configspace and concurrent lock requests will sleep until access isallowed viapci_cfg_access_unlock() again.

boolpci_cfg_access_trylock(struct pci_dev * dev)¶

try to lock PCI config reads/writes

Parameters

structpci_dev*dev

pci device struct

Description

Same as pci_cfg_access_lock, but will return 0 if access isalready locked, 1 otherwise. This function can be used fromatomic contexts.

voidpci_cfg_access_unlock(struct pci_dev * dev)¶

Unlock PCI config reads/writes

Parameters

structpci_dev*dev

pci device struct

Description

This function allows PCI config accesses to resume.

enum pci_lost_interrupt_reasonpci_lost_interrupt(struct pci_dev * pdev)¶

reports a lost PCI interrupt

Parameters

structpci_dev*pdev

device whose interrupt is lost

Description

The primary function of this routine is to report a lost interruptin a standard way which users can recognise (instead of blaming thedriver).

Return

a suggestion for fixing it (although the driver is not required toact on this).

intpci_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

structpci_dev*dev

PCI device to operate on

unsignedintnr

device-relative interrupt vector index (0-based).

irq_handler_thandler

Function to be called when the IRQ occurs.Primary handler for threaded interrupts.If NULL and thread_fn != NULL the default primary handler isinstalled.

irq_handler_tthread_fn

Function called from the IRQ handler threadIf NULL, no IRQ thread is created

void*dev_id

Cookie passed back to the handler function

constchar*fmt

Printf-like format string naming the handler

...

variable arguments

Description

This call allocates interrupt resources and enables the interrupt line andIRQ handling. From the point this call is madehandler andthread_fn maybe invoked. All interrupts requested using this function might be shared.

dev_id must not be NULL and must be globally unique.

voidpci_free_irq(struct pci_dev * dev, unsigned int nr, void * dev_id)¶

free an interrupt allocated with pci_request_irq

Parameters

structpci_dev*dev

PCI device to operate on

unsignedintnr

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 interruptline is no longer in use by any driver it is disabled. The caller mustensure the interrupt is disabled on the device before calling this function.The function does not return until any executing interrupts for this IRQhave completed.

This function must not be called from interrupt context.

boolpcie_relaxed_ordering_enabled(struct pci_dev * dev)¶

Probe for PCIe relaxed ordering enable

Parameters

structpci_dev*dev

PCI device to query

Description

Returns true if the device has enabled relaxed ordering attribute.

intpci_scan_slot(struct pci_bus * bus, int devfn)¶

Scan a PCI slot on a bus for devices

Parameters

structpci_bus*bus

PCI bus to scan

intdevfn

slot number to scan (must have zero function)

Description

Scan a PCI slot on the specified PCI bus for devices, addingdiscovered devices to thebus->devices list. New deviceswill not have is_added set.

Returns the number of new devices found.

unsigned intpci_scan_child_bus(struct pci_bus * bus)¶

Scan devices below a bus

Parameters

structpci_bus*bus

Bus to scan for devices

Description

Scans devices belowbus including subordinate buses. Returns newsubordinate number including all the found devices.

unsigned intpci_rescan_bus(struct pci_bus * bus)¶

Scan a PCI bus for devices

Parameters

structpci_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

structpci_bus*parent

struct pci_bus of parent bridge

intslot_nr

PCI_SLOT(pci_dev->devfn) or -1 for placeholder

constchar*name

user visible string presented in /sys/bus/pci/slots/<name>

structhotplug_slot*hotplug

set if caller is hotplug driver, NULL otherwise

Description

PCI slots have first class attributes such as address, speed, width,and astructpci_slot is used to manage them. This interface willeither return a newstructpci_slot to the caller, or if the pci_slotalready exists, its refcount will be incremented.

Slots are uniquely identified by apci_bus,slot_nr tuple.

There are known platforms with broken firmware that assign the samename to multiple slots. Workaround these broken platforms by renamingthe slots on behalf of the caller. If firmware assigns name N tomultiple slots:

The first slot is assigned NThe second slot is assigned N-1The third slot is assigned N-2etc.

Placeholder slots:In most cases,pci_bus,slot_nr will be sufficient to uniquely identifya slot. There is one notable exception - pSeries (rpaphp), where theslot_nr cannot be determined until a device is actually inserted intothe slot. In this scenario, the caller may pass -1 forslot_nr.

The following semantics are imposed when the caller passesslot_nr ==-1. First, we no longer check for an existingstruct pci_slot, as theremay be many slots withslot_nr of -1. The other change in semantics isuser-visible, which is the ‘address’ parameter presented in sysfs willconsist solely of a dddd:bb tuple, where dddd is the PCI domain of thestruct pci_bus and bb is the bus number. In other words, the devfn ofthe ‘placeholder’ slot will not be displayed.

voidpci_destroy_slot(struct pci_slot * slot)¶

decrement refcount for physical PCI slot

Parameters

structpci_slot*slot

struct pci_slot to decrement

Description

struct pci_slot is refcounted, so destroying them is really easy; wejust call kobject_put on its kobj and let our release methods do therest.

voidpci_hp_create_module_link(struct pci_slot * pci_slot)¶

create symbolic link to the hotplug driver module.

Parameters

structpci_slot*pci_slot

struct pci_slot

Description

Helper function for pci_hotplug_core.c to create symbolic link tothe hotplug driver module.

voidpci_hp_remove_module_link(struct pci_slot * pci_slot)¶

remove symbolic link to the hotplug driver module.

Parameters

structpci_slot*pci_slot

struct pci_slot

Description

Helper function for pci_hotplug_core.c to remove symbolic link tothe hotplug driver module.

intpci_enable_rom(struct pci_dev * pdev)¶

enable ROM decoding for a PCI device

Parameters

structpci_dev*pdev

PCI device to enable

Description

Enable ROM decoding ondev. This involves simply turning on the lastbit of the PCI ROM BAR. Note that some cards may share address decodersbetween the ROM and other resources, so enabling it may disable accessto MMIO registers or other card memory.

voidpci_disable_rom(struct pci_dev * pdev)¶

disable ROM decoding for a PCI device

Parameters

structpci_dev*pdev

PCI device to disable

Description

Disable ROM decoding on a PCI device by turning off the last bit in theROM BAR.

void __iomem *pci_map_rom(struct pci_dev * pdev, size_t * size)¶

map a PCI ROM to kernel space

Parameters

structpci_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 theactual ROM.

voidpci_unmap_rom(struct pci_dev * pdev, void __iomem * rom)¶

unmap the ROM from kernel space

Parameters

structpci_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

intpci_enable_sriov(struct pci_dev * dev, int nr_virtfn)¶

enable the SR-IOV capability

Parameters

structpci_dev*dev

the PCI device

intnr_virtfn

number of virtual functions to enable

Description

Returns 0 on success, or negative on failure.

voidpci_disable_sriov(struct pci_dev * dev)¶

disable the SR-IOV capability

Parameters

structpci_dev*dev

the PCI device

intpci_num_vf(struct pci_dev * dev)¶

return number of VFs associated with a PF device_release_driver

Parameters

structpci_dev*dev

the PCI device

Description

Returns number of VFs, or 0 if SR-IOV is not enabled.

intpci_vfs_assigned(struct pci_dev * dev)¶

returns number of VFs are assigned to a guest

Parameters

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

intpci_sriov_set_totalvfs(struct pci_dev * dev, u16 numvfs)¶

• reduce the TotalVFs available

Parameters

structpci_dev*dev

the PCI PF device

u16numvfs

number that should be used for TotalVFs supported

Description

Should be called from PF driver’s probe routine withdevice’s mutex held.

Returns 0 if PF is an SRIOV-capable device andvalue of numvfs valid. If not a PF return -ENOSYS;if numvfs is invalid return -EINVAL;if VFs already enabled, return -EBUSY.

intpci_sriov_get_totalvfs(struct pci_dev * dev)¶

• get total VFs supported on this device

Parameters

structpci_dev*dev

the PCI PF device

Description

For a PCIe device with SRIOV support, return the PCIeSRIOV capability value of TotalVFs or the value of driver_max_VFsif the driver reduced it. Otherwise 0.

intpci_sriov_configure_simple(struct pci_dev * dev, int nr_virtfn)¶

helper to configure SR-IOV

Parameters

structpci_dev*dev

the PCI device

intnr_virtfn

number of virtual functions to enable, 0 to disable

Description

Enable or disable SR-IOV for devices that don’t require any PF setupbefore enabling SR-IOV. Return value is negative on error, or number ofVFs allocated on success.

ssize_tpci_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

structfile*filp

open sysfs file

structkobject*kobj

kobject corresponding to file to read from

structbin_attribute*bin_attr

struct bin_attribute for this file

char*buf

buffer to store results

loff_toff

offset into legacy I/O port space

size_tcount

number of bytes to read

Description

Reads 1, 2, or 4 bytes from legacy I/O port space using an arch specificcallback routine (pci_legacy_read).

ssize_tpci_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

structfile*filp

open sysfs file

structkobject*kobj

kobject corresponding to file to read from

structbin_attribute*bin_attr

struct bin_attribute for this file

char*buf

buffer containing value to be written

loff_toff

offset into legacy I/O port space

size_tcount

number of bytes to write

Description

Writes 1, 2, or 4 bytes from legacy I/O port space using an arch specificcallback routine (pci_legacy_write).

intpci_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

structfile*filp

open sysfs file

structkobject*kobj

kobject corresponding to device to be mapped

structbin_attribute*attr

struct bin_attribute for this file

structvm_area_struct*vma

struct vm_area_struct passed to mmap

Description

Uses an arch specific callback, pci_mmap_legacy_mem_page_range, to mmaplegacy memory space (first meg of bus space) into application virtualmemory space.

intpci_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

structfile*filp

open sysfs file

structkobject*kobj

kobject corresponding to device to be mapped

structbin_attribute*attr

struct bin_attribute for this file

structvm_area_struct*vma

struct vm_area_struct passed to mmap

Description

Uses an arch specific callback, pci_mmap_legacy_io_page_range, to mmaplegacy IO space (first meg of bus space) into application virtualmemory space. Returns -ENOSYS if the operation isn’t supported

voidpci_adjust_legacy_attr(struct pci_bus * b, enum pci_mmap_state mmap_type)¶

adjustment of legacy file attributes

Parameters

structpci_bus*b

bus to create files under

enumpci_mmap_statemmap_type

I/O port or memory

Description

Stub implementation. Can be overridden by arch if necessary.

voidpci_create_legacy_files(struct pci_bus * b)¶

create legacy I/O port and memory files

Parameters

structpci_bus*b

bus to create files under

Description

Some platforms allow access to legacy I/O port and ISA memory space ona per-bus basis. This routine creates the files and ties them intotheir associated read, write and mmap files from pci-sysfs.c

On error unwind, but don’t propagate the error to the calleras it is ok to set up the PCI bus without these files.

intpci_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

structkobject*kobj

kobject for mapping

structbin_attribute*attr

struct bin_attribute for the file being mapped

structvm_area_struct*vma

struct vm_area_struct passed into the mmap

intwrite_combine

1 for write_combine mapping

Description

Use the regular PCI mapping routines to map a PCI resource into userspace.

voidpci_remove_resource_files(struct pci_dev * pdev)¶

cleanup resource files

Parameters

structpci_dev*pdev

dev to cleanup

Description

If we created resource files forpdev, remove them from sysfs andfree their resources.

intpci_create_resource_files(struct pci_dev * pdev)¶

create resource files in sysfs fordev

Parameters

structpci_dev*pdev

dev in question

Description

Walk the resources inpdev creating files for each resource available.

ssize_tpci_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

structfile*filp

sysfs file

structkobject*kobj

kernel object handle

structbin_attribute*bin_attr

struct bin_attribute for this file

char*buf

user input

loff_toff

file offset

size_tcount

number of byte in input

Description

writing anything except 0 enables it

ssize_tpci_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

structfile*filp

sysfs file

structkobject*kobj

kernel object handle

structbin_attribute*bin_attr

struct bin_attribute for this file

char*buf

where to put the data we read from the ROM

loff_toff

file offset

size_tcount

number of bytes to read

Description

Putcount bytes starting atoff intobuf from the ROM in the PCIdevice corresponding tokobj.

voidpci_remove_sysfs_dev_files(struct pci_dev * pdev)¶

cleanup PCI specific sysfs files

Parameters

structpci_dev*pdev

device whose entries we should free

Description

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

structhotplug_slot*slot

pointer to thestructhotplug_slot to register

structpci_bus*bus

bus this slot is on

intdevnr

device number

constchar*name

name registered with kobject core

structmodule*owner

caller module owner

constchar*mod_name

caller module name

Description

Prepares a hotplug slot for in-kernel use and immediately publishes it touser space in one go. Drivers may alternatively carry out the two stepsseparately by invoking pci_hp_initialize() andpci_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

structhotplug_slot*slot

pointer to thestructhotplug_slot to initialize

structpci_bus*bus

bus this slot is on

intdevnr

slot number

constchar*name

name registered with kobject core

structmodule*owner

caller module owner

constchar*mod_name

caller module name

Description

Allocate and fill in a PCI slot for use by a hotplug driver. Once this hasbeen called, the driver may invoke hotplug_slot_name() to get the slot’sunique name. The driver must be prepared to handle a ->reset_slot callbackfrom this point on.

Returns 0 on success or a negative int on error.

intpci_hp_add(struct hotplug_slot * slot)¶

publish hotplug slot to user space

Parameters

structhotplug_slot*slot

pointer to thestructhotplug_slot to publish

Description

Make a hotplug slot’s sysfs interface available and inform user space of itsaddition by sending a uevent. The hotplug driver must be prepared to handleallstructhotplug_slot_ops callbacks from this point on.

Returns 0 on success or a negative int on error.

voidpci_hp_deregister(struct hotplug_slot * slot)¶

deregister a hotplug_slot with the PCI hotplug subsystem

Parameters

structhotplug_slot*slot

pointer to thestructhotplug_slot to deregister

Description

Theslot must have been registered with the pci hotplug subsystempreviously with a call to pci_hp_register().

Returns 0 if successful, anything else for an error.

voidpci_hp_del(struct hotplug_slot * slot)¶

unpublish hotplug slot from user space

Parameters

structhotplug_slot*slot

pointer to thestructhotplug_slot to unpublish

Description

Remove a hotplug slot’s sysfs interface.

Returns 0 on success or a negative int on error.

voidpci_hp_destroy(struct hotplug_slot * slot)¶

remove hotplug slot from in-kernel use

Parameters

structhotplug_slot*slot

pointer to thestructhotplug_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’sunique name. The driver no longer needs to handle a ->reset_slot callbackfrom this point on.

Returns 0 on success or a negative int on error.