--- name: "rte_lcore.h" 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.h" --- # rte\_lcore.h(3) ## NAME rte\_lcore.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ ### Data Structures struct **rte\_lcore\_usage**\ ### Macros \#define **LCORE\_ID\_ANY** UINT32\_MAX\ \#define **RTE\_LCORE\_FOREACH**(i)\ \#define **RTE\_LCORE\_FOREACH\_WORKER**(i)\ ### Typedefs **typedef** int(\* **rte\_lcore\_init\_cb**) (unsigned int lcore\_id, void \*arg)\ **typedef** void(\* **rte\_lcore\_uninit\_cb**) (unsigned int lcore\_id, void \*arg)\ **typedef** int(\* **rte\_lcore\_iterate\_cb**) (unsigned int lcore\_id, void \*arg)\ **typedef** int(\* **rte\_lcore\_usage\_cb**) (unsigned int lcore\_id, struct **rte\_lcore\_usage** \*usage)\ ### Enumerations enum **rte\_lcore\_role\_t** \ ### Functions **RTE\_DECLARE\_PER\_LCORE** (unsigned, \_lcore\_id)\ enum **rte\_lcore\_role\_t** **rte\_eal\_lcore\_role** (unsigned int lcore\_id)\ int **rte\_lcore\_has\_role** (unsigned int lcore\_id, enum **rte\_lcore\_role\_t** role)\ static unsigned **rte\_lcore\_id** (void)\ unsigned int **rte\_get\_main\_lcore** (void)\ unsigned int **rte\_lcore\_count** (void)\ int **rte\_lcore\_index** (int lcore\_id)\ unsigned int **rte\_socket\_id** (void)\ unsigned int **rte\_socket\_count** (void)\ int **rte\_socket\_id\_by\_idx** (unsigned int idx)\ unsigned int **rte\_lcore\_to\_socket\_id** (unsigned int lcore\_id)\ int **rte\_lcore\_to\_cpu\_id** (int lcore\_id)\ rte\_cpuset\_t **rte\_lcore\_cpuset** (unsigned int lcore\_id)\ int **rte\_lcore\_is\_enabled** (unsigned int lcore\_id)\ unsigned int **rte\_get\_next\_lcore** (unsigned int i, int skip\_main, int wrap)\ void \* **rte\_lcore\_callback\_register** (const char \*name, **rte\_lcore\_init\_cb** init, **rte\_lcore\_uninit\_cb** uninit, void \*arg)\ void **rte\_lcore\_callback\_unregister** (void \*handle)\ int **rte\_lcore\_iterate** (**rte\_lcore\_iterate\_cb** cb, void \*arg)\ void **rte\_lcore\_register\_usage\_cb** (**rte\_lcore\_usage\_cb** cb)\ void **rte\_lcore\_dump** (FILE \*f)\ int **rte\_thread\_register** (void)\ void **rte\_thread\_unregister** (void)\ ## Detailed Description API for lcore and socket manipulation Definition in file **rte\_lcore.h**. ## Macro Definition Documentation ### #define LCORE\_ID\_ANY UINT32\_MAX Any lcore. Definition at line **26** of file **rte\_lcore.h**. ### #define RTE\_LCORE\_FOREACH(i) **Value:**.PP ``` for (i = rte_get_next_lcore(-1, 0, 0); \ i < RTE_MAX_LCORE; \ i = rte_get_next_lcore(i, 0, 0)) ``` Macro to browse all running lcores. Definition at line **217** of file **rte\_lcore.h**. ### #define RTE\_LCORE\_FOREACH\_WORKER(i) **Value:**.PP ``` for (i = rte_get_next_lcore(-1, 1, 0); \ i < RTE_MAX_LCORE; \ i = rte_get_next_lcore(i, 1, 0)) ``` Macro to browse all running lcores except the main lcore. Definition at line **225** of file **rte\_lcore.h**. ## Typedef Documentation ### typedef int(\* rte\_lcore\_init\_cb) (unsigned int lcore\_id, void \*arg) Callback prototype for initializing lcores. **Parameters** *lcore\_id* The lcore to consider. \ *arg* An opaque pointer passed at callback registration. **Returns** - • \-1 when refusing this operation, - • 0 otherwise. Definition at line **241** of file **rte\_lcore.h**. ### typedef void(\* rte\_lcore\_uninit\_cb) (unsigned int lcore\_id, void \*arg) Callback prototype for uninitializing lcores. **Parameters** *lcore\_id* The lcore to consider. \ *arg* An opaque pointer passed at callback registration. Definition at line **251** of file **rte\_lcore.h**. ### typedef int(\* rte\_lcore\_iterate\_cb) (unsigned int lcore\_id, void \*arg) Callback prototype for iterating over lcores. **Parameters** *lcore\_id* The lcore to consider. \ *arg* An opaque pointer coming from the caller. **Returns** - • 0 lets the iteration continue. - • !0 makes the iteration stop. Definition at line **309** of file **rte\_lcore.h**. ### typedef int(\* rte\_lcore\_usage\_cb) (unsigned int lcore\_id, struct rte\_lcore\_usage \*usage) Callback to allow applications to report lcore usage. **Parameters** *lcore\_id* The lcore to consider. \ *usage* Counters representing this lcore usage. This can never be NULL. **Returns** - • 0 if fields in usage were updated successfully. The fields that the application does not support must not be modified. - • a negative value if the information is not available or if any error occurred. Definition at line **359** of file **rte\_lcore.h**. ## Enumeration Type Documentation ### enum rte\_lcore\_role\_t The lcore role (used in RTE or not). Definition at line **33** of file **rte\_lcore.h**. ## Function Documentation ### RTE\_DECLARE\_PER\_LCORE (unsigned, \_lcore\_id) Per thread 'lcore id'. ### enum rte\_lcore\_role\_t rte\_eal\_lcore\_role (unsigned int lcore\_id) Get a lcore's role. **Parameters** *lcore\_id* The identifier of the lcore, which MUST be between 0 and RTE\_MAX\_LCORE-1. **Returns** The role of the lcore. ### int rte\_lcore\_has\_role (unsigned int lcore\_id, enum rte\_lcore\_role\_t role) Test if the core supplied has a specific role **Parameters** *lcore\_id* The identifier of the lcore, which MUST be between 0 and RTE\_MAX\_LCORE-1. \ *role* The role to be checked against. **Returns** Boolean value: positive if test is true; otherwise returns 0. ### static unsigned rte\_lcore\_id (void)` [inline]`, ` [static]` Return the Application thread ID of the execution unit. Note: in most cases the lcore id returned here will also correspond to the processor id of the CPU on which the thread is pinned, this will not be the case if the user has explicitly changed the thread to core affinities using --lcores EAL argument e.g. --lcores '(0-3)@10' to run threads with lcore IDs 0, 1, 2 and 3 on physical core 10.. **Returns** Logical core ID (in EAL thread or registered non-EAL thread) or LCORE\_ID\_ANY (in unregistered non-EAL thread) Definition at line **78** of file **rte\_lcore.h**. ### unsigned int rte\_get\_main\_lcore (void) Get the id of the main lcore **Returns** the id of the main lcore ### unsigned int rte\_lcore\_count (void) Return the number of execution units (lcores) on the system. **Returns** the number of execution units (lcores) on the system. ### int rte\_lcore\_index (int lcore\_id) Return the index of the lcore starting from zero. When option -c or -l is given, the index corresponds to the order in the list. For example: -c 0x30, lcore 4 has index 0, and 5 has index 1. -l 22,18 lcore 22 has index 0, and 18 has index 1. **Parameters** *lcore\_id* The targeted lcore, or -1 for the current one. **Returns** The relative index, or -1 if not enabled. ### unsigned int rte\_socket\_id (void) Return the ID of the physical socket of the logical core we are running on. **Returns** the ID of current lcoreid's physical socket ### unsigned int rte\_socket\_count (void) Return number of physical sockets detected on the system. Note that number of nodes may not be correspondent to their physical id's: for example, a system may report two socket id's, but the actual socket id's may be 0 and 8. **Returns** the number of physical sockets as recognized by EAL ### int rte\_socket\_id\_by\_idx (unsigned int idx) Return socket id with a particular index. This will return socket id at a particular position in list of all detected physical socket id's. For example, on a machine with sockets \[0, 8\], passing 1 as a parameter will return 8. **Parameters** *idx* index of physical socket id to return **Returns** - • physical socket id as recognized by EAL - • \-1 on error, with errno set to EINVAL ### unsigned int rte\_lcore\_to\_socket\_id (unsigned int lcore\_id) Get the ID of the physical socket of the specified lcore **Parameters** *lcore\_id* the targeted lcore, which MUST be between 0 and RTE\_MAX\_LCORE-1. **Returns** the ID of lcoreid's physical socket ### int rte\_lcore\_to\_cpu\_id (int lcore\_id) Return the id of the lcore on a socket starting from zero. **Parameters** *lcore\_id* The targeted lcore, or -1 for the current one. **Returns** The relative index, or -1 if not enabled. ### rte\_cpuset\_t rte\_lcore\_cpuset (unsigned int lcore\_id) Return the cpuset for a given lcore. **Parameters** *lcore\_id* the targeted lcore, which MUST be between 0 and RTE\_MAX\_LCORE-1. **Returns** The cpuset of that lcore ### int rte\_lcore\_is\_enabled (unsigned int lcore\_id) Test if an lcore is enabled. **Parameters** *lcore\_id* The identifier of the lcore, which MUST be between 0 and RTE\_MAX\_LCORE-1. **Returns** True if the given lcore is enabled; false otherwise. ### unsigned int rte\_get\_next\_lcore (unsigned int i, int skip\_main, int wrap) Get the next enabled lcore ID. **Parameters** *i* The current lcore (reference). \ *skip\_main* If true, do not return the ID of the main lcore. \ *wrap* If true, go back to 0 when RTE\_MAX\_LCORE is reached; otherwise, return RTE\_MAX\_LCORE. **Returns** The next lcore\_id or RTE\_MAX\_LCORE if not found. ### void \* rte\_lcore\_callback\_register (const char \* name, rte\_lcore\_init\_cb init, rte\_lcore\_uninit\_cb uninit, void \* arg) Register callbacks invoked when initializing and uninitializing a lcore. This function calls the init callback with all initialized lcores. Any error reported by the init callback triggers a rollback calling the uninit callback for each lcore. If this step succeeds, the callbacks are put in the lcore callbacks list that will get called for each lcore allocation/release. Note: callbacks execution is serialised under a write lock protecting the lcores and callbacks list. **Parameters** *name* A name serving as a small description for this callback. \ *init* The callback invoked when a lcore\_id is initialized. init can be NULL. \ *uninit* The callback invoked when a lcore\_id is uninitialized. uninit can be NULL. \ *arg* An optional argument that gets passed to the callback when it gets invoked. **Returns** On success, returns an opaque pointer for the registered object. On failure (either memory allocation issue in the function itself or an error is returned by the init callback itself), returns NULL. ### void rte\_lcore\_callback\_unregister (void \* handle) Unregister callbacks previously registered with rte\_lcore\_callback\_register. This function calls the uninit callback with all initialized lcores. The callbacks are then removed from the lcore callbacks list. **Parameters** *handle* The handle pointer returned by a former successful call to rte\_lcore\_callback\_register. ### int rte\_lcore\_iterate (rte\_lcore\_iterate\_cb cb, void \* arg) Iterate on all active lcores (ROLE\_RTE, ROLE\_SERVICE and ROLE\_NON\_EAL). No modification on the lcore states is allowed in the callback. Note: as opposed to init/uninit callbacks, iteration callbacks can be invoked in parallel as they are run under a read lock protecting the lcores and callbacks list. **Parameters** *cb* The callback that gets passed each lcore. \ *arg* An opaque pointer passed to cb. **Returns** Same return code as the callback last invocation (see rte\_lcore\_iterate\_cb description). ### void rte\_lcore\_register\_usage\_cb (rte\_lcore\_usage\_cb cb) Register a callback from an application to be called in **rte\_lcore\_dump()** and the /eal/lcore/info telemetry endpoint handler. Applications are expected to report lcore usage statistics via this callback. If a callback was already registered, it can be replaced with another callback or unregistered with NULL. The previously registered callback may remain in use for an undetermined period of time. **Parameters** *cb* The callback function. ### void rte\_lcore\_dump (FILE \* f) List all lcores. **Parameters** *f* The output stream where the dump should be sent. ### int rte\_thread\_register (void) Register current non-EAL thread as a lcore. **Note** This API is not compatible with the multi-process feature: - • if a primary process registers a non-EAL thread, then no secondary process will initialise. - • if a secondary process initialises successfully, trying to register a non-EAL thread from either primary or secondary processes will always end up with the thread getting LCORE\_ID\_ANY as lcore. **Returns** On success, return 0; otherwise return -1 with rte\_errno set. ### void rte\_thread\_unregister (void) Unregister current thread and release lcore if one was associated. ## Author Generated automatically by Doxygen for DPDK from the source code.