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.

Parameters

structpci_dev*pdev

the PCI device

Description

Returns error bits set in PCI_STATUS and clears them.

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

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.

Parameters

structpci_dev*dev

PCI device to query

u16start

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.

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

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.

Parameters

structpci_dev*dev

PCI device to query

u8pos

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.

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.

Parameters

structpci_dev*dev

PCI device to query

u16vendor

Vendor ID for which capability is defined

intcap

Vendor-specific capability ID

Description

Ifdev has Vendor IDvendor, search for a VSEC capability withVSEC IDcap. If found, return the capability offset inconfig space; otherwise return 0.

Parameters

structpci_dev*dev

PCI device to query

u16vendor

Vendor ID to match for the DVSEC

u16dvsec

Designated Vendor-specific capability ID

Description

If DVSEC has Vendor IDvendor and DVSEC IDdvsec return the capabilityoffset in config space; otherwise return 0.

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.

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.

Parameters

structpci_dev*dev

PCI device to handle.

pci_power_tstate

State to put the device into.

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.

Parameters

structpci_dev*dev

PCI device that we’re dealing with

Parameters

structpci_dev*dev

PCI device that we’re dealing with

Parameters

structpci_dev*dev

PCI device that we’re dealing with

Description

Return NULL if no state or error.

Parameters

structpci_dev*dev

PCI device that we’re dealing with

structpci_saved_state*state

Saved state returned frompci_store_saved_state()

Parameters

structpci_dev*dev

PCI device that we’re dealing with

structpci_saved_state**state

Pointer to saved state returned frompci_store_saved_state()

Parameters

structpci_dev*dev

PCI device to be resumed

NOTE

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

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.

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

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

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.

Parameters

structpci_dev*dev

PCI device to handle.

pci_power_tstate

PCI state from which device will issue PME#.

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

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, checkdevice_may_wakeup() for the device before calling__pci_enable_wake() for it.

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.

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.

Parameters

structpci_dev*dev

Device to handle.

Description

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

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.

Parameters

structpci_dev*dev

Target PCI device.

pm_message_tstate

Target state for the whole system.

Description

Returns PCI power state suitable fordev andstate.

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.

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.

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.

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.

Parameters

structpci_dev*pdev

PCI device whose resources are to be reserved

intbar

BAR to be reserved

constchar*name

name of the driver requesting the resource

Return

0 on success, negative error code on failure.

Description

Mark the PCI region associated with PCI devicepdev BARbar as beingreserved by ownername. Do not access any address inside the PCI regionsunless this call returns successfully.

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

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.

Parameters

structpci_dev*pdev

PCI device whose resources are to be reserved

intbars

Bitmask of BARs to be requested

constchar*name

Name of the driver requesting the resources

Return

0 on success, negative error code on failure.

Parameters

structpci_dev*pdev

PCI device to request regions from

intbars

bit mask of BARs to request

constchar*name

name of the driver requesting the resources

Return

0 on success, negative error code on failure.

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.

Parameters

structpci_dev*pdev

PCI device whose resources are to be reserved

constchar*name

name of the driver requesting the resources

Description

Mark all PCI regions associated with PCI devicepdev as being reserved byownername. Do not access any address inside the PCI regions unless thiscall returns successfully.

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

Parameters

structpci_dev*pdev

PCI device whose resources are to be reserved

constchar*name

name of the driver requesting the resources

Return

0 on success, negative error code on failure.

Description

Mark all PCI regions associated with PCI devicepdev as being reservedby ownername. 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.

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.

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.

Parameters

structpci_dev*dev

the PCI device to enable

Description

Enables bus-mastering on the device and callspcibios_set_master()to do the needed arch specific settings.

Parameters

structpci_dev*dev

the PCI device to disable

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.

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.

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.

Parameters

structpci_dev*dev

the PCI device to disable

Description

Disables PCI Memory-Write-Invalidate transaction on the device

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

Parameters

structpci_dev*dev

the PCI device to operate on

Description

Return 0 if transaction is pending 1 otherwise.

