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

   1 '\" te
   2 .\"  Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
   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_SEGMAP 9F "Nov 17, 2003"
   7 .SH NAME
   8 ddi_segmap, ddi_segmap_setup \- set up a user mapping using seg_dev
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/conf.h>
  13 #include <sys/ddi.h>
  14 #include <sys/sunddi.h>
  15
  16
  17
  18 \fBint\fR \fBddi_segmap\fR(\fBdev_t\fR \fIdev\fR, \fBoff_t\fR \fIoffset\fR, \fBstruct as *\fR\fIasp\fR,
  19      \fBcaddr_t *\fR\fIaddrp\fR, \fBoff_t\fR \fIlen\fR, \fBuint_t\fR \fIprot\fR,
  20      \fBuint_t\fR \fImaxprot\fR, \fBuint_t\fR \fIflags\fR, \fBcred_t\fR \fI*credp\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBint\fR \fBddi_segmap_setup\fR(\fBdev_t\fR \fIdev\fR, \fBoff_t\fR \fIoffset\fR, \fBstruct as *\fR\fIasp\fR,
  26      \fBcaddr_t *\fR\fIaddrp\fR, \fBoff_t\fR \fIlen\fR, \fBuint_t\fR \fIprot\fR,
  27      \fBuint_t\fR \fImaxprot\fR, \fBuint_t\fR \fIflags\fR, \fBcred_t\fR \fI*credp\fR,
  28      \fBddi_device_acc_attr_t\fR \fI*accattrp\fR, \fBuint_t\fR \fIrnumber\fR);
  29 .fi
  30
  31 .SH INTERFACE LEVEL
  32 .sp
  33 .LP
  34 These interfaces are obsolete. See \fBdevmap\fR(9E) for an alternative to
  35 \fBddi_segmap()\fR. Use \fBdevmap_setup\fR(9F) instead of
  36 \fBddi_segmap_setup()\fR.
  37 .SH PARAMETERS
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fIdev\fR \fR
  42 .ad
  43 .RS 12n
  44 The device whose memory is to be mapped.
  45 .RE
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fIoffset\fR \fR
  51 .ad
  52 .RS 12n
  53 The offset within device memory at which the mapping begins.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fIasp\fR \fR
  60 .ad
  61 .RS 12n
  62 An opaque pointer to the user address space into which the device memory should
  63 be mapped.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIaddrp\fR \fR
  70 .ad
  71 .RS 12n
  72 Pointer to the starting address within the user address space to which the
  73 device memory should be mapped.
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fIlen\fR \fR
  80 .ad
  81 .RS 12n
  82 Length (in bytes) of the memory to be mapped.
  83 .RE
  84
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fIprot\fR \fR
  89 .ad
  90 .RS 12n
  91 A bit field that specifies the protections. Some combinations of possible
  92 settings are:
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fBPROT_READ\fR \fR
  97 .ad
  98 .RS 15n
  99 Read access is desired.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBPROT_WRITE\fR \fR
 106 .ad
 107 .RS 15n
 108 Write access is desired.
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBPROT_EXEC\fR \fR
 115 .ad
 116 .RS 15n
 117 Execute access is desired.
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fBPROT_USER\fR \fR
 124 .ad
 125 .RS 15n
 126 User-level access is desired (the mapping is being done as a result of a
 127 \fBmmap\fR(2) system call).
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBPROT_ALL\fR \fR
 134 .ad
 135 .RS 15n
 136 All access is desired.
 137 .RE
 138
 139 .RE
 140
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fImaxprot\fR \fR
 145 .ad
 146 .RS 12n
 147 Maximum protection flag possible for attempted mapping (the \fBPROT_WRITE\fR
 148 bit may be masked out if the user opened the special file read-only). If
 149 \fB(maxprot & prot) != prot\fR then there is an access violation.
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fIflags\fR \fR
 156 .ad
 157 .RS 12n
 158 Flags indicating type of mapping. Possible values are (other bits may be set):
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fBMAP_PRIVATE\fR \fR
 163 .ad
 164 .RS 16n
 165 Changes are private.
 166 .RE
 167
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBMAP_SHARED\fR \fR
 172 .ad
 173 .RS 16n
 174 Changes should be shared.
 175 .RE
 176
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBMAP_FIXED\fR \fR
 181 .ad
 182 .RS 16n
 183 The user specified an address in  \fI*addrp\fR rather than letting the system
 184 pick and address.
 185 .RE
 186
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fIcredp\fR \fR
 193 .ad
 194 .RS 12n
 195 Pointer to user credential structure.
 196 .RE
 197
 198 .SS "ddi_segmap_setup(\|)"
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fIdev_acc_attr\fR \fR
 203 .ad
 204 .RS 17n
 205 Pointer to a \fBddi_device_acc_attr\fR(9S) structure which contains the device
 206 access attributes to apply to this mapping.
 207 .RE
 208
 209 .sp
 210 .ne 2
 211 .na
 212 \fB\fIrnumber\fR \fR
 213 .ad
 214 .RS 17n
 215 Index number to the register address space set.
 216 .RE
 217
 218 .SH DESCRIPTION
 219 .sp
 220 .LP
 221 Future releases of Solaris will provide this function for binary  and source
 222 compatibility.  However, for increased functionality, use
 223 \fBddi_devmap_segmap\fR(9F) instead.  See  \fBddi_devmap_segmap\fR(9F) for
 224 details.
 225 .sp
 226 .LP
 227 \fBddi_segmap\fR(\|) and \fBddi_segmap_setup()\fR set up user mappings to
 228 device space. When setting up the mapping, the  \fBddi_segmap\fR(\|) and
 229 \fBddi_segmap_setup()\fR routines call the \fBmmap\fR(9E) entry point to
 230 validate the range to be mapped.  When a user process accesses the mapping, the
 231 drivers \fBmmap\fR(9E) entry point is again called to retrieve the page frame
 232 number that needs to be loaded.  The mapping translations for that page are
 233 then loaded on behalf of the driver by the DDI framework.
 234 .sp
 235 .LP
 236 \fBddi_segmap()\fR is typically used as the \fBsegmap\fR(9E) entry in the
 237 \fBcb_ops\fR(9S) structure for those devices that do not choose to provide
 238 their own  \fBsegmap\fR(9E) entry point. However, some drivers may have their
 239 own \fBsegmap\fR(9E) entry point to do some initial processing on the
 240 parameters and then call \fBddi_segmap()\fR to establish the default memory
 241 mapping.
 242 .sp
 243 .LP
 244 \fBddi_segmap_setup()\fR is used in the drivers \fBsegmap\fR(9E) entry point to
 245 set up the mapping and assign device access attributes to that mapping.
 246 \fIrnumber\fR specifies the register  set representing the range of device
 247 memory being mapped. See  \fBddi_device_acc_attr\fR(9S) for details regarding
 248 what device access attributes are available.
 249 .sp
 250 .LP
 251 \fBddi_segmap_setup()\fR cannot be used directly in the \fBcb_ops\fR(9S)
 252 structure and requires a driver to have a \fBsegmap\fR(9E) entry point.
 253 .SH RETURN VALUES
 254 .sp
 255 .LP
 256 \fBddi_segmap()\fR and \fBddi_segmap_setup()\fR return the following values:
 257 .sp
 258 .ne 2
 259 .na
 260 \fB\fB0\fR \fR
 261 .ad
 262 .RS 12n
 263 Successful completion.
 264 .RE
 265
 266 .sp
 267 .ne 2
 268 .na
 269 \fB\fBNon-zero\fR\fR
 270 .ad
 271 .RS 12n
 272 An error occurred. In particular, they return \fBENXIO\fR if the range to be
 273 mapped is invalid.
 274 .RE
 275
 276 .SH CONTEXT
 277 .sp
 278 .LP
 279 \fBddi_segmap()\fR and \fBddi_segmap_setup()\fR can be called from user or
 280 kernel context only.
 281 .SH ATTRIBUTES
 282 .sp
 283 .LP
 284 See \fBattributes\fR(5) for a description of the following attributes:
 285 .sp
 286
 287 .sp
 288 .TS
 289 box;
 290 c | c
 291 l | l .
 292 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 293 _
 294 Stability Level Obsolete
 295 .TE
 296
 297 .SH SEE ALSO
 298 .sp
 299 .LP
 300 \fBmmap\fR(2), \fBattributes\fR(5), \fBdevmap\fR(9E), \fBmmap\fR(9E),
 301 \fBsegmap\fR(9E), \fBdevmap_setup\fR(9F), \fBcb_ops\fR(9S),
 302 \fBddi_device_acc_attr\fR(9S)
 303 .sp
 304 .LP
 305 \fIWriting Device Drivers\fR