rte_vhost.h(3)

📦 version 26.03, in nixos 26.05, nixpkgs unstable

💅 rte_vhost.h(3) — Library Functions Manual ✨

okay so bestie, this is the manual page for rte_vhost.h(3) — the Library Functions Manual entry for the vhost-user interface. We're gonna go through every detail with the exact names and values, no cap. 💖

🌸 NAME 🌸

rte_vhost.h — that's the name, periodt. Simple, iconic. 💅

✨ SYNOPSIS ✨

first up, the includes, exactly as they show up:

#include <stdbool.h>
#include <stdint.h>
#include <sys/eventfd.h>
#include <rte_compat.h>
#include <rte_memory.h>
#include <rte_mempool.h>
#include <linux/vhost.h>
#include <linux/virtio_ring.h>
#include <linux/virtio_net.h>

🎀 Data Structures 🎀

here's the struct squad, bestie:

  • struct rte_vhost_mem_region
  • struct rte_vhost_memory
  • struct rte_vhost_user_extern_ops
  • struct rte_vhost_device_ops
  • struct rte_vhost_power_monitor_cond
  • struct rte_vhost_stat
  • struct rte_vhost_stat_name

🧸 Macros 🧸

the macro moment, verbatim:

#define VHOST_USER_PROTOCOL_F_MQ   0
#define VHOST_USER_F_PROTOCOL_FEATURES   30
#define RTE_VHOST_STATS_NAME_SIZE   64

🪄 Typedefs 🪄

one typedef, and it's giving callback energy:

typedef enum rte_vhost_msg_result(* rte_vhost_msg_handle) (int vid, void *msg)

🔮 Enumerations 🔮

  • enum rte_vhost_msg_result

👑 Functions 👑

okay so here's the whole function lineup from the synopsis — yes, all of them, bestie:

