pci_device_read_ba()

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_ADVISORY — every attempt should be made to meet the request constraints, but if that isn't possible, the call doesn't fail.
  • 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:

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:

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