Parameters

structpci_dev*dev

device to reset

Description

Initiate a function level reset unconditionally ondev withoutchecking any flags and DEVCAP

Parameters

structpci_dev*dev

device to reset

boolprobe

if true, return 0 if device can be reset this way

Description

Initiate a function level reset ondev.

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.

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.

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.

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.

Parameters

structpci_dev*dev

PCI device to reset

Description

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

Parameters

structpci_slot*slot

PCI slot to probe

Description

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

Parameters

structpci_bus*bus

PCI bus to probe

Description

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

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

Parameters

structpci_dev*dev

PCI device to query

Description

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

Parameters

structpci_dev*dev

PCI device to query

Description

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

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.

Parameters

structpci_dev*dev

PCI device to query

Description

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

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

Parameters

structpci_dev*dev

PCI device to query

Description

Returns maximum payload size in bytes

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

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.

Parameters

structpci_dev*dev

PCI device to query

Description

Query the PCI device speed capability.

Return

the maximum link speed supported by the device.

Parameters

structpci_dev*dev

PCI device to query

Description

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

Parameters

structpci_dev*dev

PCI device to query

Description

Report the available bandwidth at the device.

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.

Parameters

u32hint

desired domain, 0 if any ID in the range ofmin tomax is acceptable

u32min

minimum allowable domain

u32max

maximum allowable domain, no IDs higher than INT_MAX will be returned

Parameters

structpci_dev*dev

PCI device that owns the BAR

intbar

BAR number

unsignedlongoffset

map memory at the given offset in BAR

unsignedlongmaxlen

max length of the memory to map

Description

Using this function you will get a __iomem address to your device BAR.You can access it using ioread*() and iowrite*(). These functions hidethe details if this is a MMIO or PIO address space and will just do whatyou expect from them in the correct way.

maxlen specifies the maximum length to map. If you want to get access tothe complete BAR from offset to the end, pass0 here.

Parameters

structpci_dev*dev

PCI device that owns the BAR

intbar

BAR number

unsignedlongoffset

map memory at the given offset in BAR

unsignedlongmaxlen

max length of the memory to map

Description

Using this function you will get a __iomem address to your device BAR.You can access it using ioread*() and iowrite*(). These functions hidethe details if this is a MMIO or PIO address space and will just do whatyou expect from them in the correct way. When possible write combiningis used.

maxlen specifies the maximum length to map. If you want to get access tothe complete BAR from offset to the end, pass0 here.

Parameters

structpci_dev*dev

PCI device that owns the BAR

intbar

BAR number

unsignedlongmaxlen

length of the memory to map

Description

Using this function you will get a __iomem address to your device BAR.You can access it using ioread*() and iowrite*(). These functions hidethe details if this is a MMIO or PIO address space and will just do whatyou expect from them in the correct way.

maxlen specifies the maximum length to map. If you want to get access tothe complete BAR without checking for its length first, pass0 here.

Parameters

structpci_dev*dev

PCI device that owns the BAR

intbar

BAR number

unsignedlongmaxlen

length of the memory to map

Description

Using this function you will get a __iomem address to your device BAR.You can access it using ioread*() and iowrite*(). These functions hidethe details if this is a MMIO or PIO address space and will just do whatyou expect from them in the correct way. When possible write combiningis used.

maxlen specifies the maximum length to map. If you want to get access tothe complete BAR without checking for its length first, pass0 here.

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.

Parameters

structdevice*dev

Generic device to remap IO address for

resource_size_toffset

Resource address to map

resource_size_tsize

Size of map

Description

Managedpci_remap_cfgspace(). Map is automatically unmapped on driverdetach.

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 withpci_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 anIOMEM_ERR_PTR() encoded errorcode 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);

Parameters

structpci_dev*pdev

the PCI device for which MWI is enabled

Description

Managedpci_set_mwi().

Return

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

Parameters

structpci_dev*pdev

the PCI device to operate on

intenable

boolean: whether to enable or disable PCI INTx

Return

0 on success, -ENOMEM on error.

Description

