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