#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)

__rte_experimental void	rte_lcore_register_usage_cb (rte_lcore_usage_cb cb)

void	rte_lcore_dump (FILE *f)

int	rte_thread_setname (pthread_t id, const char *name)

int	rte_thread_register (void)

void	rte_thread_unregister (void)

int	rte_ctrl_thread_create (pthread_t thread, const char name, const pthread_attr_t attr, void (start_routine)(void ), void *arg)

Detailed Description

API for lcore and socket manipulation

Definition in file rte_lcore.h.

Macro Definition Documentation

◆ LCORE_ID_ANY

#define LCORE_ID_ANY UINT32_MAX

Any lcore.

Definition at line 27 of file rte_lcore.h.

◆ RTE_LCORE_FOREACH

#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.

Examples:: examples/ipsec-secgw/event_helper.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipsec-secgw/ipsec.c, examples/ipsec-secgw/sa.c, examples/ipv4_multicast/main.c, examples/l2fwd-jobstats/main.c, examples/l3fwd-power/main.c, examples/multi_process/symmetric_mp/main.c, examples/vhost_crypto/main.c, examples/vm_power_manager/guest_cli/main.c, and examples/vm_power_manager/guest_cli/vm_power_cli_guest.c.

Definition at line 218 of file rte_lcore.h.

◆ RTE_LCORE_FOREACH_WORKER

#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.

Examples:: examples/bbdev_app/main.c, examples/bond/main.c, examples/distributor/main.c, examples/ethtool/ethtool-app/main.c, examples/eventdev_pipeline/main.c, examples/helloworld/main.c, examples/ip_fragmentation/main.c, examples/ip_pipeline/thread.c, examples/ip_reassembly/main.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipv4_multicast/main.c, examples/l2fwd-crypto/main.c, examples/l2fwd-jobstats/main.c, examples/l2fwd-keepalive/main.c, examples/l2fwd/main.c, examples/l3fwd-graph/main.c, examples/l3fwd-power/main.c, examples/link_status_interrupt/main.c, examples/multi_process/simple_mp/main.c, examples/ntb/ntb_fwd.c, examples/packet_ordering/main.c, examples/pipeline/thread.c, examples/qos_meter/main.c, examples/timer/main.c, examples/vhost/main.c, examples/vmdq/main.c, and examples/vmdq_dcb/main.c.

Definition at line 226 of file rte_lcore.h.

Typedef Documentation

◆ rte_lcore_init_cb

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

◆ rte_lcore_uninit_cb

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

◆ rte_lcore_iterate_cb

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

◆ rte_lcore_usage_cb

typedef int(* rte_lcore_usage_cb) (unsigned int lcore_id, struct rte_lcore_usage *usage)

Callback to allow applications to report lcore usage.

Parameters

[in]	lcore_id	The lcore to consider.
[out]	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 360 of file rte_lcore.h.

Enumeration Type Documentation

◆ rte_lcore_role_t

enum rte_lcore_role_t

The lcore role (used in RTE or not).

Definition at line 34 of file rte_lcore.h.

Function Documentation

◆ RTE_DECLARE_PER_LCORE()

RTE_DECLARE_PER_LCORE	(	unsigned	,
		_lcore_id
	)

Per thread "lcore id".

◆ rte_eal_lcore_role()

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.

◆ rte_lcore_has_role()

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.

◆ rte_lcore_id()

static unsigned rte_lcore_id ( void )

inlinestatic

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)

Examples:: examples/bond/main.c, examples/distributor/main.c, examples/dma/dmafwd.c, examples/ethtool/ethtool-app/main.c, examples/eventdev_pipeline/main.c, examples/eventdev_pipeline/pipeline_worker_generic.c, examples/eventdev_pipeline/pipeline_worker_tx.c, examples/flow_classify/flow_classify.c, examples/helloworld/main.c, examples/ip_fragmentation/main.c, examples/ip_pipeline/thread.c, examples/ip_reassembly/main.c, examples/ipsec-secgw/event_helper.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipsec-secgw/ipsec_worker.c, examples/ipv4_multicast/main.c, examples/l2fwd-cat/l2fwd-cat.c, examples/l2fwd-crypto/main.c, examples/l2fwd-event/l2fwd_event.c, examples/l2fwd-event/l2fwd_poll.c, examples/l2fwd-jobstats/main.c, examples/l2fwd-keepalive/main.c, examples/l2fwd/main.c, examples/l3fwd-graph/main.c, examples/l3fwd-power/main.c, examples/l3fwd/l3fwd_acl.c, examples/l3fwd/l3fwd_em.c, examples/l3fwd/l3fwd_fib.c, examples/l3fwd/l3fwd_lpm.c, examples/link_status_interrupt/main.c, examples/multi_process/client_server_mp/mp_server/main.c, examples/multi_process/simple_mp/main.c, examples/multi_process/symmetric_mp/main.c, examples/packet_ordering/main.c, examples/pipeline/thread.c, examples/ptpclient/ptpclient.c, examples/qos_meter/main.c, examples/qos_sched/main.c, examples/rxtx_callbacks/main.c, examples/server_node_efd/server/main.c, examples/skeleton/basicfwd.c, examples/timer/main.c, examples/vhost/main.c, examples/vhost_crypto/main.c, examples/vmdq/main.c, and examples/vmdq_dcb/main.c.

