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

   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 DEVMAP_ACCESS 9E "Jan 17, 1997"
   7 .SH NAME
   8 devmap_access \- device mapping access entry point
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint prefix\fR\fBdevmap_access\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBvoid *\fR\fIpvtp\fR,
  18      \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR \fIlen\fR, \fBuint_t\fR \fItype\fR, \fBuint_t\fR \fIrw\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Solaris DDI specific (Solaris DDI).
  25 .SH ARGUMENTS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fIdhp\fR \fR
  30 .ad
  31 .RS 9n
  32 An opaque mapping handle that the system uses to describe the mapping.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIpvtp\fR \fR
  39 .ad
  40 .RS 9n
  41 Driver private mapping data.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIoff\fR \fR
  48 .ad
  49 .RS 9n
  50 User offset within the logical device memory at which the access begins.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fIlen\fR \fR
  57 .ad
  58 .RS 9n
  59 Length (in bytes) of the memory being accessed.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fItype\fR \fR
  66 .ad
  67 .RS 9n
  68 Type of access operation.  Possible values are:
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBDEVMAP_ACCESS\fR \fR
  73 .ad
  74 .RS 18n
  75 Memory access.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBDEVMAP_LOCK\fR \fR
  82 .ad
  83 .RS 18n
  84 Lock the memory being accessed.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBDEVMAP_UNLOCK\fR \fR
  91 .ad
  92 .RS 18n
  93 Unlock the memory being accessed.
  94 .RE
  95
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fIrw\fR \fR
 102 .ad
 103 .RS 9n
 104 Direction of access.  Possible values are:
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBDEVMAP_READ\fR \fR
 109 .ad
 110 .RS 17n
 111 Read access attempted.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fBDEVMAP_WRITE\fR \fR
 118 .ad
 119 .RS 17n
 120 Write access attempted.
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBDEVMAP_EXEC\fR \fR
 127 .ad
 128 .RS 17n
 129 Execution access attempted.
 130 .RE
 131
 132 .RE
 133
 134 .SH DESCRIPTION
 135 .sp
 136 .LP
 137 The \fBdevmap_access()\fR entry point is an optional routine.  It notifies
 138 drivers whenever an access is made to a mapping described by  \fIdhp\fR that
 139 has not been validated or does  not have sufficient protection for the access.
 140 The system expects \fBdevmap_access()\fR to call either
 141 \fBdevmap_do_ctxmgt\fR(9F) or \fBdevmap_default_access\fR(9F) to load the
 142 memory address translations before it returns. For mappings that support
 143 context switching,  device drivers should call \fBdevmap_do_ctxmgt\fR(9F). For
 144 mappings that do not support context switching, the drivers should call
 145 \fBdevmap_default_access\fR(9F).
 146 .sp
 147 .LP
 148 In  \fBdevmap_access()\fR, drivers perform memory access related operations
 149 such as context switching, checking the availability of the memory  object, and
 150 locking and unlocking the memory object being accessed. The
 151 \fBdevmap_access()\fR entry point is set to  \fINULL\fR if no operations need
 152 to be performed.
 153 .sp
 154 .LP
 155 \fIpvtp\fR is a pointer to the driver's private mapping data that was allocated
 156 and initialized in the \fBdevmap_map\fR(9E) entry point.
 157 .sp
 158 .LP
 159 \fIoff\fR and \fIlen\fR define the range to be affected by the operations in
 160 \fBdevmap_access()\fR. \fItype\fR defines the type of operation that device
 161 drivers should perform on the memory object.  If \fBtype\fR is either
 162 \fBDEVMAP_LOCK\fR or \fBDEVMAP_UNLOCK,\fR the length passed to either
 163 \fBdevmap_do_ctxmgt\fR(9F) or \fBdevmap_default_access\fR(9F) must be same as
 164 \fIlen\fR. \fIrw\fR specifies the direction of access on the memory object.
 165 .sp
 166 .LP
 167 A non-zero return value from  \fBdevmap_access()\fR may result in a
 168 \fBSIGSEGV\fR or \fBSIGBUS\fR signal being delivered to the process.
 169 .SH RETURN VALUES
 170 .sp
 171 .LP
 172 \fBdevmap_access()\fR returns the following values:
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fB0\fR \fR
 177 .ad
 178 .RS 12n
 179 Successful completion.
 180 .RE
 181
 182 .sp
 183 .ne 2
 184 .na
 185 \fBNon-zero\fR
 186 .ad
 187 .RS 12n
 188 An error occurred.  The return value from  \fBdevmap_do_ctxmgt\fR(9F) or
 189 \fBdevmap_default_access\fR(9F) should be returned.
 190 .RE
 191
 192 .SH EXAMPLES
 193 .LP
 194 \fBExample 1 \fR\fBdevmap_access()\fR entry point
 195 .sp
 196 .LP
 197 The following is an example of the \fBdevmap_access()\fR entry point.  If the
 198 mapping supports context switching, \fBdevmap_access()\fR calls
 199 \fBdevmap_do_ctxmgt\fR(9F). Otherwise, \fBdevmap_access()\fR calls
 200 \fBdevmap_default_access\fR(9F).
 201
 202 .sp
 203 .in +2
 204 .nf
 205 \&.\|.\|.
 206 #define OFF_DO_CTXMGT  0x40000000
 207 #define OFF_NORMAL     0x40100000
 208 #define CTXMGT_SIZE    0x100000
 209 #define NORMAL_SIZE    0x100000
 210
 211 /*
 212  * Driver devmap_contextmgt(9E) callback function.
 213  */
 214 static int
 215 xx_context_mgt(devmap_cookie_t dhp, void *pvtp, offset_t offset,
 216    size_t length, uint_t type, uint_t rw)
 217 {
 218    ......
 219    /*
 220     * see devmap_contextmgt(9E) for an example
 221     */
 222 }
 223
 224 /*
 225  * Driver devmap_access(9E) entry point
 226  */
 227 static int
 228 xxdevmap_access(devmap_cookie_t dhp, void *pvtp, offset_t off,
 229    size_t len, uint_t type, uint_t rw)
 230 {
 231    offset_t diff;
 232    int err;
 233
 234    /*
 235     * check if \fIoff\fR is within the range that supports
 236     * context management.
 237     */
 238    if ((diff = off - OFF_DO_CTXMG) >= 0 && diff < CTXMGT_SIZE) {
 239        /*
 240         * calculates the length for context switching
 241         */
 242        if ((len + off) > (OFF_DO_CTXMGT + CTXMGT_SIZE))
 243            return (-1);
 244        /*
 245         * perform context switching
 246         */
 247        err = devmap_do_ctxmgt(dhp, pvtp, off, len, type,
 248            rw, xx_context_mgt);
 249     /*
 250      * check if \fI off \fRis within the range that does normal
 251      * memory mapping.
 252      */
 253     } else if ((diff = off - OFF_NORMAL) >= 0 && diff < NORMAL_SIZE) {
 254        if ((len + off) > (OFF_NORMAL + NORMAL_SIZE))
 255            return (-1);
 256        err = devmap_default_access(dhp, pvtp, off, len, type, rw);
 257     } else
 258        return (-1);
 259
 260    return (err);
 261 }
 262 .fi
 263 .in -2
 264
 265 .SH SEE ALSO
 266 .sp
 267 .LP
 268 \fBdevmap_map\fR(9E), \fBdevmap_default_access\fR(9F),
 269 \fBdevmap_do_ctxmgt\fR(9F), \fBdevmap_callback_ctl\fR(9S)
 270 .sp
 271 .LP
 272 \fIWriting Device Drivers\fR