X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=lib%2Flibrte_eal%2Fcommon%2Finclude%2Frte_malloc.h;h=3593fb45c7e58595457a1a92c226219b09eb932a;hb=a159730c2f3ae3fdabc52c20565470a9d8abd98a;hp=793f9473a08b24d640035c8a8337505d8fd94079;hpb=ff3619d6244ba9883acfc8d8cb2e92ef0eafe6f1;p=dpdk.git

diff --git a/lib/librte_eal/common/include/rte_malloc.h b/lib/librte_eal/common/include/rte_malloc.h
index 793f9473a0..3593fb45c7 100644
--- a/lib/librte_eal/common/include/rte_malloc.h
+++ b/lib/librte_eal/common/include/rte_malloc.h
@@ -1,5 +1,5 @@
 /* SPDX-License-Identifier: BSD-3-Clause
- * Copyright(c) 2010-2014 Intel Corporation
+ * Copyright(c) 2010-2019 Intel Corporation
  */
 
 #ifndef _RTE_MALLOC_H_
@@ -111,7 +111,7 @@ rte_calloc(const char *type, size_t num, size_t size, unsigned align);
 /**
  * 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
@@ -129,7 +129,33 @@ rte_calloc(const char *type, size_t num, size_t size, unsigned align);
  *   - 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
@@ -251,6 +277,9 @@ rte_malloc_validate(const void *ptr, size_t *size);
 /**
  * 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
@@ -282,9 +311,9 @@ rte_malloc_get_socket_stats(int socket,
  * @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
@@ -302,7 +331,8 @@ rte_malloc_get_socket_stats(int socket,
  *     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);
 
@@ -315,6 +345,9 @@ rte_malloc_heap_memory_add(const char *heap_name, void *va_addr, size_t len,
  * @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
@@ -330,7 +363,8 @@ rte_malloc_heap_memory_add(const char *heap_name, void *va_addr, size_t len,
  *     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);
 
 /**
@@ -354,9 +388,35 @@ rte_malloc_heap_memory_remove(const char *heap_name, void *va_addr, size_t len);
  *     EPERM  - attempted to attach memory to a reserved heap
  *     ENOENT - heap or memory chunk was not found
  */
-int __rte_experimental
+__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.
  *
@@ -373,7 +433,8 @@ rte_malloc_heap_memory_attach(const char *heap_name, void *va_addr, size_t len);
  *     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);
 
 /**
@@ -396,7 +457,8 @@ 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);
 
 /**
@@ -410,7 +472,8 @@ 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);
 
 /**
@@ -425,7 +488,8 @@ 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);
 
 /**
@@ -434,6 +498,9 @@ 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
@@ -446,10 +513,14 @@ rte_malloc_dump_stats(FILE *f, const char *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);
 
 /**
@@ -465,6 +536,7 @@ rte_malloc_dump_heaps(FILE *f);
  *   - 0: Success.
  *   - (-1): Error.
  */
+__rte_deprecated
 int
 rte_malloc_set_limit(const char *type, size_t max);