pci_device_read_irq()

Updated: April 19, 2023

Get the IRQs associated with a device

Synopsis:

#include <pci/pci.h>

pci_err_t pci_device_read_irq( pci_devhdl_t hdl,
                               int_t *nirq,
                               pci_irq_t *irq );

Arguments:

hdl
The handle of the device, obtained by calling pci_device_attach().
nirq
NULL, or a pointer to a location for the number of IRQs.
irq
NULL, or an array of pci_irq_t entries.

Library:

libpci

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

Description:

The pci_device_read_irq() function gets the IRQs associated with a device. You must have already attached to the device by successfully calling pci_device_attach().

There could be multiple IRQs associated with a single device. In general, the irq parameter should point to an array of pci_irq_t types, and you should specify the number of entries the array in the value pointed to by nirq.

By modifying the parameters, you can control returned values as follows:

Otherwise, you should allocate space for an array of pci_irq_t items and set nirq to point to the number of items allocated. Upon successful return, nirq contains a value as follows:

If the device uses more than one IRQ, it is unspecified as to which device functionality is associated with which IRQ. IRQs are returned in the irq array in enabled interrupt source order. See also Capability ID 0x5 (MSI) and Capability ID 0x11 (MSI-X) in the Capability Modules and APIs appendix.

Because the IRQs for a device provide the ability to attach interrupt handlers, it's desirable to control access to this information. This function succeeds only if hdl identifies an attacher that owns the device. When you call pci_device_attach(), you can specify whether you want to be the owner of the device. Only the owner can successfully call pci_device_read_irq() and hence be able to attach interrupt service routines.

Returns:

PCI_ERR_OK
Success.
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_ENOTSUP
The device identified by hdl doesn't support interrupts or the type of interrupts being requested. Note that this is different from a return of PCI_ERR_OK with nirq pointing to the value 0.
PCI_ERR_EINVAL
The hdl doesn't refer to a valid device that you attached to, or other parameters are otherwise invalid.
PCI_ERR_NOT_OWNER
You aren't the owner of the device; see pci_device_attach().
PCI_ERR_IRQ_CFG
An invalid configuration for interrupt sources has been established in the device.
PCI_ERR_IRQ_NOT_AVAIL
There are no interrupt vectors available.
PCI_ERR_EIO
A device-specific error occurred.

If any error occurs, you should assume that the storage that you provided contains invalid data.

Classification:

QNX Neutrino

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