'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc.
.\" 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.
.\" 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.
.\" 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]
.TH RMALLOC 9F "Nov 11, 2016"
.SH NAME
rmalloc \- allocate space from a resource map
.SH SYNOPSIS
.LP
.nf
#include <sys/map.h>
#include <sys/ddi.h>
\fBunsigned long\fR \fBrmalloc\fR(\fBstruct map *\fR\fImp\fR, \fBsize_t\fR \fIsize\fR);
.fi
.SH INTERFACE LEVEL
.sp
.LP
Architecture independent level 1 (\fBDDI/DKI\fR).
.SH PARAMETERS
.sp
.ne 2
.na
\fB\fImp\fR\fR
.ad
.RS 8n
Resource map from where the resource is drawn.
.RE
.sp
.ne 2
.na
\fB\fIsize\fR\fR
.ad
.RS 8n
Number of units of the resource.
.RE
.SH DESCRIPTION
.sp
.LP
The \fBrmalloc()\fR function is used by a driver to allocate space from a
previously defined and initialized resource map. The map itself is allocated by
calling the function \fBrmallocmap\fR(9F) or \fBrmallocmap_wait\fR(9F).
\fBrmalloc()\fR is one of six
functions used for resource map management. The other functions include:
.sp
.ne 2
.na
\fB\fBrmalloc_wait\fR(9F)\fR
.ad
.RS 20n
Allocate space from a resource map, wait if necessary.
.RE
.sp
.ne 2
.na
\fB\fBrmfree\fR(9F)\fR
.ad
.RS 20n
Return previously allocated space to a map.
.RE
.sp
.ne 2
.na
\fB\fBrmallocmap\fR(9F)\fR
.ad
.RS 20n
Allocate a resource map and initialize it.
.RE
.sp
.ne 2
.na
\fB\fBrmallocmap_wait\fR(9F)\fR
.ad
.RS 20n
Allocate a resource map and initialize it. Wait if necessary.
.RE
.sp
.ne 2
.na
\fB\fBrmfreemap\fR(9F)\fR
.ad
.RS 20n
Deallocate a resource map.
.RE
.sp
.LP
The \fBrmalloc()\fR function allocates space from a resource map in terms of
arbitrary units. The system maintains the resource map by size and index,
computed in units appropriate for the resource. For example, units may be byte
addresses, pages of memory, or blocks. The normal return value is an
\fBunsigned long\fR set to the value of the index where sufficient free space
in the resource was found.
.SH RETURN VALUES
.sp
.LP
Under normal conditions, \fBrmalloc()\fR returns the base index of the
allocated space. Otherwise, \fBrmalloc()\fR returns a \fB0\fR if all resource
map entries are already allocated.
.SH CONTEXT
.sp
.LP
The \fBrmalloc()\fR function can be called from user, interrupt, or kernel
context.
.SH EXAMPLES
.LP
\fBExample 1 \fRIllustrating the principles of map management
.sp
.LP
The following example is a simple memory map, but it illustrates the principles
of map management. A driver allocates and initializes the map by calling both
the \fBrmallocmap\fR(9F) and \fBrmfree\fR(9F) functions. \fBrmallocmap\fR(9F)
is called to establish the number of slots or entries in the map, and
\fBrmfree\fR(9F) to initialize the resource area the map is to manage. The
following example is a fragment from a hypothetical \fBstart\fR routine and
illustrates the following procedures:
.RS +4
.TP
.ie t \(bu
.el o
Returns error if the required amount of memory can not be allocated (lines
9-17).
.RE
.RS +4
.TP
.ie t \(bu
.el o
Uses \fBrmallocmap\fR(9F) to configure the total number of entries in the map,
and \fBrmfree\fR(9F) to initialize the total resource area.
.RE
.sp
.in +2
.nf
1 #define XX_MAPSIZE 12
2 #define XX_SIZE 2560
3 #define XX_BUFSIZE (XX_MAPSIZE * XX_SIZE)
4
5 static struct map *xx_mp; /* Resource map */
6 static void *bp; /* Private buffer */
.\|.\|.
7 xxstart(\|)
8 {
.\|.\|.
9 /*
10 * Allocate private buffer. If insufficient memory,
11 * display message and return error.
12 */
13 if ((bp = kmem_alloc(XX_BUFSIZE, KM_NOSLEEP) == NULL) {
14 cmn_err(CE_WARN, "xxstart: kmem_alloc failed for %d bytes",
15 XX_BUFSIZE);
16 return (ENOMEM);
17 }
18
19 /*
20 * Allocate the resource map with number
21 * of slots in map.
22 */
23 xx_mp = rmallocmap(XX_MAPSIZE);
24
25 /*
26 * Initialize the resource map with total
27 * area it is to manage.
28 */
29 rmfree(xx_mp, XX_MAPSIZE, 1);
.\|.\|.\fI\fR
.fi
.in -2
.LP
\fBExample 2 \fRAllocating buffers
.sp
.LP
The \fBrmalloc()\fR function is then used by the driver's \fBread\fR or
\fBwrite\fR routine to allocate buffers for specific data transfers. The
\fBuiomove\fR(9F) function is used to move the data between user space and
local driver memory. The device then moves data between itself and local driver
memory through \fBDMA\fR.
.sp
.LP
The next example illustrates the following procedures:
.RS +4
.TP
.ie t \(bu
.el o
The size of the \fBI/O\fR request is calculated and stored in the \fIsize\fR
variable (line 16).
.RE
.RS +4
.TP
.ie t \(bu
.el o
The number of the resource units needed is calculated and stored in the
\fIcnt\fR variable (line 19).
.RE
.RS +4
.TP
.ie t \(bu
.el o
Space is allocated from the resource map through the \fBrmalloc()\fR function
using the \fIcnt\fR value (line 25). If the allocation fails return error.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The buffer address is calculated and stored in the \fIaddr\fR variable
(line 31).
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBuiomove\fR(9F) function is used to move data to the allocated buffer
(line 37).
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the address passed to \fBuiomove\fR(9F) is invalid, \fBrmfree\fR(9F) is
called to release the previously allocated buffer, and an \fBEFAULT\fR error is
returned.
.RE
.sp
.in +2
.nf
1 #define XX_MAPSIZE 12
2 #define XX_SIZE 2560
3 #define XX_BUFSIZE (XX_MAPSIZE * XX_SIZE)
4 #define XX_MAXSIZE (XX_BUFSIZE / 4)
5
6 static struct map *xx_mp; /* Resource map */
7 static void *bp; /* Private buffer */
...
8 xxread(dev_t dev, uio_t *uiop, cred_t *credp)
9 {
10
11 void *addr;
12 size_t size;
13 unsigned long idx;
14 unsigned long cnt;
15
16 size = min(COUNT, XX_MAXSIZE); /* Break large I/O */
17 /* request into small ones */
18
19 cnt = size / XX_SIZE; /* Calculate the number of */
20 /* chunks needed */
21
22 /*
23 * Get the buffer index.
24 */
25 if ((idx = rmalloc(xx_mp, cnt)) == 0)
26 return (ENOMEM);
27
28 /*
29 * Get the buffer address.
30 */
31 addr = bp + (idx - 1) * XX_SIZE;
32
33 /*
34 * Move data to buffer. If invalid address is found,
35 * return buffer to map and return error code.
36 */
37 if (uiomove(addr, size, UIO_READ, uiop) == -1) {
38 rmfree(xx_mp, cnt, idx);
39 return (EFAULT);
40 }
41 }\fI\fR
.fi
.in -2
.SH SEE ALSO
.sp
.LP
\fBkmem_alloc\fR(9F), \fBrmalloc_wait\fR(9F), \fBrmallocmap\fR(9F),
\fBrmallocmap_wait\fR(9F),
\fBrmfree\fR(9F), \fBrmfreemap\fR(9F), \fBuiomove\fR(9F)
.sp
.LP
\fIWriting Device Drivers\fR