Tribblix: manual page: rmalloc.9f

RMALLOC(9F) Kernel Functions for Drivers RMALLOC(9F)

NAME

rmalloc - allocate space from a resource map

SYNOPSIS

#include <sys/map.h>
#include <sys/ddi.h>

unsigned long rmalloc(struct map *mp, size_t size);

INTERFACE LEVEL

Architecture independent level 1 (DDI/DKI).

PARAMETERS

mp
Resource map from where the resource is drawn.

size
Number of units of the resource.

DESCRIPTION

The rmalloc() 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 rmallocmap(9F) or
rmallocmap_wait(9F). rmalloc() is one of six functions used for
resource map management. The other functions include:

rmalloc_wait(9F)
Allocate space from a resource map, wait if
necessary.

rmfree(9F)
Return previously allocated space to a map.

rmallocmap(9F)
Allocate a resource map and initialize it.

rmallocmap_wait(9F)
Allocate a resource map and initialize it. Wait
if necessary.

rmfreemap(9F)
Deallocate a resource map.

The rmalloc() 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 unsigned long set to the value of the index where
sufficient free space in the resource was found.

RETURN VALUES

Under normal conditions, rmalloc() returns the base index of the
allocated space. Otherwise, rmalloc() returns a 0 if all resource map
entries are already allocated.

CONTEXT

The rmalloc() function can be called from user, interrupt, or kernel
context.

EXAMPLES

Example 1: Illustrating the principles of map management

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 rmallocmap(9F) and rmfree(9F) functions.
rmallocmap(9F) is called to establish the number of slots or entries
in the map, and rmfree(9F) to initialize the resource area the map is
to manage. The following example is a fragment from a hypothetical
start routine and illustrates the following procedures:

o Returns error if the required amount of memory can not be
allocated (lines 9-17).

o Uses rmallocmap(9F) to configure the total number of
entries in the map, and rmfree(9F) to initialize the total
resource area.

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);
...

Example 2: Allocating buffers

The rmalloc() function is then used by the driver's read or write
routine to allocate buffers for specific data transfers. The
uiomove(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 DMA.

The next example illustrates the following procedures:

o The size of the I/O request is calculated and stored in
the size variable (line 16).

o The number of the resource units needed is calculated and
stored in the cnt variable (line 19).

o Space is allocated from the resource map through the
rmalloc() function using the cnt value (line 25). If the
allocation fails return error.

o The buffer address is calculated and stored in the addr
variable (line 31).

o The uiomove(9F) function is used to move data to the
allocated buffer (line 37).

o If the address passed to uiomove(9F) is invalid,
rmfree(9F) is called to release the previously allocated
buffer, and an EFAULT error is returned.

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 }