rte_rawdev_pmd.h(3)

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

✨ rte_rawdev_pmd.h ✨

okay so bestie, welcome to rte_rawdev_pmd.h — the header that holds all the driver-facing raw device PMD APIs 💖. It's giving "backstage pass only", and we're about to go through it in full, no skips, no cap. Part 1 of 3, so buckle up 🎀.

🌸 NAME 🌸

rte_rawdev_pmd.h — the header file itself, and the star of this whole manual page 💅

🦋 SYNOPSIS 🦋

First things first, here's what you gotta pull in, literally verbatim:

#include <string.h>
#include <dev_driver.h>
#include <rte_malloc.h>
#include <rte_log.h>
#include <rte_common.h>
#include 'rte_rawdev.h'
not me side-eyeing that last include with the single quotes 👀 — it's written exactly like that in the original, so we are not touching it. Copy it as-is, bestie.

🌈 Data Structures

  • struct rte_rawdev_ops — the big one, the icon, the blueprint 👑

🎀 Typedefs

okay so this is the function-pointer family, and every single one of them shows up here, no exceptions, periodt ✨:

  • typedef int(* rawdev_info_get_t) (struct rte_rawdev *dev, rte_rawdev_obj_t dev_info, size_t dev_private_size)
  • typedef int(* rawdev_configure_t) (const struct rte_rawdev *dev, rte_rawdev_obj_t config, size_t config_size)
  • typedef int(* rawdev_start_t) (struct rte_rawdev *dev)
  • typedef void(* rawdev_stop_t) (struct rte_rawdev *dev)
  • typedef int(* rawdev_close_t) (struct rte_rawdev *dev)
  • typedef int(* rawdev_reset_t) (struct rte_rawdev *dev)
  • typedef int(* rawdev_queue_conf_get_t) (struct rte_rawdev *dev, uint16_t queue_id, rte_rawdev_obj_t queue_conf, size_t queue_conf_size)
  • typedef int(* rawdev_queue_setup_t) (struct rte_rawdev *dev, uint16_t queue_id, rte_rawdev_obj_t queue_conf, size_t queue_conf_size)
  • typedef int(* rawdev_queue_release_t) (struct rte_rawdev *dev, uint16_t queue_id)
  • typedef uint16_t(* rawdev_queue_count_t) (struct rte_rawdev *dev)
  • typedef int(* rawdev_enqueue_bufs_t) (struct rte_rawdev *dev, struct rte_rawdev_buf **buffers, unsigned int count, rte_rawdev_obj_t context)
  • typedef int(* rawdev_dequeue_bufs_t) (struct rte_rawdev *dev, struct rte_rawdev_buf **buffers, unsigned int count, rte_rawdev_obj_t context)
  • typedef int(* rawdev_dump_t) (struct rte_rawdev *dev, FILE *f)
  • typedef int(* rawdev_get_attr_t) (struct rte_rawdev *dev, const char *attr_name, uint64_t *attr_value)
  • typedef int(* rawdev_set_attr_t) (struct rte_rawdev *dev, const char *attr_name, const uint64_t attr_value)
  • typedef int(* rawdev_xstats_get_t) (const struct rte_rawdev *dev, const unsigned int ids[], uint64_t values[], unsigned int n)
  • typedef int(* rawdev_xstats_reset_t) (struct rte_rawdev *dev, const uint32_t ids[], uint32_t nb_ids)
  • typedef int(* rawdev_xstats_get_names_t) (const struct rte_rawdev *dev, struct rte_rawdev_xstats_name *xstats_names, unsigned int size)
  • typedef uint64_t(* rawdev_xstats_get_by_name_t) (const struct rte_rawdev *dev, const char *name, unsigned int *id)
  • typedef int(* rawdev_firmware_status_get_t) (struct rte_rawdev *dev, rte_rawdev_obj_t status_info)
  • typedef int(* rawdev_firmware_version_get_t) (struct rte_rawdev *dev, rte_rawdev_obj_t version_info)
  • typedef int(* rawdev_firmware_load_t) (struct rte_rawdev *dev, rte_rawdev_obj_t firmware_buf)
  • typedef int(* rawdev_firmware_unload_t) (struct rte_rawdev *dev)
  • typedef int(* rawdev_selftest_t) (uint16_t dev_id)

