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