rte_interrupts.h(3)

📦
version 25.11.3 · 9 versions
, in ubuntu resolute, ubuntu stonking

💖 rte_interrupts.h — the DPDK interrupt bestie handbook (part 1) 💖

okay so bestie, you found the man page for rte_interrupts.h from the Library Functions Manual and honestly? it's giving main character energy. this is the header that lets you vibe with interrupts in DPDK, and no cap, everything here matters. grab a boba, we're doing this. 🧋✨

✨ NAME ✨

rte_interrupts.h — literally the interrupt interface header. that's her. that's the whole name. 🎀

🌸 SYNOPSIS 🌸

#include <stdbool.h>
#include <rte_bitops.h>
#include <rte_common.h>
#include <rte_compat.h>
#include <rte_epoll.h>

🦋 Macros 🦋

#define RTE_INTR_INSTANCE_F_PRIVATE   UINT32_C(0)
#define RTE_INTR_INSTANCE_F_SHARED   RTE_BIT32(0)
#define RTE_INTR_EVENT_IN   RTE_BIT32(0)
#define RTE_INTR_EVENT_ERR   RTE_BIT32(1)
#define RTE_INTR_EVENT_HUP   RTE_BIT32(2)
#define RTE_INTR_EVENT_RDHUP   RTE_BIT32(3)

🎀 Typedefs 🎀

typedef void(* rte_intr_callback_fn) (void *cb_arg)
typedef void(* rte_intr_unregister_callback_fn) (struct rte_intr_handle
    *intr_handle, void *cb_arg)

💅 Enumerations 💅

enum rte_intr_handle_type { RTE_INTR_HANDLE_UNKNOWN = 0,
    RTE_INTR_HANDLE_UIO, RTE_INTR_HANDLE_UIO_INTX,
    RTE_INTR_HANDLE_VFIO_LEGACY, RTE_INTR_HANDLE_VFIO_MSI,
    RTE_INTR_HANDLE_VFIO_MSIX, RTE_INTR_HANDLE_ALARM,
    RTE_INTR_HANDLE_EXT, RTE_INTR_HANDLE_VDEV,
    RTE_INTR_HANDLE_DEV_EVENT, RTE_INTR_HANDLE_VFIO_REQ,
    RTE_INTR_HANDLE_MAX }

⭐ Functions ⭐

int rte_intr_callback_register (const struct rte_intr_handle
    *intr_handle, rte_intr_callback_fn cb, void *cb_arg)
int rte_intr_callback_unregister (const struct rte_intr_handle
    *intr_handle, rte_intr_callback_fn cb, void *cb_arg)
int rte_intr_callback_unregister_pending (const struct rte_intr_handle
    *intr_handle, rte_intr_callback_fn cb_fn, void *cb_arg,
    rte_intr_unregister_callback_fn ucb_fn)
int rte_intr_callback_unregister_sync (const struct rte_intr_handle
    *intr_handle, rte_intr_callback_fn cb, void *cb_arg)
int rte_intr_enable (const struct rte_intr_handle *intr_handle)
int rte_intr_disable (const struct rte_intr_handle *intr_handle)
int rte_intr_ack (const struct rte_intr_handle *intr_handle)
int rte_thread_is_intr (void)
struct rte_intr_handle * rte_intr_instance_alloc (uint32_t flags)
void rte_intr_instance_free (struct rte_intr_handle *intr_handle)
int rte_intr_fd_set (struct rte_intr_handle *intr_handle, int fd)
int rte_intr_fd_get (const struct rte_intr_handle *intr_handle)
int rte_intr_type_set (struct rte_intr_handle *intr_handle, enum
    rte_intr_handle_type type)
enum rte_intr_handle_type rte_intr_type_get (const struct
    rte_intr_handle *intr_handle)

💖 Detailed Description 💖

the RTE interrupt interface is here to give you functions that register and unregister callbacks for a specific interrupt. that's the vibe. 🫶

📍 Definition in file rte_interrupts.h.

🎀 Macro Definition Documentation 🎀

🌸 #define RTE_INTR_INSTANCE_F_PRIVATE UINT32_C(0)

interrupt instance allocation flags, bestie 💅

See also: rte_intr_instance_alloc

interrupt instance is not gonna be shared between primary and secondary processes. she's private. she's her own person. 💖

📍 Definition at line 34 of file rte_interrupts.h.

🌸 #define RTE_INTR_INSTANCE_F_SHARED RTE_BIT32(0)

interrupt instance will be shared between primary and secondary processes. sharing is caring, periodt. ✨

📍 Definition at line 36 of file rte_interrupts.h.

🌸 #define RTE_INTR_EVENT_IN RTE_BIT32(0)

interrupt event flags returned by rte_intr_active_events_flags(). data is available to read, go get it. 📖

📍 Definition at line 43 of file rte_interrupts.h.

