3 <!-- =============================================================== -->
7 <!-- eCos memory allocation support -->
9 <!-- =============================================================== -->
10 <!-- ####COPYRIGHTBEGIN#### -->
12 <!-- =============================================================== -->
13 <!-- Copyright (C) 2005 Andrew Lunn -->
14 <!-- This material may be distributed only subject to the terms -->
15 <!-- and conditions set forth in the Open Publication License, v1.0 -->
16 <!-- or later (the latest version is presently available at -->
17 <!-- http://www.opencontent.org/openpub/) -->
18 <!-- Distribution of the work or derivative of the work in any -->
19 <!-- standard (paper) book form is prohibited unless prior -->
20 <!-- permission obtained from the copyright holder -->
21 <!-- =============================================================== -->
23 <!-- ####COPYRIGHTEND#### -->
24 <!-- =============================================================== -->
25 <!-- #####DESCRIPTIONBEGIN#### -->
26 <!-- This explains the memory allocation functions which were -->
27 <!-- origionally part of the KAPI, but there moved a long long time -->
28 <!-- ago. I used the old documentation as a basis, so credit should -->
29 <!-- realy go to somebody else -->
30 <!-- ####DESCRIPTIONEND#### -->
31 <!-- =============================================================== -->
35 <PART id="services-memalloc-common">
36 <TITLE>Memory Allocation</TITLE>
37 <CHAPTER id="memalloc">
38 <TITLE>eCos Memory Pools</TITLE>
39 <SECT1 id="ecos-memory-pools">
40 <TITLE>eCos Memory pools</TITLE>
43 There are three sorts of memory pools. A variable size memory pool
44 is for allocating blocks of any size. A fixed size memory pool, has
45 the block size specified when the pool is created and only provides
46 blocks of that size. Both of these pools must be explicitly created.
47 The third type is the traditional heap which can be accessed using
48 malloc and friends.</PARA>
50 <refentry id="variable-pools">
53 <refentrytitle>Variable Size Allocation Pools</refentrytitle>
57 <refname>cyg_mempool_var_create</refname>
58 <refname>cyg_mempool_var_delete</refname>
59 <refname>cyg_mempool_var_alloc</refname>
60 <refname>cyg_mempool_var_timed_alloc</refname>
61 <refname>cyg_mempool_var_try_alloc</refname>
62 <refname>cyg_mempool_var_free</refname>
63 <refname>cyg_mempool_var_waiting</refname>
64 <refname>cyg_mempool_var_get_info</refname>
65 <refpurpose>Variable Size Allocation Pools</refpurpose>
71 #include <cyg/kernel/kapi.h>
74 <funcdef>void <function>cyg_mempool_var_create</function></funcdef>
75 <paramdef>void* <parameter>base</parameter></paramdef>
76 <paramdef>cyg_uint32 <parameter>size</parameter></paramdef>
77 <paramdef>cyg_handle_t* <parameter>varpool</parameter></paramdef>
78 <paramdef>cyg_mempool_var* <parameter>var</parameter></paramdef>
81 <funcdef>void <function>cyg_mempool_var_delete</function></funcdef>
82 <paramdef>cyg_handle_t <parameter>varpool</parameter></paramdef>
85 <funcdef>void* <function>cyg_mempool_var_alloc</function></funcdef>
86 <paramdef>cyg_handle_t <parameter>varpool</parameter></paramdef>
87 <paramdef>cyg_uint32 <parameter>size</parameter></paramdef>
90 <funcdef>void* <function>cyg_mempool_var_timed_alloc</function></funcdef>
91 <paramdef>cyg_handle_t <parameter>varpool</parameter></paramdef>
92 <paramdef>cyg_uint32 <parameter>size</parameter></paramdef>
93 <paramdef>cyg_tick_count_t <parameter>abstime</parameter></paramdef>
96 <funcdef>void* <function>cyg_mempool_var_try_alloc</function></funcdef>
97 <paramdef>cyg_handle_t <parameter>varpool</parameter></paramdef>
98 <paramdef>cyg_uint32 <parameter>size</parameter></paramdef>
101 <funcdef>void <function>cyg_mempool_var_free</function></funcdef>
102 <paramdef>cyg_handle_t <parameter>varpool</parameter></paramdef>
103 <paramdef>void* <parameter>p</parameter></paramdef>
106 <funcdef>cyg_bool_t <function>cyg_mempool_var_waiting</function></funcdef>
107 <paramdef>cyg_handle_t <parameter>varpool</parameter></paramdef>
110 <funcdef>void <function>cyg_mempool_var_get_info</function></funcdef>
111 <paramdef>cyg_handle_t <parameter>varpool</parameter></paramdef>
112 <paramdef>cyg_mempool_info* <parameter>info</parameter></paramdef>
117 <refsect1 id="memalloc-variable-description"><title>Description</title>
120 The variable size memory pool functions are used for allocating
121 blocks of any size. Before memory can be allocated the pool must
122 first be created by calling
123 <function>cyg_mempool_var_create()</function>. The parameter
124 <parameter>base</parameter> is a point to the bottom of the
125 memory area to be used by the pool and
126 <parameter>size</parameter> is the size of the memory area in
127 bytes. It also takes a pointer to a
128 <structname>cyg_mempool_var</structname> data structure which is
129 typically statically allocated, and may be part of a larger data
130 structure. It should be noted that some memory is take from the
131 pool for book keeping purposes. If a memory pool is no longer
132 required and there are not threads waiting to allocate memory
133 from it, it can be destroyed with
134 <function>cyg_mempool_var_delete()</function>.
138 Memory can be allocated from the pool using a number of
139 functions. They all take the
140 paramters<parameter>varpool</parameter>which indicates which
141 pool should be used and the <parameter>size</parameter>which
142 indicates who big a memory area should be
143 allocated. <function>cyg_mempool_var_alloc()</function> will
144 block until the memory becomes
145 available. <function>cyg_mempool_tryalloc()</function>will try
146 not block if no memory is available and will return
147 <literal>NULL</literal>. Otherwise a pointer to the allocated
148 memory will be returned.
149 <function>cyg_mempool_var_timed_alloc()</function> will block if
150 memory is not available and wait for memory to become available
151 until the time<parameter>abstime</parameter> is reached. It will
152 then return <literal>NULL</literal>.
156 Allocated memory can be freed using the function <function>cyg_mempool_var_free()</function>.
160 Lastly it is possible to query information about the pool using
162 <function>cyg_mempool_var_get_info()</function>. This takes a
163 pointer to the structure <structname>cyg_mempool_info</structname> which is:
177 <refentry id="fixed-pools">
180 <refentrytitle>Fixed Size Allocation Pools</refentrytitle>
184 <refname>cyg_mempool_fix_create</refname>
185 <refname>cyg_mempool_fix_delete</refname>
186 <refname>cyg_mempool_fix_alloc</refname>
187 <refname>cyg_mempool_fix_timed_alloc</refname>
188 <refname>cyg_mempool_fix_try_alloc</refname>
189 <refname>cyg_mempool_fix_free</refname>
190 <refname>cyg_mempool_fix_waiting</refname>
191 <refname>cyg_mempool_fix_get_info</refname>
192 <refpurpose>Fixed Size Allocation Pools</refpurpose>
198 #include <cyg/kernel/kapi.h>
201 <funcdef>void <function>cyg_mempool_fix_create</function></funcdef>
202 <paramdef>void* <parameter>base</parameter></paramdef>
203 <paramdef>cyg_uint32 <parameter>size</parameter></paramdef>
204 <paramdef>cyg_uint32 <parameter>blocksize</parameter></paramdef>
205 <paramdef>cyg_handle_t* <parameter>fixpool</parameter></paramdef>
206 <paramdef>cyg_mempool_var* <parameter>var</parameter></paramdef>
209 <funcdef>void <function>cyg_mempool_fix_delete</function></funcdef>
210 <paramdef>cyg_handle_t <parameter>fixpool</parameter></paramdef>
213 <funcdef>void* <function>cyg_mempool_fix_alloc</function></funcdef>
214 <paramdef>cyg_handle_t <parameter>fixpool</parameter></paramdef>
217 <funcdef>void* <function>cyg_mempool_fix_timed_alloc</function></funcdef>
218 <paramdef>cyg_handle_t <parameter>fixpool</parameter></paramdef>
219 <paramdef>cyg_tick_count_t <parameter>abstime</parameter></paramdef>
222 <funcdef>void* <function>cyg_mempool_fix_try_alloc</function></funcdef>
223 <paramdef>cyg_handle_t <parameter>fixpool</parameter></paramdef>
226 <funcdef>void <function>cyg_mempool_fix_free</function></funcdef>
227 <paramdef>cyg_handle_t <parameter>fixpool</parameter></paramdef>
228 <paramdef>void* <parameter>p</parameter></paramdef>
231 <funcdef>cyg_bool_t <function>cyg_mempool_fix_waiting</function></funcdef>
232 <paramdef>cyg_handle_t <parameter>fixpool</parameter></paramdef>
235 <funcdef>void <function>cyg_mempool_fix_get_info</function></funcdef>
236 <paramdef>cyg_handle_t <parameter>fixpool</parameter></paramdef>
237 <paramdef>cyg_mempool_info* <parameter>info</parameter></paramdef>
242 <refsect1 id="memalloc-fixed-description"><title>Description</title>
245 The fixed size memory pool functions are used for allocating
246 blocks of the same size. The allocation and free functions are
247 more efficient than the variable size pools, but are naturally
248 limited to being only able to allocate blocks of a sized
249 size. Before memory can be allocated the pool must first be
251 <function>cyg_mempool_fix_create()</function>.
253 The parameter <parameter>base</parameter> is a point to the
254 bottom of the memory area to be used by the pool and
255 <parameter>size</parameter> is the size of the memory area in
256 bytes. <parameter>blocksize</parameter> indicates the size of
257 each allocation in bytes. The function also takes a pointer to a
258 <structname>cyg_mempool_fix</structname> data structure which is
259 typically statically allocated, and may be part of a larger data
260 structure. It should be noted that some memory is take from the
261 pool for book keeping purposes. If a memory pool is no longer
262 required and there are not threads waiting to allocate memory
263 from it, it can be destroyed with
264 <function>cyg_mempool_fix_delete()</function>.
268 Memory can be allocated from the pool using a number of
269 functions. They all take the
270 paramter<parameter>fixpool</parameter>which indicates which pool
271 should be used. <function>cyg_mempool_fix_alloc()</function>
272 will block until the memory becomes
273 available. <function>cyg_mempool_tryalloc()</function>will try
274 not block if no memory is available and will return
275 <literal>NULL</literal>. Otherwise a pointer to the allocated
276 memory will be returned.
277 <function>cyg_mempool_fix_timed_alloc()</function> will block if
278 memory is not available and wait for memory to become available
279 until the time<parameter>abstime</parameter> is reached. It will
280 then return <literal>NULL</literal>. </para>
283 Allocated memory can be freed using the function <function>cyg_mempool_fix_free()</function>.
287 Lastly it is possible to query information about the pool using
289 <function>cyg_mempool_fix_get_info()</function>. This takes a
290 pointer to the structure <structname>cyg_mempool_info</structname> which is:
305 <refentry id="malloc-pools">
308 <refentrytitle>stdlib malloc Pools</refentrytitle>
312 <refname>malloc</refname>
313 <refname>calloc</refname>
314 <refname>free</refname>
315 <refname>realloc</refname>
316 <refname>mallinfo</refname>
317 <refpurpose>stdlib malloc pool</refpurpose>
323 #include <stdlib.h>
326 <funcdef>void *<function>malloc</function></funcdef>
327 <paramdef>size_t <parameter>size</parameter></paramdef>
330 <funcdef>void *<function>calloc</function></funcdef>
331 <paramdef>size_t <parameter>size</parameter></paramdef>
334 <funcdef>void <function>free</function></funcdef>
335 <paramdef>void *<parameter>ptr</parameter></paramdef>
338 <funcdef>void *<function>realloc</function></funcdef>
339 <paramdef>void *<parameter>ptr</parameter></paramdef>
340 <paramdef>size_t <parameter>size</parameter></paramdef>
343 <funcdef>struct mallinfo <function>mallinfo</function></funcdef>
349 <refsect1 id="memalloc-stdlib-description"><title>Description</title>
352 eCos provides the standard library functions used for allocating
353 memory from the heap. <function>malloc()</function> allocates a
355 <parameter>size</parameter> bytes. <function>calloc()</function>
356 performs the same, but also sets the memory to zero. The
357 function <function>free()</function> returns a block to the
358 pool. <function>realloc</function> resizes a block of
359 memory. Lastly, <function>mallinfo()</function> returns
360 information about the heap, as described by the structure
361 <structname>mallinfo</structname>:
365 int arena; /* total size of memory arena */
366 int ordblks; /* number of ordinary memory blocks */
367 int smblks; /* number of small memory blocks */
368 int hblks; /* number of mmapped regions */
369 int hblkhd; /* total space in mmapped regions */
370 int usmblks; /* space used by small memory blocks */
371 int fsmblks; /* space available for small memory blocks */
372 int uordblks; /* space used by ordinary memory blocks */
373 int fordblks; /* space free for ordinary blocks */
374 int keepcost; /* top-most, releasable (via malloc_trim) space */
375 int maxfree; /* (NON-STANDARD EXTENSION) size of largest free block */