static __rte_always_inline uint64_t rte_vhost_va_from_guest_pa (struct rte_vhost_memory *mem, uint64_t gpa, uint64_t *len)
void rte_vhost_log_write (int vid, uint64_t addr, uint64_t len)
void rte_vhost_log_used_vring (int vid, uint16_t vring_idx, uint64_t offset, uint64_t len)
__rte_experimental void rte_vhost_notify_guest (int vid, uint16_t queue_id)
int rte_vhost_driver_register (const char *path, uint64_t flags)
int rte_vhost_driver_attach_vdpa_device (const char *path, struct rte_vdpa_device *dev)
int rte_vhost_driver_detach_vdpa_device (const char *path)
struct rte_vdpa_device * rte_vhost_driver_get_vdpa_device (const char *path)
int rte_vhost_driver_get_vdpa_dev_type (const char *path, uint32_t *type)
int rte_vhost_driver_set_features (const char *path, uint64_t features)
int rte_vhost_driver_enable_features (const char *path, uint64_t features)
int rte_vhost_driver_disable_features (const char *path, uint64_t features)
int rte_vhost_driver_get_features (const char *path, uint64_t *features)
int rte_vhost_driver_set_protocol_features (const char *path, uint64_t protocol_features)
int rte_vhost_driver_get_protocol_features (const char *path, uint64_t *protocol_features)
int rte_vhost_driver_get_queue_num (const char *path, uint32_t *queue_num)
int rte_vhost_driver_set_max_queue_num (const char *path, uint32_t max_queue_pairs)
int rte_vhost_get_negotiated_features (int vid, uint64_t *features)
int rte_vhost_get_negotiated_protocol_features (int vid, uint64_t *protocol_features)
int rte_vhost_driver_start (const char *path)
int rte_vhost_get_mtu (int vid, uint16_t *mtu)
int rte_vhost_get_numa_node (int vid)
uint16_t rte_vhost_get_vring_num (int vid)
int rte_vhost_get_ifname (int vid, char *buf, size_t len)
uint16_t rte_vhost_avail_entries (int vid, uint16_t queue_id)
uint16_t rte_vhost_enqueue_burst (int vid, uint16_t queue_id, struct rte_mbuf **pkts, uint16_t count)
uint16_t rte_vhost_dequeue_burst (int vid, uint16_t queue_id, struct rte_mempool *mbuf_pool, struct rte_mbuf **pkts, uint16_t count)
int rte_vhost_get_mem_table (int vid, struct rte_vhost_memory **mem)
int rte_vhost_get_vhost_vring (int vid, uint16_t vring_idx, struct rte_vhost_vring *vring)
int rte_vhost_get_vhost_ring_inflight (int vid, uint16_t vring_idx, struct rte_vhost_ring_inflight *vring)
int rte_vhost_set_inflight_desc_split (int vid, uint16_t vring_idx, uint16_t idx)
int rte_vhost_set_inflight_desc_packed (int vid, uint16_t vring_idx, uint16_t head, uint16_t last, uint16_t *inflight_entry)
int rte_vhost_set_last_inflight_io_split (int vid, uint16_t vring_idx, uint16_t idx)
int rte_vhost_set_last_inflight_io_packed (int vid, uint16_t vring_idx, uint16_t head)
int rte_vhost_clr_inflight_desc_split (int vid, uint16_t vring_idx, uint16_t last_used_idx, uint16_t idx)
int rte_vhost_clr_inflight_desc_packed (int vid, uint16_t vring_idx, uint16_t head)
int rte_vhost_vring_call (int vid, uint16_t vring_idx)
int rte_vhost_vring_call_nonblock (int vid, uint16_t vring_idx)
uint32_t rte_vhost_rx_queue_count (int vid, uint16_t qid)
int rte_vhost_get_monitor_addr (int vid, uint16_t queue_id, struct rte_vhost_power_monitor_cond *pmc)
int rte_vhost_get_log_base (int vid, uint64_t *log_base, uint64_t *log_size)
int rte_vhost_get_vring_base (int vid, uint16_t queue_id, uint16_t *last_avail_idx, uint16_t *last_used_idx)
int rte_vhost_get_vring_base_from_inflight (int vid, uint16_t queue_id, uint16_t *last_avail_idx, uint16_t *last_used_idx)
int rte_vhost_set_vring_base (int vid, uint16_t queue_id, uint16_t last_avail_idx, uint16_t last_used_idx)
int rte_vhost_extern_callback_register (int vid, struct rte_vhost_user_extern_ops const *const ops, void *ctx)
struct rte_vdpa_device * rte_vhost_get_vdpa_device (int vid)
int rte_vhost_backend_config_change (int vid, bool need_reply)
int rte_vhost_vring_stats_get_names (int vid, uint16_t queue_id, struct rte_vhost_stat_name *name, unsigned int size)
int rte_vhost_vring_stats_get (int vid, uint16_t queue_id, struct rte_vhost_stat *stats, unsigned int n)
int rte_vhost_vring_stats_reset (int vid, uint16_t queue_id)

💖 Detailed Description 💖

Interface to vhost-user. 🦋

Definition in file rte_vhost.h.

💅 Macro Definition Documentation 💅

🌟 VHOST_USER_PROTOCOL_F_MQ

#define VHOST_USER_PROTOCOL_F_MQ   0

Protocol features. ✨

Definition at line 65 of file rte_vhost.h.

🌟 VHOST_USER_F_PROTOCOL_FEATURES

#define VHOST_USER_F_PROTOCOL_FEATURES   30

Indicate whether protocol features negotiation is supported. 💖

Definition at line 118 of file rte_vhost.h.

🌟 RTE_VHOST_STATS_NAME_SIZE

#define RTE_VHOST_STATS_NAME_SIZE   64

Maximum name length for the statistics counters. 💅

Definition at line 337 of file rte_vhost.h.

🪄 Typedef Documentation 🪄

💫 rte_vhost_msg_handle

typedef enum rte_vhost_msg_result(* rte_vhost_msg_handle) (int vid, void *msg)

Function prototype for the vhost backend to handle specific vhost user messages. 🫶

Parameters:

  • vid — vhost device id
  • msg — Message pointer.

