rte_eal.h(3)

📦
version 24.11.8 · 5 versions
, in debian trixie

💖 rte_eal.h 💖

okay so bestie, welcome to rte_eal.h(3) — that's the one from the Library Functions Manual, and yes it's a whole big C header and it is giving main character energy, no cap. This is part one of two, so buckle up, we are not skimming, we are reading everything. 💅

🌸 NAME 🌸

rte_eal.h — it's a header. That's the name, that's the whole vibe. ✨

🦋 SYNOPSIS 🦋

First things first, the includes. You gotta pull all of these in:

#include <stdint.h>
#include <time.h>
#include <rte_config.h>
#include <rte_compat.h>
#include <rte_per_lcore.h>
#include <rte_uuid.h>
#include <rte_pci_dev_feature_defs.h>

🎀 Macros 🎀

  • RTE_MAGIC — defined as 19820526, and yes it's doing the most.

🎀 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 🎀

literally the whole roster, here we go bestie:

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 💜

It's the EAL Configuration API. That's it, that's the summary, short and sweet fr fr.

Definition in file rte_eal.h.

✨ Macro Definition Documentation ✨

🍓 #define RTE_MAGIC 19820526

It's the magic number that gets written by the main partition when it's ready. cute little "i'm here" note. 🫶

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)

This is the action-function typedef that other components use. Since we set up a socket channel for primary/secondary communication, you use this function typedef to register an action for all the messages that come rolling in. 📬

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 the error signalling mechanism is up to the application. No memory allocations should take place inside the callback. (yes that's a real rule, don't do it 💀)

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)

The asynchronous reply function typedef, used by other components. Same deal as above — socket channel for primary/secondary communication — but you use this one to register an action for the 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 the error signalling mechanism is up to the application. No memory allocations should take place inside the callback. (again!! no allocations!! 🚫)

Definition at line 204 of file rte_eal.h.

🌈 typedef void(* rte_usage_hook_t) (const char *prgname)

The usage function typedef, used by the application usage function. You use this function typedef to define and call the 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

The IOVA mapping mode. IOVA mapping mode is the iommu programming mode of a device. That device (for example: an IOMMU backed DMA device) will generate physical or virtual address based on rte_iova_mode. 🔮

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, bestie. 🕵️

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. (main character goes first, everyone else waits, periodt 💅)

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. (like closing your tabs before you shut the laptop, honestly iconic)

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. (it will simply stand there and wait, no thoughts, head empty 😭)

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) 🦋

bestie, this one sends a request off to the peer process and expects the reply to come back through a separate callback. It's the non-blocking version — it fires the request and does not sit there waiting. The reply shows up later, in its own little callback moment. main character behavior honestly.

⚠️ Note: IPC may be unsupported in certain circumstances, so the caller should check for ENOTSUP error. no cap, always vibe-check your errno.

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) 💌

sending a reply back to the peer process 🫶 This one sends a reply message in response to a request message received previously. It's giving courteous, it's giving communication.

⚠️ 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. so like… you literally have to reply, bestie. ghosting is not an option here 😭

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) 🎀

Adds an application usage routine callout from the eal_usage() routine ✨

This function lets the application include its own usage message in the EAL system usage message. And heads up: the routine rte_set_application_usage_hook() needs to be called before the rte_eal_init() routine in the application. order matters, fr fr.

This routine is optional for the application and will behave as if the set routine was never called as the default behavior. no pressure, it's chill like that.

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. iconic cleanup behavior 💅

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 — so like, know before you go.

Returns

Nonzero if hugepages are enabled.

🌈 int rte_eal_has_pci (void) 🌈

Whether EAL is using the 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. (look at her go, never fails 💅)

🔥 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. lowkey the glow-up from string to array, obsessed.

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. see how that works? cute, right.

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.

and that's the whole thing bestie, we ate and left no crumbs 🫶 this page is DPDK, version 24.11.8, living at rte_eal.h(3) — auto-generated by Doxygen from the source code, so you know it's the real deal. study it, love it, man it again later 💖✨

📦 where this page comes from