🌸 #define RTE_INTR_EVENT_ERR RTE_BIT32(1)

error condition on fd. it's giving "something went wrong" energy 😭

📍 Definition at line 44 of file rte_interrupts.h.

🌸 #define RTE_INTR_EVENT_HUP RTE_BIT32(2)

hang up / disconnect. like when the call drops mid-convo. 💀

📍 Definition at line 45 of file rte_interrupts.h.

🌸 #define RTE_INTR_EVENT_RDHUP RTE_BIT32(3)

read hang up / disconnect. same vibe as above but for reads. 🦋

📍 Definition at line 46 of file rte_interrupts.h.

🦋 Typedef Documentation 🦋

⭐ typedef void(* rte_intr_callback_fn) (void *cb_arg)

the function you register for the specific interrupt. this is the callback bestie you're introducing to your interrupt. 🤝

📍 Definition at line 67 of file rte_interrupts.h.

⭐ typedef void(* rte_intr_unregister_callback_fn) (struct rte_intr_handle *intr_handle, void *cb_arg)

the function that gets called after a callback is unregistered. you can use it to close fd and free cb_arg. cleanup queen behavior. 👑

📍 Definition at line 73 of file rte_interrupts.h.

💅 Enumeration Type Documentation 💅

🌈 enum rte_intr_handle_type

the interrupt source type — like UIO, VFIO, ALARM etc. the many flavors of interrupt, if you will. 🍓

Enumerator:

  • RTE_INTR_HANDLE_UNKNOWN — generic unknown handle. the mystery guest. 🙈
  • RTE_INTR_HANDLE_UIO — uio device handle.
  • RTE_INTR_HANDLE_UIO_INTX — uio generic handle.
  • RTE_INTR_HANDLE_VFIO_LEGACY — vfio device handle (legacy).
  • RTE_INTR_HANDLE_VFIO_MSI — vfio device handle (MSI).
  • RTE_INTR_HANDLE_VFIO_MSIX — vfio device handle (MSIX).
  • RTE_INTR_HANDLE_ALARM — alarm handle. wake up bestie ⏰
  • RTE_INTR_HANDLE_EXT — external handler.
  • RTE_INTR_HANDLE_VDEV — virtual device.
  • RTE_INTR_HANDLE_DEV_EVENT — device event handle.
  • RTE_INTR_HANDLE_VFIO_REQ — VFIO request handle.
  • RTE_INTR_HANDLE_MAX — count of elements. she's the size marker, iconic. ⭐
📍 Definition at line 51 of file rte_interrupts.h.

✨ Function Documentation ✨

🌸 int rte_intr_callback_register (const struct rte_intr_handle * intr_handle, rte_intr_callback_fn cb, void * cb_arg)

registers the callback for the specific interrupt. and yes bestie, you can register multiple callbacks at the same time. no gatekeeping here. 🔥

Parameters:

  • intr_handle — pointer to the interrupt handle.
  • cb — callback address.
  • cb_arg — address of parameter for callback.

Returns:

  • on success, zero. 💖
  • on failure, a negative value. 😭

🌸 int rte_intr_callback_unregister (const struct rte_intr_handle * intr_handle, rte_intr_callback_fn cb, void * cb_arg)

unregisters the callback according to the specified interrupt handle. bye bestie 👋 but like, respectfully.

Parameters:

  • intr_handle — pointer to the interrupt handle.
  • cb — callback address.
  • cb_arg — address of parameter for callback. (void *)-1 means to remove all registered which has the same callback address. yes really, that's the magic value. 💀

Returns:

  • on success, return the number of callback entities removed.
  • on failure, a negative value.

🌸 int rte_intr_callback_unregister_pending (const struct rte_intr_handle * intr_handle, rte_intr_callback_fn cb_fn, void * cb_arg, rte_intr_unregister_callback_fn ucb_fn)

unregisters the callback according to the specified interrupt handle, after it's no longer active. fails if source is not active. she's patient but not that patient. ✋

Parameters:

  • intr_handle — pointer to the interrupt handle.
  • cb_fn — callback address.
  • cb_arg — address of parameter for callback. (void *)-1 means to remove all registered which has the same callback address.
  • ucb_fn — callback to call before cb is unregistered (optional). can be used to close fd and free cb_arg.

Returns:

  • on success, return the number of callback entities marked for remove.
  • on failure, a negative value.

🌸 int rte_intr_callback_unregister_sync (const struct rte_intr_handle * intr_handle, rte_intr_callback_fn cb, void * cb_arg)

loops until rte_intr_callback_unregister() succeeds. literally just keeps going until it works, we love persistence. 💪 after a call to this function, the callback provided by the specified interrupt handle is unregistered.

Parameters:

  • intr_handle — pointer to the interrupt handle.
  • cb — callback address.
  • cb_arg — address of parameter for callback. (void *)-1 means to remove all registered which has the same callback address.