Returns: RTE_VHOST_MSG_RESULT_OK on success, RTE_VHOST_MSG_RESULT_REPLY on success with reply, RTE_VHOST_MSG_RESULT_ERR on failure, RTE_VHOST_MSG_RESULT_NOT_HANDLED if message was not handled.

Definition at line 1 of file rte_vhost.h.

🔮 Enumeration Type Documentation 🔮

enum rte_vhost_msg_result

Possible results of the vhost user message handling callbacks. 👑

Definition at line 237 of file rte_vhost.h.

👑 Function Documentation 👑

💫 rte_vhost_va_from_guest_pa 💫

__rte_always_inline uint64_t rte_vhost_va_from_guest_pa (struct rte_vhost_memory *mem, uint64_t gpa, uint64_t *len)

This one is marked [static] in the docs. It converts a guest physical address to a host virtual address. 🦋

Parameters:

  • mem — the guest memory regions
  • gpa — the guest physical address for querying
  • len — the size of the requested area to map, updated with actual size mapped

Returns: the host virtual address on success, 0 on failure.

Definition at line 375 of file rte_vhost.h.

💫 rte_vhost_log_write 💫

void rte_vhost_log_write (int vid, uint64_t addr, uint64_t len)

This logs the memory write start with the given address. ✨ Lowkey you only need to invoke it when live migration starts — so most of the time you won't need to call it at all. To keep the performance impact as tiny as possible, the move is to check before calling it:

if (unlikely(RTE_VHOST_NEED_LOG(features)))
        rte_vhost_log_write(vid, addr, len);

Parameters:

  • vid — vhost device ID
  • addr — the starting address for write (in guest physical address space)
  • len — the length to write

💫 rte_vhost_log_used_vring 💫

void rte_vhost_log_used_vring (int vid, uint16_t vring_idx, uint64_t offset, uint64_t len)

This logs the used ring update start at the given offset. Same as rte_vhost_log_write, the docs suggest doing a check before calling it:

if (unlikely(RTE_VHOST_NEED_LOG(features)))
        rte_vhost_log_used_vring(vid, vring_idx, offset, len);

Parameters:

  • vid — vhost device ID
  • vring_idx — the vring index
  • offset — the offset inside the used ring
  • len — the length to write

💫 rte_vhost_notify_guest 💫

__rte_experimental void rte_vhost_notify_guest (int vid, uint16_t queue_id)
⚠️ Warning: EXPERIMENTAL: this API may change, or be removed, without prior notice.

This injects the offloaded interrupt into the vhost device's queue. 💅

See also: guest_notify vhost device operation

Parameters:

  • vid — vhost device ID
  • queue_id — virtio queue index

💫 rte_vhost_driver_register 💫

int rte_vhost_driver_register (const char *path, uint64_t flags)

This registers the vhost driver. The path could be different for multiple instance support. 👑

💫 rte_vhost_driver_attach_vdpa_device 💫

int rte_vhost_driver_attach_vdpa_device (const char *path, struct rte_vdpa_device *dev)

This sets the vdpa device id and enforces a single connection per socket. 🫶

Parameters:

  • path — The vhost-user socket file path
  • dev — vDPA device pointer

Returns: 0 on success, -1 on failure.

💫 rte_vhost_driver_detach_vdpa_device 💫

int rte_vhost_driver_detach_vdpa_device (const char *path)

This unsets the vdpa device id. 🎀

Parameters:

  • path — The vhost-user socket file path

Returns: 0 on success, -1 on failure.

💫 rte_vhost_driver_get_vdpa_device 💫

struct rte_vdpa_device * rte_vhost_driver_get_vdpa_device (const char *path)

This gets the device id. 💖

Parameters:

  • path — The vhost-user socket file path

Returns: vDPA device pointer, NULL on failure.

💫 rte_vhost_driver_get_vdpa_dev_type 💫

int rte_vhost_driver_get_vdpa_dev_type (const char *path, uint32_t *type)

This gets the device type of the vdpa device. ✨

Parameters:

  • path — The vhost-user socket file path
  • type — the device type of the vdpa device

