pci_device_cfg_cap_disable(), pci_device_cfg_cap_enable()

Updated: May 06, 2022

Enable or disable a capability

Synopsis:

#include <pci/pci.h>

pci_err_t pci_device_cfg_cap_disable( pci_devhdl_t hdl,
                                      pci_reqType_t reqType,
                                      pci_cap_t cap);

pci_err_t pci_device_cfg_cap_enable( pci_devhdl_t hdl,
                                     pci_reqType_t reqType,
                                     pci_cap_t cap);

Arguments:

hdl
The handle of the device, obtained by calling pci_device_attach().
reqType
The desired level of compliance to the request; one of:
  • pci_reqType_e_MANDATORY — the request must be satisfied with the requested constraints, or the request fails.
  • pci_reqType_e_ADVISORY — every attempt should be made to meet the request constraints, but if that isn't possible, the call doesn't fail.
  • pci_reqType_e_UNSPECIFIED — the request constraints aren't specified. The PCI server is free to choose any request constraints.
cap
A pointer to a capability structure.

Library:

libpci

Use the -l pci option to qcc to link against this library.

Description:

These functions enable or disable the capability identified by cap for the device identified by hdl. You must have already attached to the device by successfully calling pci_device_attach(). You can obtain the device capability by calling pci_device_read_cap().

After calling pci_device_read_cap() and before calling pci_device_cfg_cap_enable(), you might be able to modify the capability, using capability-specific APIs. See the specific capability module for details.

The reqType argument indicates the desired level of compliance to the request:

When you're: Use:
Enabling a capability pci_reqType_e_MANDATORY, pci_reqType_e_ADVISORY, or pci_reqType_e_UNSPECIFIED
Disabling a capability pci_reqType_e_UNSPECIFIED, unless the specific capability module specifies otherwise

For example, if you're enabling the MSI or MSI-X capability, you can select the desired number of IRQs to use by calling the capability-specific APIs for MSI or MSI-X. When you're enabling the capability for the device:

For an explanation of the difference between pci_reqType_e_ADVISORY and pci_reqType_e_UNSPECIFIED, see Capability ID 0x5 (MSI) and Capability ID 0x11 (MSI-X) in the Capability Modules and APIs appendix.

Note: If you need to change a capability's parameters, you must disable it, make the changes, and then reenable the capability.

Returns:

PCI_ERR_OK
The capability was successfully enabled or disabled.
PCI_ERR_EALREADY
The capability identified by cap is already enabled/disabled.
PCI_ERR_ENOTSUP
The capability can't be disabled.
PCI_ERR_EINVAL
The hdl doesn't refer to a device that you attached to, or some other parameter is otherwise invalid.
PCI_ERR_ENODEV
The device identified by hdl doesn't exist. Note that this error can also be returned if a device that supports live removal is removed after a successful call to pci_device_find().
PCI_ERR_NOT_OWNER
You don't own the device associated with hdl.

These functions can also return any of the errors documented for the specific capability being enabled or disabled.

The following internal errors are specifically related to internal resource availability and use, and are atypical:

PCI_ERR_ENOMEM
Memory for internal resources couldn't be obtained. This may be a temporary condition.
PCI_ERR_LOCK_FAILURE
An error occurred that's related to the creation, acquisition, or use of a synchronization object.

If any error occurs, the capability for the device isn't changed.

Classification:

QNX Neutrino

Safety:  
Cancellation point No
Interrupt handler No
Signal handler No
Thread Yes

See also:

pci_device_cfg_cap_isenabled()