Enable/disable PCI INTx for devicepdev.Restore the original state on driver detach.

Parameters

structpci_dev*pdev

PCI device to be initialized

Return

0 on success, negative error code on failure.

Description

Managedpci_enable_device(). Device will automatically be disabled ondriver detach.

Parameters

structpci_dev*pdev

PCI device to pin

Description

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

Parameters

structpci_dev*pdev

PCI device to access iomap table for

Return

Const pointer to array of __iomem pointers on success, NULL on failure.

Description

Access iomap allocation table fordev. If iomap table doesn’texist andpdev is managed, it will be allocated. All iomapsrecorded in the iomap table are automatically unmapped on driverdetach.

This function might sleep when the table is first allocated but canbe safely called without context and guaranteed to succeed onceallocated.

This function is DEPRECATED. Do not use it in new code. Instead, obtain amapping’s address directly from one of the pcim_* mapping functions. For

example

void __iomem *mappy = pcim_iomap(pdev, bar, length);

Parameters

structpci_dev*pdev

PCI device to iomap for

intbar

BAR to iomap

unsignedlongmaxlen

Maximum length of iomap

Return

__iomem pointer on success, NULL on failure.

Description

Managedpci_iomap(). Map is automatically unmapped on driver detach. Ifdesired, unmap manually only withpcim_iounmap().

This SHOULD only be used once per BAR.

NOTE

Contrary to the other pcim_* functions, this function does not return anIOMEM_ERR_PTR() on failure, but a simple NULL. This is done for backwardscompatibility.

Parameters

structpci_dev*pdev

PCI device to iounmap for

void__iomem*addr

Address to unmap

Description

Managedpci_iounmap().addr must have been mapped using a pcim_* mappingfunction.

Parameters

structpci_dev*pdev

PCI device to map IO resources for

intbar

Index of a BAR to map

constchar*name

Name of the driver requesting the resource

Return

__iomem pointer on success, an IOMEM_ERR_PTR on failure.

Description

Mapping and region will get automatically released on driver detach. Ifdesired, release manually only withpcim_iounmap_region().

Parameters

structpci_dev*pdev

PCI device to operate on

intbar

Index of BAR to unmap and release

Description

Unmap a BAR and release its region manually. Only pass BARs that werepreviously mapped bypcim_iomap_region().

Parameters

structpci_dev*pdev

PCI device to map IO resources for

intmask

Mask of BARs to request and iomap

constchar*name

Name of the driver requesting the resources

Return

0 on success, negative error code on failure.

Description

Request and iomap regions specified bymask.

This function is DEPRECATED. Do not use it in new code.Usepcim_iomap_region() instead.

Parameters

structpci_dev*pdev

PCI device to request region for

intbar

Index of BAR to request

constchar*name

Name of the driver requesting the resource

Return

0 on success, a negative error code on failure.

Description

Request region specified bybar.

The region will automatically be released on driver detach. If desired,release manually only withpcim_release_region().

Parameters

structpci_dev*pdev

PCI device to map IO resources for

constchar*name

name of the driver requesting the resources

Return

0 on success, negative error code on failure.

Description

Requested regions will automatically be released at driver detach. Ifdesired, release individual regions withpcim_release_region() or all ofthem at once withpcim_release_all_regions().

Parameters

structpci_dev*pdev

PCI device to map IO resources for

intbar

Index of the BAR

unsignedlongoffset

Offset from the begin of the BAR

unsignedlonglen

Length in bytes for the mapping

Return

__iomem pointer on success, an IOMEM_ERR_PTR on failure.

Description

Creates a new IO-Mapping within the specifiedbar, ranging fromoffset tooffset +len.

The mapping will automatically get unmapped on driver detach. If desired,release manually only withpcim_iounmap().

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.

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 is in its list ofsupported devices. Returns the matching pci_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.

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.

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

Parameters

conststructpci_dev*dev

the device to query

Description

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

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 intheirprobe() methods, when they bind to a device, and releasethem by callingpci_dev_put(), in theirdisconnect() methods.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

