DPDK  21.02.0
Macros | Typedefs | Enumerations | Functions
rte_lcore.h File Reference
#include <rte_config.h>
#include <rte_per_lcore.h>
#include <rte_eal.h>
#include <rte_launch.h>
#include <rte_thread.h>

Go to the source code of this file.

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)
 

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)
 
static __rte_deprecated unsigned int rte_get_master_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)
 
__rte_experimental int rte_lcore_to_cpu_id (int lcore_id)
 
__rte_experimental 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)
 
__rte_experimental void * rte_lcore_callback_register (const char *name, rte_lcore_init_cb init, rte_lcore_uninit_cb uninit, void *arg)
 
__rte_experimental void rte_lcore_callback_unregister (void *handle)
 
__rte_experimental int rte_lcore_iterate (rte_lcore_iterate_cb cb, void *arg)
 
__rte_experimental void rte_lcore_dump (FILE *f)
 
int rte_thread_setname (pthread_t id, const char *name)
 
__rte_experimental int rte_thread_getname (pthread_t id, char *name, size_t len)
 
__rte_experimental int rte_thread_register (void)
 
__rte_experimental 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

#define LCORE_ID_ANY   UINT32_MAX

Any lcore.

Definition at line 24 of file rte_lcore.h.

#define RTE_LCORE_FOREACH (   i)
#define RTE_LCORE_FOREACH_WORKER (   i)

Typedef Documentation

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

Callback prototype for initializing lcores.

Parameters
lcore_idThe lcore to consider.
argAn opaque pointer passed at callback registration.
Returns
  • -1 when refusing this operation,
  • 0 otherwise.

Definition at line 259 of file rte_lcore.h.

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

Callback prototype for uninitializing lcores.

Parameters
lcore_idThe lcore to consider.
argAn opaque pointer passed at callback registration.

Definition at line 269 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_idThe lcore to consider.
argAn opaque pointer coming from the caller.
Returns
  • 0 lets the iteration continue.
  • !0 makes the iteration stop.

Definition at line 329 of file rte_lcore.h.

Enumeration Type Documentation

The lcore role (used in RTE or not).

Definition at line 31 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_idThe 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_idThe identifier of the lcore, which MUST be between 0 and RTE_MAX_LCORE-1.
roleThe role to be checked against.
Returns
Boolean value: positive if test is true; otherwise returns 0.
Examples:
examples/qos_sched/args.c.
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/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/ioat/ioatfwd.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.c, examples/ipsec-secgw/ipsec_worker.c, examples/ipv4_multicast/main.c, examples/kni/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-acl/main.c, examples/l3fwd-graph/main.c, examples/l3fwd-power/main.c, examples/l3fwd/l3fwd_em.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/performance-thread/common/lthread.c, examples/performance-thread/common/lthread_diag.c, examples/performance-thread/common/lthread_sched.c, examples/performance-thread/l3fwd-thread/main.c, examples/performance-thread/pthread_shim/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 76 of file rte_lcore.h.

unsigned int rte_get_main_lcore ( void  )
static __rte_deprecated unsigned int rte_get_master_lcore ( void  )
inlinestatic

Deprecated function the id of the main lcore

Returns
the id of the main lcore

Definition at line 96 of file rte_lcore.h.

unsigned int rte_lcore_count ( void  )
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_idThe targeted lcore, or -1 for the current one.
Returns
The relative index, or -1 if not enabled.
Examples:
examples/performance-thread/common/lthread_sched.c, examples/vm_power_manager/channel_manager.c, and examples/vm_power_manager/power_manager.c.
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/ethtool/ethtool-app/main.c, examples/ethtool/lib/rte_ethtool.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/ioat/ioatfwd.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipsec-secgw/sad.c, examples/ipv4_multicast/main.c, examples/kni/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/performance-thread/common/lthread_sched.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.
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.
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
idxindex 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.
unsigned int rte_lcore_to_socket_id ( unsigned int  lcore_id)
__rte_experimental int rte_lcore_to_cpu_id ( int  lcore_id)
Warning
EXPERIMENTAL: this API may change without prior notice.

Return the id of the lcore on a socket starting from zero.

Parameters
lcore_idThe targeted lcore, or -1 for the current one.
Returns
The relative index, or -1 if not enabled.
__rte_experimental rte_cpuset_t rte_lcore_cpuset ( unsigned int  lcore_id)
Warning
EXPERIMENTAL: this API may change without prior notice.

Return the cpuset for a given lcore.

Parameters
lcore_idthe 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)
unsigned int rte_get_next_lcore ( unsigned int  i,
int  skip_main,
int  wrap 
)

Get the next enabled lcore ID.

Parameters
iThe current lcore (reference).
skip_mainIf true, do not return the ID of the main lcore.
wrapIf 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/ethtool/ethtool-app/main.c, examples/ioat/ioatfwd.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_experimental 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
nameA name serving as a small description for this callback.
initThe callback invoked when a lcore_id is initialized. init can be NULL.
uninitThe callback invoked when a lcore_id is uninitialized. uninit can be NULL.
argAn 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_experimental 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
handleThe handle pointer returned by a former successful call to rte_lcore_callback_register.
__rte_experimental 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
cbThe callback that gets passed each lcore.
argAn opaque pointer passed to cb.
Returns
Same return code as the callback last invocation (see rte_lcore_iterate_cb description).
__rte_experimental void rte_lcore_dump ( FILE *  f)

List all lcores.

Parameters
fThe output stream where the dump should be sent.
int rte_thread_setname ( pthread_t  id,
const char *  name 
)

Set thread names.

Note
It fails with glibc < 2.12.
Parameters
idThread id.
nameThread name to set.
Returns
On success, return 0; otherwise return a negative value.
__rte_experimental int rte_thread_getname ( pthread_t  id,
char *  name,
size_t  len 
)

Get thread name.

Note
It fails with glibc < 2.12.
Parameters
idThread id.
nameThread name to set.
lenThread name buffer length.
Returns
On success, return 0; otherwise return a negative value.
__rte_experimental 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_experimental void rte_thread_unregister ( void  )

Unregister current thread and release lcore if one was associated.

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.

Wrapper to pthread_create(), pthread_setname_np() and pthread_setaffinity_np(). 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.

Parameters
threadFilled with the thread id of the new created thread.
nameThe name of the control thread (max 16 characters including '\0').
attrAttributes for the new thread.
start_routineFunction to be executed by the new thread.
argArgument passed to start_routine.
Returns
On success, returns 0; on error, it returns a negative value corresponding to the error number.
Examples:
examples/kni/main.c, and examples/vhost/main.c.