rmfreemap(9f) [opensolaris man page]
rmallocmap(9F) Kernel Functions for Drivers rmallocmap(9F) NAME
rmallocmap, rmallocmap_wait, rmfreemap - allocate and free resource maps SYNOPSIS
#include <sys/ddi.h> #include <sys/sunddi.h> struct map *rmallocmap(size_t mapsize); struct map *rmallocmap_wait(size_t mapsize); void rmfreemap(struct map *mp); INTERFACE LEVEL
Architecture independent level 1 (DDI/DKI). PARAMETERS
mapsize Number of entries for the map. mp A pointer to the map structure to be deallocated. DESCRIPTION
rmallocmap() dynamically allocates a resource map structure. The argument mapsize defines the total number of entries in the map. In par- ticular, it is the total number of allocations that can be outstanding at any one time. rmallocmap() initializes the map but does not associate it with the actual resource. In order to associate the map with the actual resource, a call to rmfree(9F) is used to make the entirety of the actual resource available for allocation, starting from the first index into the resource. Typically, the call to rmallocmap() is followed by a call to rmfree(9F), passing the address of the map returned from rmallocmap(), the total size of the resource, and the first index into the actual resource. The resource map allocated by rmallocmap() can be used to describe an arbitrary resource in whatever allocation units are appropriate, such as blocks, pages, or data structures. This resource can then be managed by the system by subsequent calls to rmalloc(9F), rmal- loc_wait(9F), and rmfree(9F). rmallocmap_wait() is similar to rmallocmap(), with the exception that it will wait for space to become available if necessary. rmfreemap() deallocates a resource map structure previously allocated by rmallocmap() or rmallocmap_wait(). The argument mp is a pointer to the map structure to be deallocated. RETURN VALUES
Upon successful completion, rmallocmap() and rmallocmap_wait() return a pointer to the newly allocated map structure. Upon failure, rmal- locmap() returns a NULL pointer. CONTEXT
rmallocmap() and rmfreemap() can be called from user, kernel, or interrupt context. rmallocmap_wait() can only be called from user or kernel context. SEE ALSO
rmalloc(9F), rmalloc_wait(9F), rmfree(9F) Writing Device Drivers SunOS 5.11 20 Nov 1996 rmallocmap(9F)
Check Out this Related Man Page
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). rmalloc() is one of five 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. 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 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 XX_MAPSIZE 12 2 #define XX_BUFSIZE 2560 3 static struct map *xx_mp; /* Private buffer space map */ ... 4 xxstart() 5 /* 6 * Allocate private buffer. If insufficient memory, 7 * display message and halt system. 8 */ 9 { 10 register caddr_t bp; ... 11 if ((bp = kmem_alloc(XX_BUFSIZE, KM_NOSLEEP) == 0) { 12 13 cmn_err(CE_PANIC, "xxstart: kmem_alloc failed before %d buffer" 14 "allocation", XX_BUFSIZE); 15 } 16 17 /* 18 * Initialize the resource map with number 19 * of slots in map. 20 */ 21 xx_mp = rmallocmap(XX_MAPSIZE); 22 24 /* 25 * Initialize space management map with total 26 * buffer area it is to manage. 27 */ 28 rmfree(xx_mp, XX_BUFSIZE, 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() function using the size value (line 15). If the allocation 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 XX_BUFSIZE 2560 2 #define XX_MAXSIZE (XX_BUFSIZE / 4) 3 4 static struct map *xx_mp; /* Private buffer space map */ ... 5 xxread(dev_t dev, uio_t *uiop, cred_t *credp) 6 { 7 8 register caddr_t addr; 9 register int size; 10 size = min(COUNT, XX_MAXSIZE); /* Break large I/O */ 11 /* request into small ones */ 12 /* 13 * Get buffer. 14 */ 15 if ((addr = (caddr_t)rmalloc(xx_mp, size)) == 0) 16 cmn_err(CE_PANIC, "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, UIO_READ, uiop) == -1) { 24 rmfree(xx_mp, size, addr); 25 return(EFAULT); 26 } 27 } SEE ALSO
kmem_alloc(9F), rmalloc_wait(9F), rmallocmap(9F), rmfree(9F), rmfreemap(9F), uiomove(9F) Writing Device Drivers SunOS 5.11 16 Jan 2006 rmalloc(9F)