DDI_REGS_MAP_SETUP(9F) Kernel Functions for Drivers DDI_REGS_MAP_SETUP(9F)
NAME
ddi_regs_map_setup - set up a mapping for a register address space
SYNOPSIS
#include <sys/ddi.h>
#include <sys/sunddi.h>
int ddi_regs_map_setup(
dev_info_t *dip,
uint_t rnumber,
caddr_t *addrp,
offset_t offset,
offset_t len,
ddi_device_acc_attr_t *accattrp,
ddi_acc_handle_t *handlep);
INTERFACE LEVEL
illumos
DDI specific (illumos
DDI).
PARAMETERS
dip Pointer to the device's
dev_info structure.
rnumber Index of the desired tuple (0-based) in the register address
space set. See the
Register Numbers section for more
information.
addrp A platform-dependent value that, when added to an offset that
is less than or equal to the
len parameter (see below), is
used for the
dev_addr argument to the
ddi_get,
ddi_mem_get,
and
ddi_io_get/
put routines.
offset Offset into the register address space.
len Length to be mapped.
accattrp Pointer to a device access attribute structure of this
mapping (see
ddi_device_acc_attr(9S)).
handlep Pointer to a data access handle.
DESCRIPTION
ddi_regs_map_setup() maps in the register set given by
rnumber. The
register number determines which register set is mapped if more than one
exists.
offset specifies the starting location within the register space and
len indicates the size of the area to be mapped. If
len is non-zero, it
overrides the length given in the register set description. If both
len and
offset are
0, the entire space is mapped. The base of the mapped
register space is returned in
addrp.
The device access attributes are specified in the location pointed by the
accattrp argument (see
ddi_device_acc_attr(9S) for details).
The data access handle is returned in
handlep.
handlep is opaque;
drivers should not attempt to interpret its value. The handle is used by
the system to encode information for subsequent data access function
calls to maintain a consistent view between the host and the device.
Register Numbers
The
reg property is an array of tuples. The size of each tuple varies
based on the hardware device type. For example, PCI and PCI Express
devices have one size, while ISA devices have a different size. Each
tuple describes a register space that indicates a way to communicate with
the device. The
rnumber argument selects which of these to use.
For example, with PCI and PCI Express devices, the first base address
register (BAR) with a non-zero value is in
rnumber 1 because it is the
second tuple in the
reg property. The second BAR with a non-zero value
is in the third tuple (
rnumber 2).
For a full treatment of the meaning of the
reg property for PCI devices,
see
pci(5). For PCI express devices, see
pcie(5). For ISA devices, see
isa(5). For cardbus, see
cardbus(5). For SBus devices, see
sbus(5).
RETURN VALUES
ddi_regs_map_setup() returns:
DDI_SUCCESS Successfully set up the mapping for data access.
DDI_FAILURE Invalid register number
rnumber, offset
offset,
or length
len.
DDI_ME_RNUMBER_RANGE Invalid register number
rnumber or unable to
find
reg property.
DDI_REGS_ACC_CONFLICT Cannot enable the register mapping due to access
conflicts with other enabled mappings.
Note that the return value
DDI_ME_RNUMBER_RANGE is not supported on all
platforms. Also, there is potential overlap between
DDI_ME_RNUMBER_RANGE and
DDI_FAILURE. Drivers should check for
!=DDI_SUCCESS rather than
checking for a specific failure value.
CONTEXT
ddi_regs_map_setup() must be called from user or kernel context.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+---------------+--------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+--------------------------+
|Architecture | PCI Local Bus, SBus, ISA |
+---------------+--------------------------+
SEE ALSO
cardbus(5),
isa(5),
pci(5),
pcie(5),
sbus(5),
attributes(7),
ddi_regs_map_free(9F),
ddi_device_acc_attr(9S) Writing Device Drivers April 18, 2019
DDI_REGS_MAP_SETUP(9F)