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