usr/src/man/man9e/devmap_contextmgt.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_CONTEXTMGT 9E "Jan 16, 1997"
   7 .SH NAME
   8 devmap_contextmgt \- driver callback function for context management
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint\fR \fBdevmap_contextmgt\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 .RE
 124
 125 .SH DESCRIPTION
 126 .sp
 127 .LP
 128 \fBdevmap_contextmgt()\fR is a driver-supplied function that performs device
 129 context switching on a  mapping.  Device drivers pass \fBdevmap_contextmgt()\fR
 130 as an argument to \fBdevmap_do_ctxmgt\fR(9F) in the  \fBdevmap_access\fR(9E)
 131 entry point. The system will call \fBdevmap_contextmgt()\fR when memory is
 132 accessed. The system expects  \fBdevmap_contextmgt()\fR to load the memory
 133 address translations of the mapping by calling \fBdevmap_load\fR(9F) before
 134 returning.
 135 .sp
 136 .LP
 137 \fIdhp\fR uniquely identifies the mapping and is used as an argument to
 138 \fBdevmap_load\fR(9F) to validate the mapping. \fIoff\fR and \fIlen\fR define
 139 the range to be affected by the operations in \fBdevmap_contextmgt()\fR.
 140 .sp
 141 .LP
 142 The driver must check if there is already a mapping established at \fIoff\fR
 143 that needs to be unloaded. If a mapping exists at \fIoff\fR,
 144 \fBdevmap_contextmgt()\fR must call  \fBdevmap_unload\fR(9F) on the current
 145 mapping. \fBdevmap_unload\fR(9F) must be followed by \fBdevmap_load()\fR on the
 146 mapping that generated this call to \fBdevmap_contextmgt()\fR.
 147 \fBdevmap_unload\fR(9F) unloads the current mapping so that a call to
 148 \fBdevmap_access\fR(9E), which causes the system to call
 149 \fBdevmap_contextmgt()\fR, will be generated the next time the mapping is
 150 accessed.
 151 .sp
 152 .LP
 153 \fIpvtp\fR is a pointer to the driver's private mapping data that was allocated
 154 and initialized in the \fBdevmap_map\fR(9E) entry point. \fItype\fR defines the
 155 type of operation that device drivers should perform on the memory object.  If
 156 \fItype\fR is either \fBDEVMAP_LOCK\fR or \fBDEVMAP_UNLOCK\fR, the length
 157 passed to either \fBdevmap_unload\fR(9F) or \fBdevmap_load\fR(9F) must be same
 158 as \fIlen\fR. \fIrw\fR specifies the access direction on the memory object.
 159 .sp
 160 .LP
 161 A non-zero return value from  \fBdevmap_contextmgt()\fR will be returned to
 162 \fBdevmap_access\fR(9E) and will cause the corresponding operation to fail. The
 163 failure may result in a \fBSIGSEGV\fR or \fBSIGBUS\fR signal being delivered to
 164 the process.
 165 .SH RETURN VALUES
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fB0\fR \fR
 170 .ad
 171 .RS 12n
 172 Successful completion.
 173 .RE
 174
 175 .sp
 176 .ne 2
 177 .na
 178 \fBNon-zero\fR
 179 .ad
 180 .RS 12n
 181 An error occurred.
 182 .RE
 183
 184 .SH EXAMPLES
 185 .LP
 186 \fBExample 1 \fRmanaging a device context
 187 .sp
 188 .LP
 189 The following shows an example of managing a device context.
 190
 191 .sp
 192 .in +2
 193 .nf
 194 struct xxcontext cur_ctx;
 195 static int
 196 xxdevmap_contextmgt(devmap_cookie_t dhp, void *pvtp, offset_t off,
 197         size_t len, uint_t type, uint_t rw)
 198 {
 199     devmap_cookie_t cur_dhp;
 200     struct xxpvtdata *p;
 201     struct xxpvtdata *pvp = (struct xxpvtdata *)pvtp;
 202     struct xx_softc  *softc = pvp->softc;
 203     int    err;
 204
 205     mutex_enter(&softc->mutex);
 206
 207     /*
 208      * invalidate the translations of current context before
 209      * switching context.
 210      */
 211     if (cur_ctx != NULL && cur_ctx != pvp->ctx) {
 212         p = cur_ctx->pvt;
 213         cur_dhp = p->dhp;
 214         if ((err = devmap_unload(cur_dhp, off, len)) != 0)
 215             return (err);
 216     }
 217     /* Switch device context - device dependent*/
 218     ...
 219     /* Make handle the new current mapping */
 220     cur_ctx = pvp->ctx;
 221
 222     /*
 223      * Load the address translations of the calling context.
 224      */
 225     err = devmap_load(pvp->dhp, off, len, type, rw);
 226
 227     mutex_exit(&softc->mutex);
 228
 229     return (err);
 230 }
 231 .fi
 232 .in -2
 233
 234 .SH SEE ALSO
 235 .sp
 236 .LP
 237 \fBdevmap_access\fR(9E), \fBdevmap_do_ctxmgt\fR(9F) \fBdevmap_load\fR(9F),
 238 \fBdevmap_unload\fR(9F)
 239 .sp
 240 .LP
 241 \fIWriting Device Drivers\fR