Definition at line 79 of file rte_lcore.h.

◆ rte_get_main_lcore()

unsigned int rte_get_main_lcore ( void )

Get the id of the main lcore

Returns: the id of the main lcore

Examples:: examples/bbdev_app/main.c, examples/l2fwd-crypto/main.c, examples/l2fwd-event/l2fwd_poll.c, examples/l2fwd/main.c, examples/l3fwd-graph/main.c, examples/l3fwd-power/main.c, examples/link_status_interrupt/main.c, and examples/packet_ordering/main.c.

◆ rte_lcore_count()

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.

Examples:: examples/distributor/main.c, examples/dma/dmafwd.c, examples/ethtool/ethtool-app/main.c, examples/eventdev_pipeline/main.c, examples/flow_classify/flow_classify.c, examples/ip_fragmentation/main.c, examples/ip_reassembly/main.c, examples/ipsec-secgw/event_helper.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipv4_multicast/main.c, examples/l2fwd-cat/l2fwd-cat.c, examples/l2fwd-event/l2fwd_event_generic.c, examples/l2fwd-event/l2fwd_event_internal_port.c, examples/l2fwd-event/main.c, examples/l3fwd-graph/main.c, examples/l3fwd-power/main.c, examples/l3fwd/l3fwd_event.c, examples/l3fwd/l3fwd_event_generic.c, examples/l3fwd/l3fwd_event_internal_port.c, examples/l3fwd/main.c, examples/multi_process/symmetric_mp/main.c, examples/ntb/ntb_fwd.c, examples/packet_ordering/main.c, examples/ptpclient/ptpclient.c, examples/qos_meter/main.c, examples/rxtx_callbacks/main.c, examples/service_cores/main.c, examples/skeleton/basicfwd.c, examples/vhost/main.c, examples/vmdq/main.c, and examples/vmdq_dcb/main.c.

◆ rte_lcore_index()

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.

Examples:: examples/vm_power_manager/channel_manager.c, and examples/vm_power_manager/power_manager.c.

◆ rte_socket_id()

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

Examples:: examples/bbdev_app/main.c, examples/bond/main.c, examples/distributor/main.c, examples/dma/dmafwd.c, examples/ethtool/ethtool-app/main.c, examples/eventdev_pipeline/pipeline_worker_generic.c, examples/eventdev_pipeline/pipeline_worker_tx.c, examples/fips_validation/fips_dev_self_test.c, examples/fips_validation/main.c, examples/flow_classify/flow_classify.c, examples/flow_filtering/main.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipsec-secgw/sad.c, examples/ipv4_multicast/main.c, examples/l2fwd-cat/l2fwd-cat.c, examples/l2fwd-crypto/main.c, examples/l2fwd-event/main.c, examples/l2fwd-jobstats/main.c, examples/l2fwd-keepalive/main.c, examples/l2fwd/main.c, examples/l3fwd-power/main.c, examples/link_status_interrupt/main.c, examples/multi_process/client_server_mp/mp_server/init.c, examples/multi_process/simple_mp/main.c, examples/multi_process/symmetric_mp/main.c, examples/ntb/ntb_fwd.c, examples/packet_ordering/main.c, examples/ptpclient/ptpclient.c, examples/qos_meter/main.c, examples/rxtx_callbacks/main.c, examples/server_node_efd/node/node.c, examples/server_node_efd/server/init.c, examples/server_node_efd/server/main.c, examples/skeleton/basicfwd.c, examples/vhost/main.c, examples/vm_power_manager/main.c, examples/vmdq/main.c, and examples/vmdq_dcb/main.c.

◆ rte_socket_count()

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

Examples:: examples/ipsec-secgw/ipsec-secgw.c.

◆ rte_socket_id_by_idx()

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

Examples:: examples/ipsec-secgw/ipsec-secgw.c.

◆ rte_lcore_to_socket_id()

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

Examples:: examples/flow_classify/flow_classify.c, examples/ip_fragmentation/main.c, examples/ip_pipeline/thread.c, examples/ip_reassembly/main.c, examples/ipsec-secgw/event_helper.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipsec-secgw/ipsec_worker.c, examples/ipv4_multicast/main.c, examples/l3fwd-graph/main.c, examples/l3fwd-power/main.c, examples/l3fwd/l3fwd_acl.c, examples/l3fwd/main.c, examples/qos_sched/args.c, examples/qos_sched/init.c, and examples/vhost_crypto/main.c.

