rte_malloc.h revision 3d9b7210
1/*-
2 *   BSD LICENSE
3 *
4 *   Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
5 *   All rights reserved.
6 *
7 *   Redistribution and use in source and binary forms, with or without
8 *   modification, are permitted provided that the following conditions
9 *   are met:
10 *
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
16 *       distribution.
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.
20 *
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.
32 */
33
34#ifndef _RTE_MALLOC_H_
35#define _RTE_MALLOC_H_
36
37/**
38 * @file
39 * RTE Malloc. This library provides methods for dynamically allocating memory
40 * from hugepages.
41 */
42
43#include <stdio.h>
44#include <stddef.h>
45#include <rte_memory.h>
46
47#ifdef __cplusplus
48extern "C" {
49#endif
50
51/**
52 *  Structure to hold heap statistics obtained from rte_malloc_get_socket_stats function.
53 */
54struct rte_malloc_socket_stats {
55	size_t heap_totalsz_bytes; /**< Total bytes on heap */
56	size_t heap_freesz_bytes;  /**< Total free bytes on heap */
57	size_t greatest_free_size; /**< Size in bytes of largest free block */
58	unsigned free_count;       /**< Number of free elements on heap */
59	unsigned alloc_count;      /**< Number of allocated elements on heap */
60	size_t heap_allocsz_bytes; /**< Total allocated bytes on heap */
61};
62
63/**
64 * This function allocates memory from the huge-page area of memory. The memory
65 * is not cleared. In NUMA systems, the memory allocated resides on the same
66 * NUMA socket as the core that calls this function.
67 *
68 * @param type
69 *   A string identifying the type of allocated objects (useful for debug
70 *   purposes, such as identifying the cause of a memory leak). Can be NULL.
71 * @param size
72 *   Size (in bytes) to be allocated.
73 * @param align
74 *   If 0, the return is a pointer that is suitably aligned for any kind of
75 *   variable (in the same manner as malloc()).
76 *   Otherwise, the return is a pointer that is a multiple of *align*. In
77 *   this case, it must be a power of two. (Minimum alignment is the
78 *   cacheline size, i.e. 64-bytes)
79 * @return
80 *   - NULL on error. Not enough memory, or invalid arguments (size is 0,
81 *     align is not a power of two).
82 *   - Otherwise, the pointer to the allocated object.
83 */
84void *
85rte_malloc(const char *type, size_t size, unsigned align);
86
87/**
88 * Allocate zero'ed memory from the heap.
89 *
90 * Equivalent to rte_malloc() except that the memory zone is
91 * initialised with zeros. In NUMA systems, the memory allocated resides on the
92 * same NUMA socket as the core that calls this function.
93 *
94 * @param type
95 *   A string identifying the type of allocated objects (useful for debug
96 *   purposes, such as identifying the cause of a memory leak). Can be NULL.
97 * @param size
98 *   Size (in bytes) to be allocated.
99 * @param align
100 *   If 0, the return is a pointer that is suitably aligned for any kind of
101 *   variable (in the same manner as malloc()).
102 *   Otherwise, the return is a pointer that is a multiple of *align*. In
103 *   this case, it must obviously be a power of two. (Minimum alignment is the
104 *   cacheline size, i.e. 64-bytes)
105 * @return
106 *   - NULL on error. Not enough memory, or invalid arguments (size is 0,
107 *     align is not a power of two).
108 *   - Otherwise, the pointer to the allocated object.
109 */
110void *
111rte_zmalloc(const char *type, size_t size, unsigned align);
112
113/**
114 * Replacement function for calloc(), using huge-page memory. Memory area is
115 * initialised with zeros. In NUMA systems, the memory allocated resides on the
116 * same NUMA socket as the core that calls this function.
117 *
118 * @param type
119 *   A string identifying the type of allocated objects (useful for debug
120 *   purposes, such as identifying the cause of a memory leak). Can be NULL.
121 * @param num
122 *   Number of elements to be allocated.
123 * @param size
124 *   Size (in bytes) of a single element.
125 * @param align
126 *   If 0, the return is a pointer that is suitably aligned for any kind of
127 *   variable (in the same manner as malloc()).
128 *   Otherwise, the return is a pointer that is a multiple of *align*. In
129 *   this case, it must obviously be a power of two. (Minimum alignment is the
130 *   cacheline size, i.e. 64-bytes)
131 * @return
132 *   - NULL on error. Not enough memory, or invalid arguments (size is 0,
133 *     align is not a power of two).
134 *   - Otherwise, the pointer to the allocated object.
135 */
136void *
137rte_calloc(const char *type, size_t num, size_t size, unsigned align);
138
139/**
140 * Replacement function for realloc(), using huge-page memory. Reserved area
141 * memory is resized, preserving contents. In NUMA systems, the new area
142 * resides on the same NUMA socket as the old area.
143 *
144 * @param ptr
145 *   Pointer to already allocated memory
146 * @param size
147 *   Size (in bytes) of new area. If this is 0, memory is freed.
148 * @param align
149 *   If 0, the return is a pointer that is suitably aligned for any kind of
150 *   variable (in the same manner as malloc()).
151 *   Otherwise, the return is a pointer that is a multiple of *align*. In
152 *   this case, it must obviously be a power of two. (Minimum alignment is the
153 *   cacheline size, i.e. 64-bytes)
154 * @return
155 *   - NULL on error. Not enough memory, or invalid arguments (size is 0,
156 *     align is not a power of two).
157 *   - Otherwise, the pointer to the reallocated memory.
158 */
159void *
160rte_realloc(void *ptr, size_t size, unsigned align);
161
162/**
163 * This function allocates memory from the huge-page area of memory. The memory
164 * is not cleared.
165 *
166 * @param type
167 *   A string identifying the type of allocated objects (useful for debug
168 *   purposes, such as identifying the cause of a memory leak). Can be NULL.
169 * @param size
170 *   Size (in bytes) to be allocated.
171 * @param align
172 *   If 0, the return is a pointer that is suitably aligned for any kind of
173 *   variable (in the same manner as malloc()).
174 *   Otherwise, the return is a pointer that is a multiple of *align*. In
175 *   this case, it must be a power of two. (Minimum alignment is the
176 *   cacheline size, i.e. 64-bytes)
177 * @param socket
178 *   NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
179 *   will behave the same as rte_malloc().
180 * @return
181 *   - NULL on error. Not enough memory, or invalid arguments (size is 0,
182 *     align is not a power of two).
183 *   - Otherwise, the pointer to the allocated object.
184 */
185void *
186rte_malloc_socket(const char *type, size_t size, unsigned align, int socket);
187
188/**
189 * Allocate zero'ed memory from the heap.
190 *
191 * Equivalent to rte_malloc() except that the memory zone is
192 * initialised with zeros.
193 *
194 * @param type
195 *   A string identifying the type of allocated objects (useful for debug
196 *   purposes, such as identifying the cause of a memory leak). Can be NULL.
197 * @param size
198 *   Size (in bytes) to be allocated.
199 * @param align
200 *   If 0, the return is a pointer that is suitably aligned for any kind of
201 *   variable (in the same manner as malloc()).
202 *   Otherwise, the return is a pointer that is a multiple of *align*. In
203 *   this case, it must obviously be a power of two. (Minimum alignment is the
204 *   cacheline size, i.e. 64-bytes)
205 * @param socket
206 *   NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
207 *   will behave the same as rte_zmalloc().
208 * @return
209 *   - NULL on error. Not enough memory, or invalid arguments (size is 0,
210 *     align is not a power of two).
211 *   - Otherwise, the pointer to the allocated object.
212 */
213void *
214rte_zmalloc_socket(const char *type, size_t size, unsigned align, int socket);
215
216/**
217 * Replacement function for calloc(), using huge-page memory. Memory area is
218 * initialised with zeros.
219 *
220 * @param type
221 *   A string identifying the type of allocated objects (useful for debug
222 *   purposes, such as identifying the cause of a memory leak). Can be NULL.
223 * @param num
224 *   Number of elements to be allocated.
225 * @param size
226 *   Size (in bytes) of a single element.
227 * @param align
228 *   If 0, the return is a pointer that is suitably aligned for any kind of
229 *   variable (in the same manner as malloc()).
230 *   Otherwise, the return is a pointer that is a multiple of *align*. In
231 *   this case, it must obviously be a power of two. (Minimum alignment is the
232 *   cacheline size, i.e. 64-bytes)
233 * @param socket
234 *   NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
235 *   will behave the same as rte_calloc().
236 * @return
237 *   - NULL on error. Not enough memory, or invalid arguments (size is 0,
238 *     align is not a power of two).
239 *   - Otherwise, the pointer to the allocated object.
240 */
241void *
242rte_calloc_socket(const char *type, size_t num, size_t size, unsigned align, int socket);
243
244/**
245 * Frees the memory space pointed to by the provided pointer.
246 *
247 * This pointer must have been returned by a previous call to
248 * rte_malloc(), rte_zmalloc(), rte_calloc() or rte_realloc(). The behaviour of
249 * rte_free() is undefined if the pointer does not match this requirement.
250 *
251 * If the pointer is NULL, the function does nothing.
252 *
253 * @param ptr
254 *   The pointer to memory to be freed.
255 */
256void
257rte_free(void *ptr);
258
259/**
260 * If malloc debug is enabled, check a memory block for header
261 * and trailer markers to indicate that all is well with the block.
262 * If size is non-null, also return the size of the block.
263 *
264 * @param ptr
265 *   pointer to the start of a data block, must have been returned
266 *   by a previous call to rte_malloc(), rte_zmalloc(), rte_calloc()
267 *   or rte_realloc()
268 * @param size
269 *   if non-null, and memory block pointer is valid, returns the size
270 *   of the memory block
271 * @return
272 *   -1 on error, invalid pointer passed or header and trailer markers
273 *   are missing or corrupted
274 *   0 on success
275 */
276int
277rte_malloc_validate(const void *ptr, size_t *size);
278
279/**
280 * Get heap statistics for the specified heap.
281 *
282 * @param socket
283 *   An unsigned integer specifying the socket to get heap statistics for
284 * @param socket_stats
285 *   A structure which provides memory to store statistics
286 * @return
287 *   Null on error
288 *   Pointer to structure storing statistics on success
289 */
290int
291rte_malloc_get_socket_stats(int socket,
292		struct rte_malloc_socket_stats *socket_stats);
293
294/**
295 * Dump statistics.
296 *
297 * Dump for the specified type to a file. If the type argument is
298 * NULL, all memory types will be dumped.
299 *
300 * @param f
301 *   A pointer to a file for output
302 * @param type
303 *   A string identifying the type of objects to dump, or NULL
304 *   to dump all objects.
305 */
306void
307rte_malloc_dump_stats(FILE *f, const char *type);
308
309/**
310 * Set the maximum amount of allocated memory for this type.
311 *
312 * This is not yet implemented
313 *
314 * @param type
315 *   A string identifying the type of allocated objects.
316 * @param max
317 *   The maximum amount of allocated bytes for this type.
318 * @return
319 *   - 0: Success.
320 *   - (-1): Error.
321 */
322int
323rte_malloc_set_limit(const char *type, size_t max);
324
325/**
326 * Return the physical address of a virtual address obtained through
327 * rte_malloc
328 *
329 * @param addr
330 *   Adress obtained from a previous rte_malloc call
331 * @return
332 *   NULL on error
333 *   otherwise return physical address of the buffer
334 */
335phys_addr_t
336rte_malloc_virt2phy(const void *addr);
337
338#ifdef __cplusplus
339}
340#endif
341
342#endif /* _RTE_MALLOC_H_ */
343