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 static inline int rte_gettid(void) 439 { 440 if (RTE_PER_LCORE(_thread_id) == -1) 441 RTE_PER_LCORE(_thread_id) = rte_sys_gettid(); 442 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_ */ 518