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"
8 rmalloc \- allocate space from a resource map
17 \fBunsigned long\fR \fBrmalloc\fR(\fBstruct map *\fR\fImp\fR, \fBsize_t\fR \fIsize\fR);
23 Architecture independent level 1 (\fBDDI/DKI\fR).
31 Resource map from where the resource is drawn.
40 Number of units of the resource.
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:
54 \fB\fBrmalloc_wait\fR(9F)\fR
57 Allocate space from a resource map, wait if necessary.
63 \fB\fBrmfree\fR(9F)\fR
66 Return previously allocated space to a map.
72 \fB\fBrmallocmap\fR(9F)\fR
75 Allocate a resource map and initialize it.
81 \fB\fBrmallocmap_wait\fR(9F)\fR
84 Allocate a resource map and initialize it. Wait if necessary.
90 \fB\fBrmfreemap\fR(9F)\fR
93 Deallocate a resource map.
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.
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.
113 The \fBrmalloc()\fR function can be called from user, interrupt, or kernel
117 \fBExample 1 \fRIllustrating the principles of map management
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:
132 Returns error if the required amount of memory can not be allocated (lines
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.
145 1 #define XX_MAPSIZE 12
146 2 #define XX_SIZE 2560
147 3 #define XX_BUFSIZE (XX_MAPSIZE * XX_SIZE)
149 5 static struct map *xx_mp; /* Resource map */
150 6 static void *bp; /* Private buffer */
156 10 * Allocate private buffer. If insufficient memory,
157 11 * display message and return error.
159 13 if ((bp = kmem_alloc(XX_BUFSIZE, KM_NOSLEEP) == NULL) {
160 14 cmn_err(CE_WARN, "xxstart: kmem_alloc failed for %d bytes",
166 20 * Allocate the resource map with number
167 21 * of slots in map.
169 23 xx_mp = rmallocmap(XX_MAPSIZE);
172 26 * Initialize the resource map with total
173 27 * area it is to manage.
175 29 rmfree(xx_mp, XX_MAPSIZE, 1);
181 \fBExample 2 \fRAllocating buffers
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.
192 The next example illustrates the following procedures:
198 The size of the \fBI/O\fR request is calculated and stored in the \fIsize\fR
205 The number of the resource units needed is calculated and stored in the
206 \fIcnt\fR variable (line 19).
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.
219 The buffer address is calculated and stored in the \fIaddr\fR variable
226 The \fBuiomove\fR(9F) function is used to move data to the allocated buffer
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
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)
245 6 static struct map *xx_mp; /* Resource map */
246 7 static void *bp; /* Private buffer */
248 8 xxread(dev_t dev, uio_t *uiop, cred_t *credp)
253 13 unsigned long idx;
254 14 unsigned long cnt;
256 16 size = min(COUNT, XX_MAXSIZE); /* Break large I/O */
257 17 /* request into small ones */
259 19 cnt = size / XX_SIZE; /* Calculate the number of */
260 20 /* chunks needed */
263 23 * Get the buffer index.
265 25 if ((idx = rmalloc(xx_mp, cnt)) == 0)
269 29 * Get the buffer address.
271 31 addr = bp + (idx - 1) * XX_SIZE;
274 34 * Move data to buffer. If invalid address is found,
275 35 * return buffer to map and return error code.
277 37 if (uiomove(addr, size, UIO_READ, uiop) == -1) {
278 38 rmfree(xx_mp, cnt, idx);
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)
293 \fIWriting Device Drivers\fR