pci_device_read_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:

• To determine how many interrupts are associated with the device identified by hdl, pass NULL for irq. The function sets the variable pointed to by nirq to the number of supported/configured interrupts.
• If you're interested in only one IRQ, irq can be a pointer to a single pci_irq_t variable. In this case nirq can point to the value of 1, or nirq can be NULL.
  Note:

  If the device uses more than one IRQ and you request only one, an arbitrary interrupt is returned.

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 size of array specified by the value pointed to by nirq was large enough to hold all IRQs associated with the device, nirq contains a value less than or equal to the originally assigned value of nirq indicating the actual number of associated interrupts. Note that it is possible for this value to be zero.
• If the size of the array specified by the value pointed to by nirq wasn't large enough to hold all IRQs associated with the device, nirq contains a value that's the 2's complement of the number of IRQs that wouldn't fit into the allocated array.

  For example, if nirq contains the value of -2 upon successful return, all but two of the requested number of IRQs were successfully returned.

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 a thread or event to an interrupt source, 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 threads.

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 OS