4 * Copyright(c) 2010-2012 Intel Corporation. All rights reserved.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
11 * * Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
17 * * Neither the name of Intel Corporation nor the names of its
18 * contributors may be used to endorse or promote products derived
19 * from this software without specific prior written permission.
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 #ifndef _RTE_MALLOC_H_
36 #define _RTE_MALLOC_H_
40 * RTE Malloc. This library provides methods for dynamically allocating memory
51 * Structure to hold heap statistics obtained from rte_malloc_get_socket_stats function.
53 struct rte_malloc_socket_stats {
54 size_t heap_totalsz_bytes; /**< Total bytes on heap */
55 size_t heap_freesz_bytes; /**< Total free bytes on heap */
56 size_t greatest_free_size; /**< Size in bytes of largest free block */
57 unsigned free_count; /**< Number of free elements on heap */
58 unsigned alloc_count; /**< Number of allocated elements on heap */
59 size_t heap_allocsz_bytes; /**< Total allocated bytes on heap */
63 * This function allocates memory from the huge-page area of memory. The memory
64 * is not cleared. In NUMA systems, the memory allocated resides on the same
65 * NUMA socket as the core that calls this function.
68 * A string identifying the type of allocated objects (useful for debug
69 * purposes, such as identifying the cause of a memory leak). Can be NULL.
71 * Size (in bytes) to be allocated.
73 * If 0, the return is a pointer that is suitably aligned for any kind of
74 * variable (in the same manner as malloc()).
75 * Otherwise, the return is a pointer that is a multiple of *align*. In
76 * this case, it must be a power of two. (Minimum alignment is the
77 * cacheline size, i.e. 64-bytes)
79 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
80 * align is not a power of two).
81 * - Otherwise, the pointer to the allocated object.
84 rte_malloc(const char *type, size_t size, unsigned align);
87 * Allocate zero'ed memory from the heap.
89 * Equivalent to rte_malloc() except that the memory zone is
90 * initialised with zeros. In NUMA systems, the memory allocated resides on the
91 * same NUMA socket as the core that calls this function.
94 * A string identifying the type of allocated objects (useful for debug
95 * purposes, such as identifying the cause of a memory leak). Can be NULL.
97 * Size (in bytes) to be allocated.
99 * If 0, the return is a pointer that is suitably aligned for any kind of
100 * variable (in the same manner as malloc()).
101 * Otherwise, the return is a pointer that is a multiple of *align*. In
102 * this case, it must obviously be a power of two. (Minimum alignment is the
103 * cacheline size, i.e. 64-bytes)
105 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
106 * align is not a power of two).
107 * - Otherwise, the pointer to the allocated object.
110 rte_zmalloc(const char *type, size_t size, unsigned align);
113 * Replacement function for calloc(), using huge-page memory. Memory area is
114 * initialised with zeros. In NUMA systems, the memory allocated resides on the
115 * same NUMA socket as the core that calls this function.
118 * A string identifying the type of allocated objects (useful for debug
119 * purposes, such as identifying the cause of a memory leak). Can be NULL.
121 * Number of elements to be allocated.
123 * Size (in bytes) of a single element.
125 * If 0, the return is a pointer that is suitably aligned for any kind of
126 * variable (in the same manner as malloc()).
127 * Otherwise, the return is a pointer that is a multiple of *align*. In
128 * this case, it must obviously be a power of two. (Minimum alignment is the
129 * cacheline size, i.e. 64-bytes)
131 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
132 * align is not a power of two).
133 * - Otherwise, the pointer to the allocated object.
136 rte_calloc(const char *type, size_t num, size_t size, unsigned align);
139 * Replacement function for realloc(), using huge-page memory. Reserved area
140 * memory is resized, preserving contents. In NUMA systems, the new area
141 * resides on the same NUMA socket as the old area.
144 * Pointer to already allocated memory
146 * Size (in bytes) of new area. If this is 0, memory is freed.
148 * If 0, the return is a pointer that is suitably aligned for any kind of
149 * variable (in the same manner as malloc()).
150 * Otherwise, the return is a pointer that is a multiple of *align*. In
151 * this case, it must obviously be a power of two. (Minimum alignment is the
152 * cacheline size, i.e. 64-bytes)
154 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
155 * align is not a power of two).
156 * - Otherwise, the pointer to the reallocated memory.
159 rte_realloc(void *ptr, size_t size, unsigned align);
162 * This function allocates memory from the huge-page area of memory. The memory
166 * A string identifying the type of allocated objects (useful for debug
167 * purposes, such as identifying the cause of a memory leak). Can be NULL.
169 * Size (in bytes) to be allocated.
171 * If 0, the return is a pointer that is suitably aligned for any kind of
172 * variable (in the same manner as malloc()).
173 * Otherwise, the return is a pointer that is a multiple of *align*. In
174 * this case, it must be a power of two. (Minimum alignment is the
175 * cacheline size, i.e. 64-bytes)
177 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
178 * will behave the same as rte_malloc().
180 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
181 * align is not a power of two).
182 * - Otherwise, the pointer to the allocated object.
185 rte_malloc_socket(const char *type, size_t size, unsigned align, int socket);
188 * Allocate zero'ed memory from the heap.
190 * Equivalent to rte_malloc() except that the memory zone is
191 * initialised with zeros.
194 * A string identifying the type of allocated objects (useful for debug
195 * purposes, such as identifying the cause of a memory leak). Can be NULL.
197 * Size (in bytes) to be allocated.
199 * If 0, the return is a pointer that is suitably aligned for any kind of
200 * variable (in the same manner as malloc()).
201 * Otherwise, the return is a pointer that is a multiple of *align*. In
202 * this case, it must obviously be a power of two. (Minimum alignment is the
203 * cacheline size, i.e. 64-bytes)
205 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
206 * will behave the same as rte_zmalloc().
208 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
209 * align is not a power of two).
210 * - Otherwise, the pointer to the allocated object.
213 rte_zmalloc_socket(const char *type, size_t size, unsigned align, int socket);
216 * Replacement function for calloc(), using huge-page memory. Memory area is
217 * initialised with zeros.
220 * A string identifying the type of allocated objects (useful for debug
221 * purposes, such as identifying the cause of a memory leak). Can be NULL.
223 * Number of elements to be allocated.
225 * Size (in bytes) of a single element.
227 * If 0, the return is a pointer that is suitably aligned for any kind of
228 * variable (in the same manner as malloc()).
229 * Otherwise, the return is a pointer that is a multiple of *align*. In
230 * this case, it must obviously be a power of two. (Minimum alignment is the
231 * cacheline size, i.e. 64-bytes)
233 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
234 * will behave the same as rte_calloc().
236 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
237 * align is not a power of two).
238 * - Otherwise, the pointer to the allocated object.
241 rte_calloc_socket(const char *type, size_t num, size_t size, unsigned align, int socket);
244 * Frees the memory space pointed to by the provided pointer.
246 * This pointer must have been returned by a previous call to
247 * rte_malloc(), rte_zmalloc(), rte_calloc() or rte_realloc(). The behaviour of
248 * rte_free() is undefined if the pointer does not match this requirement.
250 * If the pointer is NULL, the function does nothing.
253 * The pointer to memory to be freed.
259 * If malloc debug is enabled, check a memory block for header
260 * and trailer markers to indicate that all is well with the block.
261 * If size is non-null, also return the size of the block.
264 * pointer to the start of a data block, must have been returned
265 * by a previous call to rte_malloc(), rte_zmalloc(), rte_calloc()
268 * if non-null, and memory block pointer is valid, returns the size
269 * of the memory block
271 * -1 on error, invalid pointer passed or header and trailer markers
272 * are missing or corrupted
276 rte_malloc_validate(void *ptr, size_t *size);
279 * Get heap statistics for the specified heap.
282 * An unsigned integer specifying the socket to get heap statistics for
283 * @param socket_stats
284 * A structure which provides memory to store statistics
287 * Pointer to structure storing statistics on success
290 rte_malloc_get_socket_stats(int socket,
291 struct rte_malloc_socket_stats *socket_stats);
296 * Dump for the specified type to the console. If the type argument is
297 * NULL, all memory types will be dumped.
300 * A string identifying the type of objects to dump, or NULL
301 * to dump all objects.
304 rte_malloc_dump_stats(const char *type);
307 * Set the maximum amount of allocated memory for this type.
309 * This is not yet implemented
312 * A string identifying the type of allocated objects.
314 * The maximum amount of allocated bytes for this type.
320 rte_malloc_set_limit(const char *type, size_t max);
326 #endif /* _RTE_MALLOC_H_ */