pci_device_attach()

Attach a device

Synopsis:

#include <pci/pci.h>

pci_devhdl_t pci_device_attach( pci_bdf_t bdf,
                                pci_attachFlags_t flags,
                                pci_err_t *err );

Arguments:

bdf: A unique identifier for the device you want to attach to. You can construct this value with the PCI_BDF() macro, but you more typically obtain it by calling pci_device_find().
flags: Flags that control the attachment; see below.
err: NULL, or a pointer to a location where the function can store an error code.

Library:

libpci

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

Description:

Device attachment is required in order to perform any configuration and/or write operations on a device. It's also required in order to obtain any address space (memory and I/O BAR) or interrupt information. This is to allow the attachment flags to provide access control only to software that requires this information. Attachment isn't required to read most other configuration space information. Any APIs that require a pci_devhdl_t must be attached to.

The flags parameter controls the way in which the attachment occurs as follows (see also <pci/pci.h>). You must specify one of the following bitwise-exclusive values:

pci_attachFlags_e_EXCLUSIVE: If this attachment is successful, don't allow any other caller to attach to the device.
pci_attachFlags_e_SHARED: Allow other callers to attach to the device.

You can also OR in any of the following bits:

pci_attachFlags_e_OWNER: Permit access to the address space and IRQ assignments. This flag is implied for pci_attachFlags_e_EXCLUSIVE. There can be only one owner unless you set pci_attachFlags_e_MULTI on the very first attachment that includes pci_attachFlags_e_OWNER.
pci_attachFlags_e_MULTI: If this flag is set on the first attachment with pci_attachFlags_e_OWNER set, then subsequent attachments are permitted with the pci_attachFlags_e_OWNER and pci_attachFlags_e_MULTI flags set.
If you don't set this flag on the first attachment that has pci_attachFlags_e_OWNER set, then subsequent attaches with pci_attachFlags_e_OWNER set are rejected regardless of the inclusion of pci_attachFlags_e_MULTI. That is, all multiply-owned attachers must set both the pci_attachFlags_e_OWNER and pci_attachFlags_e_MULTI flags. It's an error to set pci_attachFlags_e_MULTI with pci_attachFlags_e_EXCLUSIVE or without pci_attachFlags_e_OWNER.

The following combinations are also defined:

pci_attachFlags_OWNER = (pci_attachFlags_e_SHARED | pci_attachFlags_e_OWNER)
pci_attachFlags_MULTI_OWNER = (pci_attachFlags_e_SHARED | pci_attachFlags_e_OWNER |
                               pci_attachFlags_e_MULTI)
pci_attachFlags_EXCLUSIVE_OWNER = pci_attachFlags_e_EXCLUSIVE | pci_attachFlags_e_OWNER
pci_attachFlags_DEFAULT = pci_attachFlags_OWNER

Returns:

A handle of type pci_devhdl_t that you can use in subsequent calls to access the device, or NULL if an error occurred.

If err is non-NULL, then the reason for the failed attachment is provided as follows:

PCI_ERR_EINVAL: Invalid flags.
PCI_ERR_ENODEV: The bdf argument doesn't refer to a valid device.
PCI_ERR_ATTACH_EXCLUSIVE: The device identified by bdf is already exclusively owned.
PCI_ERR_ATTACH_SHARED: The request was for exclusive attachment, but the device identified by bdf has already been successfully attached to.
PCI_ERR_ATTACH_OWNED: The request was for ownership of the device, but the device is already owned.

The following error codes are specifically related to internal resource availability and use, and hence you aren't likely to see them:

PCI_ERR_ENOMEM: Memory for internal resources couldn't be obtained. This may be a temporary condition.
PCI_ERR_LOCK_FAILURE: There was an error related to the creation, acquisition, or use of a synchronization object.
PCI_ERR_ATTACH_LIMIT: There have been too many attachments to the device identified by bdf.

Classification:

QNX Neutrino

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