that's the whole roster 💜 every one of them, accounted for.

⭐ Functions

and here's the function lineup, bestie — again, all of them, exactly as written 🔥:

  • static struct rte_rawdev * rte_rawdev_pmd_get_named_dev (const char *name)
  • static struct rte_rawdev * rte_rawdev_pmd_get_dev (uint8_t dev_id)
  • static unsigned rte_rawdev_pmd_is_valid_dev (uint8_t dev_id)
  • struct rte_rawdev * rte_rawdev_pmd_allocate (const char *name, size_t dev_private_size, int socket_id)
  • int rte_rawdev_pmd_release (struct rte_rawdev *rawdev)
  • struct rte_rawdev * rte_rawdev_pmd_init (const char *name, size_t dev_private_size, int socket_id)
  • int rte_rawdev_pmd_uninit (const char *name)

💖 Detailed Description 💖

RTE RAW PMD APIs — that's the whole vibe of this file, fr fr.

⚠️ Note: Driver facing APIs for a raw device. These are not to be called directly by any application.

read that again, bestie 🫶 these are the driver-side doors, not the ones your app should be knocking on. Application-facing stuff lives elsewhere — this header is strictly for drivers doing their thing behind the scenes 👑

Definition in file rte_rawdev_pmd.h.

okay that's part 1 wrapped 🎀 the typedefs and functions are all sitting pretty, and there's more coming — don't go anywhere 💅

✨ Typedef Documentation ✨

okay bestie, this is the section where we meet all the function pointer typedefs a driver exports through the generic rawdev_ops structure (which lives in the rte_rawdev struct hanging off a device). every single one of them, no skipping, periodt 💖

  • typedef int(* rawdev_info_get_t) (struct rte_rawdev *dev, rte_rawdev_obj_t dev_info, size_t dev_private_size)

the whole point of this one: it's where all the functions a driver exports live, reached through that generic rawdev_ops structure supplied in the rte_rawdev structure that's associated with a device. fr fr, this is the gateway. 🌸

what it does: get device information of a device.

Parameters:

  • dev — Raw device pointer
  • dev_info — Raw device information structure
  • dev_private_size — The size of the structure pointed to by dev_info->dev_private

Returns: Returns 0 on success, negative error code on failure

Definition at line 172 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_configure_t) (const struct rte_rawdev *dev, rte_rawdev_obj_t config, size_t config_size)

what it does: Configure a device. 💅

Parameters:

  • dev — Raw device pointer
  • config — Void object containing device specific configuration
  • config_size — Size of the memory allocated for the configuration

Returns: Returns 0 on success

Definition at line 189 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_start_t) (struct rte_rawdev *dev)

what it does: Start a configured device. it's giving main character energy, the device is officially awake 🔥

Parameters:

  • dev — Raw device pointer

Returns: Returns 0 on success

Definition at line 202 of file rte_rawdev_pmd.h.

  • typedef void(* rawdev_stop_t) (struct rte_rawdev *dev)

what it does: Stop a configured device. nap time, bestie 😴

Parameters:

  • dev — Raw device pointer

Definition at line 210 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_close_t) (struct rte_rawdev *dev)

what it does: Close a configured device. 🎀

Parameters:

  • dev — Raw device pointer

Returns:

  • 0 on success
  • (-EAGAIN) if can't close as device is busy

Definition at line 222 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_reset_t) (struct rte_rawdev *dev)

what it does: Reset a configured device. factory reset but make it rawdev ✨

Parameters:

  • dev — Raw device pointer

Returns: 0 for success !0 for failure

Definition at line 233 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_queue_conf_get_t) (struct rte_rawdev *dev, uint16_t queue_id, rte_rawdev_obj_t queue_conf, size_t queue_conf_size)

what it does: Retrieve the current raw queue configuration. lowkey essential info gathering 🦋

Parameters:

  • dev — Raw device pointer
  • queue_id — Raw device queue index
  • queue_conf — Raw device queue configuration structure
  • queue_conf_size — Size of the memory allocated for the configuration

Returns: Returns 0 on success, negative errno on failure

