share/man/man9f/devmap_unload.9f

   1 '\" te
   2 .\"  Copyright (c) 1999, 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_UNLOAD 9F "Jan 22, 1997"
   7 .SH NAME
   8 devmap_unload, devmap_load \- control validation of memory address translations
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint\fR \fBdevmap_load\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR \fIlen\fR,
  18      \fBuint_t\fR \fItype\fR, \fBuint_t\fR \fIrw\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBdevmap_unload\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR \fIlen\fR);
  24 .fi
  25
  26 .SH INTERFACE LEVEL
  27 .sp
  28 .LP
  29 Solaris DDI specific (Solaris DDI).
  30 .SH PARAMETERS
  31 .sp
  32 .ne 2
  33 .na
  34 \fB\fIdhp\fR \fR
  35 .ad
  36 .RS 8n
  37 An opaque mapping handle that the system uses to describe the mapping.
  38 .RE
  39
  40 .sp
  41 .ne 2
  42 .na
  43 \fB\fIoff\fR \fR
  44 .ad
  45 .RS 8n
  46 User offset within the logical device memory at which the loading or unloading
  47 of the address translations begins.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fIlen\fR \fR
  54 .ad
  55 .RS 8n
  56 Length (in bytes) of the range being affected.
  57 .RE
  58
  59 .SS "devmap_load() only"
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fItype\fR \fR
  64 .ad
  65 .RS 9n
  66 Type of access operation.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fIrw\fR \fR
  73 .ad
  74 .RS 9n
  75 Direction of access.
  76 .RE
  77
  78 .SH DESCRIPTION
  79 .sp
  80 .LP
  81 \fBdevmap_unload()\fR and \fBdevmap_load()\fR are used to control the
  82 validation of the memory mapping described by \fIdhp\fR in the specified range.
  83 \fBdevmap_unload()\fR invalidates the mapping translations and will generate
  84 calls to the \fBdevmap_access\fR(9E) entry point next time the mapping is
  85 accessed. The drivers use \fBdevmap_load()\fR to validate the mapping
  86 translations during memory access.
  87 .sp
  88 .LP
  89 A typical use of \fBdevmap_unload()\fR and \fBdevmap_load()\fR is in the
  90 driver's context management callback function, \fBdevmap_contextmgt\fR(9E). To
  91 manage a device context, a device driver calls \fBdevmap_unload()\fR on the
  92 context about to be switched out. It switches contexts, and then calls
  93 \fBdevmap_load()\fR on the context switched in.   \fBdevmap_unload()\fR can be
  94 used to unload the mappings of other processes as well as the mappings of the
  95 calling process, but \fBdevmap_load()\fR can only be used to load the mappings
  96 of the calling process. Attempting to load another process's mappings with
  97 \fBdevmap_load()\fR will result in a system panic.
  98 .sp
  99 .LP
 100 For both routines, the range to be affected is defined by the \fIoff\fR and
 101 \fIlen\fR arguments. Requests affect the entire page containing the \fIoff\fR
 102 and all pages up to and including the page containing the last byte as
 103 indicated by \fIoff + len\fR. The arguments \fItype\fR and \fIrw\fR are
 104 provided by the system to the calling function (for example,
 105 \fBdevmap_contextmgt\fR(9E)) and should not be modified.
 106 .sp
 107 .LP
 108 Supplying a value of  \fB0\fR for the \fIlen\fR argument affects all addresses
 109 from the \fIoff\fR to the end of the mapping.  Supplying a value of \fB0\fR for
 110 the \fIoff\fR argument and a value of \fB0\fR for \fIlen\fR argument affect all
 111 addresses in the mapping.
 112 .sp
 113 .LP
 114 A non-zero return value from either \fBdevmap_unload()\fR or
 115 \fBdevmap_load()\fR will cause the corresponding operation to fail. The failure
 116 may result in a \fBSIGSEGV\fR or \fBSIGBUS\fR signal being delivered to the
 117 process.
 118 .SH RETURN VALUES
 119 .sp
 120 .ne 2
 121 .na
 122 \fB\fB0\fR \fR
 123 .ad
 124 .RS 12n
 125 Successful completion.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBNon-zero\fR\fR
 132 .ad
 133 .RS 12n
 134 An error occurred.
 135 .RE
 136
 137 .SH CONTEXT
 138 .sp
 139 .LP
 140 These routines can be called from user or kernel context only.
 141 .SH EXAMPLES
 142 .LP
 143 \fBExample 1 \fRManaging a One-Page Device Context
 144 .sp
 145 .LP
 146 The following shows an example of managing a device context that is one page in
 147 length.
 148
 149 .sp
 150 .in +2
 151 .nf
 152 struct xx_context cur_ctx;
 153
 154 static int
 155 xxdevmap_contextmgt(devmap_cookie_t dhp, void *pvtp, offset_t off,
 156    size_t len, uint_t type, uint_t rw)
 157 {
 158     int err;
 159     devmap_cookie_t cur_dhp;
 160     struct xx_pvt *p;
 161     struct xx_pvt *pvp = (struct xx_pvt *)pvtp;
 162     /* enable access callbacks for the current mapping */
 163     if (cur_ctx != NULL && cur_ctx != pvp->ctx) {
 164         p = cur_ctx->pvt;
 165         /*
 166          * unload the region from off to the end of the mapping.
 167          */
 168         cur_dhp = p->dhp;
 169         if ((err = devmap_unload(cur_dhp, off, len)) != 0)
 170             return (err);
 171     }
 172     /* Switch device context - device dependent*/
 173     ...
 174     /* Make handle the new current mapping */
 175     cur_ctx = pvp->ctx;
 176     /*
 177      * Disable callbacks and complete the access for the
 178      * mapping that generated this callback.
 179      */
 180     return (devmap_load(pvp->dhp, off, len, type, rw));
 181 }
 182 .fi
 183 .in -2
 184
 185 .SH SEE ALSO
 186 .sp
 187 .LP
 188 \fBdevmap_access\fR(9E), \fBdevmap_contextmgt\fR(9E)
 189 .sp
 190 .LP
 191 \fIWriting Device Drivers\fR