lib/librte_eal/common/include/rte_malloc.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2014 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_MALLOC_H_
   6 #define _RTE_MALLOC_H_
   7
   8 /**
   9  * @file
  10  * RTE Malloc. This library provides methods for dynamically allocating memory
  11  * from hugepages.
  12  */
  13
  14 #include <stdio.h>
  15 #include <stddef.h>
  16 #include <rte_memory.h>
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /**
  23  *  Structure to hold heap statistics obtained from rte_malloc_get_socket_stats function.
  24  */
  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 */
  32 };
  33
  34 /**
  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.
  38  *
  39  * @param type
  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.
  42  * @param size
  43  *   Size (in bytes) to be allocated.
  44  * @param align
  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)
  50  * @return
  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.
  54  */
  55 void *
  56 rte_malloc(const char *type, size_t size, unsigned align);
  57
  58 /**
  59  * Allocate zero'ed memory from the heap.
  60  *
  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.
  64  *
  65  * @param type
  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.
  68  * @param size
  69  *   Size (in bytes) to be allocated.
  70  * @param align
  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)
  76  * @return
  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.
  80  */
  81 void *
  82 rte_zmalloc(const char *type, size_t size, unsigned align);
  83
  84 /**
  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.
  88  *
  89  * @param type
  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.
  92  * @param num
  93  *   Number of elements to be allocated.
  94  * @param size
  95  *   Size (in bytes) of a single element.
  96  * @param align
  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)
 102  * @return
 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.
 106  */
 107 void *
 108 rte_calloc(const char *type, size_t num, size_t size, unsigned align);
 109
 110 /**
 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.
 114  *
 115  * @param ptr
 116  *   Pointer to already allocated memory
 117  * @param size
 118  *   Size (in bytes) of new area. If this is 0, memory is freed.
 119  * @param align
 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)
 125  * @return
 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.
 129  */
 130 void *
 131 rte_realloc(void *ptr, size_t size, unsigned align);
 132
 133 /**
 134  * This function allocates memory from the huge-page area of memory. The memory
 135  * is not cleared.
 136  *
 137  * @param type
 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.
 140  * @param size
 141  *   Size (in bytes) to be allocated.
 142  * @param align
 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)
 148  * @param socket
 149  *   NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
 150  *   will behave the same as rte_malloc().
 151  * @return
 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.
 155  */
 156 void *
 157 rte_malloc_socket(const char *type, size_t size, unsigned align, int socket);
 158
 159 /**
 160  * Allocate zero'ed memory from the heap.
 161  *
 162  * Equivalent to rte_malloc() except that the memory zone is
 163  * initialised with zeros.
 164  *
 165  * @param type
 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.
 168  * @param size
 169  *   Size (in bytes) to be allocated.
 170  * @param align
 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)
 176  * @param socket
 177  *   NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
 178  *   will behave the same as rte_zmalloc().
 179  * @return
 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.
 183  */
 184 void *
 185 rte_zmalloc_socket(const char *type, size_t size, unsigned align, int socket);
 186
 187 /**
 188  * Replacement function for calloc(), using huge-page memory. Memory area is
 189  * initialised with zeros.
 190  *
 191  * @param type
 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.
 194  * @param num
 195  *   Number of elements to be allocated.
 196  * @param size
 197  *   Size (in bytes) of a single element.
 198  * @param align
 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)
 204  * @param socket
 205  *   NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function
 206  *   will behave the same as rte_calloc().
 207  * @return
 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.
 211  */
 212 void *
 213 rte_calloc_socket(const char *type, size_t num, size_t size, unsigned align, int socket);
 214
 215 /**
 216  * Frees the memory space pointed to by the provided pointer.
 217  *
 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.
 221  *
 222  * If the pointer is NULL, the function does nothing.
 223  *
 224  * @param ptr
 225  *   The pointer to memory to be freed.
 226  */
 227 void
 228 rte_free(void *ptr);
 229
 230 /**
 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.
 234  *
 235  * @param ptr
 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()
 238  *   or rte_realloc()
 239  * @param size
 240  *   if non-null, and memory block pointer is valid, returns the size
 241  *   of the memory block
 242  * @return
 243  *   -1 on error, invalid pointer passed or header and trailer markers
 244  *   are missing or corrupted
 245  *   0 on success
 246  */
 247 int
 248 rte_malloc_validate(const void *ptr, size_t *size);
 249
 250 /**
 251  * Get heap statistics for the specified heap.
 252  *
 253  * @param socket
 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
 257  * @return
 258  *   Null on error
 259  *   Pointer to structure storing statistics on success
 260  */
 261 int
 262 rte_malloc_get_socket_stats(int socket,
 263                 struct rte_malloc_socket_stats *socket_stats);
 264
 265 /**
 266  * Dump statistics.
 267  *
 268  * Dump for the specified type to a file. If the type argument is
 269  * NULL, all memory types will be dumped.
 270  *
 271  * @param f
 272  *   A pointer to a file for output
 273  * @param type
 274  *   A string identifying the type of objects to dump, or NULL
 275  *   to dump all objects.
 276  */
 277 void
 278 rte_malloc_dump_stats(FILE *f, const char *type);
 279
 280 /**
 281  * Set the maximum amount of allocated memory for this type.
 282  *
 283  * This is not yet implemented
 284  *
 285  * @param type
 286  *   A string identifying the type of allocated objects.
 287  * @param max
 288  *   The maximum amount of allocated bytes for this type.
 289  * @return
 290  *   - 0: Success.
 291  *   - (-1): Error.
 292  */
 293 int
 294 rte_malloc_set_limit(const char *type, size_t max);
 295
 296 /**
 297  * Return the IO address of a virtual address obtained through
 298  * rte_malloc
 299  *
 300  * @param addr
 301  *   Address obtained from a previous rte_malloc call
 302  * @return
 303  *   RTE_BAD_IOVA on error
 304  *   otherwise return an address suitable for IO
 305  */
 306 rte_iova_t
 307 rte_malloc_virt2iova(const void *addr);
 308
 309 __rte_deprecated
 310 static inline phys_addr_t
 311 rte_malloc_virt2phy(const void *addr)
 312 {
 313         return rte_malloc_virt2iova(addr);
 314 }
 315
 316 #ifdef __cplusplus
 317 }
 318 #endif
 319
 320 #endif /* _RTE_MALLOC_H_ */