Returns: 0 on success, -1 on failure.

💫 rte_vhost_driver_set_features 💫

int rte_vhost_driver_set_features (const char *path, uint64_t features)

This sets the feature bits that the vhost-user driver supports. 🌸

Parameters:

  • path — The vhost-user socket file path
  • features — Supported features

Returns: 0 on success, -1 on failure.

💫 rte_vhost_driver_enable_features 💫

int rte_vhost_driver_enable_features (const char *path, uint64_t features)

This enables vhost-user driver features. 🦋

Note that:

  • the param features should be a subset of the feature bits provided by rte_vhost_driver_set_features().
  • it must be invoked before vhost-user negotiation starts.

Parameters:

  • path — The vhost-user socket file path
  • features — Features to enable

Returns: 0 on success, -1 on failure.

💫 rte_vhost_driver_disable_features 💫

int rte_vhost_driver_disable_features (const char *path, uint64_t features)

This disables vhost-user driver features. 💅

The two notes at rte_vhost_driver_enable_features() also apply here.

Parameters:

  • path — The vhost-user socket file path
  • features — Features to disable

Returns: 0 on success, -1 on failure.

💫 rte_vhost_driver_get_features 💫

int rte_vhost_driver_get_features (const char *path, uint64_t *features)

This gets the feature bits before feature negotiation. 👑

Parameters:

  • path — The vhost-user socket file path
  • features — A pointer to store the queried feature bits

Returns: 0 on success, -1 on failure.

int rte_vhost_driver_set_protocol_features (const char * path, uint64_t protocol_features)

Okay so bestie, this one lets you set the protocol feature bits before feature negotiation happens. Like picking your outfit before the party even starts 💅

  • path — the vhost-user socket file path
  • protocol_features — the supported protocol features

Returns 0 on success, -1 on failure.

int rte_vhost_driver_get_protocol_features (const char * path, uint64_t * protocol_features)

The matching reader 📖 — get the protocol feature bits, again before feature negotiation.

  • path — the vhost-user socket file path
  • protocol_features — a pointer to store the queried protocol feature bits

Returns 0 on success, -1 on failure.

int rte_vhost_driver_get_queue_num (const char * path, uint32_t * queue_num)

Grabs the queue number bits, and yep — still before feature negotiation. Timing is everything, periodt ⏰

  • path — the vhost-user socket file path
  • queue_num — a pointer to store the queried queue number bits

Returns 0 on success, -1 on failure.

int rte_vhost_driver_set_max_queue_num (const char * path, uint32_t max_queue_pairs)

Sets the max number of queue pairs the device can handle. Lowkey important detail: the value you set is ignored for Vhost-user backends — it only counts with VDUSE backends 🫶

  • path — the vhost-user socket file path
  • max_queue_pairs — the maximum number of queue pairs

Returns 0 on success, -1 on failure.

int rte_vhost_get_negotiated_features (int vid, uint64_t * features)

Now we're after the negotiation glow-up ✨ — this gets the feature bits once negotiation is done.

  • vid — Vhost device ID
  • features — a pointer to store the queried feature bits

Returns 0 on success, -1 on failure.

int rte_vhost_get_negotiated_protocol_features (int vid, uint64_t * protocol_features)

Same energy, but for the protocol feature bits — post-negotiation edition 💖

  • vid — Vhost device ID
  • protocol_features — a pointer to store the queried protocol feature bits

Returns 0 on success, -1 on failure.

int rte_vhost_driver_start (const char * path)

Starts the vhost-user driver. This is the moment, the main character moment 👑 — it triggers the vhost-user negotiation.

  • path — the vhost-user socket file path

Returns 0 on success, -1 on failure.

int rte_vhost_get_mtu (int vid, uint16_t * mtu)

Gets the MTU value of the device, if it's set in QEMU (conditional queen 👸).

  • vid — virtio-net device ID
  • mtu — the variable to store the MTU value

Returns:

  • 0 — success
  • -EAGAIN — device not yet started
  • -ENOTSUP — device does not support MTU feature

