Kernel Functions for Drivers rmalloc(9F)
NAME
rmalloc - allocate space from a resource map
SYNOPSIS
#include
#include
unsigned long rmalloc(struct map *mp, sizet size);
INTERFACE LEVEL
Architecture independent level 1 (DI/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). rmalloc() is one of five functions used for
resource map management. The other functions include:
rmallocwait(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.
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 appropri-
ate 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.
SunOS 5.11 Last change: 16 Jan 2006 1
Kernel Functions for Drivers rmalloc(9F)
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 illus-
trates 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 estab-
lish 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 hypothet-
ical start routine and illustrates the following procedures:
o Panics the system if the required amount of memory
can not be allocated (lines 11-15).
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 XMAPSIZE 12
2 #define XBUFSIZE 2560
3 static struct map *xxmp; /* Private buffer space map */
...
4 xxstart()
5 /*
6 * Allocate private buffer. If insufficient memory,
7 * display message and halt system.
8 */
9 {
10 register caddrt bp;
...
11 if ((bp = kmemalloc(XBUFSIZE, KMNOSLEP) == 0) {
12
13 cmnerr(CEPANIC, "xxstart: kmemalloc failed before %d buffer"
14 "allocation", XBUFSIZE);
15 }
16
17 /*
18 * Initialize the resource map with number
19 * of slots in map.
20 */
SunOS 5.11 Last change: 16 Jan 2006 2
Kernel Functions for Drivers rmalloc(9F)
21 xxmp = rmallocmap(XMAPSIZE);
22
24 /*
25 * Initialize space management map with total
26 * buffer area it is to manage.
27 */
28 rmfree(xxmp, XBUFSIZE, bp);
...
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 10).
o Buffers are allocated through the rmalloc() func-
tion using the size value (line 15). If the alloca-
tion fails the system will panic.
o The uiomove(9F) function is used to move data to
the allocated buffer (line 23).
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 XBUFSIZE 2560
2 #define XMAXSIZE (XBUFSIZE / 4)
3
4 static struct map *xxmp; /* Private buffer space map */
...
5 xxread(devt dev, uiot *uiop, credt *credp)
6 {
7
8 register caddrt addr;
9 register int size;
10 size = min(COUNT, XMAXSIZE); /* Break large I/O */
11 /* request into small ones */
12 /*
SunOS 5.11 Last change: 16 Jan 2006 3
Kernel Functions for Drivers rmalloc(9F)
13 * Get buffer.
14 */
15 if ((addr = (caddrt)rmalloc(xxmp, size)) == 0)
16 cmnerr(CEPANIC, "read: rmalloc failed allocation of size %d",
17 size);
18
19 /*
20 * Move data to buffer. If invalid address is found,
21 * return buffer to map and return error code.
22 */
23 if (uiomove(addr, size, UIOREAD, uiop) == -1) {
24 rmfree(xxmp, size, addr);
25 return(EFAULT);
26 }
27 }
SEE ALSO
kmemalloc(9F), rmallocwait(9F), rmallocmap(9F),
rmfree(9F), rmfreemap(9F), uiomove(9F)
Writing Device Drivers
SunOS 5.11 Last change: 16 Jan 2006 4
|
