pci_device_cfg_cap_disable(), pci_device_cfg_cap

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:

a reqType of pci_reqType_e_MANDATORY causes pci_device_cfg_cap_enable() to fail if the desired number of IRQs couldn't be allocated for the device
a reqType of either pci_reqType_e_ADVISORY or pci_reqType_e_UNSPECIFIED wouldn't

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