int rte_vhost_get_numa_node (int vid)

Tells you which numa node the virtio net device's memory is allocated from 🧠

  • vid — vhost device ID

Returns the numa node, or -1 on failure.

uint16_t rte_vhost_get_vring_num (int vid)

How many vrings does this device even support, bestie? That's the whole question 💫

  • vid — vhost device ID

Returns the number of vrings, or 0 on failure.

int rte_vhost_get_ifname (int vid, char * buf, size_t len)

Gets the virtio net device's ifname — which, fun fact, is the vhost-user socket file path 🎀

  • vid — vhost device ID
  • buf — the buffer to stored the queried ifname
  • len — the length of buf

Returns 0 on success, -1 on failure.

uint16_t rte_vhost_avail_entries (int vid, uint16_t queue_id)

How many avail entries are still chilling in the queue? 👀

  • vid — vhost device ID
  • queue_id — virtio queue index

Returns the num of avail entries left.

uint16_t rte_vhost_enqueue_burst (int vid, uint16_t queue_id, struct rte_mbuf ** pkts, uint16_t count)

This one adds buffers to the virtio device's RX virtqueue 🚀 Buffers can come from the physical port or from another virtual device. You get a packet count back showing how many packets actually made it into the RX queue successfully.

  • vid — vhost device ID
  • queue_id — virtio queue index in mq case
  • pkts — array to contain packets to be enqueued
  • count — packets num to be enqueued

Returns the num of packets enqueued.

uint16_t rte_vhost_dequeue_burst (int vid, uint16_t queue_id, struct rte_mempool * mbuf_pool, struct rte_mbuf ** pkts, uint16_t count)

The reverse vibes 🔄 — pulls guest buffers out of the virtio device's TX virtqueue, builds host mbufs, copies the guest buffer content into those host mbufs, and stashes them in pkts so you can go process them.

  • vid — vhost device ID
  • queue_id — virtio queue index in mq case
  • mbuf_pool — mbuf_pool where host mbuf is allocated.
  • pkts — array to contain packets to be dequeued
  • count — packets num to be dequeued

Returns the num of packets dequeued.

int rte_vhost_get_mem_table (int vid, struct rte_vhost_memory ** mem)

Gets the guest mem table — literally just a list of memory regions 🗂️

An rte_vhost_vhost_memory object gets allocated internally to hold the guest memory regions. Heads up bestie: the application should free it at the destroy_device() callback. Don't leave it hanging 🙈

  • vid — vhost device ID
  • mem — to store the returned mem regions

Returns 0 on success, -1 on failure.

int rte_vhost_get_vhost_vring (int vid, uint16_t vring_idx, struct rte_vhost_vring * vring)

Gets all the guest vring info — the vring address, the vring size, the whole little package ✨

  • vid — vhost device ID
  • vring_idx — vring index
  • vring — the structure to hold the requested vring info

Returns 0 on success, -1 on failure.

int rte_vhost_get_vhost_ring_inflight (int vid, uint16_t vring_idx, struct rte_vhost_ring_inflight * vring)

Same but inflight-flavoured 🦋 — gets the guest inflight vring info, which includes the inflight ring and the resubmit list.

  • vid — vhost device ID
  • vring_idx — vring index
  • vring — the structure to hold the requested inflight vring info

Returns 0 on success, -1 on failure.

int rte_vhost_set_inflight_desc_split (int vid, uint16_t vring_idx, uint16_t idx)

Sets a split inflight descriptor. This function saves descriptors that have been consumed in the available ring 💾

  • vid — vhost device ID
  • vring_idx — vring index
  • idx — inflight entry index

Returns 0 on success, -1 on failure.

int rte_vhost_set_inflight_desc_packed (int vid, uint16_t vring_idx, uint16_t head, uint16_t last, uint16_t * inflight_entry)

Sets a packed inflight descriptor and grabs the corresponding inflight entry — two-for-one, we love efficiency 🎀 This function saves descriptors that have been consumed.

  • vid — vhost device ID
  • vring_idx — vring index
  • head — head of descriptors
  • last — last of descriptors
  • inflight_entry — corresponding inflight entry