Definition at line 250 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_queue_setup_t) (struct rte_rawdev *dev, uint16_t queue_id, rte_rawdev_obj_t queue_conf, size_t queue_conf_size)

what it does: Setup an raw queue. yes the original says "an raw queue", we're not fixing it, we're honoring it 💀

Parameters:

  • dev — Raw device pointer
  • queue_id — Rawqueue index
  • queue_conf — Rawqueue configuration structure
  • queue_conf_size — Size of the memory allocated for the configuration

Returns: Returns 0 on success.

Definition at line 270 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_queue_release_t) (struct rte_rawdev *dev, uint16_t queue_id)

what it does: Release resources allocated by given raw queue. giving them back, no hoarding 🙈

Parameters:

  • dev — Raw device pointer
  • queue_id — Raw queue index

Definition at line 283 of file rte_rawdev_pmd.h.

  • typedef uint16_t(* rawdev_queue_count_t) (struct rte_rawdev *dev)

what it does: Get the count of number of queues configured on this device. 🧮

there's another way to fetch this info — you could fetch the device configuration. but that assumes the device configuration managed by the driver actually has that kind of information, and bestie, we can't assume that.

this function helps in getting queue count supported, independently. so iconic of it. it can help in cases where iterator needs to be implemented. 💖

Parameters:

  • dev — Raw device pointer

Returns: Number of queues; 0 is assumed to be a valid response.

Definition at line 301 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_enqueue_bufs_t) (struct rte_rawdev *dev, struct rte_rawdev_buf **buffers, unsigned int count, rte_rawdev_obj_t context)

what it does: Enqueue an array of raw buffers to the device. 🚀

the buffer being used is opaque — it can be obtained from mempool or from any other source. interpretation of buffer is responsibility of driver. iykyk, the driver decides what it all means.

Parameters:

  • dev — Raw device pointer
  • buffers — array of buffers
  • count — number of buffers passed
  • context — an opaque object representing context of the call; for example, an application can pass information about the queues on which enqueue needs to be done. Or, the enqueue operation might be passed reference to an object containing a callback (agreed upon between application and driver).

Returns:

  • >=0 Count of buffers successfully enqueued (0: no buffers enqueued)
  • <0 Error count in case of error

Definition at line 325 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_dequeue_bufs_t) (struct rte_rawdev *dev, struct rte_rawdev_buf **buffers, unsigned int count, rte_rawdev_obj_t context)

what it does: Dequeue an array of raw buffers from the device. the reverse slay 🌈

Parameters:

  • dev — Raw device pointer
  • buffers — array of buffers
  • count — Max buffers expected to be dequeued
  • context — an opaque object representing context of the call. Based on this object, the application and driver can coordinate for dequeue operation involving agreed upon semantics. For example, queue information/id on which Dequeue needs to be performed.

Returns:

  • >0, ~0: Count of buffers returned
  • <0: Error

Whether short dequeue is success or failure is decided between app and driver. so that's a them-thing, not a us-thing 🫶

Definition at line 350 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_dump_t) (struct rte_rawdev *dev, FILE *f)

what it does: Dump internal information. spill the tea, device 🍓

Parameters:

  • dev — Raw device pointer
  • f — A pointer to a file for output

Returns: 0 for success, !0 Error

Definition at line 366 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_get_attr_t) (struct rte_rawdev *dev, const char *attr_name, uint64_t *attr_value)

what it does: Get an attribute value from implementation. Attribute is an opaque handle agreed upon between application and PMD. lowkey a whole secret handshake 🤝

Parameters:

  • dev — Raw device pointer
  • attr_name — Opaque object representing an attribute in implementation.
  • attr_value — [out] Opaque response to the attribute value. In case of error, this remains untouched. This is double pointer of void type.

Returns: 0 for success !0 Error; attr_value remains untouched in case of error.

Definition at line 383 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_set_attr_t) (struct rte_rawdev *dev, const char *attr_name, const uint64_t attr_value)

what it does: Set an attribute value. Attribute is an opaque handle agreed upon between application and PMD. 💅

Parameters:

  • dev — Raw device pointer
  • attr_name — Opaque object representing an attribute in implementation.
  • attr_value — Value of the attribute represented by attr_name

