rte_lcore.h(3)

📦
version 25.11.3 · 11 versions
, in ubuntu resolute, ubuntu stonking

✨ rte_lcore.h(3) — Library Functions Manual ✨

okay bestie, welcome to the lcore manual, aka the place where your CPU cores get their whole personality 💅 this is rte_lcore.h from the Library Functions Manual and it's literally the blueprint for how lcores and sockets get wrangled. grab a strawberry drink 🍓 and let's get into it.

🌸 SYNOPSIS 🌸

so first things first, here's what you gotta pull in:

#include <stdio.h>
#include <rte_compat.h>
#include <rte_config.h>
#include <rte_per_lcore.h>
#include <rte_eal.h>
#include <rte_launch.h>
#include <rte_thread.h>

🎀 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. that's the whole vibe. it's giving "let me organize your cores and your sockets, bestie" ✨

Definition in file rte_lcore.h.

🦋 Macro Definition Documentation 🦋

✨ #define LCORE_ID_ANY UINT32_MAX

Any lcore. literally any of them, no cap. 🌈

Definition at line 26 of file rte_lcore.h.

✨ #define RTE_LCORE_FOREACH( i)

Value:

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. it's the group chat scroll of lcores, fr fr. 👑

Definition at line 216 of file rte_lcore.h.

✨ #define RTE_LCORE_FOREACH_WORKER( i)

Value:

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. main character lcore is excluded, we're hyping up the workers only 💅

Definition at line 224 of file rte_lcore.h.

🌈 Typedef Documentation 🌈

💖 typedef int(* rte_lcore_init_cb) (unsigned int lcore_id, void *arg)

Callback prototype for initializing lcores. it's the "hey wake up bestie, time to shine" call 🌸

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 240 of file rte_lcore.h.

💖 typedef void(* rte_lcore_uninit_cb) (unsigned int lcore_id, void *arg)

Callback prototype for uninitializing lcores. the goodbye era 😭

Parameters

  • lcore_id — The lcore to consider.
  • arg — An opaque pointer passed at callback registration.

Definition at line 250 of file rte_lcore.h.

💖 typedef int(* rte_lcore_iterate_cb) (unsigned int lcore_id, void *arg)

Callback prototype for iterating over lcores. the little walk-through, one by one, no skipping 🚶‍♀️✨

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 308 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. like a vibe check but for how busy your lcore is. 📊

Parameters

  • lcore_id — The lcore to consider.
  • usage — Counters representing this lcore usage. This can never be NULL. not even in your wildest dreams, bestie 🙈

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 358 of file rte_lcore.h.

👑 Enumeration Type Documentation 👑

💅 enum rte_lcore_role_t

The lcore role (used in RTE or not). are you on the team or not, pick a lane 🎀

Definition at line 33 of file rte_lcore.h.

okay bestie that's part one, keep scrolling for the rest 👀 we're not done yet

🌸 FUNCTION DOCUMENTATION 🌸

✨ RTE_DECLARE_PER_LCORE (unsigned , _lcore_id )

Per thread "lcore id". That's it, that's the whole thing bestie — it's the per-thread lcore id declaration and it's doing exactly what it says on the tin. 💅

🎀 enum rte_lcore_role_t rte_eal_lcore_role (unsigned int lcore_id)

Get a lcore's role. Like, what is this core's job? Its whole career? This tells you. 👑

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. Vibe check, but for cores. 💖

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.

🌈 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 — but that is not the case if the user has explicitly changed the thread to core affinities using the --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. The main character's id, basically. 👑

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. So like, position in the lineup.

When option -c or -l is given, the index corresponds to the order in the list. For example: -l 22,18 lcore 22 has index 0, and 18 has index 1. periodt. ✨

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 NUMA node of the logical core we are running on.

Returns

the ID of current lcoreid's NUMA node

💅 unsigned int rte_socket_count (void )

Return number of NUMA nodes detected on the system.

Note that number of nodes may not be correspondent to their NUMA ID's: for example, a system may report two NUMA ID's, but the actual NUMA ID's may be 0 and 8. yeah it's giving chaos but that's just how it is 😭

Returns

the number of NUMA ID's 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 NUMA node ID's. For example, on a machine with NUMA nodes [0, 8], passing 1 as a parameter will return 8. slay.

Parameters

  • idx — index of NUMA node ID to return

Returns

  • NUMA node 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 NUMA node 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 NUMA node

🔥 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. Is she awake? Is she online? bestie check. 💖

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. Like scrolling to the next story, but for cores. 📱

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. So you get pinged when a lcore wakes up and when it goes night-night. 🛌

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. Breaking up with your callback, respectfully. 💔

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. so like, look but don't touch, okay?? 🙈

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. (spooky but true 💀)

Parameters

  • cb — The callback function.

🌸 void rte_lcore_dump (FILE * f)

List all lcores. The whole roster, laid out. 📋

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. bye bestie, freeing your seat at the table 🫶

💖 AUTHOR 💖

Generated automatically by Doxygen for DPDK from the source code.

okay that's a wrap on rte_lcore.h(3), bestie!! 🎀✨ this whole thing is from DPDK Version 25.11.3 and it's the rte_lcore.h(3) page, auto-served to you by Doxygen straight from the source code, and honestly? iconic of it. now go forth and pin your threads responsibly, no cap 👑💅🌸

📦 where this page comes from