/* SPDX-License-Identifier: BSD-3-Clause
- * Copyright(c) 2010-2014 Intel Corporation
+ * Copyright(c) 2010-2019 Intel Corporation
*/
#ifndef _RTE_MALLOC_H_
/**
* Replacement function for realloc(), using huge-page memory. Reserved area
* memory is resized, preserving contents. In NUMA systems, the new area
- * resides on the same NUMA socket as the old area.
+ * may not reside on the same NUMA node as the old one.
*
* @param ptr
* Pointer to already allocated memory
* - Otherwise, the pointer to the reallocated memory.
*/
void *
-rte_realloc(void *ptr, size_t size, unsigned align);
+rte_realloc(void *ptr, size_t size, unsigned int align);
+
+/**
+ * Replacement function for realloc(), using huge-page memory. Reserved area
+ * memory is resized, preserving contents. In NUMA systems, the new area
+ * resides on requested NUMA socket.
+ *
+ * @param ptr
+ * Pointer to already allocated memory
+ * @param size
+ * Size (in bytes) of new area. If this is 0, memory is freed.
+ * @param align
+ * If 0, the return is a pointer that is suitably aligned for any kind of
+ * variable (in the same manner as malloc()).
+ * Otherwise, the return is a pointer that is a multiple of *align*. In
+ * this case, it must obviously be a power of two. (Minimum alignment is the
+ * cacheline size, i.e. 64-bytes)
+ * @param socket
+ * NUMA socket to allocate memory on.
+ * @return
+ * - NULL on error. Not enough memory, or invalid arguments (size is 0,
+ * align is not a power of two).
+ * - Otherwise, the pointer to the reallocated memory.
+ */
+__rte_experimental
+void *
+rte_realloc_socket(void *ptr, size_t size, unsigned int align, int socket);
/**
* This function allocates memory from the huge-page area of memory. The memory
/**
* Get heap statistics for the specified heap.
*
+ * @note This function is not thread-safe with respect to
+ * ``rte_malloc_heap_create()``/``rte_malloc_heap_destroy()`` functions.
+ *
* @param socket
* An unsigned integer specifying the socket to get heap statistics for
* @param socket_stats
*
* @note Multiple memory chunks can be added to the same heap
*
+ * @note Before accessing this memory in other processes, it needs to be
+ * attached in each of those processes by calling
+ * ``rte_malloc_heap_memory_attach`` in each other process.
+ *
* @note Memory must be previously allocated for DPDK to be able to use it as a
* malloc heap. Failing to do so will result in undefined behavior, up to and
* including segmentation faults.
* @param heap_name
* Name of the heap to add memory chunk to
* @param va_addr
- * Start of virtual area to add to the heap
+ * Start of virtual area to add to the heap. Must be aligned by ``page_sz``.
* @param len
- * Length of virtual area to add to the heap
+ * Length of virtual area to add to the heap. Must be aligned by ``page_sz``.
* @param iova_addrs
* Array of page IOVA addresses corresponding to each page in this memory
* area. Can be NULL, in which case page IOVA addresses will be set to
* EPERM - attempted to add memory to a reserved heap
* ENOSPC - no more space in internal config to store a new memory chunk
*/
-int __rte_experimental
+__rte_experimental
+int
rte_malloc_heap_memory_add(const char *heap_name, void *va_addr, size_t len,
rte_iova_t iova_addrs[], unsigned int n_pages, size_t page_sz);
* @note Memory area must not contain any allocated elements to allow its
* removal from the heap
*
+ * @note All other processes must detach from the memory chunk prior to it being
+ * removed from the heap.
+ *
* @param heap_name
* Name of the heap to remove memory from
* @param va_addr
* ENOENT - heap or memory chunk was not found
* EBUSY - memory chunk still contains data
*/
-int __rte_experimental
+__rte_experimental
+int
rte_malloc_heap_memory_remove(const char *heap_name, void *va_addr, size_t len);
+/**
+ * Attach to an already existing chunk of external memory in another process.
+ *
+ * @note This function must be called before any attempt is made to use an
+ * already existing external memory chunk. This function does *not* need to
+ * be called if a call to ``rte_malloc_heap_memory_add`` was made in the
+ * current process.
+ *
+ * @param heap_name
+ * Heap name to which this chunk of memory belongs
+ * @param va_addr
+ * Start address of memory chunk to attach to
+ * @param len
+ * Length of memory chunk to attach to
+ * @return
+ * 0 on successful attach
+ * -1 on unsuccessful attach, with rte_errno set to indicate cause for error:
+ * EINVAL - one of the parameters was invalid
+ * EPERM - attempted to attach memory to a reserved heap
+ * ENOENT - heap or memory chunk was not found
+ */
+__rte_experimental
+int
+rte_malloc_heap_memory_attach(const char *heap_name, void *va_addr, size_t len);
+
+/**
+ * Detach from a chunk of external memory in secondary process.
+ *
+ * @note This function must be called in before any attempt is made to remove
+ * external memory from the heap in another process. This function does *not*
+ * need to be called if a call to ``rte_malloc_heap_memory_remove`` will be
+ * called in current process.
+ *
+ * @param heap_name
+ * Heap name to which this chunk of memory belongs
+ * @param va_addr
+ * Start address of memory chunk to attach to
+ * @param len
+ * Length of memory chunk to attach to
+ * @return
+ * 0 on successful detach
+ * -1 on unsuccessful detach, with rte_errno set to indicate cause for error:
+ * EINVAL - one of the parameters was invalid
+ * EPERM - attempted to detach memory from a reserved heap
+ * ENOENT - heap or memory chunk was not found
+ */
+__rte_experimental
+int
+rte_malloc_heap_memory_detach(const char *heap_name, void *va_addr, size_t len);
+
/**
* Creates a new empty malloc heap with a specified name.
*
* EEXIST - heap by name of ``heap_name`` already exists
* ENOSPC - no more space in internal config to store a new heap
*/
-int __rte_experimental
+__rte_experimental
+int
rte_malloc_heap_create(const char *heap_name);
/**
* EPERM - attempting to destroy reserved heap
* EBUSY - heap still contains data
*/
-int __rte_experimental
+__rte_experimental
+int
rte_malloc_heap_destroy(const char *heap_name);
/**
* EINVAL - ``name`` was NULL
* ENOENT - heap identified by the name ``name`` was not found
*/
-int __rte_experimental
+__rte_experimental
+int
rte_malloc_heap_get_socket(const char *name);
/**
* 0 if socket ID refers to internal DPDK memory
* -1 if socket ID is invalid
*/
-int __rte_experimental
+__rte_experimental
+int
rte_malloc_heap_socket_is_external(int socket_id);
/**
* Dump for the specified type to a file. If the type argument is
* NULL, all memory types will be dumped.
*
+ * @note This function is not thread-safe with respect to
+ * ``rte_malloc_heap_create()``/``rte_malloc_heap_destroy()`` functions.
+ *
* @param f
* A pointer to a file for output
* @param type
/**
* Dump contents of all malloc heaps to a file.
*
+ * @note This function is not thread-safe with respect to
+ * ``rte_malloc_heap_create()``/``rte_malloc_heap_destroy()`` functions.
+ *
* @param f
* A pointer to a file for output
*/
-void __rte_experimental
+__rte_experimental
+void
rte_malloc_dump_heaps(FILE *f);
/**
* - 0: Success.
* - (-1): Error.
*/
+__rte_deprecated
int
rte_malloc_set_limit(const char *type, size_t max);
rte_iova_t
rte_malloc_virt2iova(const void *addr);
-__rte_deprecated
-static inline phys_addr_t
-rte_malloc_virt2phy(const void *addr)
-{
- return rte_malloc_virt2iova(addr);
-}
-
#ifdef __cplusplus
}
#endif