--- name: "RTE_LCORE_VAR_ALLOC" section: "3" platform: "linux" package: "dpdk-doc" version: "24.11.4-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rte_lcore_var.h" --- # RTE\_LCORE\_VAR\_ALLOC(3) Part of [rte\_lcore\_var.h(3)](/rte_lcore_var.h/3.md). ## NAME rte\_lcore\_var.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ ### Macros \#define **RTE\_LCORE\_VAR\_HANDLE\_TYPE**(type) type \*\ \#define **RTE\_LCORE\_VAR\_HANDLE**(type, name) **RTE\_LCORE\_VAR\_HANDLE\_TYPE**(type) name\ \#define **RTE\_LCORE\_VAR\_ALLOC\_SIZE\_ALIGN**(handle, size, align) handle = **rte\_lcore\_var\_alloc**(size, align)\ \#define **RTE\_LCORE\_VAR\_ALLOC\_SIZE**(handle, size) **RTE\_LCORE\_VAR\_ALLOC\_SIZE\_ALIGN**(handle, size, 0)\ \#define **RTE\_LCORE\_VAR\_ALLOC**(handle)\ \#define **RTE\_LCORE\_VAR\_INIT\_SIZE\_ALIGN**(name, size, align)\ \#define **RTE\_LCORE\_VAR\_INIT\_SIZE**(name, size) **RTE\_LCORE\_VAR\_INIT\_SIZE\_ALIGN**(name, size, 0)\ \#define **RTE\_LCORE\_VAR\_INIT**(name)\ \#define **RTE\_LCORE\_VAR\_LCORE**(lcore\_id, handle) ((typeof(handle))**rte\_lcore\_var\_lcore**(lcore\_id, handle))\ \#define **RTE\_LCORE\_VAR**(handle) **RTE\_LCORE\_VAR\_LCORE**(**rte\_lcore\_id**(), handle)\ \#define **RTE\_LCORE\_VAR\_FOREACH**(lcore\_id, value, handle)\ ### Functions static void \* **rte\_lcore\_var\_lcore** (unsigned int lcore\_id, void \*handle)\ \_\_rte\_experimental void \* **rte\_lcore\_var\_alloc** (size\_t size, size\_t align) **\_\_rte\_alloc\_size**(1) **\_\_rte\_alloc\_align**(2)\ ## Detailed Description Lcore variables This API provides a mechanism to create and access per-lcore id variables in a space- and cycle-efficient manner. Please refer to the lcore variables' programmer's guide for an overview of this API and its implementation. EXPERIMENTAL: this API may change, or be removed, without prior notice. Definition in file **rte\_lcore\_var.h**. ## Macro Definition Documentation ### #define RTE\_LCORE\_VAR\_HANDLE\_TYPE(type) type \* Given the lcore variable type, produces the type of the lcore variable handle. Definition at line **36** of file **rte\_lcore\_var.h**. ### #define RTE\_LCORE\_VAR\_HANDLE(type, name) RTE\_LCORE\_VAR\_HANDLE\_TYPE(type) name Define an lcore variable handle. This macro defines a variable which is used as a handle to access the various instances of a per-lcore id variable. This macro clarifies that the declaration is an lcore handle, not a regular pointer. Add **static** as a prefix in case the lcore variable is only to be accessed from a particular translation unit. Definition at line **51** of file **rte\_lcore\_var.h**. ### #define RTE\_LCORE\_VAR\_ALLOC\_SIZE\_ALIGN(handle, size, align) handle = rte\_lcore\_var\_alloc(size, align) Allocate space for an lcore variable, and initialize its handle. The values of the lcore variable are initialized to zero. Definition at line **59** of file **rte\_lcore\_var.h**. ### #define RTE\_LCORE\_VAR\_ALLOC\_SIZE(handle, size) RTE\_LCORE\_VAR\_ALLOC\_SIZE\_ALIGN(handle, size, 0) Allocate space for an lcore variable, and initialize its handle, with values aligned for any type of object. The values of the lcore variable are initialized to zero. Definition at line **68** of file **rte\_lcore\_var.h**. ### #define RTE\_LCORE\_VAR\_ALLOC(handle) **Value:**.PP ``` RTE_LCORE_VAR_ALLOC_SIZE_ALIGN(handle, sizeof(*(handle)), \ alignof(typeof(*(handle)))) ``` Allocate space for an lcore variable of the size and alignment requirements suggested by the handle pointer type, and initialize its handle. The values of the lcore variable are initialized to zero. Definition at line **77** of file **rte\_lcore\_var.h**. ### #define RTE\_LCORE\_VAR\_INIT\_SIZE\_ALIGN(name, size, align) **Value:**.PP ``` RTE_INIT(rte_lcore_var_init_ ## name) \ { \ RTE_LCORE_VAR_ALLOC_SIZE_ALIGN(name, size, align); \ } ``` Allocate an explicitly-sized, explicitly-aligned lcore variable by means of a **RTE\_INIT** constructor. The values of the lcore variable are initialized to zero. Definition at line **87** of file **rte\_lcore\_var.h**. ### #define RTE\_LCORE\_VAR\_INIT\_SIZE(name, size) RTE\_LCORE\_VAR\_INIT\_SIZE\_ALIGN(name, size, 0) Allocate an explicitly-sized lcore variable by means of a **RTE\_INIT** constructor. The values of the lcore variable are initialized to zero. Definition at line **99** of file **rte\_lcore\_var.h**. ### #define RTE\_LCORE\_VAR\_INIT(name) **Value:**.PP ``` RTE_INIT(rte_lcore_var_init_ ## name) \ { \ RTE_LCORE_VAR_ALLOC(name); \ } ``` Allocate an lcore variable by means of a **RTE\_INIT** constructor. The values of the lcore variable are initialized to zero. Definition at line **107** of file **rte\_lcore\_var.h**. ### #define RTE\_LCORE\_VAR\_LCORE(lcore\_id, handle) ((typeof(handle))rte\_lcore\_var\_lcore(lcore\_id, handle)) Get pointer to lcore variable instance with the specified lcore id. **Parameters** *lcore\_id* The lcore id specifying which of the `RTE_MAX_LCORE` value instances should be accessed. The lcore id need not be valid (e.g., may be **LCORE\_ID\_ANY**), but in such a case, the pointer is also not valid (and thus should not be dereferenced). \ *handle* The lcore variable handle. Definition at line **143** of file **rte\_lcore\_var.h**. ### #define RTE\_LCORE\_VAR(handle) RTE\_LCORE\_VAR\_LCORE(rte\_lcore\_id(), handle) Get pointer to lcore variable instance of the current thread. May only be used by EAL threads and registered non-EAL threads. Definition at line **151** of file **rte\_lcore\_var.h**. ### #define RTE\_LCORE\_VAR\_FOREACH(lcore\_id, value, handle) **Value:**.PP ``` for ((lcore_id) = \ (((value) = RTE_LCORE_VAR_LCORE(0, handle)), 0); \ (lcore_id) < RTE_MAX_LCORE; \ (lcore_id)++, (value) = RTE_LCORE_VAR_LCORE(lcore_id, \ handle)) ``` Iterate over each lcore id's value for an lcore variable. **Parameters** *lcore\_id* An `unsigned int` variable successively set to the lcore id of every valid lcore id (up to `RTE_MAX_LCORE`). \ *value* A pointer variable successively set to point to lcore variable value instance of the current lcore id being processed. \ *handle* The lcore variable handle. Definition at line **166** of file **rte\_lcore\_var.h**. ## Function Documentation ### static void \* rte\_lcore\_var\_lcore (unsigned int lcore\_id, void \* handle)` [inline]`, ` [static]` Get void pointer to lcore variable instance with the specified lcore id. **Parameters** *lcore\_id* The lcore id specifying which of the `RTE_MAX_LCORE` value instances should be accessed. The lcore id need not be valid (e.g., may be **LCORE\_ID\_ANY**), but in such a case, the pointer is also not valid (and thus should not be dereferenced). \ *handle* The lcore variable handle. Definition at line **126** of file **rte\_lcore\_var.h**. ### \_\_rte\_experimental void \* rte\_lcore\_var\_alloc (size\_t size, size\_t align) Allocate space in the per-lcore id buffers for an lcore variable. The pointer returned is only an opaque identifier of the variable. To get an actual pointer to a particular instance of the variable, use **RTE\_LCORE\_VAR** or **RTE\_LCORE\_VAR\_LCORE**. The lcore variable values' memory is set to zero. The allocation is always successful, barring a fatal exhaustion of the per-lcore id buffer space. **rte\_lcore\_var\_alloc()** is not multi-thread safe. The allocated memory cannot be freed. **Parameters** *size* The size (in bytes) of the variable's per-lcore id value. Must be \> 0. \ *align* If 0, the values will be suitably aligned for any kind of type (i.e., alignof(max\_align\_t)). Otherwise, the values will be aligned on a multiple of *align*, which must be a power of 2 and equal or less than `RTE_CACHE_LINE_SIZE`. **Returns** The variable's handle, stored in a void pointer value. The value is always non-NULL. ## Author Generated automatically by Doxygen for DPDK from the source code.