pci_device_read

Get the base addresses of a device

Synopsis:

#include <pci/pci.h>

pci_err_t pci_device_read_ba( pci_devhdl_t hdl,
                              int_t *nba,
                              pci_ba_t *ba,
                              pci_reqType_t reqType );

Arguments:

hdl

The handle of the device, obtained by calling pci_device_attach().

nba

A pointer to a location that can hold the number of entries in the ba array (see below).

ba

NULL, or an array of pci_ba_t structures where the function can store information about the device's supported address spaces (see below). For more information about this structure, see pci_device_map_as().

reqType

The desired level of compliance to the request; one of:

pci_reqType_e_MANDATORY — the request must be satisfied with the requested constraints, or the request fails.
pci_reqType_e_UNSPECIFIED — the request constraints aren't specified. The PCI server is free to choose any request constraints.

Library:

libpci

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

Description:

The pci_device_read_ba() function gets the base addresses for a device. You must have already attached to the device by successfully calling pci_device_attach().

PCI devices contain multiple BARs (Base Address Registers) that may be applicable to different address space types. To simplify the retrieval of the base address information, the pci_device_read_ba() function is provided. This function gets an array of pci_ba_t types that uniquely identify all of the supported address spaces of the device identified by hdl.

In general, the ba parameter should point to an array of pci_ba_t types, in which case you specify the number of entries in the array in the value pointed to by nba.

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

To determine how many valid base addresses the device uses, set ba to NULL and set the variable pointed to by nba to the maximum number of BARs. The number of implemented base addresses is returned in *nba.
Note: If you set the variable pointed to by nba to zero, pci_device_read_ba() returns PCI_ERR_OK but doesn't set *nba to the number of valid base addresses.
If you're interested in only one base address, ba can be a pointer to a single pci_ba_t variable. In this case, nba can point to the value of 1, or nba can be NULL. Note that in this case only the first implemented base address will be returned.

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

If the size of array specified by the value pointed to by nba was large enough to hold all implemented base addresses for the device, nba contains a value less than or equal to the originally assigned value of nba indicating the actual number of implemented base addresses. Note that this value can be zero.
If the size of the array specified by the value pointed to by nba wasn't large enough to hold all implemented base addresses for the device, nba contains a value that's the 2's complement of the number of base addresses that wouldn't fit into the allocated array.
For example, if nba contains the value of -2 upon successful return, all but two of the requested number of base addresses were successfully returned.

In all of the above cases, you should set the reqType argument to pci_reqType_e_UNSPECIFIED. Optionally, you can retrieve the address space information for a specific BAR or set of BARs. If you set reqType to pci_reqType_e_MANDATORY and initialize the ba.bar_num field for each of the *nba entries, the function returns only the address space information for the specified BAR or BARs. If you specify the same BAR number more than once, multiple identical entries are returned. If you specify an invalid BAR number, the entry is of type pci_asType_e_NONE.

Valid BAR numbers are from 0 through 5, inclusive. Use a BAR number of -1 to retrieve address space information for expansion ROMs. Note also, that if you specify pci_reqType_e_MANDATORY, *nba isn't updated to reflect the actual number of valid address spaces; it remains as you set it.

Because the base addresses for a device provide the location of memory mapped device registers, 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_ba() and hence be able to map and control the device.

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 isn't supported. Note that this is different from a return of PCI_ERR_OK with nba 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. This error can also be returned from the hardware-dependent module.
PCI_ERR_NOT_OWNER: You aren't the owner of the device; see pci_device_attach().
PCI_ERR_ASPACE_INVALID: The base addresses assigned to the device couldn't be translated into usable values for you. This is generally a hardware-dependent module error.
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