Returns 0 on success, -1 on failure.

int rte_vhost_set_last_inflight_io_split (int vid, uint16_t vring_idx, uint16_t idx)

Saves the head of the list that the last batch of used descriptors points at 📌

  • vid — vhost device ID
  • vring_idx — vring index
  • idx — descriptor entry index

Returns 0 on success, -1 on failure.

int rte_vhost_set_last_inflight_io_packed (int vid, uint16_t vring_idx, uint16_t head)

Updates inflight free_head, used_idx and used_wrap_counter 💅 Note the ordering, bestie: it updates status first, before updating descriptors to used. Order matters, no cap.

  • vid — vhost device ID
  • vring_idx — vring index
  • head — head of descriptors

Returns 0 on success, -1 on failure.

int rte_vhost_clr_inflight_desc_split (int vid, uint16_t vring_idx, uint16_t last_used_idx, uint16_t idx)

Clears the split inflight status 🧹✨

  • vid — vhost device ID
  • vring_idx — vring index
  • last_used_idx — last used idx of used ring
  • idx — inflight entry index

Returns 0 on success, -1 on failure.

int rte_vhost_clr_inflight_desc_packed (int vid, uint16_t vring_idx, uint16_t head)

Clears the packed inflight status. Same cleansing energy, packed flavour 🫧

  • vid — vhost device ID
  • vring_idx — vring index
  • head — inflight entry index

Returns 0 on success, -1 on failure.

int rte_vhost_vring_call (int vid, uint16_t vring_idx)

Notifies the guest that used descriptors have been added to the vring 🔔 And important: this function acts as a memory barrier.

  • vid — vhost device ID
  • vring_idx — vring index

Returns 0 on success, -1 on failure.

int rte_vhost_vring_call_nonblock (int vid, uint16_t vring_idx)

Same notification business — tells the guest that used descriptors landed in the vring, and it acts as a memory barrier too 🔔 But this one's the nonblocking sibling: it returns -EAGAIN when vq's access lock is held by another thread, and then you should try again later. Polite queueing, honestly 💀

  • vid — vhost device ID
  • vring_idx — vring index

Returns 0 on success, -1 on failure, -EAGAIN for another retry.

uint32_t rte_vhost_rx_queue_count (int vid, uint16_t qid)

Gets the vhost RX queue avail count 📊

  • vid — vhost device ID
  • qid — virtio queue index in mq case

Returns the num of desc available.

int rte_vhost_get_monitor_addr (int vid, uint16_t queue_id, struct rte_vhost_power_monitor_cond * pmc)

Gets the power monitor address of the vhost device ⚡🌱

  • vid — vhost device ID
  • queue_id — vhost queue ID
  • pmc — power monitor condition

Returns 0 on success, -1 on failure.

int rte_vhost_get_log_base (int vid, uint64_t * log_base, uint64_t * log_size)

Gets the log base and the log size of the vhost device — the whole log situation 📝

  • vid — vhost device ID
  • log_base — vhost log base
  • log_size — vhost log size

Returns 0 on success, -1 on failure.

int rte_vhost_get_vring_base (int vid, uint16_t queue_id, uint16_t * last_avail_idx, uint16_t * last_used_idx)

Gets the last_avail/used_idx of the vhost virtqueue 🔍

  • vid — vhost device ID
  • queue_id — vhost queue index
  • last_avail_idx — vhost last_avail_idx to get
  • last_used_idx — vhost last_used_idx to get

Returns 0 on success, -1 on failure.

int rte_vhost_get_vring_base_from_inflight (int vid, uint16_t queue_id, uint16_t * last_avail_idx, uint16_t * last_used_idx)

Gets last_avail/last_used of the vhost virtqueue 🌀 This one is designed for the reconnection and it's specific for the packed ring, because we can get those two parameters from the inflight queueregion. Iykyk 💫

  • vid — vhost device ID
  • queue_id — vhost queue index
  • last_avail_idx — vhost last_avail_idx to get
  • last_used_idx — vhost last_used_idx to get