◆ rte_lcore_to_cpu_id()

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_lcore_cpuset()

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

◆ rte_lcore_is_enabled()

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.

Examples:: examples/bbdev_app/main.c, examples/eventdev_pipeline/main.c, examples/ip_fragmentation/main.c, examples/ip_pipeline/thread.c, examples/ip_reassembly/main.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipv4_multicast/main.c, examples/l2fwd-crypto/main.c, examples/l2fwd-event/l2fwd_poll.c, examples/l2fwd-jobstats/main.c, examples/l2fwd-keepalive/main.c, examples/l2fwd/main.c, examples/l3fwd-graph/main.c, examples/l3fwd-power/main.c, examples/l3fwd-power/perf_core.c, examples/l3fwd/main.c, examples/link_status_interrupt/main.c, examples/packet_ordering/main.c, examples/vhost/main.c, and examples/vmdq/main.c.

◆ rte_get_next_lcore()

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.

Examples:: examples/bond/main.c, examples/dma/dmafwd.c, examples/ethtool/ethtool-app/main.c, examples/flow_classify/flow_classify.c, examples/ipsec-secgw/event_helper.c, examples/ipsec-secgw/ipsec-secgw.c, examples/timer/main.c, examples/vm_power_manager/guest_cli/vm_power_cli_guest.c, and examples/vm_power_manager/main.c.

◆ rte_lcore_callback_register()

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.

◆ rte_lcore_callback_unregister()

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.

◆ rte_lcore_iterate()

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).

◆ rte_lcore_register_usage_cb()

__rte_experimental void rte_lcore_register_usage_cb ( rte_lcore_usage_cb cb )

Warning: EXPERIMENTAL: this API may change without prior notice.

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.

◆ rte_lcore_dump()

void rte_lcore_dump ( FILE * f )

List all lcores.

Parameters

f	The output stream where the dump should be sent.

◆ rte_thread_setname()

int rte_thread_setname	(	pthread_t	id,
		const char *	name
	)

Set thread names.

Note: It fails with glibc < 2.12.

Parameters

id	Thread id.
name	Thread name to set.

Returns: On success, return 0; otherwise return a negative value.

◆ rte_thread_register()

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.

◆ rte_thread_unregister()

void rte_thread_unregister ( void )

Unregister current thread and release lcore if one was associated.

◆ rte_ctrl_thread_create()

int rte_ctrl_thread_create	(	pthread_t *	thread,
		const char *	name,
		const pthread_attr_t *	attr,
		void ()(void *)	start_routine,
		void *	arg
	)

Create a control thread.

Creates a control thread with the given name and attributes. The affinity of the new thread is based on the CPU affinity retrieved at the time rte_eal_init() was called, the dataplane and service lcores are then excluded. If setting the name of the thread fails, the error is ignored and a debug message is logged.

Parameters

thread	Filled with the thread id of the new created thread.
name	The name of the control thread (max 16 characters including '\0').
attr	Attributes for the new thread.
start_routine	Function to be executed by the new thread.
arg	Argument passed to start_routine.

Returns: On success, returns 0; on error, it returns a negative value corresponding to the error number.

Examples:: examples/vhost/main.c, and examples/vhost_blk/vhost_blk.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ LCORE_ID_ANY

◆ RTE_LCORE_FOREACH

◆ RTE_LCORE_FOREACH_WORKER

Typedef Documentation

◆ rte_lcore_init_cb

◆ rte_lcore_uninit_cb

◆ rte_lcore_iterate_cb

◆ rte_lcore_usage_cb

Enumeration Type Documentation

◆ rte_lcore_role_t

Function Documentation

◆ RTE_DECLARE_PER_LCORE()

◆ rte_eal_lcore_role()

◆ rte_lcore_has_role()

◆ rte_lcore_id()

◆ rte_get_main_lcore()

◆ rte_lcore_count()

◆ rte_lcore_index()

◆ rte_socket_id()

◆ rte_socket_count()

◆ rte_socket_id_by_idx()

◆ rte_lcore_to_socket_id()

◆ rte_lcore_to_cpu_id()

◆ rte_lcore_cpuset()

◆ rte_lcore_is_enabled()

◆ rte_get_next_lcore()

◆ rte_lcore_callback_register()

◆ rte_lcore_callback_unregister()

◆ rte_lcore_iterate()

◆ rte_lcore_register_usage_cb()

◆ rte_lcore_dump()

◆ rte_thread_setname()

◆ rte_thread_register()

◆ rte_thread_unregister()

◆ rte_ctrl_thread_create()