Parameters

unsignedintclass

search for a PCI device with this base class code

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 matching base class code, the reference count to the device isincremented. Seepci_match_one_device() to figure out how does this works.A new search is initiated by passingNULL as thefrom argument.Otherwise iffrom is notNULL, searches continue from next device on theglobal list. The reference count forfrom is always decremented if it isnotNULL.

Return

A pointer to a matched PCI device,NULL Otherwise.

Parameters

conststructpci_device_id*ids

A pointer to a null terminated list ofstructpci_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.

Parameters

structirq_data*data

pointer to irqdata associated to that interrupt

Parameters

structirq_data*data

pointer to irqdata associated to that interrupt

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.

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_alignfalignf

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.

Parameters

structpci_dev*dev

device to add

Description

This adds add sysfs entries and start device drivers

Parameters

conststructpci_bus*bus

bus to check for new devices

Description

Start driver for PCI devices and add some sysfs entries.

Parameters

structpci_bus*top

bus whose devices should be walked

int(*cb)(structpci_dev*,void*)

callback to be called for each device found

void*userdata

arbitrary pointer to be passed to callback

Description

Walk the given bus, including any bridged deviceson buses under this bus. Call the provided callbackon each device found.

We check the return ofcb each time. If it returns anythingother than 0, we break out.

Parameters

structpci_bus*top

bus whose devices should be walked

int(*cb)(structpci_dev*,void*)

callback to be called for each device found

void*userdata

arbitrary pointer to be passed to callback

Description

Same semantics aspci_walk_bus(), but walks the bus in reverse order.

Parameters

structpci_bus*bus

pci bus struct

structpci_ops*ops

new raw operations

Description

Return previous raw operations

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.

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.

Parameters

structpci_dev*dev

pci device struct

Description

This function allows PCI config accesses to resume.

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.

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.

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.

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.

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.

Parameters

structpci_dev*dev

PCI device to query

Description

Returns true if the device has enabled relaxed ordering attribute.

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.

Parameters

structpci_bus*bus

Bus to scan for devices

Description

Scans devices belowbus including subordinate buses. Returns newsubordinate number including all the found 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.

Parameters

structpci_bus*parent

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

Parameters

structpci_slot*slot

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

Parameters

u64bytes

size in bytes

Description

Convert size in bytes to encoded BAR Size in Resizable BAR Capability(PCIe r6.2, sec. 7.8.6.3).

Return

encoded BAR Size as defined in the PCIe spec (0=1MB, 31=128TB)

Parameters

intsize

encoded BAR Size as defined in the PCIe spec (0=1MB, 31=128TB)

Return

BAR size in bytes

Parameters

structpci_dev*pdev

PCI device

intbar

BAR to query

Description

Get the possible sizes of a resizable BAR as bitmask.

Return

A bitmask of possible sizes (bit 0=1MB, bit 31=128TB), or0 ifBAR isn’t resizable.

Parameters

structpci_dev*pdev

PCI device

intbar

BAR to check

intsize

encoded size as defined in the PCIe spec (0=1MB, 31=128TB)

Return

true ifbar is resizable andsize is supported, otherwisefalse.

Parameters

structpci_dev*pdev

PCI device

intbar

BAR to query

Description

Get the largest supported size of a resizable BAR as a size.

Return

the encoded maximum BAR size as defined in the PCIe spec(0=1MB, 31=128TB), or-NOENT on error.

Parameters

structpci_dev*dev

the PCI device

intresno

index of the BAR to be resized

intsize

new size as defined in the spec (0=1MB, 31=128TB)

intexclude_bars

a mask of BARs that should not be released

Description

Reconfigureresno tosize and re-run resource assignment algorithmwith the new size.

Prior to resize, releasedev resources that share a bridge window withresno. This unpins the bridge window resource to allow changing it.

The caller may prevent releasing a particular BAR by providingexclude_bars mask, but this may result in the resize operation failingdue to insufficient space.

Return

0 on success, or negative on error. In case of an error, theresources are restored to their original places.

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.

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.