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_memory.h>
23 * Structure to hold heap statistics obtained from rte_malloc_get_socket_stats function.
25 struct rte_malloc_socket_stats {
26 size_t heap_totalsz_bytes; /**< Total bytes on heap */
27 size_t heap_freesz_bytes; /**< Total free bytes on heap */
28 size_t greatest_free_size; /**< Size in bytes of largest free block */
29 unsigned free_count; /**< Number of free elements on heap */
30 unsigned alloc_count; /**< Number of allocated elements on heap */
31 size_t heap_allocsz_bytes; /**< Total allocated bytes on heap */
35 * This function allocates memory from the huge-page area of memory. The memory
36 * is not cleared. In NUMA systems, the memory allocated resides on the same
37 * NUMA socket as the core that calls this function.
40 * A string identifying the type of allocated objects (useful for debug
41 * purposes, such as identifying the cause of a memory leak). Can be NULL.
43 * Size (in bytes) to be allocated.
45 * If 0, the return is a pointer that is suitably aligned for any kind of
46 * variable (in the same manner as malloc()).
47 * Otherwise, the return is a pointer that is a multiple of *align*. In
48 * this case, it must be a power of two. (Minimum alignment is the
49 * cacheline size, i.e. 64-bytes)
51 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
52 * align is not a power of two).
53 * - Otherwise, the pointer to the allocated object.
56 rte_malloc(const char *type, size_t size, unsigned align);
59 * Allocate zero'ed memory from the heap.
61 * Equivalent to rte_malloc() except that the memory zone is
62 * initialised with zeros. In NUMA systems, the memory allocated resides on the
63 * same NUMA socket as the core that calls this function.
66 * A string identifying the type of allocated objects (useful for debug
67 * purposes, such as identifying the cause of a memory leak). Can be NULL.
69 * Size (in bytes) to be allocated.
71 * If 0, the return is a pointer that is suitably aligned for any kind of
72 * variable (in the same manner as malloc()).
73 * Otherwise, the return is a pointer that is a multiple of *align*. In
74 * this case, it must obviously be a power of two. (Minimum alignment is the
75 * cacheline size, i.e. 64-bytes)
77 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
78 * align is not a power of two).
79 * - Otherwise, the pointer to the allocated object.
82 rte_zmalloc(const char *type, size_t size, unsigned align);
85 * Replacement function for calloc(), using huge-page memory. Memory area is
86 * initialised with zeros. In NUMA systems, the memory allocated resides on the
87 * same NUMA socket as the core that calls this function.
90 * A string identifying the type of allocated objects (useful for debug
91 * purposes, such as identifying the cause of a memory leak). Can be NULL.
93 * Number of elements to be allocated.
95 * Size (in bytes) of a single element.
97 * If 0, the return is a pointer that is suitably aligned for any kind of
98 * variable (in the same manner as malloc()).
99 * Otherwise, the return is a pointer that is a multiple of *align*. In
100 * this case, it must obviously be a power of two. (Minimum alignment is the
101 * cacheline size, i.e. 64-bytes)
103 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
104 * align is not a power of two).
105 * - Otherwise, the pointer to the allocated object.
108 rte_calloc(const char *type, size_t num, size_t size, unsigned align);
111 * Replacement function for realloc(), using huge-page memory. Reserved area
112 * memory is resized, preserving contents. In NUMA systems, the new area
113 * resides on the same NUMA socket as the old area.
116 * Pointer to already allocated memory
118 * Size (in bytes) of new area. If this is 0, memory is freed.
120 * If 0, the return is a pointer that is suitably aligned for any kind of
121 * variable (in the same manner as malloc()).
122 * Otherwise, the return is a pointer that is a multiple of *align*. In
123 * this case, it must obviously be a power of two. (Minimum alignment is the
124 * cacheline size, i.e. 64-bytes)
126 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
127 * align is not a power of two).
128 * - Otherwise, the pointer to the reallocated memory.
131 rte_realloc(void *ptr, size_t size, unsigned align);
134 * This function allocates memory from the huge-page area of memory. The memory
138 * A string identifying the type of allocated objects (useful for debug
139 * purposes, such as identifying the cause of a memory leak). Can be NULL.
141 * Size (in bytes) to be allocated.
143 * If 0, the return is a pointer that is suitably aligned for any kind of
144 * variable (in the same manner as malloc()).
145 * Otherwise, the return is a pointer that is a multiple of *align*. In
146 * this case, it must be a power of two. (Minimum alignment is the
147 * cacheline size, i.e. 64-bytes)
149 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
150 * will behave the same as rte_malloc().
152 * - NULL on error. Not enough memory, or invalid arguments (size is 0,
153 * align is not a power of two).
154 * - Otherwise, the pointer to the allocated object.
157 rte_malloc_socket(const char *type, size_t size, unsigned align, int socket);
160 * Allocate zero'ed memory from the heap.
162 * Equivalent to rte_malloc() except that the memory zone is
163 * initialised with zeros.
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 obviously 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_zmalloc().
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_zmalloc_socket(const char *type, size_t size, unsigned align, int socket);
188 * Replacement function for calloc(), using huge-page memory. Memory area is
189 * initialised with zeros.
192 * A string identifying the type of allocated objects (useful for debug
193 * purposes, such as identifying the cause of a memory leak). Can be NULL.
195 * Number of elements to be allocated.
197 * Size (in bytes) of a single element.
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_calloc().
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_calloc_socket(const char *type, size_t num, size_t size, unsigned align, int socket);
216 * Frees the memory space pointed to by the provided pointer.
218 * This pointer must have been returned by a previous call to
219 * rte_malloc(), rte_zmalloc(), rte_calloc() or rte_realloc(). The behaviour of
220 * rte_free() is undefined if the pointer does not match this requirement.
222 * If the pointer is NULL, the function does nothing.
225 * The pointer to memory to be freed.
231 * If malloc debug is enabled, check a memory block for header
232 * and trailer markers to indicate that all is well with the block.
233 * If size is non-null, also return the size of the block.
236 * pointer to the start of a data block, must have been returned
237 * by a previous call to rte_malloc(), rte_zmalloc(), rte_calloc()
240 * if non-null, and memory block pointer is valid, returns the size
241 * of the memory block
243 * -1 on error, invalid pointer passed or header and trailer markers
244 * are missing or corrupted
248 rte_malloc_validate(const void *ptr, size_t *size);
251 * Get heap statistics for the specified heap.
254 * An unsigned integer specifying the socket to get heap statistics for
255 * @param socket_stats
256 * A structure which provides memory to store statistics
259 * Pointer to structure storing statistics on success
262 rte_malloc_get_socket_stats(int socket,
263 struct rte_malloc_socket_stats *socket_stats);
268 * Dump for the specified type to a file. If the type argument is
269 * NULL, all memory types will be dumped.
272 * A pointer to a file for output
274 * A string identifying the type of objects to dump, or NULL
275 * to dump all objects.
278 rte_malloc_dump_stats(FILE *f, const char *type);
281 * Set the maximum amount of allocated memory for this type.
283 * This is not yet implemented
286 * A string identifying the type of allocated objects.
288 * The maximum amount of allocated bytes for this type.
294 rte_malloc_set_limit(const char *type, size_t max);
297 * Return the IO address of a virtual address obtained through
301 * Address obtained from a previous rte_malloc call
303 * RTE_BAD_IOVA on error
304 * otherwise return an address suitable for IO
307 rte_malloc_virt2iova(const void *addr);
310 static inline phys_addr_t
311 rte_malloc_virt2phy(const void *addr)
313 return rte_malloc_virt2iova(addr);
320 #endif /* _RTE_MALLOC_H_ */