Returns 0 on success, -1 on failure.

int rte_vhost_set_vring_base (int vid, uint16_t queue_id, uint16_t last_avail_idx, uint16_t last_used_idx)

Sets the last_avail/used_idx of the vhost virtqueue ✍️ The setter to the getter above, we love a matched pair 🫶

  • vid — vhost device ID
  • queue_id — vhost queue index
  • last_avail_idx — last_avail_idx to set
  • last_used_idx — last_used_idx to set

Returns 0 on success, -1 on failure.

int rte_vhost_extern_callback_register (int vid, struct rte_vhost_user_extern_ops const *const ops, void * ctx)

Bestie, this is the “hook me up with external message handling callbacks” function. It registers external message handling callbacks. Slay.

Parameters

  • vid — vhost device ID
  • ops — virtio external callbacks to register
  • ctx — additional context passed to the callbacks

Returns

0 on success, -1 on failure. No cap.

struct rte_vdpa_device * rte_vhost_get_vdpa_device (int vid)

Grab the vdpa device id for a vhost device. It’s giving “find my vDPA bestie.”

Parameters

  • vid — vhost device id

Returns

vDPA device pointer on success, NULL on failure. 🫶

int rte_vhost_backend_config_change (int vid, bool need_reply)

Notify the guest that it should get virtio configuration space from the backend. Communication era 💅.

Parameters

  • vid — vhost device ID
  • need_reply — wait for the frontend response the status of this operation

Returns

0 on success, < 0 on failure.

int rte_vhost_vring_stats_get_names (int vid, uint16_t queue_id, struct rte_vhost_stat_name * name, unsigned int size)

Retrieve names of statistics of a Vhost virtqueue. Iconic little name-collector behavior.

There is an assumption that stat_names and stats arrays are matched by array index: stats_names[i].name => stats[i].value.

Parameters

  • vid — vhost device ID
  • queue_id — vhost queue index
  • name — array of at least size elements to be filled. If set to NULL, the function returns the required number of elements.
  • size — The number of elements in stats_names array.

Returns

  • Success if greater than 0 and lower or equal to size. The return value indicates the number of elements filled in the names array.
  • Failure if greater than size. The return value indicates the number of elements the names array that should be given to succeed.
  • Failure if lower than 0. The device ID or queue ID is invalid or
    • statistics collection is not enabled.

int rte_vhost_vring_stats_get (int vid, uint16_t queue_id, struct rte_vhost_stat * stats, unsigned int n)

Retrieve statistics of a Vhost virtqueue. This is the actual stats-haver of the situation.

There is an assumption that stat_names and stats arrays are matched by array index: stats_names[i].name => stats[i].value.

Parameters

  • vid — vhost device ID
  • queue_id — vhost queue index
  • stats — A pointer to a table of structure of type rte_vhost_stat to be filled with virtqueue statistics ids and values.
  • n — The number of elements in stats array.

Returns

  • Success if greater than 0 and lower or equal to n. The return value indicates the number of elements filled in the stats array.
  • Failure if greater than n. The return value indicates the number of elements the stats array that should be given to succeed.
  • Failure if lower than 0. The device ID or queue ID is invalid, or statistics collection is not enabled.

int rte_vhost_vring_stats_reset (int vid, uint16_t queue_id)

Reset statistics of a Vhost virtqueue. Clean-slate moment, we love a fresh start ✨.

Parameters

  • vid — vhost device ID
  • queue_id — vhost queue index

Returns

  • Success if 0. Statistics have been reset.
  • Failure if lower than 0. The device ID or queue ID is invalid, or statistics collection is not enabled.

✨ AUTHOR ✨

Generated automatically by Doxygen for DPDK from the source code.

Okay bestie, cute little footer sign-off: this page is from DPDK Version 26.03.0 and it’s rte_vhost.h(3) — and the date line is whatever Doxygen stamped down there, because that’s its main character moment. 🎀✨

📦 where this page comes from