Returns:

  • on success, return the number of callback entities removed.
  • on failure, a negative value.

🌸 int rte_intr_enable (const struct rte_intr_handle * intr_handle)

enables the interrupt for the specified handle. wake her up ✨

Parameters:

  • intr_handle — pointer to the interrupt handle.

Returns:

  • on success, zero.
  • on failure, a negative value.

🌸 int rte_intr_disable (const struct rte_intr_handle * intr_handle)

disables the interrupt for the specified handle. she's napping now, do not disturb 😴

Parameters:

  • intr_handle — pointer to the interrupt handle.

Returns:

  • on success, zero.
  • on failure, a negative value.

🌸 int rte_intr_ack (const struct rte_intr_handle * intr_handle)

acknowledges an interrupt raised for the specified handle.

⚠️ bestie listen closely — this function should be called at the end of each interrupt handler either from application or driver, so that the currently raised interrupt is acked and further new interrupts are raised. skip this and you'll be stuck, fr fr.

Parameters:

  • intr_handle — pointer to the interrupt handle.

Returns:

  • on success, zero.
  • on failure, a negative value.

🌸 int rte_thread_is_intr (void )

checks if you're currently executing in interrupt context. vibe check but for your thread. 🕵️‍♀️

Returns:

  • non zero in case of interrupt context
  • zero in case of process context

🌸 struct rte_intr_handle * rte_intr_instance_alloc (uint32_t flags)

allocates memory for an interrupt instance. the API takes a flag as an argument which defines from where memory should be allocated — i.e. either using DPDK memory management library APIs or normal heap allocation. default memory allocation for event fds and the event list array is done, and that can be realloced later based on the size of MSIX interrupts supported by a PCI device.

💡 this function should be called from application or driver, before calling any of the interrupt APIs. she's the opening act, the main event comes after. 🎬

Parameters:

  • flags — see RTE_INTR_INSTANCE_F_* flags definitions.

Returns:

  • on success, address of interrupt handle.
  • on failure, NULL.

🌸 void rte_intr_instance_free (struct rte_intr_handle * intr_handle)

frees the memory allocated for interrupt handle resources. giving back what you borrowed, we love a responsible queen. 🫶

Parameters:

  • intr_handle — interrupt handle allocated with rte_intr_instance_alloc(). if intr_handle is NULL, no operation is performed. (so it's fine, no crash, breathe.)

🌸 int rte_intr_fd_set (struct rte_intr_handle * intr_handle, int fd)

sets the fd field of the interrupt handle with a user-provided file descriptor.

Parameters:

  • intr_handle — pointer to the interrupt handle.
  • fd — file descriptor value provided by user.

Returns:

  • on success, zero.
  • on failure, a negative value and rte_errno is set. 👀

🌸 int rte_intr_fd_get (const struct rte_intr_handle * intr_handle)

returns the fd field of the given interrupt handle instance. peek at her file descriptor, respectfully. 👑

Parameters:

  • intr_handle — pointer to the interrupt handle.

Returns:

  • on success, fd field.
  • on failure, a negative value.

🌸 int rte_intr_type_set (struct rte_intr_handle * intr_handle, enum rte_intr_handle_type type)

sets the type field of the interrupt handle with a user-provided interrupt type.

Parameters:

  • intr_handle — pointer to the interrupt handle.
  • type — interrupt type

Returns:

  • on success, zero.
  • on failure, a negative value and rte_errno is set. 😤

🌸 enum rte_intr_handle_type rte_intr_type_get (const struct rte_intr_handle * intr_handle)

returns the type field of the given interrupt handle instance.

Parameters:

  • intr_handle — pointer to the interrupt handle.

Returns:

  • on success, interrupt type
  • on failure, RTE_INTR_HANDLE_UNKNOWN. the mystery guest returns 🙈

stay tuned bestie, part 2 is coming and it's gonna be just as iconic 💜✨

🎀 AUTHOR 🎀

okay so bestie, plot twist: there's no human author here. no mysterious hoodie-wearing Unix wizard typing this at 3am. 🙈

This page was generated automatically by Doxygen for DPDK from the source code. that's it, that's the whole origin story. the docs robot read the actual source, did its little Doxygen thing, and this page fell out. iconic behaviour honestly ✨

so if you spot something cursed in here, don't come for an author — the source code is the main character, and Doxygen is just the messenger. 💅

and that's a wrap on rte_interrupts.h(3), bestie!! 🫶 you made it to the end, which is giving dedication. go forth and interrupt responsibly. ✨

DPDK Version 25.11.3 🦋 — that's the flavour of the docs you just read, so if numbers start acting different on your box, check your version first, fr fr.

mwah, love u, bye!! 💖🌸🎀

📦 where this page comes from