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