Returns: 0 for success !0 Error

Definition at line 401 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_xstats_get_t) (const struct rte_rawdev *dev, const unsigned int ids[], uint64_t values[], unsigned int n)

what it does: Retrieve a set of statistics from device. 📊

heads up bestie: being a raw device, the stats are specific to the device being implemented, thus represented as xstats. so don't expect a universal stat list, mmkay?

Parameters:

  • dev — Raw device pointer
  • ids — The stat ids to retrieve
  • values — The returned stat values
  • n — The number of id values and entries in the values array

Returns: The number of stat values successfully filled into the values array

Definition at line 421 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_xstats_reset_t) (struct rte_rawdev *dev, const uint32_t ids[], uint32_t nb_ids)

what it does: Resets the statistic values in xstats for the device. clean slate energy ✨

Definition at line 427 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_xstats_get_names_t) (const struct rte_rawdev *dev, struct rte_rawdev_xstats_name *xstats_names, unsigned int size)

what it does: Get names of extended stats of an raw device 👑

Parameters:

  • dev — Raw device pointer
  • xstats_names — Array of name values to be filled in
  • size — Number of values in the xstats_names array

Returns: When size >= the number of stats, return the number of stat values filled into the array. When size < the number of available stats, return the number of stats values, and do not fill in any data into xstats_names. so if you undersized your array, you get nothing filled in, fr fr. 😭

Definition at line 446 of file rte_rawdev_pmd.h.

  • typedef uint64_t(* rawdev_xstats_get_by_name_t) (const struct rte_rawdev *dev, const char *name, unsigned int *id)

what it does: Get value of one stats and optionally return its id. 🎀

Parameters:

  • dev — Raw device pointer
  • name — The name of the stat to retrieve
  • id — Pointer to an unsigned int where we store the stat-id. This pointer may be null if the id is not required.

Returns: The value of the stat, or (uint64_t)-1 if the stat is not found. If the stat is not found, the id value will be returned as (unsigned)-1, if id pointer is non-NULL. so sad when a stat just doesn't exist 💔

Definition at line 465 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_firmware_status_get_t) (struct rte_rawdev *dev, rte_rawdev_obj_t status_info)

what it does: Get firmware/device-stack status. Implementation to allocate buffer for returning information. 🔧

Parameters:

  • dev — Raw device pointer
  • status_info — void block containing device specific status information

Returns: 0 for success, !0 for failure, with undefined value in status_info

Definition at line 481 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_firmware_version_get_t) (struct rte_rawdev *dev, rte_rawdev_obj_t version_info)

what it does: Get firmware version information. what's your firmware's sign bestie 💅

Parameters:

  • dev — Raw device pointer
  • version_info — void pointer to version information returned by device

Returns: 0 for success, !0 for failure, with undefined value in version_info

Definition at line 495 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_firmware_load_t) (struct rte_rawdev *dev, rte_rawdev_obj_t firmware_buf)

what it does: Load firmware from a buffer (DMA'able). 🚀

Parameters:

  • dev — Raw device pointer
  • firmware_buf — Pointer to firmware image

Returns:

  • >0, ~0: for successful load
  • <0: for failure

See also: Application may use firmware_version_get for ascertaining successful load. iykyk, check the version after, that's your vibe check. ✅

Definition at line 512 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_firmware_unload_t) (struct rte_rawdev *dev)

what it does: Unload firmware. bye bye firmware 🦋

Parameters:

  • dev — Raw device pointer

Returns:

  • >0, ~0 for successful unloading
  • <0 for failure in unloading
Note: Application can use the firmware_status_get or firmware_version_get to get result of unload.

Definition at line 527 of file rte_rawdev_pmd.h.

  • typedef int(* rawdev_selftest_t) (uint16_t dev_id)

what it does: Start rawdev selftest. the device doing a little self check, iconic 🪞💖

Returns: Return 0 on success

Definition at line 535 of file rte_rawdev_pmd.h.

💫 FUNCTION DOCUMENTATION 💫

🌸 rte_rawdev_pmd_get_named_dev

struct rte_rawdev * rte_rawdev_pmd_get_named_dev (const char * name)

