]>
Commit | Line | Data |
---|---|---|
9f95a23c TL |
1 | /* SPDX-License-Identifier: BSD-3-Clause |
2 | * Copyright(c) 2010-2018 Intel Corporation | |
7c673cae FG |
3 | */ |
4 | ||
5 | #ifndef _RTE_EAL_H_ | |
6 | #define _RTE_EAL_H_ | |
7 | ||
8 | /** | |
9 | * @file | |
10 | * | |
11 | * EAL Configuration API | |
12 | */ | |
13 | ||
14 | #include <stdint.h> | |
15 | #include <sched.h> | |
9f95a23c | 16 | #include <time.h> |
7c673cae | 17 | |
7c673cae | 18 | #include <rte_config.h> |
9f95a23c TL |
19 | #include <rte_compat.h> |
20 | #include <rte_per_lcore.h> | |
21 | #include <rte_bus.h> | |
22 | ||
23 | #include <rte_pci_dev_feature_defs.h> | |
7c673cae FG |
24 | |
25 | #ifdef __cplusplus | |
26 | extern "C" { | |
27 | #endif | |
28 | ||
29 | #define RTE_MAGIC 19820526 /**< Magic number written by the main partition when ready. */ | |
30 | ||
31 | /* Maximum thread_name length. */ | |
32 | #define RTE_MAX_THREAD_NAME_LEN 16 | |
33 | ||
34 | /** | |
35 | * The lcore role (used in RTE or not). | |
36 | */ | |
37 | enum rte_lcore_role_t { | |
38 | ROLE_RTE, | |
39 | ROLE_OFF, | |
9f95a23c | 40 | ROLE_SERVICE, |
7c673cae FG |
41 | }; |
42 | ||
43 | /** | |
9f95a23c | 44 | * The type of process in a linux, multi-process setup |
7c673cae FG |
45 | */ |
46 | enum rte_proc_type_t { | |
47 | RTE_PROC_AUTO = -1, /* allow auto-detection of primary/secondary */ | |
48 | RTE_PROC_PRIMARY = 0, /* set to zero, so primary is the default */ | |
49 | RTE_PROC_SECONDARY, | |
50 | ||
51 | RTE_PROC_INVALID | |
52 | }; | |
53 | ||
54 | /** | |
55 | * The global RTE configuration structure. | |
56 | */ | |
57 | struct rte_config { | |
58 | uint32_t master_lcore; /**< Id of the master lcore */ | |
59 | uint32_t lcore_count; /**< Number of available logical cores. */ | |
9f95a23c TL |
60 | uint32_t numa_node_count; /**< Number of detected NUMA nodes. */ |
61 | uint32_t numa_nodes[RTE_MAX_NUMA_NODES]; /**< List of detected NUMA nodes. */ | |
62 | uint32_t service_lcore_count;/**< Number of available service cores. */ | |
7c673cae FG |
63 | enum rte_lcore_role_t lcore_role[RTE_MAX_LCORE]; /**< State of cores. */ |
64 | ||
65 | /** Primary or secondary configuration */ | |
66 | enum rte_proc_type_t process_type; | |
67 | ||
9f95a23c TL |
68 | /** PA or VA mapping mode */ |
69 | enum rte_iova_mode iova_mode; | |
70 | ||
7c673cae FG |
71 | /** |
72 | * Pointer to memory configuration, which may be shared across multiple | |
73 | * DPDK instances | |
74 | */ | |
75 | struct rte_mem_config *mem_config; | |
76 | } __attribute__((__packed__)); | |
77 | ||
78 | /** | |
79 | * Get the global configuration structure. | |
80 | * | |
81 | * @return | |
82 | * A pointer to the global configuration structure. | |
83 | */ | |
84 | struct rte_config *rte_eal_get_configuration(void); | |
85 | ||
86 | /** | |
87 | * Get a lcore's role. | |
88 | * | |
89 | * @param lcore_id | |
90 | * The identifier of the lcore. | |
91 | * @return | |
92 | * The role of the lcore. | |
93 | */ | |
94 | enum rte_lcore_role_t rte_eal_lcore_role(unsigned lcore_id); | |
95 | ||
96 | ||
97 | /** | |
98 | * Get the process type in a multi-process setup | |
99 | * | |
100 | * @return | |
101 | * The process type | |
102 | */ | |
103 | enum rte_proc_type_t rte_eal_process_type(void); | |
104 | ||
105 | /** | |
106 | * Request iopl privilege for all RPL. | |
107 | * | |
108 | * This function should be called by pmds which need access to ioports. | |
109 | ||
110 | * @return | |
111 | * - On success, returns 0. | |
112 | * - On failure, returns -1. | |
113 | */ | |
114 | int rte_eal_iopl_init(void); | |
115 | ||
116 | /** | |
117 | * Initialize the Environment Abstraction Layer (EAL). | |
118 | * | |
119 | * This function is to be executed on the MASTER lcore only, as soon | |
120 | * as possible in the application's main() function. | |
121 | * | |
122 | * The function finishes the initialization process before main() is called. | |
123 | * It puts the SLAVE lcores in the WAIT state. | |
124 | * | |
125 | * When the multi-partition feature is supported, depending on the | |
126 | * configuration (if CONFIG_RTE_EAL_MAIN_PARTITION is disabled), this | |
127 | * function waits to ensure that the magic number is set before | |
128 | * returning. See also the rte_eal_get_configuration() function. Note: | |
129 | * This behavior may change in the future. | |
130 | * | |
131 | * @param argc | |
11fdf7f2 TL |
132 | * A non-negative value. If it is greater than 0, the array members |
133 | * for argv[0] through argv[argc] (non-inclusive) shall contain pointers | |
134 | * to strings. | |
7c673cae | 135 | * @param argv |
11fdf7f2 TL |
136 | * An array of strings. The contents of the array, as well as the strings |
137 | * which are pointed to by the array, may be modified by this function. | |
7c673cae FG |
138 | * @return |
139 | * - On success, the number of parsed arguments, which is greater or | |
140 | * equal to zero. After the call to rte_eal_init(), | |
11fdf7f2 TL |
141 | * all arguments argv[x] with x < ret may have been modified by this |
142 | * function call and should not be further interpreted by the | |
143 | * application. The EAL does not take any ownership of the memory used | |
144 | * for either the argv array, or its members. | |
145 | * - On failure, -1 and rte_errno is set to a value indicating the cause | |
146 | * for failure. In some instances, the application will need to be | |
147 | * restarted as part of clearing the issue. | |
148 | * | |
149 | * Error codes returned via rte_errno: | |
150 | * EACCES indicates a permissions issue. | |
151 | * | |
152 | * EAGAIN indicates either a bus or system resource was not available, | |
153 | * setup may be attempted again. | |
154 | * | |
155 | * EALREADY indicates that the rte_eal_init function has already been | |
156 | * called, and cannot be called again. | |
157 | * | |
158 | * EFAULT indicates the tailq configuration name was not found in | |
159 | * memory configuration. | |
160 | * | |
161 | * EINVAL indicates invalid parameters were passed as argv/argc. | |
162 | * | |
163 | * ENOMEM indicates failure likely caused by an out-of-memory condition. | |
164 | * | |
165 | * ENODEV indicates memory setup issues. | |
166 | * | |
167 | * ENOTSUP indicates that the EAL cannot initialize on this system. | |
168 | * | |
169 | * EPROTO indicates that the PCI bus is either not present, or is not | |
170 | * readable by the eal. | |
9f95a23c TL |
171 | * |
172 | * ENOEXEC indicates that a service core failed to launch successfully. | |
7c673cae FG |
173 | */ |
174 | int rte_eal_init(int argc, char **argv); | |
175 | ||
9f95a23c TL |
176 | /** |
177 | * Clean up the Environment Abstraction Layer (EAL) | |
178 | * | |
179 | * This function must be called to release any internal resources that EAL has | |
180 | * allocated during rte_eal_init(). After this call, no DPDK function calls may | |
181 | * be made. It is expected that common usage of this function is to call it | |
182 | * just before terminating the process. | |
183 | * | |
184 | * @return 0 Successfully released all internal EAL resources | |
185 | * @return -EFAULT There was an error in releasing all resources. | |
186 | */ | |
187 | int rte_eal_cleanup(void); | |
188 | ||
7c673cae FG |
189 | /** |
190 | * Check if a primary process is currently alive | |
191 | * | |
192 | * This function returns true when a primary process is currently | |
193 | * active. | |
194 | * | |
195 | * @param config_file_path | |
196 | * The config_file_path argument provided should point at the location | |
197 | * that the primary process will create its config file. If NULL, the default | |
198 | * config file path is used. | |
199 | * | |
200 | * @return | |
201 | * - If alive, returns 1. | |
202 | * - If dead, returns 0. | |
203 | */ | |
204 | int rte_eal_primary_proc_alive(const char *config_file_path); | |
205 | ||
9f95a23c TL |
206 | #define RTE_MP_MAX_FD_NUM 8 /* The max amount of fds */ |
207 | #define RTE_MP_MAX_NAME_LEN 64 /* The max length of action name */ | |
208 | #define RTE_MP_MAX_PARAM_LEN 256 /* The max length of param */ | |
209 | struct rte_mp_msg { | |
210 | char name[RTE_MP_MAX_NAME_LEN]; | |
211 | int len_param; | |
212 | int num_fds; | |
213 | uint8_t param[RTE_MP_MAX_PARAM_LEN]; | |
214 | int fds[RTE_MP_MAX_FD_NUM]; | |
215 | }; | |
216 | ||
217 | struct rte_mp_reply { | |
218 | int nb_sent; | |
219 | int nb_received; | |
220 | struct rte_mp_msg *msgs; /* caller to free */ | |
221 | }; | |
222 | ||
223 | /** | |
224 | * Action function typedef used by other components. | |
225 | * | |
226 | * As we create socket channel for primary/secondary communication, use | |
227 | * this function typedef to register action for coming messages. | |
228 | * | |
229 | * @note When handling IPC request callbacks, the reply must be sent even in | |
230 | * cases of error handling. Simply returning success or failure will *not* | |
231 | * send a response to the requestor. | |
232 | * Implementation of error signalling mechanism is up to the application. | |
233 | * | |
234 | * @note No memory allocations should take place inside the callback. | |
235 | */ | |
236 | typedef int (*rte_mp_t)(const struct rte_mp_msg *msg, const void *peer); | |
237 | ||
238 | /** | |
239 | * Asynchronous reply function typedef used by other components. | |
240 | * | |
241 | * As we create socket channel for primary/secondary communication, use | |
242 | * this function typedef to register action for coming responses to asynchronous | |
243 | * requests. | |
244 | * | |
245 | * @note When handling IPC request callbacks, the reply must be sent even in | |
246 | * cases of error handling. Simply returning success or failure will *not* | |
247 | * send a response to the requestor. | |
248 | * Implementation of error signalling mechanism is up to the application. | |
249 | * | |
250 | * @note No memory allocations should take place inside the callback. | |
251 | */ | |
252 | typedef int (*rte_mp_async_reply_t)(const struct rte_mp_msg *request, | |
253 | const struct rte_mp_reply *reply); | |
254 | ||
255 | /** | |
256 | * @warning | |
257 | * @b EXPERIMENTAL: this API may change without prior notice | |
258 | * | |
259 | * Register an action function for primary/secondary communication. | |
260 | * | |
261 | * Call this function to register an action, if the calling component wants | |
262 | * to response the messages from the corresponding component in its primary | |
263 | * process or secondary processes. | |
264 | * | |
265 | * @param name | |
266 | * The name argument plays as the nonredundant key to find the action. | |
267 | * | |
268 | * @param action | |
269 | * The action argument is the function pointer to the action function. | |
270 | * | |
271 | * @return | |
272 | * - 0 on success. | |
273 | * - (<0) on failure. | |
274 | */ | |
275 | int __rte_experimental | |
276 | rte_mp_action_register(const char *name, rte_mp_t action); | |
277 | ||
278 | /** | |
279 | * @warning | |
280 | * @b EXPERIMENTAL: this API may change without prior notice | |
281 | * | |
282 | * Unregister an action function for primary/secondary communication. | |
283 | * | |
284 | * Call this function to unregister an action if the calling component does | |
285 | * not want to response the messages from the corresponding component in its | |
286 | * primary process or secondary processes. | |
287 | * | |
288 | * @param name | |
289 | * The name argument plays as the nonredundant key to find the action. | |
290 | * | |
291 | */ | |
292 | void __rte_experimental | |
293 | rte_mp_action_unregister(const char *name); | |
294 | ||
295 | /** | |
296 | * @warning | |
297 | * @b EXPERIMENTAL: this API may change without prior notice | |
298 | * | |
299 | * Send a message to the peer process. | |
300 | * | |
301 | * This function will send a message which will be responded by the action | |
302 | * identified by name in the peer process. | |
303 | * | |
304 | * @param msg | |
305 | * The msg argument contains the customized message. | |
306 | * | |
307 | * @return | |
308 | * - On success, return 0. | |
309 | * - On failure, return -1, and the reason will be stored in rte_errno. | |
310 | */ | |
311 | int __rte_experimental | |
312 | rte_mp_sendmsg(struct rte_mp_msg *msg); | |
313 | ||
314 | /** | |
315 | * @warning | |
316 | * @b EXPERIMENTAL: this API may change without prior notice | |
317 | * | |
318 | * Send a request to the peer process and expect a reply. | |
319 | * | |
320 | * This function sends a request message to the peer process, and will | |
321 | * block until receiving reply message from the peer process. | |
322 | * | |
323 | * @note The caller is responsible to free reply->replies. | |
324 | * | |
325 | * @note This API must not be used inside memory-related or IPC callbacks, and | |
326 | * no memory allocations should take place inside such callback. | |
327 | * | |
328 | * @param req | |
329 | * The req argument contains the customized request message. | |
330 | * | |
331 | * @param reply | |
332 | * The reply argument will be for storing all the replied messages; | |
333 | * the caller is responsible for free reply->msgs. | |
334 | * | |
335 | * @param ts | |
336 | * The ts argument specifies how long we can wait for the peer(s) to reply. | |
337 | * | |
338 | * @return | |
339 | * - On success, return 0. | |
340 | * - On failure, return -1, and the reason will be stored in rte_errno. | |
341 | */ | |
342 | int __rte_experimental | |
343 | rte_mp_request_sync(struct rte_mp_msg *req, struct rte_mp_reply *reply, | |
344 | const struct timespec *ts); | |
345 | ||
346 | /** | |
347 | * @warning | |
348 | * @b EXPERIMENTAL: this API may change without prior notice | |
349 | * | |
350 | * Send a request to the peer process and expect a reply in a separate callback. | |
351 | * | |
352 | * This function sends a request message to the peer process, and will not | |
353 | * block. Instead, reply will be received in a separate callback. | |
354 | * | |
355 | * @param req | |
356 | * The req argument contains the customized request message. | |
357 | * | |
358 | * @param ts | |
359 | * The ts argument specifies how long we can wait for the peer(s) to reply. | |
360 | * | |
361 | * @param clb | |
362 | * The callback to trigger when all responses for this request have arrived. | |
363 | * | |
364 | * @return | |
365 | * - On success, return 0. | |
366 | * - On failure, return -1, and the reason will be stored in rte_errno. | |
367 | */ | |
368 | int __rte_experimental | |
369 | rte_mp_request_async(struct rte_mp_msg *req, const struct timespec *ts, | |
370 | rte_mp_async_reply_t clb); | |
371 | ||
372 | /** | |
373 | * @warning | |
374 | * @b EXPERIMENTAL: this API may change without prior notice | |
375 | * | |
376 | * Send a reply to the peer process. | |
377 | * | |
378 | * This function will send a reply message in response to a request message | |
379 | * received previously. | |
380 | * | |
381 | * @note When handling IPC request callbacks, the reply must be sent even in | |
382 | * cases of error handling. Simply returning success or failure will *not* | |
383 | * send a response to the requestor. | |
384 | * Implementation of error signalling mechanism is up to the application. | |
385 | * | |
386 | * @param msg | |
387 | * The msg argument contains the customized message. | |
388 | * | |
389 | * @param peer | |
390 | * The peer argument is the pointer to the peer socket path. | |
391 | * | |
392 | * @return | |
393 | * - On success, return 0. | |
394 | * - On failure, return -1, and the reason will be stored in rte_errno. | |
395 | */ | |
396 | int __rte_experimental | |
397 | rte_mp_reply(struct rte_mp_msg *msg, const char *peer); | |
398 | ||
399 | /** | |
400 | * Register all mp action callbacks for hotplug. | |
401 | * | |
402 | * @return | |
403 | * 0 on success, negative on error. | |
404 | */ | |
405 | int __rte_experimental | |
406 | rte_mp_dev_hotplug_init(void); | |
407 | ||
7c673cae FG |
408 | /** |
409 | * Usage function typedef used by the application usage function. | |
410 | * | |
9f95a23c | 411 | * Use this function typedef to define and call rte_set_application_usage_hook() |
7c673cae FG |
412 | * routine. |
413 | */ | |
414 | typedef void (*rte_usage_hook_t)(const char * prgname); | |
415 | ||
416 | /** | |
417 | * Add application usage routine callout from the eal_usage() routine. | |
418 | * | |
419 | * This function allows the application to include its usage message | |
420 | * in the EAL system usage message. The routine rte_set_application_usage_hook() | |
421 | * needs to be called before the rte_eal_init() routine in the application. | |
422 | * | |
423 | * This routine is optional for the application and will behave as if the set | |
424 | * routine was never called as the default behavior. | |
425 | * | |
426 | * @param usage_func | |
427 | * The func argument is a function pointer to the application usage routine. | |
428 | * Called function is defined using rte_usage_hook_t typedef, which is of | |
429 | * the form void rte_usage_func(const char * prgname). | |
430 | * | |
431 | * Calling this routine with a NULL value will reset the usage hook routine and | |
432 | * return the current value, which could be NULL. | |
433 | * @return | |
434 | * - Returns the current value of the rte_application_usage pointer to allow | |
435 | * the caller to daisy chain the usage routines if needing more then one. | |
436 | */ | |
437 | rte_usage_hook_t | |
438 | rte_set_application_usage_hook(rte_usage_hook_t usage_func); | |
439 | ||
440 | /** | |
441 | * macro to get the lock of tailq in mem_config | |
442 | */ | |
443 | #define RTE_EAL_TAILQ_RWLOCK (&rte_eal_get_configuration()->mem_config->qlock) | |
444 | ||
445 | /** | |
9f95a23c | 446 | * macro to get the multiple lock of mempool shared by multiple-instance |
7c673cae FG |
447 | */ |
448 | #define RTE_EAL_MEMPOOL_RWLOCK (&rte_eal_get_configuration()->mem_config->mplock) | |
449 | ||
450 | /** | |
451 | * Whether EAL is using huge pages (disabled by --no-huge option). | |
452 | * The no-huge mode cannot be used with UIO poll-mode drivers like igb/ixgbe. | |
453 | * It is useful for NIC drivers (e.g. librte_pmd_mlx4, librte_pmd_vmxnet3) or | |
454 | * crypto drivers (e.g. librte_crypto_nitrox) provided by third-parties such | |
455 | * as 6WIND. | |
456 | * | |
457 | * @return | |
458 | * Nonzero if hugepages are enabled. | |
459 | */ | |
460 | int rte_eal_has_hugepages(void); | |
461 | ||
9f95a23c TL |
462 | /** |
463 | * Whether EAL is using PCI bus. | |
464 | * Disabled by --no-pci option. | |
465 | * | |
466 | * @return | |
467 | * Nonzero if the PCI bus is enabled. | |
468 | */ | |
469 | int rte_eal_has_pci(void); | |
470 | ||
471 | /** | |
472 | * Whether the EAL was asked to create UIO device. | |
473 | * | |
474 | * @return | |
475 | * Nonzero if true. | |
476 | */ | |
477 | int rte_eal_create_uio_dev(void); | |
478 | ||
479 | /** | |
480 | * The user-configured vfio interrupt mode. | |
481 | * | |
482 | * @return | |
483 | * Interrupt mode configured with the command line, | |
484 | * RTE_INTR_MODE_NONE by default. | |
485 | */ | |
486 | enum rte_intr_mode rte_eal_vfio_intr_mode(void); | |
487 | ||
7c673cae FG |
488 | /** |
489 | * A wrap API for syscall gettid. | |
490 | * | |
491 | * @return | |
492 | * On success, returns the thread ID of calling process. | |
493 | * It is always successful. | |
494 | */ | |
495 | int rte_sys_gettid(void); | |
496 | ||
497 | /** | |
498 | * Get system unique thread id. | |
499 | * | |
500 | * @return | |
501 | * On success, returns the thread ID of calling process. | |
502 | * It is always successful. | |
503 | */ | |
504 | static inline int rte_gettid(void) | |
505 | { | |
506 | static RTE_DEFINE_PER_LCORE(int, _thread_id) = -1; | |
507 | if (RTE_PER_LCORE(_thread_id) == -1) | |
508 | RTE_PER_LCORE(_thread_id) = rte_sys_gettid(); | |
509 | return RTE_PER_LCORE(_thread_id); | |
510 | } | |
511 | ||
9f95a23c TL |
512 | /** |
513 | * Get the iova mode | |
514 | * | |
515 | * @return | |
516 | * enum rte_iova_mode value. | |
517 | */ | |
518 | enum rte_iova_mode rte_eal_iova_mode(void); | |
519 | ||
520 | /** | |
521 | * Get user provided pool ops name for mbuf | |
522 | * | |
523 | * @return | |
524 | * returns user provided pool ops name. | |
525 | */ | |
526 | const char * | |
527 | rte_eal_mbuf_user_pool_ops(void); | |
528 | ||
529 | /** | |
530 | * Get the runtime directory of DPDK | |
531 | * | |
532 | * @return | |
533 | * The runtime directory path of DPDK | |
534 | */ | |
535 | const char * | |
536 | rte_eal_get_runtime_dir(void); | |
7c673cae FG |
537 | |
538 | #ifdef __cplusplus | |
539 | } | |
540 | #endif | |
541 | ||
542 | #endif /* _RTE_EAL_H_ */ |