'\" te
.\" Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved.
.TH ddi_regs_map_setup 9F "16 Dec 2011" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
ddi_regs_map_setup \- set up a mapping for a register address space
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>

\fBint\fR \fBddi_regs_map_setup\fR(\fBdev_info_t\fR \fI*dip\fR, \fBuint_t\fR \fIrnumber\fR, \fBcaddr_t\fR \fI*addrp\fR,
     \fBoffset_t\fR \fIoffset\fR, \fBoffset_t\fR \fIlen\fR, \fBddi_device_acc_attr_t\fR \fI*accattrp\fR, 
     \fBddi_acc_handle_t\fR \fI*handlep\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris \fBDDI\fR specific (Solaris \fBDDI\fR).
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 12n
.rt  
Pointer to the device's \fBdev_info\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIrnumber\fR\fR
.ad
.RS 12n
.rt  
Index number to the register address space set. A value of 0 indicates PCI configuration space, while a value of 1 indicates the real start of device register sets.
.RE

.sp
.ne 2
.mk
.na
\fB\fIaddrp\fR\fR
.ad
.RS 12n
.rt  
A platform-dependent value that, when added to an offset that is less than or equal to the \fIlen\fR parameter (see below), is used for the \fBdev_addr\fR argument to the \fBddi_get\fR, \fBddi_mem_get\fR, and \fBddi_io_get\fR/\fBput\fR routines.
.RE

.sp
.ne 2
.mk
.na
\fB\fIoffset\fR\fR
.ad
.RS 12n
.rt  
Offset into the register address space.
.RE

.sp
.ne 2
.mk
.na
\fB\fIlen\fR\fR
.ad
.RS 12n
.rt  
Length to be mapped.
.RE

.sp
.ne 2
.mk
.na
\fB\fIaccattrp\fR\fR
.ad
.RS 12n
.rt  
Pointer to a device access attribute structure of this mapping (see \fBddi_device_acc_attr\fR(9S)). 
.RE

.sp
.ne 2
.mk
.na
\fB\fIhandlep\fR\fR
.ad
.RS 12n
.rt  
Pointer to a data access handle.
.RE

.SH DESCRIPTION
.sp
.LP
\fBddi_regs_map_setup()\fR maps in the register set given by \fIrnumber\fR. The register number determines which register set is mapped if more than one exists.
.sp
.LP
\fIoffset\fR specifies the starting location within the register space and  \fIlen\fR indicates the size of the area to be mapped. If  \fIlen\fR is non-zero, it overrides the length given in the register set description. If both \fIlen\fR and  \fIoffset\fR are \fB0\fR, the entire space is mapped. The base of the mapped register space is returned in  \fIaddrp\fR. 
.sp
.LP
The device access attributes are specified in the location pointed by the  \fIaccattrp\fR argument (see  \fBddi_device_acc_attr\fR(9S) for details).
.sp
.LP
The data access handle is returned in  \fIhandlep\fR. \fIhandlep\fR 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.
.SH RETURN VALUES
.sp
.LP
\fBddi_regs_map_setup()\fR returns:
.sp
.ne 2
.mk
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 25n
.rt  
Successfully set up the mapping for data access.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 25n
.rt  
Invalid register number \fIrnumber\fR, offset \fIoffset\fR, or length \fIlen\fR. 
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_ME_RNUMBER_RANGE\fR\fR
.ad
.RS 25n
.rt  
Invalid register number \fIrnumber\fR or unable to find \fIreg\fR property.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_REGS_ACC_CONFLICT\fR\fR
.ad
.RS 25n
.rt  
Cannot enable the register mapping due to access conflicts with other enabled mappings.
.RE

.sp
.LP
Note that the return value \fBDDI_ME_RNUMBER_RANGE\fR is not supported on all platforms. Also, there is potential overlap between \fBDDI_ME_RNUMBER_RANGE\fR and \fBDDI_FAILURE\fR. Drivers should check for \fB!=DDI_SUCCESS\fR rather than checking for a specific failure value.
.SH CONTEXT
.sp
.LP
\fBddi_regs_map_setup()\fR must be called from user or kernel context.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
ArchitecturePCI Local Bus, SBus, ISA
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBddi_regs_map_free\fR(9F), \fBddi_device_acc_attr\fR(9S) 
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR