rte_vhost.h(3)

NAME
rte_vhost.h

SYNOPSIS

#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

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

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

  Typedefs

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

  Enumerations

enum rte_vhost_msg_result

  Functions

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

  #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

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

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.

  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

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

  int rte_vhost_driver_register (const char * path, uint64_t flags)
Register vhost driver. path could be different for multiple instance support.

  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

  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

  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

  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

  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

  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

  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

  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)
Set the protocol feature bits before feature negotiation.

Parameters
    path The vhost-user socket file path
    protocol_features Supported protocol features

Returns
    0 on success, -1 on failure

  int rte_vhost_driver_get_protocol_features (const char * path, uint64_t * protocol_features)
Get the protocol feature bits before feature negotiation.

Parameters
    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 before feature negotiation.

Parameters
    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)
Set the maximum number of queue pairs supported by the device. The value set is ignored for Vhost-user backends. It is only taken into account with VDUSE backends.

Parameters
    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

Parameters
    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)
Get the protocol feature bits after negotiation

Parameters
    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 function triggers the vhost-user negotiation.

Parameters
    path The vhost-user socket file path

Returns
    0 on success, -1 on failure

  int rte_vhost_get_mtu (int vid, uint16_t * mtu)
Get the MTU value of the device if set in QEMU.

Parameters
    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)
Get the numa node from which the virtio net device's memory is allocated.

Parameters
    vid vhost device ID

Returns
    The numa node, -1 on failure

  uint16_t rte_vhost_get_vring_num (int vid)
Get the number of vrings the device supports.

Parameters
    vid vhost device ID

Returns
    The number of vrings, 0 on failure

  int rte_vhost_get_ifname (int vid, char * buf, size_t len)
Get the virtio net device's ifname, which is the vhost-user socket file path.

Parameters
    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)
Get how many avail entries are left in the queue

Parameters
    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 function adds buffers to the virtio devices RX virtqueue. Buffers can be received from the physical port or from another virtual device. A packet count is returned to indicate the number of packets that were successfully added to the RX queue.

Parameters
    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)
This function gets guest buffers from the virtio device TX virtqueue, construct host mbufs, copies guest buffer content to host mbufs and store them in pkts to be processed.

Parameters
    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 guest mem table: a list of memory regions.

An rte_vhost_vhost_memory object will be allocated internally, to hold the guest memory regions. Application should free it at destroy_device() callback.

Parameters
    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, including the vring address, vring size, etc.

Parameters
    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, including inflight ring and resubmit list.

Parameters
    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 save descriptors that has been consumed in available ring

Parameters
    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 corresponding inflight entry

This function save descriptors that has been consumed

Parameters
    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)
Save the head of list that the last batch of used descriptors.

Parameters
    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)
Update the inflight free_head, used_idx and used_wrap_counter.

This function will update status first before updating descriptors to used

Parameters
    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.

Parameters
    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.

Parameters
    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. This function acts as a memory barrier.

Parameters
    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)
Notify the guest that used descriptors have been added to the vring. This function acts as a memory barrier. This function will return -EAGAIN when vq's access lock is held by other thread, user should try again later.

Parameters
    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 vhost RX queue avail count.

Parameters
    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 power monitor address of the vhost device

Parameters
    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 log base and log size of the vhost device

Parameters
    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 last_avail/used_idx of the vhost virtqueue

Parameters
    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 the reconnection and it's specific for the packed ring as we can get the two parameters from the inflight queueregion

Parameters
    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)
Set last_avail/used_idx of the vhost virtqueue

Parameters
    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)
Register external message handling callbacks

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

  struct rte_vdpa_device * rte_vhost_get_vdpa_device (int vid)
Get vdpa device id for vhost device.

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 should get virtio configuration space from backend.

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.

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.

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.

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.