[inline], [static]

okay so first things first, bestie — the source has a lil fragment of prose floating above this one that literally reads The pool of rte_rawdev structures. That's it, that's the whole sentence, she's just vibing there unattached 🫶. Then the actual job description kicks in: this one grabs the rte_rawdev structure device pointer for the named device. Name in, pointer out. iykyk.

Parameters

  • name — the device name you're using to select the device structure. that's the whole selection criteria, no cap.

Returns

  • The rte_rawdev structure pointer for the given device ID. 💖

Definition at line 87 of file rte_rawdev_pmd.h.

🦋 rte_rawdev_pmd_get_dev

struct rte_rawdev * rte_rawdev_pmd_get_dev (uint8_t dev_id)

[inline], [static]

Same energy as the one above but she takes an ID instead of a name 🎀. Get the rte_rawdev structure device pointer for given device ID. That's the vibe check, that's the whole function, periodt.

Parameters

  • dev_id — raw device index.

Returns

  • The rte_rawdev structure pointer for the given device ID. ✨

Definition at line 115 of file rte_rawdev_pmd.h.

🧚 rte_rawdev_pmd_is_valid_dev

unsigned rte_rawdev_pmd_is_valid_dev (uint8_t dev_id)

[inline], [static]

Validation era 💅. This one asks the big question: is this raw device index actually a valid attached raw device, or are we delulu? Validate if the raw device index is a valid attached raw device. That's it. That's her whole personality.

Parameters

  • dev_id — raw device index.

Returns

  • If the device index is valid (1) or not (0). Literally a yes-or-no, iconic.

Definition at line 139 of file rte_rawdev_pmd.h.

🔥 rte_rawdev_pmd_allocate

struct rte_rawdev * rte_rawdev_pmd_allocate (const char * name,
                                             size_t dev_private_size,
                                             int socket_id)

bestie this is the main character right here 👑. She allocates a brand new rawdev slot for a raw device and hands back the pointer to that slot so the driver can go use it. No cap.

Parameters

  • name — unique identifier name for each device. every device needs her own name, no sharing, that's the rule.
  • dev_private_size — size of private data memory allocated within the rte_rawdev object. Set to 0 to disable internal memory allocation and allow for self-allocation. (yes, 0 is a real option, she said self-allocation rights 😌)
  • socket_id — socket to allocate resources on.

Returns

  • Slot in the rte_dev_devices array for a new device;

Definition — she lives in rte_rawdev_pmd.h, right alongside her friends above. 💜

💀 rte_rawdev_pmd_release

int rte_rawdev_pmd_release (struct rte_rawdev * rawdev)

girlies this is the goodbye function 😭. Release the specified rawdev device. It's giving cleanup era, it's giving letting go.

Parameters

  • rawdev — the rawdev pointer is the address of the rte_rawdev structure.

Returns

  • 0 on success, negative on error.

🌈 rte_rawdev_pmd_init

struct rte_rawdev * rte_rawdev_pmd_init (const char * name,
                                         size_t dev_private_size,
                                         int socket_id)

Creation energy ✨. Creates a new raw device and returns the pointer to that device. It's literally birth but for hardware abstraction, slay.

Parameters

  • name — pointer to a character array containing name of the device.
  • dev_private_size — size of raw PMDs private data.
  • socket_id — socket to allocate resources on.

Returns

  • Raw device pointer if device is successfully created. 🎀
  • NULL if device cannot be created. (and yes, if she can't be created you get the NULL, not a crash, not a vibe, just NULL 🙈)

⭐ rte_rawdev_pmd_uninit

int rte_rawdev_pmd_uninit (const char * name)

Destroy a raw device 💥. Full send, no takebacks, she's gone.

Parameters

  • name — name of the device.

Returns

  • 0 on success, negative on error.

👑 AUTHOR 👑

Generated automatically by Doxygen for DPDK from the source code. So technically the bot wrote herself, which is kind of iconic ngl 🫶

aaaand that's a wrap on the whole page bestie!! 🎀 This one came to you from DPDK, Version 25.11.3, and it's the rte_rawdev_pmd.h(3) manual page — go forth and allocate responsibly, mwah 💅💖

📦 where this page comes from