1rmalloc(9F) Kernel Functions for Drivers rmalloc(9F)
2
6 rmalloc - allocate space from a resource map
7
9 #include <sys/map.h>
10 #include <sys/ddi.h>
11 unsigned long rmalloc(struct map *mp, size_t size);
15
18 Architecture independent level 1 (DDI/DKI).
19
21 mp Resource map from where the resource is drawn.
22 size Number of units of the resource.
25
28 The rmalloc() function is used by a driver to allocate space from a
29 previously defined and initialized resource map. The map itself is
30 allocated by calling the function rmallocmap(9F). rmalloc() is one of
31 five functions used for resource map management. The other functions
32 include:
33 rmalloc_wait(9F) Allocate space from a resource map, wait if neces‐
35 sary.
36 rmfree(9F) Return previously allocated space to a map.
39 rmallocmap(9F) Allocate a resource map and initialize it.
42 rmfreemap(9F) Deallocate a resource map.
45 The rmalloc() function allocates space from a resource map in terms of
49 arbitrary units. The system maintains the resource map by size and
50 index, computed in units appropriate for the resource. For example,
51 units may be byte addresses, pages of memory, or blocks. The normal
52 return value is an unsigned long set to the value of the index where
53 sufficient free space in the resource was found.
54
56 Under normal conditions, rmalloc() returns the base index of the allo‐
57 cated space. Otherwise, rmalloc() returns a 0 if all resource map
58 entries are already allocated.
59
61 The rmalloc() function can be called from user, interrupt, or kernel
62 context.
63
65 Example 1 Illustrating the principles of map management
66 The following example is a simple memory map, but it illustrates the
69 principles of map management. A driver allocates and initializes the
70 map by calling both the rmallocmap(9F) and rmfree(9F) functions. rmal‐
71 locmap(9F) is called to establish the number of slots or entries in the
72 map, and rmfree(9F) to initialize the resource area the map is to man‐
73 age. The following example is a fragment from a hypothetical start rou‐
74 tine and illustrates the following procedures:
75 o Panics the system if the required amount of memory can not
78 be allocated (lines 11-15).
79 o Uses rmallocmap(9F) to configure the total number of entries
81 in the map, and rmfree(9F) to initialize the total resource
82 area.
83 1 #define XX_MAPSIZE 12
85 2 #define XX_BUFSIZE 2560
86 3 static struct map *xx_mp; /* Private buffer space map */
87 ...
88 4 xxstart()
89 5 /*
90 6 * Allocate private buffer. If insufficient memory,
91 7 * display message and halt system.
92 8 */
93 9 {
94 10 register caddr_t bp;
95 ...
96 11 if ((bp = kmem_alloc(XX_BUFSIZE, KM_NOSLEEP) == 0) {
97 12
98 13 cmn_err(CE_PANIC, "xxstart: kmem_alloc failed before %d buffer"
99 14 "allocation", XX_BUFSIZE);
100 15 }
101 16
102 17 /*
103 18 * Initialize the resource map with number
104 19 * of slots in map.
105 20 */
106 21 xx_mp = rmallocmap(XX_MAPSIZE);
107 22
108 24 /*
109 25 * Initialize space management map with total
110 26 * buffer area it is to manage.
111 27 */
112 28 rmfree(xx_mp, XX_BUFSIZE, bp);
113 ...
114 Example 2 Allocating buffers
117 The rmalloc() function is then used by the driver's read or write rou‐
120 tine to allocate buffers for specific data transfers. The uiomove(9F)
121 function is used to move the data between user space and local driver
122 memory. The device then moves data between itself and local driver mem‐
123 ory through DMA.
124 The next example illustrates the following procedures:
128 o The size of the I/O request is calculated and stored in the
131 size variable (line 10).
132 o Buffers are allocated through the rmalloc() function using
134 the size value (line 15). If the allocation fails the system
135 will panic.
136 o The uiomove(9F) function is used to move data to the allo‐
138 cated buffer (line 23).
139 o If the address passed to uiomove(9F) is invalid, rmfree(9F)
141 is called to release the previously allocated buffer, and an
142 EFAULT error is returned.
143 1 #define XX_BUFSIZE 2560
145 2 #define XX_MAXSIZE (XX_BUFSIZE / 4)
146 3
147 4 static struct map *xx_mp; /* Private buffer space map */
148 ...
149 5 xxread(dev_t dev, uio_t *uiop, cred_t *credp)
150 6 {
151 7
152 8 register caddr_t addr;
153 9 register int size;
154 10 size = min(COUNT, XX_MAXSIZE); /* Break large I/O */
155 11 /* request into small ones */
156 12 /*
157 13 * Get buffer.
158 14 */
159 15 if ((addr = (caddr_t)rmalloc(xx_mp, size)) == 0)
160 16 cmn_err(CE_PANIC, "read: rmalloc failed allocation of size %d",
161 17 size);
162 18
163 19 /*
164 20 * Move data to buffer. If invalid address is found,
165 21 * return buffer to map and return error code.
166 22 */
167 23 if (uiomove(addr, size, UIO_READ, uiop) == -1) {
168 24 rmfree(xx_mp, size, addr);
169 25 return(EFAULT);
170 26 }
171 27 }
172
175 kmem_alloc(9F), rmalloc_wait(9F), rmallocmap(9F), rmfree(9F),
176 rmfreemap(9F), uiomove(9F)
177 Writing Device Drivers
180SunOS 5.11 16 Jan 2006 rmalloc(9F)