rte_dev.h(3)

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

✨ NAME ✨

rte_dev.h — bestie, that's it, that's the whole name. Just the header file, no extra lore. 💅 (This one lives in the Library Functions Manual, section 3, so when you're yelling for it you're yelling for rte_dev.h(3).) 🫶

🌸 SYNOPSIS 🌸

Okay so first things first, you gotta pull in the whole friend group:

#include <stdio.h>
#include <rte_config.h>
#include <rte_common.h>
#include <rte_log.h>

And then here's the entire cast of characters this header hands you. Buckle up, it's a lot, but we're built for this. 👑

💖 Data Structures

  • struct rte_mem_resource
  • struct rte_dev_iterator

🦋 Typedefs

  • typedef int(* rte_dev_cmp_t) (const struct rte_device *dev, const void *data)
  • typedef void *(* rte_dev_iterate_t) (const void *start, const char *devstr, const struct rte_dev_iterator *it)

🎀 Enumerations

  • enum rte_dev_event_type { RTE_DEV_EVENT_ADD, RTE_DEV_EVENT_REMOVE, RTE_DEV_EVENT_MAX }
  • enum rte_dev_policy

🧚 Functions

Like, the entire roster, no skips, no "you'll figure it out":

  • const char * rte_driver_name (const struct rte_driver *driver)
  • const struct rte_bus * rte_dev_bus (const struct rte_device *dev)
  • const char * rte_dev_bus_info (const struct rte_device *dev)
  • const struct rte_devargs * rte_dev_devargs (const struct rte_device *dev)
  • const struct rte_driver * rte_dev_driver (const struct rte_device *dev)
  • const char * rte_dev_name (const struct rte_device *dev)
  • int rte_dev_numa_node (const struct rte_device *dev)
  • int rte_dev_is_probed (const struct rte_device *dev)
  • int rte_eal_hotplug_add (const char *busname, const char *devname, const char *drvargs)
  • int rte_dev_probe (const char *devargs)
  • int rte_eal_hotplug_remove (const char *busname, const char *devname)
  • int rte_dev_remove (struct rte_device *dev)
  • int rte_dev_iterator_init (struct rte_dev_iterator *it, const char *str)
  • struct rte_device * rte_dev_iterator_next (struct rte_dev_iterator *it)
  • int rte_dev_event_callback_register (const char *device_name, rte_dev_event_cb_fn cb_fn, void *cb_arg)
  • int rte_dev_event_callback_unregister (const char *device_name, rte_dev_event_cb_fn cb_fn, void *cb_arg)
  • void rte_dev_event_callback_process (const char *device_name, enum rte_dev_event_type event)
  • int rte_dev_event_monitor_start (void)
  • int rte_dev_event_monitor_stop (void)
  • int rte_dev_hotplug_handle_enable (void)
  • int rte_dev_hotplug_handle_disable (void)
  • int rte_dev_dma_map (struct rte_device *dev, void *addr, uint64_t iova, size_t len)
  • int rte_dev_dma_unmap (struct rte_device *dev, void *addr, uint64_t iova, size_t len)

👑 Detailed Description 👑

RTE PMD Registration Interface — that's the whole vibe of this file, bestie.

Real talk though: this file manages the list of device drivers. That's the job. That's what it does. 🫡

Definition in file rte_dev.h.

💜 Typedef Documentation 💜

🌈 typedef int(* rte_dev_cmp_t) (const struct rte_device *dev, const void *data)

Device comparison function. ✨

So this is the type of function you use when you wanna compare an rte_device against some arbitrary data. Lowkey a matchmaker, highkey a sorting tool. 💘

