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 #include <rte_thread.h> 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 #define LCORE_ID_ANY UINT32_MAX /**< Any lcore. */ 25 26 RTE_DECLARE_PER_LCORE(unsigned, _lcore_id); /**< Per thread "lcore id". */ 27 28 /** 29 * The lcore role (used in RTE or not). 30 */ 31 enum rte_lcore_role_t { 32 ROLE_RTE, 33 ROLE_OFF, 34 ROLE_SERVICE, 35 ROLE_NON_EAL, 36 }; 37 38 /** 39 * Get a lcore's role. 40 * 41 * @param lcore_id 42 * The identifier of the lcore, which MUST be between 0 and RTE_MAX_LCORE-1. 43 * @return 44 * The role of the lcore. 45 */ 46 enum rte_lcore_role_t rte_eal_lcore_role(unsigned int lcore_id); 47 48 /** 49 * Test if the core supplied has a specific role 50 * 51 * @param lcore_id 52 * The identifier of the lcore, which MUST be between 0 and 53 * RTE_MAX_LCORE-1. 54 * @param role 55 * The role to be checked against. 56 * @return 57 * Boolean value: positive if test is true; otherwise returns 0. 58 */ 59 int 60 rte_lcore_has_role(unsigned int lcore_id, enum rte_lcore_role_t role); 61 62 /** 63 * Return the Application thread ID of the execution unit. 64 * 65 * Note: in most cases the lcore id returned here will also correspond 66 * to the processor id of the CPU on which the thread is pinned, this 67 * will not be the case if the user has explicitly changed the thread to 68 * core affinities using --lcores EAL argument e.g. --lcores '(0-3)@10' 69 * to run threads with lcore IDs 0, 1, 2 and 3 on physical core 10.. 70 * 71 * @return 72 * Logical core ID (in EAL thread or registered non-EAL thread) or 73 * LCORE_ID_ANY (in unregistered non-EAL thread) 74 */ 75 static inline unsigned 76 rte_lcore_id(void) 77 { 78 return RTE_PER_LCORE(_lcore_id); 79 } 80 81 /** 82 * Get the id of the main lcore 83 * 84 * @return 85 * the id of the main lcore 86 */ 87 unsigned int rte_get_main_lcore(void); 88 89 /** 90 * Deprecated function the id of the main lcore 91 * 92 * @return 93 * the id of the main lcore 94 */ 95 __rte_deprecated 96 static inline unsigned int rte_get_master_lcore(void) 97 { 98 return rte_get_main_lcore(); 99 } 100 101 /** 102 * Return the number of execution units (lcores) on the system. 103 * 104 * @return 105 * the number of execution units (lcores) on the system. 106 */ 107 unsigned int rte_lcore_count(void); 108 109 /** 110 * Return the index of the lcore starting from zero. 111 * 112 * When option -c or -l is given, the index corresponds 113 * to the order in the list. 114 * For example: 115 * -c 0x30, lcore 4 has index 0, and 5 has index 1. 116 * -l 22,18 lcore 22 has index 0, and 18 has index 1. 117 * 118 * @param lcore_id 119 * The targeted lcore, or -1 for the current one. 120 * @return 121 * The relative index, or -1 if not enabled. 122 */ 123 int rte_lcore_index(int lcore_id); 124 125 /** 126 * Return the ID of the physical socket of the logical core we are 127 * running on. 128 * @return 129 * the ID of current lcoreid's physical socket 130 */ 131 unsigned int rte_socket_id(void); 132 133 /** 134 * Return number of physical sockets detected on the system. 135 * 136 * Note that number of nodes may not be correspondent to their physical id's: 137 * for example, a system may report two socket id's, but the actual socket id's 138 * may be 0 and 8. 139 * 140 * @return 141 * the number of physical sockets as recognized by EAL 142 */ 143 unsigned int 144 rte_socket_count(void); 145 146 /** 147 * Return socket id with a particular index. 148 * 149 * This will return socket id at a particular position in list of all detected 150 * physical socket id's. For example, on a machine with sockets [0, 8], passing 151 * 1 as a parameter will return 8. 152 * 153 * @param idx 154 * index of physical socket id to return 155 * 156 * @return 157 * - physical socket id as recognized by EAL 158 * - -1 on error, with errno set to EINVAL 159 */ 160 int 161 rte_socket_id_by_idx(unsigned int idx); 162 163 /** 164 * Get the ID of the physical socket of the specified lcore 165 * 166 * @param lcore_id 167 * the targeted lcore, which MUST be between 0 and RTE_MAX_LCORE-1. 168 * @return 169 * the ID of lcoreid's physical socket 170 */ 171 unsigned int 172 rte_lcore_to_socket_id(unsigned int lcore_id); 173 174 /** 175 * @warning 176 * @b EXPERIMENTAL: this API may change without prior notice. 177 * 178 * Return the id of the lcore on a socket starting from zero. 179 * 180 * @param lcore_id 181 * The targeted lcore, or -1 for the current one. 182 * @return 183 * The relative index, or -1 if not enabled. 184 */ 185 __rte_experimental 186 int 187 rte_lcore_to_cpu_id(int lcore_id); 188 189 #ifdef RTE_HAS_CPUSET 190 191 /** 192 * @warning 193 * @b EXPERIMENTAL: this API may change without prior notice. 194 * 195 * Return the cpuset for a given lcore. 196 * @param lcore_id 197 * the targeted lcore, which MUST be between 0 and RTE_MAX_LCORE-1. 198 * @return 199 * The cpuset of that lcore 200 */ 201 __rte_experimental 202 rte_cpuset_t 203 rte_lcore_cpuset(unsigned int lcore_id); 204 205 #endif /* RTE_HAS_CPUSET */ 206 207 /** 208 * Test if an lcore is enabled. 209 * 210 * @param lcore_id 211 * The identifier of the lcore, which MUST be between 0 and 212 * RTE_MAX_LCORE-1. 213 * @return 214 * True if the given lcore is enabled; false otherwise. 215 */ 216 int rte_lcore_is_enabled(unsigned int lcore_id); 217 218 /** 219 * Get the next enabled lcore ID. 220 * 221 * @param i 222 * The current lcore (reference). 223 * @param skip_main 224 * If true, do not return the ID of the main lcore. 225 * @param wrap 226 * If true, go back to 0 when RTE_MAX_LCORE is reached; otherwise, 227 * return RTE_MAX_LCORE. 228 * @return 229 * The next lcore_id or RTE_MAX_LCORE if not found. 230 */ 231 unsigned int rte_get_next_lcore(unsigned int i, int skip_main, int wrap); 232 233 /** 234 * Macro to browse all running lcores. 235 */ 236 #define RTE_LCORE_FOREACH(i) \ 237 for (i = rte_get_next_lcore(-1, 0, 0); \ 238 i < RTE_MAX_LCORE; \ 239 i = rte_get_next_lcore(i, 0, 0)) 240 241 /** 242 * Macro to browse all running lcores except the main lcore. 243 */ 244 #define RTE_LCORE_FOREACH_WORKER(i) \ 245 for (i = rte_get_next_lcore(-1, 1, 0); \ 246 i < RTE_MAX_LCORE; \ 247 i = rte_get_next_lcore(i, 1, 0)) 248 249 #define RTE_LCORE_FOREACH_SLAVE(l) \ 250 RTE_DEPRECATED(RTE_LCORE_FOREACH_SLAVE) RTE_LCORE_FOREACH_WORKER(l) 251 252 /** 253 * Callback prototype for initializing lcores. 254 * 255 * @param lcore_id 256 * The lcore to consider. 257 * @param arg 258 * An opaque pointer passed at callback registration. 259 * @return 260 * - -1 when refusing this operation, 261 * - 0 otherwise. 262 */ 263 typedef int (*rte_lcore_init_cb)(unsigned int lcore_id, void *arg); 264 265 /** 266 * Callback prototype for uninitializing lcores. 267 * 268 * @param lcore_id 269 * The lcore to consider. 270 * @param arg 271 * An opaque pointer passed at callback registration. 272 */ 273 typedef void (*rte_lcore_uninit_cb)(unsigned int lcore_id, void *arg); 274 275 /** 276 * Register callbacks invoked when initializing and uninitializing a lcore. 277 * 278 * This function calls the init callback with all initialized lcores. 279 * Any error reported by the init callback triggers a rollback calling the 280 * uninit callback for each lcore. 281 * If this step succeeds, the callbacks are put in the lcore callbacks list 282 * that will get called for each lcore allocation/release. 283 * 284 * Note: callbacks execution is serialised under a write lock protecting the 285 * lcores and callbacks list. 286 * 287 * @param name 288 * A name serving as a small description for this callback. 289 * @param init 290 * The callback invoked when a lcore_id is initialized. 291 * init can be NULL. 292 * @param uninit 293 * The callback invoked when a lcore_id is uninitialized. 294 * uninit can be NULL. 295 * @param arg 296 * An optional argument that gets passed to the callback when it gets 297 * invoked. 298 * @return 299 * On success, returns an opaque pointer for the registered object. 300 * On failure (either memory allocation issue in the function itself or an 301 * error is returned by the init callback itself), returns NULL. 302 */ 303 __rte_experimental 304 void * 305 rte_lcore_callback_register(const char *name, rte_lcore_init_cb init, 306 rte_lcore_uninit_cb uninit, void *arg); 307 308 /** 309 * Unregister callbacks previously registered with rte_lcore_callback_register. 310 * 311 * This function calls the uninit callback with all initialized lcores. 312 * The callbacks are then removed from the lcore callbacks list. 313 * 314 * @param handle 315 * The handle pointer returned by a former successful call to 316 * rte_lcore_callback_register. 317 */ 318 __rte_experimental 319 void 320 rte_lcore_callback_unregister(void *handle); 321 322 /** 323 * Callback prototype for iterating over lcores. 324 * 325 * @param lcore_id 326 * The lcore to consider. 327 * @param arg 328 * An opaque pointer coming from the caller. 329 * @return 330 * - 0 lets the iteration continue. 331 * - !0 makes the iteration stop. 332 */ 333 typedef int (*rte_lcore_iterate_cb)(unsigned int lcore_id, void *arg); 334 335 /** 336 * Iterate on all active lcores (ROLE_RTE, ROLE_SERVICE and ROLE_NON_EAL). 337 * No modification on the lcore states is allowed in the callback. 338 * 339 * Note: as opposed to init/uninit callbacks, iteration callbacks can be 340 * invoked in parallel as they are run under a read lock protecting the lcores 341 * and callbacks list. 342 * 343 * @param cb 344 * The callback that gets passed each lcore. 345 * @param arg 346 * An opaque pointer passed to cb. 347 * @return 348 * Same return code as the callback last invocation (see rte_lcore_iterate_cb 349 * description). 350 */ 351 __rte_experimental 352 int 353 rte_lcore_iterate(rte_lcore_iterate_cb cb, void *arg); 354 355 /** 356 * List all lcores. 357 * 358 * @param f 359 * The output stream where the dump should be sent. 360 */ 361 __rte_experimental 362 void 363 rte_lcore_dump(FILE *f); 364 365 /** 366 * Set thread names. 367 * 368 * @note It fails with glibc < 2.12. 369 * 370 * @param id 371 * Thread id. 372 * @param name 373 * Thread name to set. 374 * @return 375 * On success, return 0; otherwise return a negative value. 376 */ 377 int rte_thread_setname(pthread_t id, const char *name); 378 379 /** 380 * Get thread name. 381 * 382 * @note It fails with glibc < 2.12. 383 * 384 * @param id 385 * Thread id. 386 * @param name 387 * Thread name to set. 388 * @param len 389 * Thread name buffer length. 390 * @return 391 * On success, return 0; otherwise return a negative value. 392 */ 393 __rte_experimental 394 int rte_thread_getname(pthread_t id, char *name, size_t len); 395 396 /** 397 * Register current non-EAL thread as a lcore. 398 * 399 * @note This API is not compatible with the multi-process feature: 400 * - if a primary process registers a non-EAL thread, then no secondary process 401 * will initialise. 402 * - if a secondary process initialises successfully, trying to register a 403 * non-EAL thread from either primary or secondary processes will always end 404 * up with the thread getting LCORE_ID_ANY as lcore. 405 * 406 * @return 407 * On success, return 0; otherwise return -1 with rte_errno set. 408 */ 409 __rte_experimental 410 int 411 rte_thread_register(void); 412 413 /** 414 * Unregister current thread and release lcore if one was associated. 415 */ 416 __rte_experimental 417 void 418 rte_thread_unregister(void); 419 420 /** 421 * Create a control thread. 422 * 423 * Wrapper to pthread_create(), pthread_setname_np() and 424 * pthread_setaffinity_np(). The affinity of the new thread is based 425 * on the CPU affinity retrieved at the time rte_eal_init() was called, 426 * the dataplane and service lcores are then excluded. 427 * 428 * @param thread 429 * Filled with the thread id of the new created thread. 430 * @param name 431 * The name of the control thread (max 16 characters including '\0'). 432 * @param attr 433 * Attributes for the new thread. 434 * @param start_routine 435 * Function to be executed by the new thread. 436 * @param arg 437 * Argument passed to start_routine. 438 * @return 439 * On success, returns 0; on error, it returns a negative value 440 * corresponding to the error number. 441 */ 442 int 443 rte_ctrl_thread_create(pthread_t *thread, const char *name, 444 const pthread_attr_t *attr, 445 void *(*start_routine)(void *), void *arg); 446 447 #ifdef __cplusplus 448 } 449 #endif 450 451 452 #endif /* _RTE_LCORE_H_ */ 453