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

See also:

pci_device_detach()