share/man/man9e/devmap.9e

   1 '\" te
   2 .\"  Copyright (c) 2000, Sun Microsystems, Inc.,  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH DEVMAP 9E "Jan 15, 1997"
   8 .SH NAME
   9 devmap \- validate and translate virtual mapping for memory mapped device
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddi.h>
  14 #include <sys/sunddi.h>
  15
  16
  17
  18 \fBint prefix\fR\fBdevmap\fR(\fBdev_t\fR \fIdev\fR, \fBdevmap_cookie_t\fR \fIdhp\fR, \fBoffset_t\fR \fIoff\fR,
  19      \fBsize_t\fR \fIlen\fR, \fBsize_t *\fR\fImaplen\fR, \fBuint_t\fR \fImodel\fR);
  20 .fi
  21
  22 .SH INTERFACE LEVEL
  23 .sp
  24 .LP
  25 Solaris DDI specific (Solaris DDI).
  26 .SH PARAMETERS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIdev\fR \fR
  31 .ad
  32 .RS 11n
  33 Device whose memory is to be mapped.
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIdhp\fR \fR
  40 .ad
  41 .RS 11n
  42 An opaque mapping handle that the system uses to describe the mapping.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIoff\fR \fR
  49 .ad
  50 .RS 11n
  51 User offset within the logical device memory at which the mapping begins.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIlen\fR \fR
  58 .ad
  59 .RS 11n
  60 Length (in bytes) of the mapping to be mapped.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fImaplen\fR \fR
  67 .ad
  68 .RS 11n
  69 Pointer to length (in bytes) of mapping that has been validated. \fImaplen\fR
  70 is less than or equal to  \fIlen\fR.
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fImodel\fR \fR
  77 .ad
  78 .RS 11n
  79 The data model type of the current thread.
  80 .RE
  81
  82 .SH DESCRIPTION
  83 .sp
  84 .LP
  85 \fBdevmap()\fR is a required entry point for character drivers supporting
  86 memory-mapped devices if the drivers use the devmap framework to set up the
  87 mapping. A memory mapped device has memory  that can be mapped into a process's
  88 address space. The \fBmmap\fR(2) system call, when applied to a character
  89 special file, allows this device memory to be mapped into user space for direct
  90 access by the user applications.
  91 .sp
  92 .LP
  93 As a result of a \fBmmap\fR(2) system call, the system calls the \fBdevmap()\fR
  94 entry point during the mapping setup when \fBD_DEVMAP\fR is set in the
  95 \fBcb_flag\fR field of the \fBcb_ops\fR(9S) structure, and any of the following
  96 conditions apply:
  97 .RS +4
  98 .TP
  99 .ie t \(bu
 100 .el o
 101 \fBddi_devmap_segmap\fR(9F) is used as the \fBsegmap\fR(9E) entry point.
 102 .RE
 103 .RS +4
 104 .TP
 105 .ie t \(bu
 106 .el o
 107 \fBsegmap\fR(9E) entry point is set to \fINULL.\fR
 108 .RE
 109 .RS +4
 110 .TP
 111 .ie t \(bu
 112 .el o
 113 \fBmmap\fR(9E) entry point is set to \fINULL.\fR
 114 .RE
 115 .sp
 116 .LP
 117 Otherwise \fBEINVAL\fR will be returned to \fBmmap\fR(2).
 118 .sp
 119 .LP
 120 Device drivers should use \fBdevmap()\fR to validate the user mappings to the
 121 device, to translate the logical offset,  \fIoff\fR, to the corresponding
 122 physical offset within the device address space, and to pass the mapping
 123 information to the system for setting up the mapping.
 124 .sp
 125 .LP
 126 \fIdhp\fR is a device mapping handle that the system uses to describe a mapping
 127 to a memory that is either contiguous in physical address space or in kernel
 128 virtual address space. The system may create multiple mapping  handles in one
 129 \fBmmap\fR(2) system call (for example, if the mapping contains multiple
 130 physically discontiguous memory regions).
 131 .sp
 132 .LP
 133 \fImodel\fR returns the C Language Type Model which the current thread expects.
 134 It is set to \fBDDI_MODEL_ILP32\fR if the current thread expects 32-bit (
 135 \fIILP32\fR) semantics, or \fBDDI_MODEL_LP64\fR if the current thread expects
 136 64-bit ( \fILP64\fR) semantics. \fImodel\fR is used in combination with
 137 \fBddi_model_convert_from\fR(9F) to determine whether there is a data model
 138 mismatch between the current thread and the device driver. The device driver
 139 might have to adjust the shape of data structures before exporting them to a
 140 user thread which supports a different data model.
 141 .sp
 142 .LP
 143 \fBdevmap()\fR should return \fBEINVAL\fR if the logical offset, \fIoff\fR, is
 144 out of the range of memory exported by the device to user space. If \fIoff\fR +
 145 \fIlen\fR exceeds the range of the contiguous memory, \fBdevmap()\fR should
 146 return the length from  \fIoff\fR to the end of the contiguous memory region.
 147 The system will repeatedly call \fBdevmap()\fR until the original mapping
 148 length is satisfied. The driver sets \fI*maplen\fR to the validated length
 149 which must be either less than or equal to \fIlen\fR.
 150 .sp
 151 .LP
 152 The \fBdevmap()\fR entry point must initialize the mapping parameters before
 153 passing them to the system through either \fBdevmap_devmem_setup\fR(9F) (if the
 154 memory being mapped is device memory) or \fBdevmap_umem_setup\fR(9F) (if the
 155 memory being mapped is kernel memory). The \fBdevmap()\fR entry point
 156 initializes the mapping parameters by mapping the control callback structure
 157 (see \fBdevmap_callback_ctl\fR(9S)), the device access attributes, mapping
 158 length, maximum protection possible for the mapping, and optional mapping
 159 flags. See \fBdevmap_devmem_setup\fR(9F) and \fBdevmap_umem_setup\fR(9F) for
 160 further information on initializing the mapping parameters.
 161 .sp
 162 .LP
 163 The system will copy the driver's \fBdevmap_callback_ctl\fR(9S) data into its
 164 private memory so the drivers do not need to keep the data structure after the
 165 return from either \fBdevmap_devmem_setup\fR(9F) or
 166 \fBdevmap_umem_setup\fR(9F).
 167 .sp
 168 .LP
 169 For device mappings, the system establishes the mapping to the physical address
 170 that corresponds to \fIoff\fR by passing the register number and the offset
 171 within the register address space to  \fBdevmap_devmem_setup\fR(9F).
 172 .sp
 173 .LP
 174 For kernel memory mapping, the system selects a user virtual address that is
 175 aligned with the kernel address being mapped for cache coherence.
 176 .SH RETURN VALUES
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fB0\fR \fR
 181 .ad
 182 .RS 12n
 183 Successful completion.
 184 .RE
 185
 186 .sp
 187 .ne 2
 188 .na
 189 \fBNon-zero\fR
 190 .ad
 191 .RS 12n
 192 An error occurred.
 193 .RE
 194
 195 .SH EXAMPLES
 196 .LP
 197 \fBExample 1 \fRImplementing the \fBdevmap()\fR Entry Point
 198 .sp
 199 .LP
 200 The following is an example of the implementation for the \fBdevmap()\fR entry
 201 point. For mapping device memory, \fBdevmap()\fR calls
 202 \fBdevmap_devmem_setup\fR(9F) with the register number, \fIrnumber\fR, and the
 203 offset within the register, \fIroff\fR. For mapping kernel memory, the driver
 204 must first allocate the kernel memory using \fBddi_umem_alloc\fR(9F). For
 205 example, \fBddi_umem_alloc\fR(9F) can be called in the \fBattach\fR(9E)
 206 routine. The resulting kernel memory cookie is stored in the driver soft state
 207 structure, which is accessible from the \fBdevmap()\fR entry point. See
 208 \fBddi_soft_state\fR(9F). \fBdevmap()\fR passes the cookie obtained from
 209 \fBddi_umem_alloc\fR(9F) and the offset within the allocated kernel memory to
 210 \fBdevmap_umem_setup\fR(9F). The corresponding \fBddi_umem_free\fR(9F) can be
 211 made in the \fBdetach\fR(9E) routine to free up the kernel memory.
 212
 213 .sp
 214 .in +2
 215 .nf
 216 \&.\|.\|.
 217 #define MAPPING_SIZE 0x2000        /* size of the mapping */
 218 #define MAPPING_START 0x70000000   /* logical offset at beginning
 219                                       of the mapping */
 220 static
 221 struct devmap_callback_ctl xxmap_ops = {
 222            DEVMAP_OPS_REV,                /* devmap_ops version number */
 223            xxmap_map,                     /* devmap_ops map routine */
 224            xxmap_access,                  /* devmap_ops access routine */
 225            xxmap_dup,                     /* devmap_ops dup routine */
 226            xxmap_unmap,                   /* devmap_ops unmap routine  */
 227 };
 228
 229
 230 static int
 231 xxdevmap(dev_t dev, devmap_cookie_t dhp, offset_t off, size_t len,
 232    size_t *maplen, uint_t model)
 233 {
 234    int    instance;
 235    struct xxstate *xsp;
 236    struct ddi_device_acc_attr *endian_attr;
 237    struct devmap_callback_ctl *callbackops = NULL;
 238    ddi_umem_cookie_t cookie;
 239    dev_info_t *dip;
 240    offset_t   roff;
 241    offset_t   koff;
 242    uint_t rnumber;
 243    uint_t maxprot;
 244    uint_t flags = 0;
 245    size_t length;
 246    int    err;
 247
 248    /* get device soft state */
 249    instance = getminor(dev);
 250    xsp = ddi_get_soft_state(statep, instance);
 251    if (xsp == NULL)
 252       return (-1);
 253
 254    dip = xsp->dip;
 255    /* check for a valid offset */
 256    if ( \fIoff is invalid\fR )
 257       return (-1);
 258    /* check if len is within the range of contiguous memory */
 259    if ( \fB(\fR\fIoff\fR\fB + \fR\fIlen\fR\fB)\fR \fIis contiguous\fR\fB\&.)\fR
 260        length = len;
 261    else
 262        length = MAPPING_START + MAPPING_SIZE - off;
 263
 264    /* device access attributes */
 265    endian_attr = xsp->endian_attr;
 266
 267    if ( \fI off is referring to a device memory. \fR ) {
 268                                  /* assign register related parameters */
 269       rnumber = XXX;             /* index to register set at off */
 270       roff = XXX;                /* offset of rnumber at local bus */
 271       callbackops = &xxmap_ops;  /* do all callbacks for this mapping */
 272       maxprot = PROT_ALL;        /* allowing all access */
 273       if ((err = devmap_devmem_setup(dhp, dip, callbackops, rnumber, roff,
 274                length, maxprot, flags, endian_attr)) < 0)
 275
 276
 277           return (err);
 278
 279    } else if (\fI off is referring to a kernel memory.\fR) {
 280       cookie = xsp->cookie;      /* cookie is obtained from
 281                                     ddi_umem_alloc(9F) */
 282       koff = XXX;                /* offset within the kernel memory. */
 283       callbackops = NULL;        /* don't do callback for this mapping */
 284       maxprot = PROT_ALL;        /* allowing all access */
 285       if ((err = devmap_umem_setup(dhp, dip, callbackops, cookie, koff,
 286                length, maxprot, flags, endian_attr)) < 0)
 287          return (err);
 288   }
 289
 290             *maplen = length;
 291     return (0);
 292 }
 293 .fi
 294 .in -2
 295
 296 .SH SEE ALSO
 297 .sp
 298 .LP
 299 \fBmmap\fR(2), \fBattach\fR(9E), \fBdetach\fR(9E), \fBmmap\fR(9E),
 300 \fBsegmap\fR(9E), \fBddi_devmap_segmap\fR(9F),
 301 \fBddi_model_convert_from\fR(9F), \fBddi_soft_state\fR(9F),
 302 \fBddi_umem_alloc\fR(9F), \fBddi_umem_free\fR(9F),
 303 \fBdevmap_devmem_setup\fR(9F), \fBdevmap_setup\fR(9F),
 304 \fBdevmap_umem_setup\fR(9F), \fBcb_ops\fR(9S), \fBdevmap_callback_ctl\fR(9S)
 305 .sp
 306 .LP
 307 \fIWriting Device Drivers\fR