usr/src/man/man9f/ddi_regs_map_setup.9f

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH DDI_REGS_MAP_SETUP 9F "Nov 18, 2004"
   7 .SH NAME
   8 ddi_regs_map_setup \- set up a mapping for a register address space
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \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,
  18      \fBoffset_t\fR \fIoffset\fR, \fBoffset_t\fR \fIlen\fR, \fBddi_device_acc_attr_t\fR \fI*accattrp\fR,
  19      \fBddi_acc_handle_t\fR \fI*handlep\fR);
  20 .fi
  21
  22 .SH INTERFACE LEVEL
  23 .sp
  24 .LP
  25 Solaris \fBDDI\fR specific (Solaris \fBDDI\fR).
  26 .SH PARAMETERS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIdip\fR\fR
  31 .ad
  32 .RS 12n
  33 Pointer to the device's \fBdev_info\fR structure.
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIrnumber\fR\fR
  40 .ad
  41 .RS 12n
  42 Index number to the register address space set.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIaddrp\fR\fR
  49 .ad
  50 .RS 12n
  51 A platform-dependent value that, when added to an offset that is less than or
  52 equal to the \fIlen\fR parameter (see below), is used for the \fBdev_addr\fR
  53 argument to the \fBddi_get\fR, \fBddi_mem_get\fR, and
  54 \fBddi_io_get\fR/\fBput\fR routines.
  55 .RE
  56
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fIoffset\fR\fR
  61 .ad
  62 .RS 12n
  63 Offset into the register address space.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIlen\fR\fR
  70 .ad
  71 .RS 12n
  72 Length to be mapped.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fIaccattrp\fR\fR
  79 .ad
  80 .RS 12n
  81 Pointer to a device access attribute structure of this mapping (see
  82 \fBddi_device_acc_attr\fR(9S)).
  83 .RE
  84
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fIhandlep\fR\fR
  89 .ad
  90 .RS 12n
  91 Pointer to a data access handle.
  92 .RE
  93
  94 .SH DESCRIPTION
  95 .sp
  96 .LP
  97 \fBddi_regs_map_setup()\fR maps in the register set given by \fIrnumber\fR. The
  98 register number determines which register set is mapped if more than one
  99 exists.
 100 .sp
 101 .LP
 102 \fIoffset\fR specifies the starting location within the register space and
 103 \fIlen\fR indicates the size of the area to be mapped. If  \fIlen\fR is
 104 non-zero, it overrides the length given in the register set description. If
 105 both \fIlen\fR and  \fIoffset\fR are \fB0\fR, the entire space is mapped. The
 106 base of the mapped register space is returned in  \fIaddrp\fR.
 107 .sp
 108 .LP
 109 The device access attributes are specified in the location pointed by the
 110 \fIaccattrp\fR argument (see  \fBddi_device_acc_attr\fR(9S) for details).
 111 .sp
 112 .LP
 113 The data access handle is returned in  \fIhandlep\fR. \fIhandlep\fR is opaque;
 114 drivers should not attempt to interpret its value. The handle is used by the
 115 system to encode information for subsequent data access function calls to
 116 maintain a consistent view between the host and the device.
 117 .SH RETURN VALUES
 118 .sp
 119 .LP
 120 \fBddi_regs_map_setup()\fR returns:
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBDDI_SUCCESS\fR\fR
 125 .ad
 126 .RS 25n
 127 Successfully set up the mapping for data access.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBDDI_FAILURE\fR\fR
 134 .ad
 135 .RS 25n
 136 Invalid register number \fIrnumber\fR, offset \fIoffset\fR, or length
 137 \fIlen\fR.
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fBDDI_ME_RNUMBER_RANGE\fR\fR
 144 .ad
 145 .RS 25n
 146 Invalid register number \fIrnumber\fR or unable to find \fIreg\fR property.
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBDDI_REGS_ACC_CONFLICT\fR\fR
 153 .ad
 154 .RS 25n
 155 Cannot enable the register mapping due to access conflicts with other enabled
 156 mappings.
 157 .RE
 158
 159 .sp
 160 .LP
 161 Note that the return value \fBDDI_ME_RNUMBER_RANGE\fR is not supported on all
 162 platforms. Also, there is potential overlap between \fBDDI_ME_RNUMBER_RANGE\fR
 163 and \fBDDI_FAILURE\fR. Drivers should check for \fB!=DDI_SUCCESS\fR rather than
 164 checking for a specific failure value.
 165 .SH CONTEXT
 166 .sp
 167 .LP
 168 \fBddi_regs_map_setup()\fR must be called from user or kernel context.
 169 .SH ATTRIBUTES
 170 .sp
 171 .LP
 172 See \fBattributes\fR(5) for descriptions of the following attributes:
 173 .sp
 174
 175 .sp
 176 .TS
 177 box;
 178 c | c
 179 l | l .
 180 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 181 _
 182 Architecture    PCI Local Bus, SBus, ISA
 183 .TE
 184
 185 .SH SEE ALSO
 186 .sp
 187 .LP
 188 \fBattributes\fR(5), \fBddi_regs_map_free\fR(9F), \fBddi_device_acc_attr\fR(9S)
 189 .sp
 190 .LP
 191 \fIWriting Device Drivers\fR