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