Parameters

  • dev — Device handle. (the little guy we're checking)
  • data — Data to compare against. The type of this parameter is determined by the kind of comparison performed by the function. (so like, you decide what data even means, no pressure 🫠)

Returns

  • 0 if the device matches the data.
  • !0 if the device does not match.
  • <0 if ordering is possible and the device is lower than the data.
  • >0 if ordering is possible and the device is greater than the data.
Definition at line 233 of file rte_dev.h.

🌈 typedef void *(* rte_dev_iterate_t) (const void *start, const char *devstr, const struct rte_dev_iterator *it)

Device iteration function. 🦋

Find the next device matching properties passed in parameters. The function takes an additional start parameter, that is used as starting context when relevant.

The function returns the current element in the iteration. This return value will potentially be used as a start parameter in subsequent calls to the function. (yes bestie, it's a lil relay race 🏃‍♀️💨)

The additional iterator parameter is only there if a specific implementation needs additional context. It must not be modified by the iteration function itself. No touching. 🙅‍♀️

Parameters

  • start — Starting iteration context.
  • devstr — Device description string.
  • it — Device iterator.

Returns

The address of the current element matching the device description string. 📍

Definition at line 278 of file rte_dev.h.

🎀 Enumeration Type Documentation 🎀

⭐ enum rte_dev_event_type

The device event type.

Enumerator

  • RTE_DEV_EVENT_ADD — device being added 🎉
  • RTE_DEV_EVENT_REMOVE — device being removed 😭
  • RTE_DEV_EVENT_MAX — max value of this enum (the ceiling, the limit, the final boss 👑)
Definition at line 34 of file rte_dev.h.

⭐ enum rte_dev_policy

Device policies. That's the description, bestie, that's all they gave us. 📋

Definition at line 47 of file rte_dev.h.

…and that's only part 1, so don't you dare close the tab — more is coming 🫶

✨ FUNCTION DOCUMENTATION ✨

okay bestie we're in the big one now — this is where the actual functions live. grab a snack, this is giving ✨reference manual✨ but make it cute. every single one of these is real, and yes, I kept every param and every return value, no cap 💅

rte_driver_name</p>

const char * rte_driver_name(const struct rte_driver *driver);

Pull the driver name out, girl. that's it, that's the function.

Parameters

  • driver — a pointer to a driver structure.

Returns

  • a pointer to the driver name string.

rte_dev_bus</p>

const struct rte_bus * rte_dev_bus(const struct rte_device *dev);

Which bus does this device live on? find out here 🚌

Parameters

  • dev — a pointer to a device structure.

Returns

  • a pointer to this device's bus.

rte_dev_bus_info</p>

const char * rte_dev_bus_info(const struct rte_device *dev);

Grab the bus-specific tea about a device ☕

Parameters

  • dev — a pointer to a device structure.

Returns

  • a string describing this device, or NULL if there isn't one available. (iykyk, always check for the NULL 💀)

rte_dev_devargs</p>

const struct rte_devargs * rte_dev_devargs(const struct rte_device *dev);

Get the devargs for a device.

Parameters

  • dev — a pointer to a device structure.

Returns

  • a pointer to this device's devargs.

rte_dev_driver</p>

const struct rte_driver * rte_dev_driver(const struct rte_device *dev);

The driver this device is vibing with. periodt.

Parameters

  • dev — a pointer to a device structure.

Returns

  • a pointer to this device's driver.

rte_dev_name</p>

const char * rte_dev_name(const struct rte_device *dev);

What's the device called? name reveal 😌

Parameters

  • dev — a pointer to a device structure.

Returns

  • a pointer to this device's name.

rte_dev_numa_node</p>

int rte_dev_numa_node(const struct rte_device *dev);

Which NUMA node is this device on? lowkey essential info 🧠

Parameters

  • dev — a pointer to a device structure.

Returns

  • a pointer to this device's numa node. (that's genuinely what the doc says for an int return, bestie — I'm just the messenger, not about to rewrite the docs on you 🙈)

rte_dev_is_probed</p>

int rte_dev_is_probed(const struct rte_device *dev);

Status check on a device — has it been probed or not?

Parameters

  • dev — generic device pointer.

Returns

  • (int)true if it's already been probed successfully, 0 otherwise.

rte_eal_hotplug_add</p>

int rte_eal_hotplug_add(const char *busname, const char *devname, const char *drvargs);

Hotplug-add a given device to a specific bus 🔥🔌

Multi-process heads up: in multi-process, it will ask the other processes to add the same device. A failure, in any process, will rollback the action. so no half-done chaos, it's all or nothing ✨

Parameters

  • busname — the bus name the device is being added to.
  • devname — the device name. based on this name, eal will find a driver capable of handling it and hand it over to the driver's probing function.
  • drvargs — device arguments to pass to the driver.

Returns

  • 0 on success, negative on error.

rte_dev_probe</p>

int rte_dev_probe(const char *devargs);

Add matching devices. matching era 🎯

Multi-process heads up: in multi-process, it will ask the other processes to add the same device. A failure, in any process, will rollback the action.

Parameters

  • devargs — device arguments, including bus, class and driver properties.

Returns

  • 0 on success, negative on error.

rte_eal_hotplug_remove</p>

int rte_eal_hotplug_remove(const char *busname, const char *devname);

Hotplug-remove a given device from a specific bus. bye bestie 👋💔

Multi-process heads up: in multi-process, it will ask the other processes to remove the same device. A failure, in any process, will rollback the action.

Parameters

  • busname — the bus name the device is being removed from.
  • devname — the device name being removed.

Returns

  • 0 on success, negative on error.

rte_dev_remove</p>

int rte_dev_remove(struct rte_device *dev);

Remove one device. one. singular. not a group thing 😤

Multi-process heads up: in multi-process, it will ask the other processes to remove the same device. A failure, in any process, will rollback the action.

Parameters

  • dev — data structure of the device to remove.

Returns

  • 0 on success, negative on error.

rte_dev_iterator_init</p>

int rte_dev_iterator_init(struct rte_dev_iterator *it, const char *str);

Initializes a device iterator ✨

This iterator lets you access a whole list of devices matching some criteria. The matching happens across all buses and classes that are currently registered, filtered by the device description you pass in as the parameter.

Big selling point: this function will not allocate any memory. it is safe to stop the iteration at any moment and just let the iterator go out of context. no cleanup drama, no leaks, we love to see it 🫶

Parameters

  • it — device iterator handle.
  • str — device description string.

Returns

  • 0 on successful initialization. <0 on error.

rte_dev_iterator_next</p>

struct rte_device * rte_dev_iterator_next(struct rte_dev_iterator *it);

Iterates on a device iterator ➡️

Generates a new rte_device handle corresponding to the next element in the list that the iterator is describing.

The next object gets returned, and the iterator is updated.

Parameters

  • it — device iterator handle.

Returns

  • an rte_device handle if one is found.
  • NULL if an error occurred (rte_errno is set).
  • NULL if no device could be found (rte_errno is not set).
Careful, bestie: those two NULLs mean completely different things. check rte_errno before you panic 💀

rte_dev_event_callback_register</p>

int rte_dev_event_callback_register(const char *device_name, rte_dev_event_cb_fn cb_fn, void *cb_arg);

Registers the callback for the specific device. and yes, multiple callbacks can be registered at the same time — the more the merrier 💅

Parameters

  • device_name — the device name, that is the param name of the struct rte_device. a null value means it applies to all devices.
  • cb_fn — callback address.
  • cb_arg — address of the parameter for the callback.

Returns

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

rte_dev_event_callback_unregister</p>

int rte_dev_event_callback_unregister(const char *device_name, rte_dev_event_cb_fn cb_fn, void *cb_arg);

Unregisters the callback according to the specified device. clean up after yourself queen 👑

Parameters

  • device_name — the device name, that is the param name of the struct rte_device. a null value means it applies to all devices and their callbacks.
  • cb_fn — callback address.
  • cb_arg — address of the parameter for the callback. (void *)-1 means remove all registered ones that have the same callback address.

Returns

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

rte_dev_event_callback_process</p>

void rte_dev_event_callback_process(const char *device_name, enum rte_dev_event_type event);

Executes all the user-application-registered callbacks for that specific device. everyone gets their moment 🎤

Parameters

  • device_name — the device name.
  • event — the device event type.

rte_dev_event_monitor_start</p>

int rte_dev_event_monitor_start(void);

Start the device event monitoring. it's watching 👀✨

Returns

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

rte_dev_event_monitor_stop</p>

int rte_dev_event_monitor_stop(void);

Stop the device event monitoring. okay it's done watching, go home 🏠

Returns

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

rte_dev_hotplug_handle_enable</p>

int rte_dev_hotplug_handle_enable(void);

Enable hotplug handling for devices 🔌🔥

Returns

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

rte_dev_hotplug_handle_disable</p>

int rte_dev_hotplug_handle_disable(void);

Disable hotplug handling for devices. shutting it down 🚫

Returns

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

rte_dev_dma_map</p>

int rte_dev_dma_map(struct rte_device *dev, void *addr, uint64_t iova, size_t len);

Device-level DMA map function. after a successful call, the memory segment will be mapped to the given device 🗺️

NOTE: memory must be registered in advance using the rte_extmem_* APIs. no prereg, no mapping, that's the rule 🫶

Parameters

  • dev — device pointer.
  • addr — virtual address to map.
  • iova — IOVA address to map.
  • len — length of the memory segment being mapped.

Returns

  • 0 if the mapping was successful. a negative value and rte_errno is set otherwise.

rte_dev_dma_unmap</p>

int rte_dev_dma_unmap(struct rte_device *dev, void *addr, uint64_t iova, size_t len);

Device-level DMA unmap function. after a successful call, the memory segment will no longer be accessible by the given device. it's giving ✨gone✨

NOTE: memory must be registered in advance using the rte_extmem_* APIs.

Parameters

  • dev — device pointer.
  • addr — virtual address to unmap.
  • iova — IOVA address to unmap.
  • len — length of the memory segment being mapped.

Returns

  • 0 if the un-mapping was successful. a negative value and rte_errno is set otherwise.

✨ AUTHOR ✨

Generated automatically by Doxygen for DPDK from the source code. (yes girl, the docs wrote themselves — very main character energy of them 😌)

and that's a wrap on rte_dev.h(3), bestie!! 🎀 you made it through the entire function list, every param, every return value, every <0 — I'm so proud, genuinely. this page came from DPDK, Version 25.11.3, and it's dated rte_dev.h(3) — that's the source/version/date footer, in case you ever need to cite your girl. go forth and hotplug responsibly 💖🦋

📦 where this page comes from