1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2010-2019 Intel Corporation
10 * RTE Malloc. This library provides methods for dynamically allocating memory
16 #include <rte_compat.h>
17 #include <rte_memory.h>
24 * Structure to hold heap statistics obtained from rte_malloc_get_socket_stats function.
26 struct rte_malloc_socket_stats {
27 size_t heap_totalsz_bytes; /**< Total bytes on heap */
28 size_t heap_freesz_bytes; /**< Total free bytes on heap */
29 size_t greatest_free_size; /**< Size in bytes of largest free block */
30 unsigned free_count; /**< Number of free elements on heap */
31 unsigned alloc_count; /**< Number of allocated elements on heap */
32 size_t heap_allocsz_bytes; /**< Total allocated bytes on heap */
36 * This function allocates memory from the huge-page area of memory. The memory
37 * is not cleared. In NUMA systems, the memory allocated resides on the same
38 * NUMA socket as the core that calls this function.
41 * A string identifying the type of allocated objects (useful for debug
42 * purposes, such as identifying the cause of a memory leak). Can be NULL.
44 * Size (in bytes) to be allocated.
46 * If 0, the return is a pointer that is suitably aligned for any kind of
47 * variable (in the same manner as malloc()).
48 * Otherwise, the return is a pointer that is a multiple of *align*. In
49 * this case, it must be a power of two. (Minimum alignment is the
50 * cacheline size, i.e. 64-bytes)
52 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
53 * align is not a power of two).
54 * - Otherwise, the pointer to the allocated object.
57 rte_malloc(const char *type, size_t size, unsigned align)
61 * Allocate zero'ed memory from the heap.
63 * Equivalent to rte_malloc() except that the memory zone is
64 * initialised with zeros. In NUMA systems, the memory allocated resides on the
65 * same 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 obviously 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_zmalloc(const char *type, size_t size, unsigned align)
88 * Replacement function for calloc(), using huge-page memory. Memory area is
89 * initialised with zeros. In NUMA systems, the memory allocated resides on the
90 * same NUMA socket as the core that calls this function.
93 * A string identifying the type of allocated objects (useful for debug
94 * purposes, such as identifying the cause of a memory leak). Can be NULL.
96 * Number of elements to be allocated.
98 * Size (in bytes) of a single element.
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)
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.
111 rte_calloc(const char *type, size_t num, size_t size, unsigned align)
112 __rte_alloc_size(2, 3);
115 * Replacement function for realloc(), using huge-page memory. Reserved area
116 * memory is resized, preserving contents. In NUMA systems, the new area
117 * may not reside on the same NUMA node as the old one.
120 * Pointer to already allocated memory
122 * Size (in bytes) of new area. If this is 0, memory is freed.
124 * If 0, the return is a pointer that is suitably aligned for any kind of
125 * variable (in the same manner as malloc()).
126 * Otherwise, the return is a pointer that is a multiple of *align*. In
127 * this case, it must obviously be a power of two. (Minimum alignment is the
128 * cacheline size, i.e. 64-bytes)
130 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
131 * align is not a power of two).
132 * - Otherwise, the pointer to the reallocated memory.
135 rte_realloc(void *ptr, size_t size, unsigned int 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 requested NUMA socket.
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 * NUMA socket to allocate memory on.
156 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
157 * align is not a power of two).
158 * - Otherwise, the pointer to the reallocated memory.
162 rte_realloc_socket(void *ptr, size_t size, unsigned int align, int socket)
163 __rte_alloc_size(2, 3);
166 * This function allocates memory from the huge-page area of memory. The memory
170 * A string identifying the type of allocated objects (useful for debug
171 * purposes, such as identifying the cause of a memory leak). Can be NULL.
173 * Size (in bytes) to be allocated.
175 * If 0, the return is a pointer that is suitably aligned for any kind of
176 * variable (in the same manner as malloc()).
177 * Otherwise, the return is a pointer that is a multiple of *align*. In
178 * this case, it must be a power of two. (Minimum alignment is the
179 * cacheline size, i.e. 64-bytes)
181 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
182 * will behave the same as rte_malloc().
184 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
185 * align is not a power of two).
186 * - Otherwise, the pointer to the allocated object.
189 rte_malloc_socket(const char *type, size_t size, unsigned align, int socket)
193 * Allocate zero'ed memory from the heap.
195 * Equivalent to rte_malloc() except that the memory zone is
196 * initialised with zeros.
199 * A string identifying the type of allocated objects (useful for debug
200 * purposes, such as identifying the cause of a memory leak). Can be NULL.
202 * Size (in bytes) to be allocated.
204 * If 0, the return is a pointer that is suitably aligned for any kind of
205 * variable (in the same manner as malloc()).
206 * Otherwise, the return is a pointer that is a multiple of *align*. In
207 * this case, it must obviously be a power of two. (Minimum alignment is the
208 * cacheline size, i.e. 64-bytes)
210 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
211 * will behave the same as rte_zmalloc().
213 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
214 * align is not a power of two).
215 * - Otherwise, the pointer to the allocated object.
218 rte_zmalloc_socket(const char *type, size_t size, unsigned align, int socket)
222 * Replacement function for calloc(), using huge-page memory. Memory area is
223 * initialised with zeros.
226 * A string identifying the type of allocated objects (useful for debug
227 * purposes, such as identifying the cause of a memory leak). Can be NULL.
229 * Number of elements to be allocated.
231 * Size (in bytes) of a single element.
233 * If 0, the return is a pointer that is suitably aligned for any kind of
234 * variable (in the same manner as malloc()).
235 * Otherwise, the return is a pointer that is a multiple of *align*. In
236 * this case, it must obviously be a power of two. (Minimum alignment is the
237 * cacheline size, i.e. 64-bytes)
239 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
240 * will behave the same as rte_calloc().
242 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
243 * align is not a power of two).
244 * - Otherwise, the pointer to the allocated object.
247 rte_calloc_socket(const char *type, size_t num, size_t size, unsigned align, int socket)
248 __rte_alloc_size(2, 3);
251 * Frees the memory space pointed to by the provided pointer.
253 * This pointer must have been returned by a previous call to
254 * rte_malloc(), rte_zmalloc(), rte_calloc() or rte_realloc(). The behaviour of
255 * rte_free() is undefined if the pointer does not match this requirement.
257 * If the pointer is NULL, the function does nothing.
260 * The pointer to memory to be freed.
266 * If malloc debug is enabled, check a memory block for header
267 * and trailer markers to indicate that all is well with the block.
268 * If size is non-null, also return the size of the block.
271 * pointer to the start of a data block, must have been returned
272 * by a previous call to rte_malloc(), rte_zmalloc(), rte_calloc()
275 * if non-null, and memory block pointer is valid, returns the size
276 * of the memory block
278 * -1 on error, invalid pointer passed or header and trailer markers
279 * are missing or corrupted
283 rte_malloc_validate(const void *ptr, size_t *size);
286 * Get heap statistics for the specified heap.
288 * @note This function is not thread-safe with respect to
289 * ``rte_malloc_heap_create()``/``rte_malloc_heap_destroy()`` functions.
292 * An unsigned integer specifying the socket to get heap statistics for
293 * @param socket_stats
294 * A structure which provides memory to store statistics
297 * Pointer to structure storing statistics on success
300 rte_malloc_get_socket_stats(int socket,
301 struct rte_malloc_socket_stats *socket_stats);
304 * Add memory chunk to a heap with specified name.
306 * @note Multiple memory chunks can be added to the same heap
308 * @note Before accessing this memory in other processes, it needs to be
309 * attached in each of those processes by calling
310 * ``rte_malloc_heap_memory_attach`` in each other process.
312 * @note Memory must be previously allocated for DPDK to be able to use it as a
313 * malloc heap. Failing to do so will result in undefined behavior, up to and
314 * including segmentation faults.
316 * @note Calling this function will erase any contents already present at the
317 * supplied memory address.
320 * Name of the heap to add memory chunk to
322 * Start of virtual area to add to the heap. Must be aligned by ``page_sz``.
324 * Length of virtual area to add to the heap. Must be aligned by ``page_sz``.
326 * Array of page IOVA addresses corresponding to each page in this memory
327 * area. Can be NULL, in which case page IOVA addresses will be set to
330 * Number of elements in the iova_addrs array. Ignored if ``iova_addrs``
333 * Page size of the underlying memory
337 * - -1 in case of error, with rte_errno set to one of the following:
338 * EINVAL - one of the parameters was invalid
339 * EPERM - attempted to add memory to a reserved heap
340 * ENOSPC - no more space in internal config to store a new memory chunk
344 rte_malloc_heap_memory_add(const char *heap_name, void *va_addr, size_t len,
345 rte_iova_t iova_addrs[], unsigned int n_pages, size_t page_sz);
348 * Remove memory chunk from heap with specified name.
350 * @note Memory chunk being removed must be the same as one that was added;
351 * partially removing memory chunks is not supported
353 * @note Memory area must not contain any allocated elements to allow its
354 * removal from the heap
356 * @note All other processes must detach from the memory chunk prior to it being
357 * removed from the heap.
360 * Name of the heap to remove memory from
362 * Virtual address to remove from the heap
364 * Length of virtual area to remove from the heap
368 * - -1 in case of error, with rte_errno set to one of the following:
369 * EINVAL - one of the parameters was invalid
370 * EPERM - attempted to remove memory from a reserved heap
371 * ENOENT - heap or memory chunk was not found
372 * EBUSY - memory chunk still contains data
376 rte_malloc_heap_memory_remove(const char *heap_name, void *va_addr, size_t len);
379 * Attach to an already existing chunk of external memory in another process.
381 * @note This function must be called before any attempt is made to use an
382 * already existing external memory chunk. This function does *not* need to
383 * be called if a call to ``rte_malloc_heap_memory_add`` was made in the
387 * Heap name to which this chunk of memory belongs
389 * Start address of memory chunk to attach to
391 * Length of memory chunk to attach to
393 * 0 on successful attach
394 * -1 on unsuccessful attach, with rte_errno set to indicate cause for error:
395 * EINVAL - one of the parameters was invalid
396 * EPERM - attempted to attach memory to a reserved heap
397 * ENOENT - heap or memory chunk was not found
401 rte_malloc_heap_memory_attach(const char *heap_name, void *va_addr, size_t len);
404 * Detach from a chunk of external memory in secondary process.
406 * @note This function must be called in before any attempt is made to remove
407 * external memory from the heap in another process. This function does *not*
408 * need to be called if a call to ``rte_malloc_heap_memory_remove`` will be
409 * called in current process.
412 * Heap name to which this chunk of memory belongs
414 * Start address of memory chunk to attach to
416 * Length of memory chunk to attach to
418 * 0 on successful detach
419 * -1 on unsuccessful detach, with rte_errno set to indicate cause for error:
420 * EINVAL - one of the parameters was invalid
421 * EPERM - attempted to detach memory from a reserved heap
422 * ENOENT - heap or memory chunk was not found
426 rte_malloc_heap_memory_detach(const char *heap_name, void *va_addr, size_t len);
429 * Creates a new empty malloc heap with a specified name.
431 * @note Heaps created via this call will automatically get assigned a unique
432 * socket ID, which can be found using ``rte_malloc_heap_get_socket()``
435 * Name of the heap to create.
438 * - 0 on successful creation
439 * - -1 in case of error, with rte_errno set to one of the following:
440 * EINVAL - ``heap_name`` was NULL, empty or too long
441 * EEXIST - heap by name of ``heap_name`` already exists
442 * ENOSPC - no more space in internal config to store a new heap
446 rte_malloc_heap_create(const char *heap_name);
449 * Destroys a previously created malloc heap with specified name.
451 * @note This function will return a failure result if not all memory allocated
452 * from the heap has been freed back to the heap
454 * @note This function will return a failure result if not all memory segments
455 * were removed from the heap prior to its destruction
458 * Name of the heap to create.
462 * - -1 in case of error, with rte_errno set to one of the following:
463 * EINVAL - ``heap_name`` was NULL, empty or too long
464 * ENOENT - heap by the name of ``heap_name`` was not found
465 * EPERM - attempting to destroy reserved heap
466 * EBUSY - heap still contains data
470 rte_malloc_heap_destroy(const char *heap_name);
473 * Find socket ID corresponding to a named heap.
476 * Heap name to find socket ID for
478 * Socket ID in case of success (a non-negative number)
479 * -1 in case of error, with rte_errno set to one of the following:
480 * EINVAL - ``name`` was NULL
481 * ENOENT - heap identified by the name ``name`` was not found
485 rte_malloc_heap_get_socket(const char *name);
488 * Check if a given socket ID refers to externally allocated memory.
490 * @note Passing SOCKET_ID_ANY will return 0.
495 * 1 if socket ID refers to externally allocated memory
496 * 0 if socket ID refers to internal DPDK memory
497 * -1 if socket ID is invalid
501 rte_malloc_heap_socket_is_external(int socket_id);
506 * Dump for the specified type to a file. If the type argument is
507 * NULL, all memory types will be dumped.
509 * @note This function is not thread-safe with respect to
510 * ``rte_malloc_heap_create()``/``rte_malloc_heap_destroy()`` functions.
513 * A pointer to a file for output
515 * A string identifying the type of objects to dump, or NULL
516 * to dump all objects.
519 rte_malloc_dump_stats(FILE *f, const char *type);
522 * Dump contents of all malloc heaps to a file.
524 * @note This function is not thread-safe with respect to
525 * ``rte_malloc_heap_create()``/``rte_malloc_heap_destroy()`` functions.
528 * A pointer to a file for output
532 rte_malloc_dump_heaps(FILE *f);
535 * Set the maximum amount of allocated memory for this type.
537 * This is not yet implemented
540 * A string identifying the type of allocated objects.
542 * The maximum amount of allocated bytes for this type.
549 rte_malloc_set_limit(const char *type, size_t max);
552 * Return the IO address of a virtual address obtained through
556 * Address obtained from a previous rte_malloc call
558 * RTE_BAD_IOVA on error
559 * otherwise return an address suitable for IO
562 rte_malloc_virt2iova(const void *addr);
568 #endif /* _RTE_MALLOC_H_ */