share/man/man9f/rmalloc.9f

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc.
   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 RMALLOC 9F "Nov 11, 2016"
   7 .SH NAME
   8 rmalloc \- allocate space from a resource map
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/map.h>
  13 #include <sys/ddi.h>
  14
  15
  16
  17 \fBunsigned long\fR \fBrmalloc\fR(\fBstruct map *\fR\fImp\fR, \fBsize_t\fR \fIsize\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .sp
  22 .LP
  23 Architecture independent level 1 (\fBDDI/DKI\fR).
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fImp\fR\fR
  29 .ad
  30 .RS 8n
  31 Resource map from where the resource is drawn.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIsize\fR\fR
  38 .ad
  39 .RS 8n
  40 Number of units of the resource.
  41 .RE
  42
  43 .SH DESCRIPTION
  44 .sp
  45 .LP
  46 The \fBrmalloc()\fR function is used by a driver to allocate space from a
  47 previously defined and initialized resource map. The map itself is allocated by
  48 calling the function \fBrmallocmap\fR(9F) or \fBrmallocmap_wait\fR(9F).
  49 \fBrmalloc()\fR is one of six
  50 functions used for resource map management. The other functions include:
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fBrmalloc_wait\fR(9F)\fR
  55 .ad
  56 .RS 20n
  57 Allocate space from a resource map, wait if necessary.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fBrmfree\fR(9F)\fR
  64 .ad
  65 .RS 20n
  66 Return previously allocated space to a map.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBrmallocmap\fR(9F)\fR
  73 .ad
  74 .RS 20n
  75 Allocate a resource map and initialize it.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBrmallocmap_wait\fR(9F)\fR
  82 .ad
  83 .RS 20n
  84 Allocate a resource map and initialize it.  Wait if necessary.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBrmfreemap\fR(9F)\fR
  91 .ad
  92 .RS 20n
  93 Deallocate a resource map.
  94 .RE
  95
  96 .sp
  97 .LP
  98 The \fBrmalloc()\fR function allocates space from a resource map in terms of
  99 arbitrary units. The system maintains the resource map by size and index,
 100 computed in units appropriate for the  resource. For example, units may be byte
 101 addresses, pages of memory, or blocks. The normal return value is an
 102 \fBunsigned long\fR set to the value of the index where sufficient free space
 103 in the resource was found.
 104 .SH RETURN VALUES
 105 .sp
 106 .LP
 107 Under normal conditions, \fBrmalloc()\fR returns the base index of the
 108 allocated space. Otherwise, \fBrmalloc()\fR returns a \fB0\fR if all resource
 109 map entries are already allocated.
 110 .SH CONTEXT
 111 .sp
 112 .LP
 113 The \fBrmalloc()\fR function can be called from user, interrupt, or kernel
 114 context.
 115 .SH EXAMPLES
 116 .LP
 117 \fBExample 1 \fRIllustrating the principles of map management
 118 .sp
 119 .LP
 120 The following example is a simple memory map, but it illustrates the principles
 121 of map management. A driver allocates and initializes the map by calling both
 122 the \fBrmallocmap\fR(9F) and \fBrmfree\fR(9F) functions. \fBrmallocmap\fR(9F)
 123 is called to establish the number of slots or entries in the map, and
 124 \fBrmfree\fR(9F) to initialize the resource area the map is to manage. The
 125 following example is a fragment from a hypothetical \fBstart\fR routine and
 126 illustrates the following procedures:
 127
 128 .RS +4
 129 .TP
 130 .ie t \(bu
 131 .el o
 132 Returns error if the required amount of memory can not be allocated (lines
 133 9-17).
 134 .RE
 135 .RS +4
 136 .TP
 137 .ie t \(bu
 138 .el o
 139 Uses \fBrmallocmap\fR(9F) to configure the total number of entries in the map,
 140 and \fBrmfree\fR(9F) to initialize the total resource area.
 141 .RE
 142 .sp
 143 .in +2
 144 .nf
 145 1   #define XX_MAPSIZE  12
 146 2   #define XX_SIZE     2560
 147 3   #define XX_BUFSIZE  (XX_MAPSIZE * XX_SIZE)
 148 4
 149 5   static struct map *xx_mp;         /* Resource map */
 150 6   static void *bp;                  /* Private buffer */
 151     .\|.\|.
 152 7   xxstart(\|)
 153 8   {
 154     .\|.\|.
 155 9     /*
 156 10     *  Allocate private buffer.  If insufficient memory,
 157 11     *  display message and return error.
 158 12     */
 159 13    if ((bp = kmem_alloc(XX_BUFSIZE, KM_NOSLEEP) == NULL)  {
 160 14        cmn_err(CE_WARN, "xxstart: kmem_alloc failed for %d bytes",
 161 15            XX_BUFSIZE);
 162 16        return (ENOMEM);
 163 17    }
 164 18
 165 19    /*
 166 20     * Allocate the resource map with number
 167 21     * of slots in map.
 168 22     */
 169 23    xx_mp = rmallocmap(XX_MAPSIZE);
 170 24
 171 25    /*
 172 26     * Initialize the resource map with total
 173 27     * area it is to manage.
 174 28     */
 175 29    rmfree(xx_mp, XX_MAPSIZE, 1);
 176       .\|.\|.\fI\fR
 177 .fi
 178 .in -2
 179
 180 .LP
 181 \fBExample 2 \fRAllocating buffers
 182 .sp
 183 .LP
 184 The \fBrmalloc()\fR function is then used by the driver's \fBread\fR or
 185 \fBwrite\fR routine to allocate buffers for specific data transfers. The
 186 \fBuiomove\fR(9F) function is used to move the data between user space and
 187 local driver memory. The device then moves data between itself and local driver
 188 memory through \fBDMA\fR.
 189
 190 .sp
 191 .LP
 192 The next example illustrates the following procedures:
 193
 194 .RS +4
 195 .TP
 196 .ie t \(bu
 197 .el o
 198 The size of the \fBI/O\fR request is calculated and stored in the \fIsize\fR
 199 variable (line 16).
 200 .RE
 201 .RS +4
 202 .TP
 203 .ie t \(bu
 204 .el o
 205 The number of the resource units needed is calculated and stored in the
 206 \fIcnt\fR variable (line 19).
 207 .RE
 208 .RS +4
 209 .TP
 210 .ie t \(bu
 211 .el o
 212 Space is allocated from the resource map through the \fBrmalloc()\fR function
 213 using the \fIcnt\fR value (line 25).  If the allocation fails return error.
 214 .RE
 215 .RS +4
 216 .TP
 217 .ie t \(bu
 218 .el o
 219 The buffer address is calculated and stored in the \fIaddr\fR variable
 220 (line 31).
 221 .RE
 222 .RS +4
 223 .TP
 224 .ie t \(bu
 225 .el o
 226 The \fBuiomove\fR(9F) function is used to move data to the allocated buffer
 227 (line 37).
 228 .RE
 229 .RS +4
 230 .TP
 231 .ie t \(bu
 232 .el o
 233 If the address passed to \fBuiomove\fR(9F) is invalid, \fBrmfree\fR(9F) is
 234 called to release the previously allocated buffer, and an \fBEFAULT\fR error is
 235 returned.
 236 .RE
 237 .sp
 238 .in +2
 239 .nf
 240 1   #define XX_MAPSIZE  12
 241 2   #define XX_SIZE     2560
 242 3   #define XX_BUFSIZE  (XX_MAPSIZE * XX_SIZE)
 243 4   #define XX_MAXSIZE  (XX_BUFSIZE / 4)
 244 5
 245 6   static struct map *xx_mp;         /* Resource map */
 246 7   static void *bp;                  /* Private buffer */
 247     ...
 248 8   xxread(dev_t dev, uio_t *uiop, cred_t *credp)
 249 9   {
 250 10
 251 11    void *addr;
 252 12    size_t size;
 253 13    unsigned long idx;
 254 14    unsigned long cnt;
 255 15
 256 16    size = min(COUNT, XX_MAXSIZE);  /* Break large I/O  */
 257 17                                    /* request into small ones */
 258 18
 259 19    cnt = size / XX_SIZE;           /* Calculate the number of */
 260 20                                    /* chunks needed */
 261 21
 262 22    /*
 263 23     * Get the buffer index.
 264 24     */
 265 25    if ((idx = rmalloc(xx_mp, cnt)) == 0)
 266 26        return (ENOMEM);
 267 27
 268 28    /*
 269 29     * Get the buffer address.
 270 30     */
 271 31    addr = bp + (idx - 1) * XX_SIZE;
 272 32
 273 33    /*
 274 34     * Move data to buffer.  If invalid address is found,
 275 35     * return buffer to map and return error code.
 276 36     */
 277 37    if (uiomove(addr, size, UIO_READ, uiop) == -1)  {
 278 38        rmfree(xx_mp, cnt, idx);
 279 39        return (EFAULT);
 280 40    }
 281 41  }\fI\fR
 282 .fi
 283 .in -2
 284
 285 .SH SEE ALSO
 286 .sp
 287 .LP
 288 \fBkmem_alloc\fR(9F), \fBrmalloc_wait\fR(9F), \fBrmallocmap\fR(9F),
 289 \fBrmallocmap_wait\fR(9F),
 290 \fBrmfree\fR(9F), \fBrmfreemap\fR(9F), \fBuiomove\fR(9F)
 291 .sp
 292 .LP
 293 \fIWriting Device Drivers\fR