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

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (c) 2002, 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 MMAP 9E "Sep 27, 2002"
   8 .SH NAME
   9 mmap \- check virtual mapping for memory mapped device
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/types.h>
  14 #include <sys/cred.h>
  15 #include <sys/mman.h>
  16 #include <sys/ddi.h>
  17
  18
  19
  20 \fBint prefix\fR\fBmmap\fR(\fBdev_t\fR \fIdev\fR, \fBoff_t\fR \fIoff\fR, \fBint\fR \fIprot\fR);
  21 .fi
  22
  23 .SH INTERFACE LEVEL
  24 .sp
  25 .LP
  26 This interface is obsolete. \fBdevmap\fR(9E) should be used instead.
  27 .SH PARAMETERS
  28 .sp
  29 .ne 2
  30 .na
  31 \fB\fIdev\fR \fR
  32 .ad
  33 .RS 9n
  34 Device whose memory is to be mapped.
  35 .RE
  36
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fIoff\fR \fR
  41 .ad
  42 .RS 9n
  43 Offset within device memory at which mapping begins.
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIprot\fR \fR
  50 .ad
  51 .RS 9n
  52 A bit field that specifies the protections this page of memory will receive.
  53 Possible settings are:
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fBPROT_READ\fR \fR
  58 .ad
  59 .RS 15n
  60 Read access will be granted.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fBPROT_WRITE\fR \fR
  67 .ad
  68 .RS 15n
  69 Write access will be granted.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBPROT_EXEC\fR \fR
  76 .ad
  77 .RS 15n
  78 Execute access will be granted.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fBPROT_USER\fR \fR
  85 .ad
  86 .RS 15n
  87 User-level access will be granted.
  88 .RE
  89
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fBPROT_ALL\fR \fR
  94 .ad
  95 .RS 15n
  96 All access will be granted.
  97 .RE
  98
  99 .RE
 100
 101 .SH DESCRIPTION
 102 .sp
 103 .LP
 104 Future releases of Solaris will provide this function for binary and source
 105 compatibility. However, for increased functionality, use \fBdevmap\fR(9E)
 106 instead. See \fBdevmap\fR(9E) for details.
 107 .sp
 108 .LP
 109 The \fBmmap()\fR entry point is a required entry point for character drivers
 110 supporting memory-mapped devices. A memory mapped device has memory that can be
 111 mapped into a process's address space. The \fBmmap\fR(2) system call, when
 112 applied to a character special file, allows this device memory to be mapped
 113 into user space for direct access by the user application.
 114 .sp
 115 .LP
 116 The \fBmmap()\fR entry point is called as a result of an \fBmmap\fR(2) system
 117 call, and also as a result of a page fault. \fBmmap()\fR is called to translate
 118 the offset \fIoff\fR in device memory to the corresponding physical page frame
 119 number.
 120 .sp
 121 .LP
 122 The \fBmmap()\fR entry point checks if the offset \fIoff\fR is within the range
 123 of pages exported by the device. For example, a device that has 512 bytes of
 124 memory that can be mapped into user space should not support offsets greater
 125 than 512. If the offset does not exist, then \fB-1\fR is returned. If the
 126 offset does exist, \fBmmap()\fR returns the value returned by
 127 \fBhat_getkpfnum\fR(9F) for the physical page in device memory containing the
 128 offset \fIoff\fR.
 129 .sp
 130 .LP
 131 \fBhat_getkpfnum\fR(9F) accepts a kernel virtual address as an argument. A
 132 kernel virtual address can be obtained by calling \fBddi_regs_map_setup\fR(9F)
 133 in the driver's \fBattach\fR(9E) routine. The corresponding
 134 \fBddi_regs_map_free\fR(9F) call can be made in the driver's \fBdetach\fR(9E)
 135 routine. Refer to the example below \fImmap Entry Point\fR for more
 136 information.
 137 .sp
 138 .LP
 139 \fBmmap()\fR should only be supported for memory-mapped devices. See
 140 \fBsegmap\fR(9E) for further information on memory-mapped device drivers.
 141 .sp
 142 .LP
 143 If a device driver shares data structures with the application, for example
 144 through exported kernel memory, and the driver gets recompiled for a 64-bit
 145 kernel but the application remains 32-bit, the binary layout of any data
 146 structures will be incompatible if they contain longs or pointers. The driver
 147 needs to know whether there is a model mismatch between the current thread and
 148 the kernel and take necessary action. \fBddi_mmap_get_model\fR(9F) can be use
 149 to get the C Language Type Model which the current thread expects. In
 150 combination with \fBddi_model_convert_from\fR(9F) the driver can determine
 151 whether there is a data model mismatch between the current thread and the
 152 device driver. The device driver might have to adjust the shape of data
 153 structures before exporting them to a user thread which supports a different
 154 data model. See \fBddi_mmap_get_model\fR(9F) for an example.
 155 .SH RETURN VALUES
 156 .sp
 157 .LP
 158 If the protection and offset are valid for the device, the driver should return
 159 the value returned by \fBhat_getkpfnum\fR(9F), for the page at offset \fIoff\fR
 160 in the device's memory. If not, \fB-1\fR should be returned.
 161 .SH EXAMPLES
 162 .LP
 163 \fBExample 1 \fR\fBmmap()\fR Entry Point
 164 .sp
 165 .LP
 166 The following is an example of the \fBmmap()\fR entry point. If offset
 167 \fIoff\fR is valid, \fBhat_getkpfnum\fR(9F) is called to obtain the page frame
 168 number corresponding to this offset in the device's memory. In this example,
 169 \fBxsp\(->regp\(->csr\fR is a kernel virtual address which maps to device
 170 memory. \fBddi_regs_map_setup\fR(9F) can be used to obtain this address. For
 171 example, \fBddi_regs_map_setup\fR(9F) can be called in the driver's
 172 \fBattach\fR(9E) routine. The resulting kernel virtual address is stored in the
 173 \fBxxstate\fR structure, which is accessible from the driver's \fBmmap()\fR
 174 entry point. See \fBddi_soft_state\fR(9F). The corresponding
 175 \fBddi_regs_map_free\fR(9F) call can be made in the driver's  \fBdetach\fR(9E)
 176 routine.
 177
 178 .sp
 179 .in +2
 180 .nf
 181 struct reg {
 182                 uint8_t csr;
 183                 uint8_t data;
 184 };
 185 struct xxstate {
 186         .\|.\|.
 187                 struct reg      *regp
 188         .\|.\|.
 189 };
 190
 191 struct xxstate *xsp;
 192 \&.\|.\|.
 193
 194 static int
 195 xxmmap(dev_t dev, off_t off, int prot)
 196 {
 197         int             instance;
 198         struct xxstate *xsp;
 199
 200          /* No write access */
 201         if (prot & PROT_WRITE)
 202                             return (-1);
 203
 204         instance = getminor(dev);
 205         xsp = ddi_get_soft_state(statep, instance);
 206         if (xsp == NULL)
 207                             return (-1);
 208
 209         /* check for a valid offset */
 210                if ( off is invalid )
 211                             return (-1);
 212                return (hat_getkpfnum (xsp->regp->csr + off));
 213 }
 214 .fi
 215 .in -2
 216
 217 .SH ATTRIBUTES
 218 .sp
 219 .LP
 220 See \fBattributes\fR(5) for a description of the following attributes:
 221 .sp
 222
 223 .sp
 224 .TS
 225 box;
 226 c | c
 227 l | l .
 228 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 229 _
 230 Stability Level Obsolete
 231 .TE
 232
 233 .SH SEE ALSO
 234 .sp
 235 .LP
 236 \fBmmap\fR(2), \fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E),
 237 \fBdevmap\fR(9E), \fBsegmap\fR(9E), \fBddi_btop\fR(9F),
 238 \fBddi_get_soft_state\fR(9F), \fBddi_mmap_get_model\fR(9F),
 239 \fBddi_model_convert_from\fR(9F), \fBddi_regs_map_free\fR(9F),
 240 \fBddi_regs_map_setup\fR(9F), \fBddi_soft_state\fR(9F), \fBdevmap_setup\fR(9F),
 241 \fBgetminor\fR(9F), \fBhat_getkpfnum\fR(9F)
 242 .sp
 243 .LP
 244 \fIWriting Device Drivers\fR
 245 .SH NOTES
 246 .sp
 247 .LP
 248 For some devices, mapping device memory in the driver's \fBattach\fR(9E)
 249 routine and unmapping device memory in the driver's \fBdetach\fR(9E) routine is
 250 a sizeable drain on system resources. This is especially true for devices with
 251 a large amount of physical address space.
 252 .sp
 253 .LP
 254 One alternative is to create a mapping for only the first page of device memory
 255 in \fBattach\fR(9E). If the device memory is contiguous, a kernel page frame
 256 number may be obtained by calling \fBhat_getkpfnum\fR(9F) with the kernel
 257 virtual address of the first page of device memory and adding the desired page
 258 offset to the result. The page offset may be obtained by converting the byte
 259 offset \fIoff\fR to pages. See \fBddi_btop\fR(9F).
 260 .sp
 261 .LP
 262 Another alternative is to call \fBddi_regs_map_setup\fR(9F) and
 263 \fBddi_regs_map_free\fR(9F) in \fBmmap()\fR. These function calls would bracket
 264 the call to \fBhat_getkpfnum\fR(9F).
 265 .sp
 266 .LP
 267 However, note that the above alternatives may not work in all cases. The
 268 existence of intermediate nexus devices with memory management unit translation
 269 resources that are not locked down may cause unexpected and undefined behavior.