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

   1 '\" te
   2 .\"  Copyright (c) 2000, 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_DO_CTXMGT 9F "Jan 22, 1997"
   7 .SH NAME
   8 devmap_do_ctxmgt \- perform device context switching on a mapping
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint\fR \fBdevmap_do_ctxmgt\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBvoid\fR \fI*pvtp\fR, \fBoffset_t\fR \fIoff\fR,
  18      \fBsize_t\fR \fIlen\fR, \fBuint_t\fR \fItype\fR,
  19      \fBuint_t\fR \fIrw\fR, \fBint (*\fR\fIdevmap_contextmgt\fR)devmap_cookie_t,
  20      void *, offset_t, size_t, uint_t, uint_t);
  21 .fi
  22
  23 .SH INTERFACE LEVEL
  24 .sp
  25 .LP
  26 Solaris DDI specific (Solaris DDI).
  27 .SH PARAMETERS
  28 .sp
  29 .ne 2
  30 .na
  31 \fB\fIdhp\fR \fR
  32 .ad
  33 .RS 22n
  34 An opaque mapping handle that the system uses to describe the mapping.
  35 .RE
  36
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fIpvtp\fR \fR
  41 .ad
  42 .RS 22n
  43 Driver private mapping data.
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIoff\fR \fR
  50 .ad
  51 .RS 22n
  52 User offset within the logical device memory at which the access begins.
  53 .RE
  54
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fIlen\fR \fR
  59 .ad
  60 .RS 22n
  61 Length (in bytes) of the memory being accessed.
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fIdevmap_contextmgt\fR \fR
  68 .ad
  69 .RS 22n
  70 The address of driver function that the system will call to perform context
  71 switching on a mapping. See \fBdevmap_contextmgt\fR(9E) for details.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fItype\fR \fR
  78 .ad
  79 .RS 22n
  80 Type of access operation.  Provided by \fBdevmap_access\fR(9E). Should not be
  81 modified.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fIrw\fR \fR
  88 .ad
  89 .RS 22n
  90 Direction of access.  Provided by \fBdevmap_access\fR(9E). Should not be
  91 modified.
  92 .RE
  93
  94 .SH DESCRIPTION
  95 .sp
  96 .LP
  97 Device drivers call \fBdevmap_do_ctxmgt()\fR in the \fBdevmap_access\fR(9E)
  98 entry point to perform device context switching on a mapping.
  99 \fBdevmap_do_ctxmgt()\fR passes a pointer to a driver supplied callback
 100 function, \fBdevmap_contextmgt\fR(9E), to the system that will perform the
 101 actual device context switching.  If \fBdevmap_contextmgt\fR(9E) is not a valid
 102 driver callback function, the system will fail the memory access operation
 103 which will result in a \fBSIGSEGV\fR or \fBSIGBUS\fR signal being delivered to
 104 the process.
 105 .sp
 106 .LP
 107 \fBdevmap_do_ctxmgt()\fR performs context switching on the mapping object
 108 identified by \fIdhp\fR and \fIpvtp\fR in the range specified by \fIoff\fR and
 109 \fIlen\fR. The arguments \fIdhp\fR, \fIpvtp\fR, \fItype\fR, and \fIrw\fR are
 110 provided by the \fBdevmap_access\fR(9E) entry point and must not be modified.
 111 The range from \fIoff\fR to \fIoff+len\fR must support context switching.
 112 .sp
 113 .LP
 114 The system will pass through \fIdhp\fR,\fI pvtp\fR,\fI off\fR, \fI len\fR,\fI
 115 type\fR, and \fIrw\fR to \fBdevmap_contextmgt\fR(9E) in order to perform the
 116 actual device context switching.  The return value from
 117 \fBdevmap_contextmgt\fR(9E) will be returned directly to
 118 \fBdevmap_do_ctxmgt()\fR.
 119 .SH RETURN VALUES
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fB0\fR \fR
 124 .ad
 125 .RS 12n
 126 Successful completion.
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBNon-zero\fR\fR
 133 .ad
 134 .RS 12n
 135 An error occurred.
 136 .RE
 137
 138 .SH CONTEXT
 139 .sp
 140 .LP
 141 \fBdevmap_do_ctxmgt()\fR must be called from the driver's
 142 \fBdevmap_access\fR(9E) entry point.
 143 .SH EXAMPLES
 144 .LP
 145 \fBExample 1 \fRUsing devmap_do_ctxmgt in the devmap_access entry point.
 146 .sp
 147 .LP
 148 The following shows an example of using \fBdevmap_do_ctxmgt()\fR in the
 149 \fBdevmap_access\fR(9E) entry point.
 150
 151 .sp
 152 .in +2
 153 .nf
 154 \&.\|.\|.
 155 #define OFF_DO_CTXMGT  0x40000000
 156 #define OFF_NORMAL     0x40100000
 157 #define CTXMGT_SIZE    0x100000
 158 #define NORMAL_SIZE    0x100000
 159
 160 /*
 161  * Driver devmap_contextmgt(9E) callback function.
 162  */
 163 static int
 164 xx_context_mgt(devmap_cookie_t dhp, void *pvtp, offset_t offset,
 165     size_t length, uint_t type, uint_t rw)
 166 {
 167     ......
 168     /*
 169      * see devmap_contextmgt(9E) for an example
 170      */
 171 }
 172
 173 /*
 174  * Driver devmap_access(9E) entry point
 175  */
 176 static int
 177 xxdevmap_access(devmap_cookie_t dhp, void *pvtp, offset_t off,
 178     size_t len, uint_t type, uint_t rw)
 179 {
 180     offset_t diff;
 181     int err;
 182
 183     /*
 184      * check if off is within the range that supports
 185      * context management.
 186      */
 187     if ((diff = off - OFF_DO_CTXMG) >= 0 && diff < CTXMGT_SIZE) {
 188         /*
 189          * calculates the length for context switching
 190          */
 191         if ((len + off) > (OFF_DO_CTXMGT + CTXMGT_SIZE))
 192             return (-1);
 193         /*
 194          * perform context switching
 195          */
 196         err = devmap_do_ctxmgt(dhp, pvtp, off, len, type,
 197                     rw, xx_context_mgt);
 198     /*
 199      * check if off is within the range that does normal
 200      * memory mapping.
 201      */
 202     } else if ((diff = off - OFF_NORMAL) >= 0 && diff < NORMAL_SIZE) {
 203         if ((len + off) > (OFF_NORMAL + NORMAL_SIZE))
 204             return (-1);
 205         err = devmap_default_access(dhp, pvtp, off, len, type, rw);
 206     } else
 207         return (-1);
 208
 209     return (err);
 210 }
 211 .fi
 212 .in -2
 213
 214 .SH SEE ALSO
 215 .sp
 216 .LP
 217 \fBdevmap_access\fR(9E), \fBdevmap_contextmgt\fR(9E),
 218 \fBdevmap_default_access\fR(9F)
 219 .sp
 220 .LP
 221 \fIWriting Device Drivers\fR