pci_device_find()

Locate a device that matches the specified criteria

Synopsis:

#include <pci/pci.h>

pci_bdf_t pci_device_find( const uint_t idx,
                           const pci_vid_t vid,
                           const pci_did_t did,
                           const pci_ccode_t classcode );

Arguments:

idx: The zero-based index of a specific device that you want to find; see below.
vid: The vendor ID you want to match, or PCI_VID_ANY.
did: The device ID you want to match, or PCI_DID_ANY.
classcode: The class or subclass that you want to match, or PCI_CCODE_ANY.

Library:

libpci

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

Description:

The pci_device_find() function kets you locate a specific device by specifying any combination of the vendor ID vid, device ID did, and class (and subclass) code classcode filter parameters. Any parameter can be wild-carded by using PCI_VID_ANY, PCI_DID_ANY, or PCI_CCODE_ANY, respectively.

The class code is of type pci_ccode_t, which contains 3 bytes as defined in the PCI specification:

MSb                                        LSb
        0000 0000 CCCC CCCC cccc cccc rrrr rrrr

C - represents the base class
c - represents the sub class
r - represents a register level programming interface

To encode and decode the class code, you can use the macros defined in <pci/pci_ccode.h>, as well as the following macros, defined in <pci/pci.h>:

PCI_CCODE_CLASS(_cc_)
PCI_CCODE_SUBCLASS(_cc_)
PCI_CCODE_REG_IF(_cc_)
PCI_CCODE(_C_, _c_, _r_)

Wild cards for the subclass and register interface let you widen the search for class codes. You can use the following values independently or together for the subclass and register interface respectively when constructing a classcode to search for:

PCI_CCODE_SUBCLASS_ANY
PCI_CCODE_REG_IF_ANY

For example:

PCI_CCODE(base_class, PCI_CCODE_SUBCLASS_ANY, PCI_CCODE_REG_IF_ANY)
PCI_CCODE(base_class, subclass, PCI_CCODE_REG_IF_ANY)

You can find the defined vendor IDs in <pci/pci_id.h>. In addition, the idx parameter lets you select from multiple instances of devices meeting the search criteria. By calling pci_device_find() repeatedly with an incrementing idx value, you can find all instances of a device meeting the search criteria.

Note: The idx parameter has no association with a given device. It's used only as an instance token across multiple find calls when the search criteria don't change. The same device (as identified by the returned pci_bdf_t) could be identified for a different idx value if you use different search criteria. If you change the search criteria, reset the starting idx value to 0, or the function might return PCI_ERR_ENODEV.

The search criteria parameters allow the following filter combinations:

`vid`	`did`	`classcode`	Result
PCI_VID_ANY	PCI_DID_ANY	PCI_CCODE_ANY	All devices
PCI_VID_ANY	PCI_DID_ANY	A class code	All devices of a specified class
PCI_VID_ANY	A device ID	PCI_CCODE_ANY	All devices with a specific device ID
PCI_VID_ANY	A device ID	A class code	All devices of a specified class with a specific device ID
A vendor ID	PCI_DID_ANY	PCI_CCODE_ANY	All devices from a specific vendor
A vendor ID	PCI_DID_ANY	A class code	All devices of a specified class from a specific vendor
A vendor ID	A device ID	PCI_CCODE_ANY	All devices with a specific device ID from a specific vendor
A vendor ID	A device ID	A class code	All devices of a specified class with a specific device ID from a specific vendor

Returns:

A pci_bdf_t value that uniquely identifies a specific device and which you can use to attach to the device or to perform various read operations (see pci_device_read_*()), or PCI_BDF_NONE if a device couldn't be found based on the search criteria.

Classification:

QNX Neutrino

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