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_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:
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
-
int
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.
-
int
pci_find_next_ext_capability
(struct pci_dev * dev, int start, int cap)¶ Find an extended capability
Parameters
struct pci_dev * dev
- PCI device to query
int 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.
-
int
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:
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
-
int
pci_find_next_ht_capability
(struct pci_dev * dev, int pos, int ht_cap)¶ query a device’s Hypertransport capabilities
Parameters
struct pci_dev * dev
- PCI device to query
int 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.
-
int
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.
-
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.
-
struct pci_dev *
pci_find_pcie_root_port
(struct pci_dev * dev)¶ return PCIe Root Port
Parameters
struct pci_dev * dev
- PCI device to query
Description
Traverse up the parent chain and return the PCIe Root Port PCI Device for a given PCI Device.
-
int
__pci_complete_power_transition
(struct pci_dev * dev, pci_power_t state)¶ Complete power transition of a PCI device
Parameters
struct pci_dev * dev
- PCI device to handle.
pci_power_t state
- State to put the device into.
Description
This function should not be called directly by device drivers.
-
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 device already is in the requested state. 0 if device’s power state has been successfully changed.
-
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
- PCI device to be suspended
pm_message_t state
- target sleep state for the whole system. This is the value
that is passed to
suspend()
function.
Description
Returns PCI power state suitable for given device and given system message.
-
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
Description
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 * dev, pci_power_t state, bool enable)¶ enable PCI device as wakeup event source
Parameters
struct pci_dev * dev
- PCI device affected
pci_power_t state
- PCI state from which device will issue wakeup events
bool enable
- True to enable event generation; false to disable
Description
This enables the device as a wakeup event source, or disables it. When such events involves platform-specific hooks, those hooks are called automatically by this routine.
Devices with legacy power management (no standard PCI PM capabilities) always require such platform hooks.
RETURN VALUE: 0 is returned on success -EINVAL is returned if device is not supposed to wake up the system Error code depending on the platform is returned if both the platform and the native mechanism fail to enable the generation of wake-up events
-
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 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.
-
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.
-
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.
-
int
pci_request_region_exclusive
(struct pci_dev * pdev, int bar, const char * res_name)¶ Reserved 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 BR 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.The key difference that _exclusive makes it that userspace is explicitly not allowed to map the resource via /dev/mem or sysfs.
-
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)¶ Reserved 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)¶ Reserved PCI I/O and memory resources
Parameters
struct pci_dev * pdev
- PCI device whose resources are to be reserved
const char * res_name
- Name to be associated with resource.
Description
Mark all PCI regions associated with PCI device pdev as being reserved by owner res_name. Do not access any address inside the PCI regions unless this call returns successfully.
pci_request_regions_exclusive()
will mark the region so that /dev/mem and the sysfs MMIO access will not be allowed.Returns 0 on success, or
EBUSY
on error. A warning message is also printed on failure.
-
int
pci_remap_iospace
(const struct resource * res, phys_addr_t phys_addr)¶ Remap the memory mapped I/O space
Parameters
const struct resource * res
- Resource describing the I/O space
phys_addr_t phys_addr
- physical address of range to be mapped
Description
Remap the memory mapped I/O space described by the res and the CPU physical address phys_addr into virtual address space. Only architectures that have memory mapped IO functions defined (and the PCI_IOBASE value defined) should call this function.
-
void
pci_unmap_iospace
(struct resource * res)¶ Unmap the memory mapped I/O space
Parameters
struct resource * res
- resource to be unmapped
Description
Unmap the CPU virtual address res from virtual address space. Only architectures that have memory mapped IO functions defined (and the PCI_IOBASE value defined) should call this function.
-
void __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
Helper function for pci_set_mwi. Originally copied from drivers/net/acenic.c. Copyright 1998-2001 by Jes Sorensen, <jes**trained**-monkey.org>.
Return
An appropriate -ERRNO error value on error, or zero for success.
-
int
pci_set_mwi
(struct pci_dev * dev)¶ enables memory-write-invalidate PCI transaction
Parameters
struct pci_dev * dev
- the PCI device for which MWI is enabled
Description
Enables the Memory-Write-Invalidate transaction in PCI_COMMAND
.
Return
An appropriate -ERRNO error value on error, or zero for success.
-
int
pci_try_set_mwi
(struct pci_dev * dev)¶ enables memory-write-invalidate PCI transaction
Parameters
struct pci_dev * dev
- the PCI device for which MWI is enabled
Description
Enables the Memory-Write-Invalidate transaction in PCI_COMMAND
.
Callers are not required to check the return value.
Return
An appropriate -ERRNO error value on error, or zero for success.
-
void
pci_clear_mwi
(struct pci_dev * dev)¶ disables Memory-Write-Invalidate for device dev
Parameters
struct pci_dev * dev
- the PCI device to disable
Description
Disables PCI Memory-Write-Invalidate transaction on the device
-
void
pci_intx
(struct pci_dev * pdev, int enable)¶ enables/disables PCI INTx for device dev
Parameters
struct pci_dev * pdev
- the PCI device to operate on
int enable
- boolean: whether to enable or disable PCI INTx
Description
Enables/disables PCI INTx for device dev
-
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)¶ waits for pending transaction
Parameters
struct pci_dev * dev
- the PCI device to operate on
Description
Return 0 if transaction is pending 1 otherwise.
-
void
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 on dev. The caller should ensure the
device supports FLR before calling this function, e.g. by using the
pcie_has_flr()
helper.
-
void
pci_reset_bridge_secondary_bus
(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
(struct pci_dev * dev)¶ 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.
The device function is presumed to be unused 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_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 in that it saves and restores device state over the reset.
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_reset_slot
(struct pci_slot * slot)¶ reset a PCI slot
Parameters
struct pci_slot * slot
- PCI slot to reset
Description
A PCI bus may host multiple slots, each slot may support a reset mechanism independent of other slots. For instance, some slots may support slot power control. In the case of a 1:1 bus to slot architecture, this function may wrap the bus reset to avoid spurious slot related events such as hotplug. Generally a slot reset should be attempted before a bus reset. All of the function of the slot and any subordinate buses behind the slot are reset through this function. PCI config space of all devices in the slot and behind the slot is saved before and restored after reset.
Return 0 on success, non-zero on error.
-
int
pci_try_reset_slot
(struct pci_slot * slot)¶ Try to reset a PCI slot
Parameters
struct pci_slot * slot
- PCI slot to reset
Description
Same as above except return -EAGAIN if the slot cannot be locked
-
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_bus * bus)¶ reset a PCI bus
Parameters
struct pci_bus * bus
- top level PCI bus to reset
Description
Do a bus reset on the given bus and any subordinate buses, saving and restoring state of all devices.
Return 0 on success, non-zero on error.
-
int
pci_try_reset_bus
(struct pci_bus * bus)¶ Try to reset a PCI bus
Parameters
struct pci_bus * bus
- top level PCI bus to reset
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 erratas 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
-
int
pcie_get_minimum_link
(struct pci_dev * dev, enum pci_bus_speed * speed, enum pcie_link_width * width)¶ determine minimum link settings of a PCI device
Parameters
struct pci_dev * dev
- PCI device to query
enum pci_bus_speed * speed
- storage for minimum speed
enum pcie_link_width * width
- storage for minimum width
Description
This function will walk up the PCI device chain and determine the minimum link width and speed of 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 present in the
system 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.
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, const 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
const 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).
-
int
pci_irq_get_node
(struct pci_dev * pdev, int vec)¶ return the numa node of a particular msi vector
Parameters
struct pci_dev * pdev
- PCI device to operate on
int vec
- 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 (*)(void *, const struct resource *, 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 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
-
ssize_t
pci_read_vpd
(struct pci_dev * dev, loff_t pos, size_t count, void * buf)¶ Read one entry from Vital Product Data
Parameters
struct pci_dev * dev
- pci device struct
loff_t pos
- offset in vpd space
size_t count
- number of bytes to read
void * buf
- pointer to where to store result
-
ssize_t
pci_write_vpd
(struct pci_dev * dev, loff_t pos, size_t count, const void * buf)¶ Write entry to Vital Product Data
Parameters
struct pci_dev * dev
- pci device struct
loff_t pos
- offset in vpd space
size_t count
- number of bytes to write
const void * buf
- buffer containing write data
-
int
pci_set_vpd_size
(struct pci_dev * dev, size_t len)¶ Set size of Vital Product Data space
Parameters
struct pci_dev * dev
- pci device struct
size_t len
- size of vpd space
-
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.
-
enum pci_lost_interrupt_reason
pci_lost_interrupt
(struct pci_dev * pdev)¶ reports a lost PCI interrupt
Parameters
struct pci_dev * pdev
- device whose interrupt is lost
Description
The primary function of this routine is to report a lost interrupt in a standard way which users can recognise (instead of blaming the driver).
Return
a suggestion for fixing it (although the driver is not required to act on this).
-
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.
-
int
__ht_create_irq
(struct pci_dev * dev, int idx, ht_irq_update_t * update)¶ create an irq and attach it to a device.
Parameters
struct pci_dev * dev
- The hypertransport device to find the irq capability on.
int idx
- Which of the possible irqs to attach to.
ht_irq_update_t * update
- Function to be called when changing the htirq message
Description
The irq number of the new irq or a negative error value is returned.
-
int
ht_create_irq
(struct pci_dev * dev, int idx)¶ create an irq and attach it to a device.
Parameters
struct pci_dev * dev
- The hypertransport device to find the irq capability on.
int idx
- Which of the possible irqs to attach to.
Description
ht_create_irq needs to be called for all hypertransport devices that generate irqs.
The irq number of the new irq or a negative error value is returned.
-
void
ht_destroy_irq
(unsigned int irq)¶ destroy an irq created with ht_create_irq
Parameters
unsigned int irq
- irq to be destroyed
Description
This reverses ht_create_irq removing the specified irq from existence. The irq should be free before this happens.
-
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_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, adds them, and enables 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 the 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
Map a PCI ROM into kernel space. If ROM is boot video ROM, the shadow BIOS copy will be returned instead of the actual ROM.
-
void
pci_unmap_rom
(struct pci_dev * pdev, void __iomem * rom)¶ unmap the ROM from kernel space
Parameters
struct pci_dev * pdev
- pointer to pci device struct
void __iomem * rom
- virtual address of the previous mapping
Description
Remove a mapping of a previously mapped ROM
-
void __iomem *
pci_platform_rom
(struct pci_dev * pdev, size_t * size)¶ provides a pointer to any ROM image provided by the platform
Parameters
struct pci_dev * pdev
- pointer to pci device struct
size_t * size
- pointer to receive size of pci window over 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.
-
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
Registers a hotplug slot with the pci hotplug subsystem, which will allow userspace interaction to the slot.
Returns 0 if successful, anything else for an error.
-
int
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.
-
int
pci_hp_change_slot_info
(struct hotplug_slot * slot, struct hotplug_slot_info * info)¶ changes the slot’s information structure in the core
Parameters
struct hotplug_slot * slot
- pointer to the slot whose info has changed
struct hotplug_slot_info * info
- pointer to the info copy into the slot’s info structure
Description
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.