--- name: "rte_eal.h" section: "3" platform: "linux" package: "dpdk-doc" version: "24.11.4-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rte_eal.h" --- # rte\_eal.h(3) ## NAME rte\_eal.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ ### Macros \#define **RTE\_MAGIC** 19820526\ ### Typedefs **typedef** int(\* **rte\_mp\_t**) (const struct rte\_mp\_msg \*msg, const void \*peer)\ **typedef** int(\* **rte\_mp\_async\_reply\_t**) (const struct rte\_mp\_msg \*request, const struct rte\_mp\_reply \*reply)\ **typedef** void(\* **rte\_usage\_hook\_t**) (const char \*prgname)\ ### Enumerations enum **rte\_proc\_type\_t** \ enum **rte\_iova\_mode** \ ### Functions enum **rte\_proc\_type\_t** **rte\_eal\_process\_type** (void)\ int **rte\_eal\_iopl\_init** (void)\ int **rte\_eal\_init** (int argc, char \*\*argv)\ int **rte\_eal\_cleanup** (void)\ int **rte\_eal\_primary\_proc\_alive** (const char \*config\_file\_path)\ bool **rte\_mp\_disable** (void)\ int **rte\_mp\_action\_register** (const char \*name, **rte\_mp\_t** action)\ void **rte\_mp\_action\_unregister** (const char \*name)\ int **rte\_mp\_sendmsg** (struct rte\_mp\_msg \*msg)\ int **rte\_mp\_request\_sync** (struct rte\_mp\_msg \*req, struct rte\_mp\_reply \*reply, const struct timespec \*ts)\ int **rte\_mp\_request\_async** (struct rte\_mp\_msg \*req, const struct timespec \*ts, **rte\_mp\_async\_reply\_t** clb)\ int **rte\_mp\_reply** (struct rte\_mp\_msg \*msg, const char \*peer)\ **rte\_usage\_hook\_t** **rte\_set\_application\_usage\_hook** (**rte\_usage\_hook\_t** usage\_func)\ int **rte\_eal\_has\_hugepages** (void)\ int **rte\_eal\_has\_pci** (void)\ int **rte\_eal\_create\_uio\_dev** (void)\ enum rte\_intr\_mode **rte\_eal\_vfio\_intr\_mode** (void)\ void **rte\_eal\_vfio\_get\_vf\_token** (**rte\_uuid\_t** vf\_token)\ int **rte\_sys\_gettid** (void)\ static int **rte\_gettid** (void)\ \_\_rte\_internal uint64\_t **rte\_eal\_get\_baseaddr** (void)\ enum **rte\_iova\_mode** **rte\_eal\_iova\_mode** (void)\ const char \* **rte\_eal\_mbuf\_user\_pool\_ops** (void)\ const char \* **rte\_eal\_get\_runtime\_dir** (void)\ \_\_rte\_internal int **rte\_eal\_parse\_coremask** (const char \*coremask, int \*cores)\ ## Detailed Description EAL Configuration API Definition in file **rte\_eal.h**. ## Macro Definition Documentation ### #define RTE\_MAGIC 19820526 Magic number written by the main partition when ready. Definition at line **28** of file **rte\_eal.h**. ## Typedef Documentation ### typedef int(\* rte\_mp\_t) (const struct rte\_mp\_msg \*msg, const void \*peer) Action function typedef used by other components. As we create socket channel for primary/secondary communication, use this function typedef to register action for coming messages. **Note** When handling IPC request callbacks, the reply must be sent even in cases of error handling. Simply returning success or failure will *not* send a response to the requestor. Implementation of error signalling mechanism is up to the application. No memory allocations should take place inside the callback. Definition at line **188** of file **rte\_eal.h**. ### typedef int(\* rte\_mp\_async\_reply\_t) (const struct rte\_mp\_msg \*request, const struct rte\_mp\_reply \*reply) Asynchronous reply function typedef used by other components. As we create socket channel for primary/secondary communication, use this function typedef to register action for coming responses to asynchronous requests. **Note** When handling IPC request callbacks, the reply must be sent even in cases of error handling. Simply returning success or failure will *not* send a response to the requestor. Implementation of error signalling mechanism is up to the application. No memory allocations should take place inside the callback. Definition at line **204** of file **rte\_eal.h**. ### typedef void(\* rte\_usage\_hook\_t) (const char \*prgname) Usage function typedef used by the application usage function. Use this function typedef to define and call **rte\_set\_application\_usage\_hook()** routine. Definition at line **350** of file **rte\_eal.h**. ## Enumeration Type Documentation ### enum rte\_proc\_type\_t The type of process in a linux, multi-process setup Definition at line **33** of file **rte\_eal.h**. ### enum rte\_iova\_mode IOVA mapping mode. IOVA mapping mode is iommu programming mode of a device. That device (for example: IOMMU backed DMA device) based on rte\_iova\_mode will generate physical or virtual address. Definition at line **461** of file **rte\_eal.h**. ## Function Documentation ### enum rte\_proc\_type\_t rte\_eal\_process\_type (void) Get the process type in a multi-process setup **Returns** The process type ### int rte\_eal\_iopl\_init (void) Request iopl privilege for all RPL. This function should be called by pmds which need access to ioports. **Returns** - • On success, returns 0. - • On failure, returns -1. ### int rte\_eal\_init (int argc, char \*\* argv) Initialize the Environment Abstraction Layer (EAL). This function is to be executed on the MAIN lcore only, as soon as possible in the application's main() function. It puts the WORKER lcores in the WAIT state. **Parameters** *argc* A non-negative value. If it is greater than 0, the array members for argv\[0\] through argv\[argc\] (non-inclusive) shall contain pointers to strings. \ *argv* An array of strings. The contents of the array, as well as the strings which are pointed to by the array, may be modified by this function. The program name pointer argv\[0\] is copied into the last parsed argv so that argv\[0\] is still the same after deducing the parsed arguments. **Returns** - • On success, the number of parsed arguments, which is greater or equal to zero. After the call to **rte\_eal\_init()**, all arguments argv\[x\] with x \< ret may have been modified by this function call and should not be further interpreted by the application. The EAL does not take any ownership of the memory used for either the argv array, or its members. - • On failure, -1 and rte\_errno is set to a value indicating the cause for failure. In some instances, the application will need to be restarted as part of clearing the issue. Error codes returned via rte\_errno: EACCES indicates a permissions issue. EAGAIN indicates either a bus or system resource was not available, setup may be attempted again. EALREADY indicates that the rte\_eal\_init function has already been called, and cannot be called again. EFAULT indicates the tailq configuration name was not found in memory configuration. EINVAL indicates invalid parameters were passed as argv/argc. ENOMEM indicates failure likely caused by an out-of-memory condition. ENODEV indicates memory setup issues. ENOTSUP indicates that the EAL cannot initialize on this system. EPROTO indicates that the PCI bus is either not present, or is not readable by the eal. ENOEXEC indicates that a service core failed to launch successfully. ### int rte\_eal\_cleanup (void) Clean up the Environment Abstraction Layer (EAL) This function must be called to release any internal resources that EAL has allocated during **rte\_eal\_init()**. After this call, no DPDK function calls may be made. It is expected that common usage of this function is to call it just before terminating the process. **Returns** - • 0 Successfully released all internal EAL resources. - • \-EFAULT There was an error in releasing all resources. ### int rte\_eal\_primary\_proc\_alive (const char \* config\_file\_path) Check if a primary process is currently alive This function returns true when a primary process is currently active. **Parameters** *config\_file\_path* The config\_file\_path argument provided should point at the location that the primary process will create its config file. If NULL, the default config file path is used. **Returns** - • If alive, returns 1. - • If dead, returns 0. ### bool rte\_mp\_disable (void) Disable multiprocess. This function can be called to indicate that multiprocess won't be used for the rest of the application life. **Returns** - • true if called from a primary process that had no secondary processes attached, - • false, otherwise. ### int rte\_mp\_action\_register (const char \* name, rte\_mp\_t action) Register an action function for primary/secondary communication. Call this function to register an action, if the calling component wants to response the messages from the corresponding component in its primary process or secondary processes. **Note** IPC may be unsupported in certain circumstances, so caller should check for ENOTSUP error. **Parameters** *name* The name argument plays as the nonredundant key to find the action.\ *action* The action argument is the function pointer to the action function. **Returns** - • 0 on success. - • (\<0) on failure. ### void rte\_mp\_action\_unregister (const char \* name) Unregister an action function for primary/secondary communication. Call this function to unregister an action if the calling component does not want to response the messages from the corresponding component in its primary process or secondary processes. **Note** IPC may be unsupported in certain circumstances, so caller should check for ENOTSUP error. **Parameters** *name* The name argument plays as the nonredundant key to find the action. ### int rte\_mp\_sendmsg (struct rte\_mp\_msg \* msg) Send a message to the peer process. This function will send a message which will be responded by the action identified by name in the peer process. **Parameters** *msg* The msg argument contains the customized message. **Returns** - • On success, return 0. - • On failure, return -1, and the reason will be stored in rte\_errno. ### int rte\_mp\_request\_sync (struct rte\_mp\_msg \* req, struct rte\_mp\_reply \* reply, const struct timespec \* ts) Send a request to the peer process and expect a reply. This function sends a request message to the peer process, and will block until receiving reply message from the peer process. **Note** The caller is responsible to free reply-\>replies. This API must not be used inside memory-related or IPC callbacks, and no memory allocations should take place inside such callback. IPC may be unsupported in certain circumstances, so caller should check for ENOTSUP error. **Parameters** *req* The req argument contains the customized request message.\ *reply* The reply argument will be for storing all the replied messages; the caller is responsible for free reply-\>msgs.\ *ts* The ts argument specifies how long we can wait for the peer(s) to reply. **Returns** - • On success, return 0. - • On failure, return -1, and the reason will be stored in rte\_errno. ### int rte\_mp\_request\_async (struct rte\_mp\_msg \* req, const struct timespec \* ts, rte\_mp\_async\_reply\_t clb) Send a request to the peer process and expect a reply in a separate callback. This function sends a request message to the peer process, and will not block. Instead, reply will be received in a separate callback. **Note** IPC may be unsupported in certain circumstances, so caller should check for ENOTSUP error. **Parameters** *req* The req argument contains the customized request message.\ *ts* The ts argument specifies how long we can wait for the peer(s) to reply.\ *clb* The callback to trigger when all responses for this request have arrived. **Returns** - • On success, return 0. - • On failure, return -1, and the reason will be stored in rte\_errno. ### int rte\_mp\_reply (struct rte\_mp\_msg \* msg, const char \* peer) Send a reply to the peer process. This function will send a reply message in response to a request message received previously. **Note** When handling IPC request callbacks, the reply must be sent even in cases of error handling. Simply returning success or failure will *not* send a response to the requestor. Implementation of error signalling mechanism is up to the application. **Parameters** *msg* The msg argument contains the customized message.\ *peer* The peer argument is the pointer to the peer socket path. **Returns** - • On success, return 0. - • On failure, return -1, and the reason will be stored in rte\_errno. ### rte\_usage\_hook\_t rte\_set\_application\_usage\_hook (rte\_usage\_hook\_t usage\_func) Add application usage routine callout from the eal\_usage() routine. This function allows the application to include its usage message in the EAL system usage message. The routine **rte\_set\_application\_usage\_hook()** needs to be called before the **rte\_eal\_init()** routine in the application. This routine is optional for the application and will behave as if the set routine was never called as the default behavior. **Parameters** *usage\_func* The func argument is a function pointer to the application usage routine. Called function is defined using rte\_usage\_hook\_t typedef, which is of the form void rte\_usage\_func(const char \* prgname). Calling this routine with a NULL value will reset the usage hook routine and return the current value, which could be NULL. **Returns** - • Returns the current value of the rte\_application\_usage pointer to allow the caller to daisy chain the usage routines if needing more then one. ### int rte\_eal\_has\_hugepages (void) Whether EAL is using huge pages (disabled by --no-huge option). The no-huge mode is not compatible with all drivers or features. **Returns** Nonzero if hugepages are enabled. ### int rte\_eal\_has\_pci (void) Whether EAL is using PCI bus. Disabled by --no-pci option. **Returns** Nonzero if the PCI bus is enabled. ### int rte\_eal\_create\_uio\_dev (void) Whether the EAL was asked to create UIO device. **Returns** Nonzero if true. ### enum rte\_intr\_mode rte\_eal\_vfio\_intr\_mode (void) The user-configured vfio interrupt mode. **Returns** Interrupt mode configured with the command line, RTE\_INTR\_MODE\_NONE by default. ### void rte\_eal\_vfio\_get\_vf\_token (rte\_uuid\_t vf\_token) Copy the user-configured vfio VF token. **Parameters** *vf\_token* vfio VF token configured with the command line is copied into this parameter, zero uuid by default. ### int rte\_sys\_gettid (void) A wrap API for syscall gettid. **Returns** On success, returns the thread ID of calling process. It is always successful. ### static int rte\_gettid (void)` [inline]`, ` [static]` Get system unique thread id. **Returns** On success, returns the thread ID of calling process. It is always successful. Definition at line **438** of file **rte\_eal.h**. ### \_\_rte\_internal uint64\_t rte\_eal\_get\_baseaddr (void) Get the OS-specific EAL base address. **Returns** The base address. ### enum rte\_iova\_mode rte\_eal\_iova\_mode (void) Get the iova mode **Returns** enum rte\_iova\_mode value. ### const char \* rte\_eal\_mbuf\_user\_pool\_ops (void) Get user provided pool ops name for mbuf **Returns** returns user provided pool ops name. ### const char \* rte\_eal\_get\_runtime\_dir (void) Get the runtime directory of DPDK **Returns** The runtime directory path of DPDK ### \_\_rte\_internal int rte\_eal\_parse\_coremask (const char \* coremask, int \* cores) Convert a string describing a mask of core ids into an array of core ids. On success, the passed array is filled with the orders of the core ids present in the mask (-1 indicating that a core id is absent). For example, passing a 0xa coremask results in cores\[1\] = 0, cores\[3\] = 1, and the rest of the array is set to -1. **Parameters** *coremask* A string describing a mask of core ids. \ *cores* An array where to store the core ids orders. This array must be at least RTE\_MAX\_LCORE large. **Returns** 0 on success, -1 if the string content was invalid. ## Author Generated automatically by Doxygen for DPDK from the source code.