usr/src/man/man9e/devmap_unmap.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_UNMAP 9E "Jan 21, 1997"
   7 .SH NAME
   8 devmap_unmap \- device mapping unmap entry point
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBvoid prefix\fR\fBdevmap_unmap\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBvoid *\fR\fIpvtp\fR,
  18      \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR\fIlen\fR, \fBdevmap_cookie_t\fR \fInew_dhp1\fR,
  19      \fBvoid **\fR\fInew_pvtp1\fR, \fBdevmap_cookie_t\fR\fInew_dhp2\fR, \fBvoid **\fR\fInew_pvtp2\fR);
  20 .fi
  21
  22 .SH INTERFACE LEVEL
  23 .sp
  24 .LP
  25 Solaris DDI specific (Solaris DDI).
  26 .SH ARGUMENTS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIdhp\fR \fR
  31 .ad
  32 .RS 14n
  33 An opaque mapping handle that the system uses to describe the mapping.
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIpvtp\fR \fR
  40 .ad
  41 .RS 14n
  42 Driver private mapping data.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIoff\fR \fR
  49 .ad
  50 .RS 14n
  51 User offset within the logical device memory at which the unmapping begins.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIlen\fR \fR
  58 .ad
  59 .RS 14n
  60 Length (in bytes) of the memory being unmapped.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fInew_dhp1\fR \fR
  67 .ad
  68 .RS 14n
  69 The opaque mapping handle that the system uses to describe the new region that
  70 ends at (\fIoff\fR - 1) . \fInew_dhp1\fR may be  \fINULL\fR.
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fInew_pvtp1\fR \fR
  77 .ad
  78 .RS 14n
  79 A pointer to be filled in by the driver with the driver  private mapping data
  80 for the new region that ends at (\fIoff\fR - 1); ignored if \fInew_dhp1\fR is
  81 \fINULL\fR.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fInew_dhp2\fR \fR
  88 .ad
  89 .RS 14n
  90 The opaque mapping handle that the system uses to describe the new region that
  91 begins at (\fIoff \fR + \fIlen\fR); \fInew_dhp2\fR may be  \fINULL\fR.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fInew_pvtp2\fR \fR
  98 .ad
  99 .RS 14n
 100 A pointer to be filled in by the driver with the driver private mapping data
 101 for the new region that begins at (\fIoff\fR + \fIlen\fR);  ignored if
 102 \fInew_dhp2\fR is  \fINULL\fR.
 103 .RE
 104
 105 .SH DESCRIPTION
 106 .sp
 107 .LP
 108 \fBdevmap_unmap()\fR is called when the system removes the mapping in the range
 109 [ \fIoff\fR, \fIoff\fR + \fIlen\fR ], such as in the  \fBmunmap\fR(2) or
 110 \fBexit\fR(2) system calls. Device drivers use \fBdevmap_unmap()\fR to free up
 111 the resources allocated in \fBdevmap_map\fR(9E).
 112 .sp
 113 .LP
 114 \fIdhp\fR is the mapping handle that uniquely identifies the mapping.   The
 115 driver stores the mapping attributes in the driver's private data, \fIpvtp\fR,
 116 when the mapping is created.  See \fBdevmap_map\fR(9E) for details.
 117 .sp
 118 .LP
 119 \fIoff\fR and \fIlen\fR define the range to be affected by
 120 \fBdevmap_unmap()\fR. This range is within the boundary of the mapping
 121 described by \fIdhp\fR.
 122 .sp
 123 .LP
 124 If the range [ \fIoff\fR, \fIoff\fR + \fIlen\fR ] covers the entire mapping,
 125 the system passes  \fINULL\fR to  \fInew_dhp1\fR, \fInew_pvtp1\fR,
 126 \fInew_dhp2\fR, and \fInew_pvtp2\fR. The system expects device drivers to free
 127 all resources allocated for this  mapping.
 128 .sp
 129 .LP
 130 If \fIoff\fR is at the beginning of the mapping and  \fIlen\fR does not cover
 131 the entire mapping, the system sets  \fINULL\fR to \fInew_dhp1\fR and to
 132 \fInew_pvtp1\fR. The system expects the drivers to allocate new driver private
 133 data for the region that starts at \fIoff\fR + \fIlen\fR and to set
 134 \fI*new_pvtp2\fR to point to it. \fInew_dhp2\fR is the mapping handle of the
 135 newly mapped object.
 136 .sp
 137 .LP
 138 If \fIoff\fR is not at the beginning of the mapping, but \fIoff\fR + \fIlen\fR
 139 is at the end of the mapping the system passes  \fINULL\fR to \fInew_dhp2\fR
 140 and \fInew_pvtp2\fR. The system then expects the drivers to allocate new driver
 141 private data for the region that begins at the beginning of the mapping (for
 142 example, stored in \fIpvtp\fR) and to set \fI*new_pvtp1\fR to point to it.
 143 \fInew_dhp1\fR is the mapping handle of the newly mapped object.
 144 .sp
 145 .LP
 146 The drivers should free up the driver private data, \fIpvtp\fR, previously
 147 allocated in \fBdevmap_map\fR(9E) before returning to the system.
 148 .SH EXAMPLES
 149 .LP
 150 \fBExample 1 \fR\fBdevmap_unmap()\fR implementation
 151 .sp
 152 .in +2
 153 .nf
 154 static void
 155 xxdevmap_unmap(devmap_cookie_t dhp, void *pvtp, offset_t off,
 156     size_t len, devmap_cookie_t new_dhp1, void **new_pvtp1,
 157     devmap_cookie_t new_dhp2, void **new_pvtp2)
 158 {
 159     struct xxpvtdata *ptmp;
 160     struct xxpvtdata *p = (struct xxpvtdata *)pvtp;
 161     struct xx_softc  *softc = p->softc;
 162     mutex_enter(&softc->mutex);
 163     /*
 164      * If new_dhp1 is not NULL, create a new driver private data
 165      * for the region from the beginning of old mapping to off.
 166      */
 167     if (new_dhp1 != NULL) {
 168         ptmp = kmem_zalloc(sizeof (struct xxpvtdata), KM_SLEEP);
 169         ptmp->dhp = new_dhp1;
 170         ptmp->off = pvtp->off;
 171         ptmp->len = off - pvtp->off;
 172         *new_pvtp1 = ptmp;
 173     }
 174
 175     /*
 176      * If new_dhp2 is not NULL, create a new driver private data
 177      * for the region from off+len to the end of the old mapping.
 178      */
 179     if (new_dhp2 != NULL) {
 180         ptmp = kmem_zalloc(sizeof (struct xxpvtdata), KM_SLEEP);
 181         ptmp->off = off + len;
 182         ptmp->len = pvpt->len - (off + len - pvtp->off);
 183         ptmp->dhp = new_dhp2;
 184         *new_pvtp2 = ptmp;
 185     }
 186
 187     /* Destroy the driver private data - Device dependent */
 188     ...
 189     kmem_free(pvtp, sizeof (struct xxpvtdata));
 190     mutex_exit(&softc->mutex);
 191 }
 192 .fi
 193 .in -2
 194
 195 .SH SEE ALSO
 196 .sp
 197 .LP
 198 \fBexit\fR(2), \fBmunmap\fR(2), \fBdevmap_map\fR(9E),
 199 \fBdevmap_callback_ctl\fR(9S)
 200 .sp
 201 .LP
 202 \fIWriting Device Drivers\fR