rte_vhost.h(3)

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

💖 rte_vhost.h(3) — Library Functions Manual 💖

okay bestie, welcome to the vhost-user chapter of your life. this is rte_vhost.h, and it's giving main character energy in DPDK. no cap.

✨ NAME ✨

rte_vhost.h — yes, that's the whole name, periodt.

🦋 SYNOPSIS 🦋

First, the includes. Don't skip a single one, iykyk:

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

Then we got the data structures, macros, typedefs, enumerations, and functions. Let's vibe through each.

💖 Data Structures 💖

  • 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

These are the structs you'll be passing around, bestie. Obsessed.

✨ Macros ✨

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

Macros, but make it fashion. 💅

🎀 Typedefs 🎀

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

This one's a function pointer typedef. The way it handles vhost user messages? iconic.

🌸 Enumerations 🌸

  • enum rte_vhost_msg_result

Just one enum here, but it's important, fr fr.

💅 Functions 💅

Here's the full lineup, no gatekeeping:

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)

That's a lot of functions, but we'll break them down below. Not me being obsessed with every single one. 🫶

💜 Detailed Description 💜

It's the interface to vhost-user. Literally. The definition is in file rte_vhost.h.

🔥 Macro Definition Documentation 🔥

#define VHOST_USER_PROTOCOL_F_MQ 0

Protocol features. Definition at line 65 of file rte_vhost.h.

#define VHOST_USER_F_PROTOCOL_FEATURES 30

Indicate whether protocol features negotiation is supported. Definition at line 118 of file rte_vhost.h.

#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. It's giving callback energy.

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) [static]

Convert guest physical address to host virtual address. slay.

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)

Log the memory write start with given address.

This function only need be invoked when the live migration starts. Therefore, we won't need call it at all in the most of time. For making the performance impact be minimum, it's suggested to do a 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)

Log the used ring update start at given offset.

Same as rte_vhost_log_write, it's suggested to do 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.

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

Register vhost driver. 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)

Set the vdpa device id, enforce 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)

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

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

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

Set the feature bits 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)

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

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

Get 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 this one sets the protocol feature bits 💅 and it has to happen before feature negotiation — like, before the whole handshake situation kicks off. Timing matters, bestie.

  • 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 lil sibling of the one above — instead of setting, you're getting 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)

get the queue number bits, and yep, before feature negotiation, same vibe 🎀

  • 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 maximum number of queue pairs supported by the device 👑

⚠️ heads up bestie: the value you set here gets ignored for Vhost-user backends. it is only taken into account with VDUSE backends. so don't come crying to me when your vhost-user backend doesn't care 💀
  • 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)

get the feature bits after negotiation. negotiation's over, the deal is done, this is the tea 🍵

  • 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 protocol feature bits, and again after negotiation 🌈

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

start the vhost-user driver 🚀 — this is the function that triggers the vhost-user negotiation. main character moment fr.

  • 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 was set in QEMU. conditional king 👑

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

Returns:

  • 0 — success 💖
  • -EAGAIN — device not yet started (give it a sec, bestie)
  • -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, -1 on failure

uint16_t rte_vhost_get_vring_num(int vid)

how many vrings does the device support? let's find out 🎀

  • vid — vhost device ID

Returns: the number of vrings, 0 on failure

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

gets the virtio net device's ifname — which, plot twist, 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 left in the queue 👀

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

Returns: 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 — no judgement. it hands you back a packet count so you know how many packets actually made it successfully into the RX queue ✨

  • 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: 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 trick 💫 this grabs guest buffers from the virtio device's TX virtqueue, constructs host mbufs, copies the guest buffer content over to those host mbufs, and stores them in pkts so you can go process them. it's giving ✨move the data✨

  • 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: num of packets dequeued

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

get the guest mem table: a list of memory regions 🗺️

💀 IMPORTANT bestie: an rte_vhost_vhost_memory object will be allocated internally to hold the guest memory regions. your application should free it at the destroy_device() callback. do not forget. do not be that person.
  • 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)

get guest vring info — the vring address, vring size, etc. all the vring lore 💅

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

get guest inflight vring info, which means 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)

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

set packed inflight descriptor and get the corresponding inflight entry — two birds, one function 🦋

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 👑

  • 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 the inflight free_head, used_idx and used_wrap_counter 🔄

