lib/librte_eal/include/rte_lcore.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2014 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_LCORE_H_
   6 #define _RTE_LCORE_H_
   7
   8 /**
   9  * @file
  10  *
  11  * API for lcore and socket manipulation
  12  *
  13  */
  14 #include <rte_config.h>
  15 #include <rte_per_lcore.h>
  16 #include <rte_eal.h>
  17 #include <rte_launch.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 #define LCORE_ID_ANY     UINT32_MAX       /**< Any lcore. */
  24
  25 RTE_DECLARE_PER_LCORE(unsigned, _lcore_id);  /**< Per thread "lcore id". */
  26
  27 /**
  28  * The lcore role (used in RTE or not).
  29  */
  30 enum rte_lcore_role_t {
  31         ROLE_RTE,
  32         ROLE_OFF,
  33         ROLE_SERVICE,
  34 };
  35
  36 /**
  37  * Get a lcore's role.
  38  *
  39  * @param lcore_id
  40  *   The identifier of the lcore, which MUST be between 0 and RTE_MAX_LCORE-1.
  41  * @return
  42  *   The role of the lcore.
  43  */
  44 enum rte_lcore_role_t rte_eal_lcore_role(unsigned int lcore_id);
  45
  46 /**
  47  * Test if the core supplied has a specific role
  48  *
  49  * @param lcore_id
  50  *   The identifier of the lcore, which MUST be between 0 and
  51  *   RTE_MAX_LCORE-1.
  52  * @param role
  53  *   The role to be checked against.
  54  * @return
  55  *   Boolean value: positive if test is true; otherwise returns 0.
  56  */
  57 int
  58 rte_lcore_has_role(unsigned int lcore_id, enum rte_lcore_role_t role);
  59
  60 /**
  61  * Return the Application thread ID of the execution unit.
  62  *
  63  * Note: in most cases the lcore id returned here will also correspond
  64  *   to the processor id of the CPU on which the thread is pinned, this
  65  *   will not be the case if the user has explicitly changed the thread to
  66  *   core affinities using --lcores EAL argument e.g. --lcores '(0-3)@10'
  67  *   to run threads with lcore IDs 0, 1, 2 and 3 on physical core 10..
  68  *
  69  * @return
  70  *  Logical core ID (in EAL thread) or LCORE_ID_ANY (in non-EAL thread)
  71  */
  72 static inline unsigned
  73 rte_lcore_id(void)
  74 {
  75         return RTE_PER_LCORE(_lcore_id);
  76 }
  77
  78 /**
  79  * Get the id of the master lcore
  80  *
  81  * @return
  82  *   the id of the master lcore
  83  */
  84 unsigned int rte_get_master_lcore(void);
  85
  86 /**
  87  * Return the number of execution units (lcores) on the system.
  88  *
  89  * @return
  90  *   the number of execution units (lcores) on the system.
  91  */
  92 unsigned int rte_lcore_count(void);
  93
  94 /**
  95  * Return the index of the lcore starting from zero.
  96  *
  97  * When option -c or -l is given, the index corresponds
  98  * to the order in the list.
  99  * For example:
 100  * -c 0x30, lcore 4 has index 0, and 5 has index 1.
 101  * -l 22,18 lcore 22 has index 0, and 18 has index 1.
 102  *
 103  * @param lcore_id
 104  *   The targeted lcore, or -1 for the current one.
 105  * @return
 106  *   The relative index, or -1 if not enabled.
 107  */
 108 int rte_lcore_index(int lcore_id);
 109
 110 /**
 111  * Return the ID of the physical socket of the logical core we are
 112  * running on.
 113  * @return
 114  *   the ID of current lcoreid's physical socket
 115  */
 116 unsigned int rte_socket_id(void);
 117
 118 /**
 119  * Return number of physical sockets detected on the system.
 120  *
 121  * Note that number of nodes may not be correspondent to their physical id's:
 122  * for example, a system may report two socket id's, but the actual socket id's
 123  * may be 0 and 8.
 124  *
 125  * @return
 126  *   the number of physical sockets as recognized by EAL
 127  */
 128 unsigned int
 129 rte_socket_count(void);
 130
 131 /**
 132  * Return socket id with a particular index.
 133  *
 134  * This will return socket id at a particular position in list of all detected
 135  * physical socket id's. For example, on a machine with sockets [0, 8], passing
 136  * 1 as a parameter will return 8.
 137  *
 138  * @param idx
 139  *   index of physical socket id to return
 140  *
 141  * @return
 142  *   - physical socket id as recognized by EAL
 143  *   - -1 on error, with errno set to EINVAL
 144  */
 145 int
 146 rte_socket_id_by_idx(unsigned int idx);
 147
 148 /**
 149  * Get the ID of the physical socket of the specified lcore
 150  *
 151  * @param lcore_id
 152  *   the targeted lcore, which MUST be between 0 and RTE_MAX_LCORE-1.
 153  * @return
 154  *   the ID of lcoreid's physical socket
 155  */
 156 unsigned int
 157 rte_lcore_to_socket_id(unsigned int lcore_id);
 158
 159 /**
 160  * @warning
 161  * @b EXPERIMENTAL: this API may change without prior notice.
 162  *
 163  * Return the id of the lcore on a socket starting from zero.
 164  *
 165  * @param lcore_id
 166  *   The targeted lcore, or -1 for the current one.
 167  * @return
 168  *   The relative index, or -1 if not enabled.
 169  */
 170 __rte_experimental
 171 int
 172 rte_lcore_to_cpu_id(int lcore_id);
 173
 174 /**
 175  * @warning
 176  * @b EXPERIMENTAL: this API may change without prior notice.
 177  *
 178  * Return the cpuset for a given lcore.
 179  * @param lcore_id
 180  *   the targeted lcore, which MUST be between 0 and RTE_MAX_LCORE-1.
 181  * @return
 182  *   The cpuset of that lcore
 183  */
 184 __rte_experimental
 185 rte_cpuset_t
 186 rte_lcore_cpuset(unsigned int lcore_id);
 187
 188 /**
 189  * Test if an lcore is enabled.
 190  *
 191  * @param lcore_id
 192  *   The identifier of the lcore, which MUST be between 0 and
 193  *   RTE_MAX_LCORE-1.
 194  * @return
 195  *   True if the given lcore is enabled; false otherwise.
 196  */
 197 int rte_lcore_is_enabled(unsigned int lcore_id);
 198
 199 /**
 200  * Get the next enabled lcore ID.
 201  *
 202  * @param i
 203  *   The current lcore (reference).
 204  * @param skip_master
 205  *   If true, do not return the ID of the master lcore.
 206  * @param wrap
 207  *   If true, go back to 0 when RTE_MAX_LCORE is reached; otherwise,
 208  *   return RTE_MAX_LCORE.
 209  * @return
 210  *   The next lcore_id or RTE_MAX_LCORE if not found.
 211  */
 212 unsigned int rte_get_next_lcore(unsigned int i, int skip_master, int wrap);
 213
 214 /**
 215  * Macro to browse all running lcores.
 216  */
 217 #define RTE_LCORE_FOREACH(i)                                            \
 218         for (i = rte_get_next_lcore(-1, 0, 0);                          \
 219              i<RTE_MAX_LCORE;                                           \
 220              i = rte_get_next_lcore(i, 0, 0))
 221
 222 /**
 223  * Macro to browse all running lcores except the master lcore.
 224  */
 225 #define RTE_LCORE_FOREACH_SLAVE(i)                                      \
 226         for (i = rte_get_next_lcore(-1, 1, 0);                          \
 227              i<RTE_MAX_LCORE;                                           \
 228              i = rte_get_next_lcore(i, 1, 0))
 229
 230 /**
 231  * Set core affinity of the current thread.
 232  * Support both EAL and non-EAL thread and update TLS.
 233  *
 234  * @param cpusetp
 235  *   Point to cpu_set_t for setting current thread affinity.
 236  * @return
 237  *   On success, return 0; otherwise return -1;
 238  */
 239 int rte_thread_set_affinity(rte_cpuset_t *cpusetp);
 240
 241 /**
 242  * Get core affinity of the current thread.
 243  *
 244  * @param cpusetp
 245  *   Point to cpu_set_t for getting current thread cpu affinity.
 246  *   It presumes input is not NULL, otherwise it causes panic.
 247  *
 248  */
 249 void rte_thread_get_affinity(rte_cpuset_t *cpusetp);
 250
 251 /**
 252  * Set thread names.
 253  *
 254  * @note It fails with glibc < 2.12.
 255  *
 256  * @param id
 257  *   Thread id.
 258  * @param name
 259  *   Thread name to set.
 260  * @return
 261  *   On success, return 0; otherwise return a negative value.
 262  */
 263 int rte_thread_setname(pthread_t id, const char *name);
 264
 265 /**
 266  * Get thread name.
 267  *
 268  * @note It fails with glibc < 2.12.
 269  *
 270  * @param id
 271  *   Thread id.
 272  * @param name
 273  *   Thread name to set.
 274  * @param len
 275  *   Thread name buffer length.
 276  * @return
 277  *   On success, return 0; otherwise return a negative value.
 278  */
 279 __rte_experimental
 280 int rte_thread_getname(pthread_t id, char *name, size_t len);
 281
 282 /**
 283  * Create a control thread.
 284  *
 285  * Wrapper to pthread_create(), pthread_setname_np() and
 286  * pthread_setaffinity_np(). The affinity of the new thread is based
 287  * on the CPU affinity retrieved at the time rte_eal_init() was called,
 288  * the dataplane and service lcores are then excluded.
 289  *
 290  * @param thread
 291  *   Filled with the thread id of the new created thread.
 292  * @param name
 293  *   The name of the control thread (max 16 characters including '\0').
 294  * @param attr
 295  *   Attributes for the new thread.
 296  * @param start_routine
 297  *   Function to be executed by the new thread.
 298  * @param arg
 299  *   Argument passed to start_routine.
 300  * @return
 301  *   On success, returns 0; on error, it returns a negative value
 302  *   corresponding to the error number.
 303  */
 304 int
 305 rte_ctrl_thread_create(pthread_t *thread, const char *name,
 306                 const pthread_attr_t *attr,
 307                 void *(*start_routine)(void *), void *arg);
 308
 309 #ifdef __cplusplus
 310 }
 311 #endif
 312
 313
 314 #endif /* _RTE_LCORE_H_ */