1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2010-2014 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);
60 * Allocate zero'ed memory from the heap.
62 * Equivalent to rte_malloc() except that the memory zone is
63 * initialised with zeros. In NUMA systems, the memory allocated resides on the
64 * same NUMA socket as the core that calls this function.
67 * A string identifying the type of allocated objects (useful for debug
68 * purposes, such as identifying the cause of a memory leak). Can be NULL.
70 * Size (in bytes) to be allocated.
72 * If 0, the return is a pointer that is suitably aligned for any kind of
73 * variable (in the same manner as malloc()).
74 * Otherwise, the return is a pointer that is a multiple of *align*. In
75 * this case, it must obviously be a power of two. (Minimum alignment is the
76 * cacheline size, i.e. 64-bytes)
78 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
79 * align is not a power of two).
80 * - Otherwise, the pointer to the allocated object.
83 rte_zmalloc(const char *type, size_t size, unsigned align);
86 * Replacement function for calloc(), using huge-page memory. Memory area is
87 * initialised with zeros. In NUMA systems, the memory allocated resides on the
88 * same NUMA socket as the core that calls this function.
91 * A string identifying the type of allocated objects (useful for debug
92 * purposes, such as identifying the cause of a memory leak). Can be NULL.
94 * Number of elements to be allocated.
96 * Size (in bytes) of a single element.
98 * If 0, the return is a pointer that is suitably aligned for any kind of
99 * variable (in the same manner as malloc()).
100 * Otherwise, the return is a pointer that is a multiple of *align*. In
101 * this case, it must obviously be a power of two. (Minimum alignment is the
102 * cacheline size, i.e. 64-bytes)
104 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
105 * align is not a power of two).
106 * - Otherwise, the pointer to the allocated object.
109 rte_calloc(const char *type, size_t num, size_t size, unsigned align);
112 * Replacement function for realloc(), using huge-page memory. Reserved area
113 * memory is resized, preserving contents. In NUMA systems, the new area
114 * resides on the same NUMA socket as the old area.
117 * Pointer to already allocated memory
119 * Size (in bytes) of new area. If this is 0, memory is freed.
121 * If 0, the return is a pointer that is suitably aligned for any kind of
122 * variable (in the same manner as malloc()).
123 * Otherwise, the return is a pointer that is a multiple of *align*. In
124 * this case, it must obviously be a power of two. (Minimum alignment is the
125 * cacheline size, i.e. 64-bytes)
127 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
128 * align is not a power of two).
129 * - Otherwise, the pointer to the reallocated memory.
132 rte_realloc(void *ptr, size_t size, unsigned align);
135 * This function allocates memory from the huge-page area of memory. The memory
139 * A string identifying the type of allocated objects (useful for debug
140 * purposes, such as identifying the cause of a memory leak). Can be NULL.
142 * Size (in bytes) to be allocated.
144 * If 0, the return is a pointer that is suitably aligned for any kind of
145 * variable (in the same manner as malloc()).
146 * Otherwise, the return is a pointer that is a multiple of *align*. In
147 * this case, it must be a power of two. (Minimum alignment is the
148 * cacheline size, i.e. 64-bytes)
150 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
151 * will behave the same as rte_malloc().
153 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
154 * align is not a power of two).
155 * - Otherwise, the pointer to the allocated object.
158 rte_malloc_socket(const char *type, size_t size, unsigned align, int socket);
161 * Allocate zero'ed memory from the heap.
163 * Equivalent to rte_malloc() except that the memory zone is
164 * initialised with zeros.
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.
170 * Size (in bytes) to be allocated.
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 obviously be a power of two. (Minimum alignment is the
176 * cacheline size, i.e. 64-bytes)
178 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
179 * will behave the same as rte_zmalloc().
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.
186 rte_zmalloc_socket(const char *type, size_t size, unsigned align, int socket);
189 * Replacement function for calloc(), using huge-page memory. Memory area is
190 * initialised with zeros.
193 * A string identifying the type of allocated objects (useful for debug
194 * purposes, such as identifying the cause of a memory leak). Can be NULL.
196 * Number of elements to be allocated.
198 * Size (in bytes) of a single element.
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)
206 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
207 * will behave the same as rte_calloc().
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.
214 rte_calloc_socket(const char *type, size_t num, size_t size, unsigned align, int socket);
217 * Frees the memory space pointed to by the provided pointer.
219 * This pointer must have been returned by a previous call to
220 * rte_malloc(), rte_zmalloc(), rte_calloc() or rte_realloc(). The behaviour of
221 * rte_free() is undefined if the pointer does not match this requirement.
223 * If the pointer is NULL, the function does nothing.
226 * The pointer to memory to be freed.
232 * If malloc debug is enabled, check a memory block for header
233 * and trailer markers to indicate that all is well with the block.
234 * If size is non-null, also return the size of the block.
237 * pointer to the start of a data block, must have been returned
238 * by a previous call to rte_malloc(), rte_zmalloc(), rte_calloc()
241 * if non-null, and memory block pointer is valid, returns the size
242 * of the memory block
244 * -1 on error, invalid pointer passed or header and trailer markers
245 * are missing or corrupted
249 rte_malloc_validate(const void *ptr, size_t *size);
252 * Get heap statistics for the specified heap.
255 * An unsigned integer specifying the socket to get heap statistics for
256 * @param socket_stats
257 * A structure which provides memory to store statistics
260 * Pointer to structure storing statistics on success
263 rte_malloc_get_socket_stats(int socket,
264 struct rte_malloc_socket_stats *socket_stats);
267 * Add memory chunk to a heap with specified name.
269 * @note Multiple memory chunks can be added to the same heap
271 * @note Before accessing this memory in other processes, it needs to be
272 * attached in each of those processes by calling
273 * ``rte_malloc_heap_memory_attach`` in each other process.
275 * @note Memory must be previously allocated for DPDK to be able to use it as a
276 * malloc heap. Failing to do so will result in undefined behavior, up to and
277 * including segmentation faults.
279 * @note Calling this function will erase any contents already present at the
280 * supplied memory address.
283 * Name of the heap to add memory chunk to
285 * Start of virtual area to add to the heap
287 * Length of virtual area to add to the heap
289 * Array of page IOVA addresses corresponding to each page in this memory
290 * area. Can be NULL, in which case page IOVA addresses will be set to
293 * Number of elements in the iova_addrs array. Ignored if ``iova_addrs``
296 * Page size of the underlying memory
300 * - -1 in case of error, with rte_errno set to one of the following:
301 * EINVAL - one of the parameters was invalid
302 * EPERM - attempted to add memory to a reserved heap
303 * ENOSPC - no more space in internal config to store a new memory chunk
305 int __rte_experimental
306 rte_malloc_heap_memory_add(const char *heap_name, void *va_addr, size_t len,
307 rte_iova_t iova_addrs[], unsigned int n_pages, size_t page_sz);
310 * Remove memory chunk from heap with specified name.
312 * @note Memory chunk being removed must be the same as one that was added;
313 * partially removing memory chunks is not supported
315 * @note Memory area must not contain any allocated elements to allow its
316 * removal from the heap
318 * @note All other processes must detach from the memory chunk prior to it being
319 * removed from the heap.
322 * Name of the heap to remove memory from
324 * Virtual address to remove from the heap
326 * Length of virtual area to remove from the heap
330 * - -1 in case of error, with rte_errno set to one of the following:
331 * EINVAL - one of the parameters was invalid
332 * EPERM - attempted to remove memory from a reserved heap
333 * ENOENT - heap or memory chunk was not found
334 * EBUSY - memory chunk still contains data
336 int __rte_experimental
337 rte_malloc_heap_memory_remove(const char *heap_name, void *va_addr, size_t len);
340 * Attach to an already existing chunk of external memory in another process.
342 * @note This function must be called before any attempt is made to use an
343 * already existing external memory chunk. This function does *not* need to
344 * be called if a call to ``rte_malloc_heap_memory_add`` was made in the
348 * Heap name to which this chunk of memory belongs
350 * Start address of memory chunk to attach to
352 * Length of memory chunk to attach to
354 * 0 on successful attach
355 * -1 on unsuccessful attach, with rte_errno set to indicate cause for error:
356 * EINVAL - one of the parameters was invalid
357 * EPERM - attempted to attach memory to a reserved heap
358 * ENOENT - heap or memory chunk was not found
360 int __rte_experimental
361 rte_malloc_heap_memory_attach(const char *heap_name, void *va_addr, size_t len);
364 * Detach from a chunk of external memory in secondary process.
366 * @note This function must be called in before any attempt is made to remove
367 * external memory from the heap in another process. This function does *not*
368 * need to be called if a call to ``rte_malloc_heap_memory_remove`` will be
369 * called in current process.
372 * Heap name to which this chunk of memory belongs
374 * Start address of memory chunk to attach to
376 * Length of memory chunk to attach to
378 * 0 on successful detach
379 * -1 on unsuccessful detach, with rte_errno set to indicate cause for error:
380 * EINVAL - one of the parameters was invalid
381 * EPERM - attempted to detach memory from a reserved heap
382 * ENOENT - heap or memory chunk was not found
384 int __rte_experimental
385 rte_malloc_heap_memory_detach(const char *heap_name, void *va_addr, size_t len);
388 * Creates a new empty malloc heap with a specified name.
390 * @note Heaps created via this call will automatically get assigned a unique
391 * socket ID, which can be found using ``rte_malloc_heap_get_socket()``
394 * Name of the heap to create.
397 * - 0 on successful creation
398 * - -1 in case of error, with rte_errno set to one of the following:
399 * EINVAL - ``heap_name`` was NULL, empty or too long
400 * EEXIST - heap by name of ``heap_name`` already exists
401 * ENOSPC - no more space in internal config to store a new heap
403 int __rte_experimental
404 rte_malloc_heap_create(const char *heap_name);
407 * Destroys a previously created malloc heap with specified name.
409 * @note This function will return a failure result if not all memory allocated
410 * from the heap has been freed back to the heap
412 * @note This function will return a failure result if not all memory segments
413 * were removed from the heap prior to its destruction
416 * Name of the heap to create.
420 * - -1 in case of error, with rte_errno set to one of the following:
421 * EINVAL - ``heap_name`` was NULL, empty or too long
422 * ENOENT - heap by the name of ``heap_name`` was not found
423 * EPERM - attempting to destroy reserved heap
424 * EBUSY - heap still contains data
426 int __rte_experimental
427 rte_malloc_heap_destroy(const char *heap_name);
430 * Find socket ID corresponding to a named heap.
433 * Heap name to find socket ID for
435 * Socket ID in case of success (a non-negative number)
436 * -1 in case of error, with rte_errno set to one of the following:
437 * EINVAL - ``name`` was NULL
438 * ENOENT - heap identified by the name ``name`` was not found
440 int __rte_experimental
441 rte_malloc_heap_get_socket(const char *name);
444 * Check if a given socket ID refers to externally allocated memory.
446 * @note Passing SOCKET_ID_ANY will return 0.
451 * 1 if socket ID refers to externally allocated memory
452 * 0 if socket ID refers to internal DPDK memory
453 * -1 if socket ID is invalid
455 int __rte_experimental
456 rte_malloc_heap_socket_is_external(int socket_id);
461 * Dump for the specified type to a file. If the type argument is
462 * NULL, all memory types will be dumped.
465 * A pointer to a file for output
467 * A string identifying the type of objects to dump, or NULL
468 * to dump all objects.
471 rte_malloc_dump_stats(FILE *f, const char *type);
474 * Dump contents of all malloc heaps to a file.
477 * A pointer to a file for output
479 void __rte_experimental
480 rte_malloc_dump_heaps(FILE *f);
483 * Set the maximum amount of allocated memory for this type.
485 * This is not yet implemented
488 * A string identifying the type of allocated objects.
490 * The maximum amount of allocated bytes for this type.
496 rte_malloc_set_limit(const char *type, size_t max);
499 * Return the IO address of a virtual address obtained through
503 * Address obtained from a previous rte_malloc call
505 * RTE_BAD_IOVA on error
506 * otherwise return an address suitable for IO
509 rte_malloc_virt2iova(const void *addr);
512 static inline phys_addr_t
513 rte_malloc_virt2phy(const void *addr)
515 return rte_malloc_virt2iova(addr);
522 #endif /* _RTE_MALLOC_H_ */