usr/src/man/man9e/segmap.9e

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (c) 1995, Sun Microsystems, Inc.  All Rights Reserved
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH SEGMAP 9E "Jan 14, 1997"
   8 .SH NAME
   9 segmap \- map device memory into user space
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/types.h>
  14 #include <sys/mman.h>
  15 #include <sys/param.h>
  16 #include <sys/vm.h>
  17 #include <sys/ddi.h>
  18 #include <sys/sunddi.h>
  19
  20
  21
  22 \fBint prefix\fR\fBsegmap\fR(\fBdev_t\fR \fIdev\fR, \fBoff_t\fR \fIoff\fR, \fBstruct as *\fR\fIasp\fR, \fBcaddr_t *\fR\fIaddrp\fR,
  23      \fBoff_t\fR \fIlen\fR, \fBunsigned int\fR \fIprot\fR, \fBunsigned int\fR \fImaxprot\fR, \fBunsigned int\fR \fIflags\fR,
  24      \fBcred_t *\fR\fIcred_p\fR);
  25 .fi
  26
  27 .SH INTERFACE LEVEL
  28 .sp
  29 .LP
  30 Architecture independent level 2 (DKI only).
  31 .SH ARGUMENTS
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fIdev\fR \fR
  36 .ad
  37 .RS 12n
  38 Device whose memory is to be mapped.
  39 .RE
  40
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fIoff\fR \fR
  45 .ad
  46 .RS 12n
  47 Offset within device memory at which mapping begins.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fIasp\fR \fR
  54 .ad
  55 .RS 12n
  56 Pointer to the address space into which the device memory should be mapped.
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fIaddrp\fR \fR
  63 .ad
  64 .RS 12n
  65 Pointer to the address in the address space to which the device memory should
  66 be mapped.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fIlen\fR \fR
  73 .ad
  74 .RS 12n
  75 Length (in bytes) of the memory to be mapped.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fIprot\fR \fR
  82 .ad
  83 .RS 12n
  84 A bit field that specifies the protections. Possible settings are:
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBPROT_READ\fR \fR
  89 .ad
  90 .RS 15n
  91 Read access is desired.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBPROT_WRITE\fR \fR
  98 .ad
  99 .RS 15n
 100 Write access is desired.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBPROT_EXEC\fR \fR
 107 .ad
 108 .RS 15n
 109 Execute access is desired.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBPROT_USER\fR \fR
 116 .ad
 117 .RS 15n
 118 User-level access is desired (the mapping is  being done as a result of a
 119 \fBmmap\fR(2) system call).
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBPROT_ALL\fR \fR
 126 .ad
 127 .RS 15n
 128 All access is desired.
 129 .RE
 130
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fImaxprot\fR \fR
 137 .ad
 138 .RS 12n
 139 Maximum protection flag possible for attempted mapping; the \fBPROT_WRITE\fR
 140 bit may be masked out if the user opened the special file read-only.
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fIflags\fR \fR
 147 .ad
 148 .RS 12n
 149 Flags indicating type of mapping. Possible values are (other bits may be set):
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fBMAP_SHARED\fR \fR
 154 .ad
 155 .RS 16n
 156 Changes should be shared.
 157 .RE
 158
 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 .RE
 169
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fIcred_p\fR \fR
 174 .ad
 175 .RS 12n
 176 Pointer to the  user credentials structure.
 177 .RE
 178
 179 .SH DESCRIPTION
 180 .sp
 181 .LP
 182 The  \fBsegmap()\fR entry point is an optional routine for character drivers
 183 that support memory mapping.  The  \fBmmap\fR(2) system call, when applied to a
 184 character special file, allows device memory to be mapped into user space for
 185 direct access by the user application.
 186 .sp
 187 .LP
 188 Typically, a character driver that needs to support the  \fBmmap\fR(2) system
 189 call supplies either an \fBdevmap\fR(9E) entry point, or both an
 190 \fBdevmap\fR(9E) and a  \fBsegmap()\fR entry point routine (see the
 191 \fBdevmap\fR(9E) reference page). If no \fBsegmap()\fR entry point is provided
 192 for the driver,  \fBdevmap_setup\fR(9F) is used as a default.
 193 .sp
 194 .LP
 195 A driver for a memory-mapped device would provide a  \fBsegmap()\fR entry point
 196 if it:
 197 .RS +4
 198 .TP
 199 .ie t \(bu
 200 .el o
 201 needs to maintain a separate context for each user mapping.  See
 202 \fBdevmap_setup\fR(9F) for details.
 203 .RE
 204 .RS +4
 205 .TP
 206 .ie t \(bu
 207 .el o
 208 needs to assign device access attributes to the user mapping.
 209 .RE
 210 .sp
 211 .LP
 212 The responsibilities of a  \fBsegmap()\fR entry point are:
 213 .RS +4
 214 .TP
 215 .ie t \(bu
 216 .el o
 217 Verify that the range, defined by  \fIoffset\fR and  \fIlen\fR, to be mapped is
 218 valid for  the device. Typically, this task is performed by calling the
 219 \fBdevmap\fR(9E) entry point. Note that if you are using
 220 \fBddi_devmap_segmap\fR(9F) or \fBdevmap_setup\fR(9F) to set up the mapping, it
 221 will call your \fBdevmap\fR(9E) entry point for you to validate the range to be
 222 mapped.
 223 .RE
 224 .RS +4
 225 .TP
 226 .ie t \(bu
 227 .el o
 228 Assign device access attributes to the mapping.  See
 229 \fBddi_devmap_segmap\fR(9F), and \fBddi_device_acc_attr\fR(9S) for details.
 230 .RE
 231 .RS +4
 232 .TP
 233 .ie t \(bu
 234 .el o
 235 Set up device contexts for the user mapping if your device requires  context
 236 switching.  See \fBdevmap_setup\fR(9F) for details.
 237 .RE
 238 .RS +4
 239 .TP
 240 .ie t \(bu
 241 .el o
 242 Perform the mapping with \fBddi_devmap_segmap\fR(9F), or \fBdevmap_setup\fR(9F)
 243 and return the status if it fails.
 244 .RE
 245 .SH RETURN VALUES
 246 .sp
 247 .LP
 248 The \fBsegmap()\fR routine should return  \fB0\fR if the driver is successful
 249 in performing the memory map of its device address space into the specified
 250 address space.
 251 .sp
 252 .LP
 253 The \fBsegmap()\fR must return an error number on failure. For example, valid
 254 error numbers would be  \fBENXIO\fR if the offset/length pair specified exceeds
 255 the limits of the device memory, or  \fBEINVAL\fR if the driver detects an
 256 invalid type of mapping attempted.
 257 .sp
 258 .LP
 259 If one of the mapping routines \fBddi_devmap_segmap()\fR or
 260 \fBdevmap_setup()\fRfails, you must return the error number returned by the
 261 respective routine.
 262 .SH SEE ALSO
 263 .sp
 264 .LP
 265 \fBmmap\fR(2), \fBdevmap\fR(9E), \fBdevmap_setup\fR(9F),
 266 \fBddi_devmap_segmap\fR(9F), \fBddi_device_acc_attr\fR(9S)
 267 .sp
 268 .LP
 269 \fIWriting Device Drivers\fR