note bestie: this function will update 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)

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

clear the packed inflight status 🧹🎀

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

notify the guest that used descriptors have been added to the vring 📣 — so basically you're like "hey bestie, new stuff in the ring" 🫶

this function also acts as a memory barrier. respect the 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 energy — tells the guest used descriptors got added to the vring, and it also acts as a memory barrier 🧠✨

BUT: this one will return -EAGAIN when vq's access lock is held by another thread, and in that case you should try again later. don't spam it, just circle back 💅
  • 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)

get the vhost RX queue avail count 👀

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

Returns: num of desc available

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

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

get the log base and log size of the vhost device 📜

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

get the last_avail_idx/last_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)

get last_avail/last_used of the vhost virtqueue 🌈

this function is designed for reconnection, and it's specific for the packed ring, because we can get the two parameters from the inflight queue region 💫

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

and now the setter version — set the last_avail_idx/last_used_idx of the vhost virtqueue 👑

  • 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

✨ rte_vhost_extern_callback_register ✨

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

okay so bestie, this one is literally how you sign up your own external message handling callbacks 💅 like, you're telling vhost "hey, when messages come through, pls also let me have a lil say."

Parameters

  • vid — the vhost device ID (iykyk, it's always the device ID 🫶)
  • ops — the virtio external callbacks you wanna register, of type struct rte_vhost_user_extern_ops const *const
  • ctx — extra context that gets handed off to those callbacks, so your functions can actually know what's going on

Returns

  • 0 on success 🎀
  • -1 on failure 😭

🦋 rte_vhost_get_vdpa_device 🦋

struct rte_vdpa_device * rte_vhost_get_vdpa_device (int vid)

Get the vdpa device id for a vhost device. basically "which vDPA device is this vhost device vibing as?" ✨

Parameters

  • vid — vhost device id

Returns

  • a vDPA device pointer on success 👑
  • NULL on failure 💀

🌸 rte_vhost_backend_config_change 🌸

int rte_vhost_backend_config_change (int vid, bool need_reply)

Notify the guest that it should get virtio configuration space from the backend. like sending a lil "hey girl, the config space is over here now" text 💌

Parameters

  • vid — vhost device ID
  • need_reply — wait for the frontend's response about the status of this operation (so yes, you can wait for the read receipt 🙈)

Returns

  • 0 on success
  • < 0 on failure

🌈 rte_vhost_vring_stats_get_names 🌈

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

Retrieve the names of a Vhost virtqueue's statistics. label szn ✨

Heads up bestie: there's an assumption baked in here that stat_names and stats arrays are matched by array index, like stats_names[i].name => stats[i].value. no cap, it's positional.

Parameters

  • vid — vhost device ID
  • queue_id — vhost queue index
  • name — array of at least size elements to be filled. If you set it to NULL, the function just returns the required number of elements instead (so you can ask "how many do I even need?" first, iconic)
  • size — the number of elements in the stats_names array

Returns

  • Success if it's greater than 0 and lower or equal to size. The return value tells you the number of elements filled in the names array 🎉
  • Failure if it's greater than size. The return value tells you the number of elements the names array should be given to succeed.
  • Failure if it's lower than 0. Either the device ID or queue ID is invalid, or statistics collection is not enabled 💀

💜 rte_vhost_vring_stats_get 💜

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

Retrieve the statistics of a Vhost virtqueue. the actual numbers, the receipts, the data 📊

Same assumption as above bestie: stat_names and stats arrays are matched by array index — stats_names[i].name => stats[i].value. it's giving positional matching.

Parameters

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

Returns

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

🧚 rte_vhost_vring_stats_reset 🧚

int rte_vhost_vring_stats_reset (int vid, uint16_t queue_id)

Reset the statistics of a Vhost virtqueue. clean slate energy 🌸 fresh start, we love to see it.

Parameters

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

Returns

  • Success if 0. The statistics have been reset 🎀
  • Failure if it's lower than 0. Either 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.

no thoughts, just a robot writing docs for us, and honestly? it ate 🤖✨

and that's a wrap on the whole page bestie!! this iconic lil doc lives in DPDK, Version 25.11.3, filed under rte_vhost.h(3) 💖 go forth, build your vhost stuff, and slay 🫶 periodt 💅

📦 where this page comes from