rte_vhost.h File Reference

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

Go to the source code of this file.

Data Structures
struct	rte_vhost_mem_region
struct	rte_vhost_memory
struct	rte_vhost_user_extern_ops
struct	vhost_device_ops

Macros
#define	VHOST_USER_PROTOCOL_F_MQ   0
#define	VHOST_USER_F_PROTOCOL_FEATURES   30

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

Enumerations
enum	rte_vhost_msg_result

Functions
static __rte_deprecated __rte_always_inline uint64_t	rte_vhost_gpa_to_vva (struct rte_vhost_memory *mem, uint64_t gpa)
static __rte_experimental __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)
int	rte_vhost_driver_register (const char *path, uint64_t flags)
__rte_experimental int	rte_vhost_driver_attach_vdpa_device (const char *path, int did)
__rte_experimental int	rte_vhost_driver_detach_vdpa_device (const char *path)
__rte_experimental int	rte_vhost_driver_get_vdpa_device_id (const char *path)
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)
__rte_experimental int	rte_vhost_driver_set_protocol_features (const char *path, uint64_t protocol_features)
__rte_experimental int	rte_vhost_driver_get_protocol_features (const char *path, uint64_t *protocol_features)
__rte_experimental int	rte_vhost_driver_get_queue_num (const char *path, uint32_t *queue_num)
int	rte_vhost_get_negotiated_features (int vid, uint64_t *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)
__rte_deprecated uint32_t	rte_vhost_get_queue_num (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)
__rte_experimental int	rte_vhost_get_vhost_ring_inflight (int vid, uint16_t vring_idx, struct rte_vhost_ring_inflight *vring)
__rte_experimental int	rte_vhost_set_inflight_desc_split (int vid, uint16_t vring_idx, uint16_t idx)
__rte_experimental int	rte_vhost_set_inflight_desc_packed (int vid, uint16_t vring_idx, uint16_t head, uint16_t last, uint16_t *inflight_entry)
__rte_experimental int	rte_vhost_set_last_inflight_io_split (int vid, uint16_t vring_idx, uint16_t idx)
__rte_experimental int	rte_vhost_set_last_inflight_io_packed (int vid, uint16_t vring_idx, uint16_t head)
__rte_experimental int	rte_vhost_clr_inflight_desc_split (int vid, uint16_t vring_idx, uint16_t last_used_idx, uint16_t idx)
__rte_experimental 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)
uint32_t	rte_vhost_rx_queue_count (int vid, uint16_t qid)
__rte_experimental int	rte_vhost_get_log_base (int vid, uint64_t *log_base, uint64_t *log_size)
__rte_experimental int	rte_vhost_get_vring_base (int vid, uint16_t queue_id, uint16_t *last_avail_idx, uint16_t *last_used_idx)
__rte_experimental int	rte_vhost_get_vring_base_from_inflight (int vid, uint16_t queue_id, uint16_t *last_avail_idx, uint16_t *last_used_idx)
__rte_experimental int	rte_vhost_set_vring_base (int vid, uint16_t queue_id, uint16_t last_avail_idx, uint16_t last_used_idx)
__rte_experimental int	rte_vhost_extern_callback_register (int vid, struct rte_vhost_user_extern_ops const *const ops, void *ctx)
__rte_experimental int	rte_vhost_get_vdpa_device_id (int vid)

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 59 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 108 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 246 of file rte_vhost.h.

Enumeration Type Documentation

rte_vhost_msg_result

enum rte_vhost_msg_result

Possible results of the vhost user message handling callbacks

Definition at line 221 of file rte_vhost.h.

Function Documentation

rte_vhost_gpa_to_vva()

static __rte_deprecated __rte_always_inline uint64_t rte_vhost_gpa_to_vva ( struct rte_vhost_memory *  mem, uint64_t  gpa  )

static

Convert guest physical address to host virtual address

This function is deprecated because unsafe. New rte_vhost_va_from_guest_pa() should be used instead to ensure guest physical ranges are fully and contiguously mapped into process virtual address space.

Parameters

mem	the guest memory regions
gpa	the guest physical address for querying

Returns

the host virtual address on success, 0 on failure

Definition at line 306 of file rte_vhost.h.

rte_vhost_va_from_guest_pa()

static __rte_experimental __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 safely

This variant of rte_vhost_gpa_to_vva() takes care all the requested length is mapped and contiguous in process address space.

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

Examples:

examples/vhost/virtio_net.c, and examples/vhost_blk/vhost_blk.c.

Definition at line 341 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_driver_register()

int rte_vhost_driver_register	(	const char *	path,
		uint64_t	flags
	)

Register vhost driver. path could be different for multiple instance support.

Examples:

examples/tep_termination/main.c, examples/vdpa/main.c, examples/vhost/main.c, examples/vhost_blk/vhost_blk.c, and examples/vhost_crypto/main.c.

rte_vhost_driver_attach_vdpa_device()

__rte_experimental int rte_vhost_driver_attach_vdpa_device	(	const char *	path,
		int	did
	)

Set the vdpa device id, enforce single connection per socket

Parameters

path	The vhost-user socket file path
did	Device id

Returns

0 on success, -1 on failure

Examples:

examples/vdpa/main.c.

rte_vhost_driver_detach_vdpa_device()

__rte_experimental 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

Examples:

examples/vdpa/main.c.

rte_vhost_driver_get_vdpa_device_id()

__rte_experimental int rte_vhost_driver_get_vdpa_device_id

(

const char *

path

)

Get the device id

Parameters

path	The vhost-user socket file path

Returns

Device id, -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

Examples:

examples/vhost/main.c, and examples/vhost_blk/vhost_blk.c.

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

Examples:

examples/vhost/main.c.

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

Examples:

examples/tep_termination/main.c, and examples/vhost/main.c.

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

rte_vhost_driver_set_protocol_features()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk_compat.c.

rte_vhost_driver_get_protocol_features()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk_compat.c.

rte_vhost_driver_get_queue_num()

__rte_experimental 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

rte_vhost_get_negotiated_features()

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

Examples:

examples/vhost/virtio_net.c, and examples/vhost_blk/vhost_blk.c.

rte_vhost_driver_start()

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

Examples:

examples/tep_termination/main.c, examples/vdpa/main.c, examples/vhost/main.c, examples/vhost_blk/vhost_blk.c, and examples/vhost_crypto/main.c.

rte_vhost_get_mtu()

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

rte_vhost_get_numa_node()

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

rte_vhost_get_queue_num()

__rte_deprecated uint32_t rte_vhost_get_queue_num

(

int

vid

)

Deprecated:

Get the number of queues the device supports.

Note this function is deprecated, as it returns a queue pair number, which is vhost specific. Instead, rte_vhost_get_vring_num should be used.

Parameters

vid	vhost device ID

Returns

The number of queues, 0 on failure

rte_vhost_get_vring_num()

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

Examples:

examples/vhost/virtio_net.c.

rte_vhost_get_ifname()

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

Examples:

examples/vdpa/main.c, examples/vhost_blk/vhost_blk.c, examples/vhost_blk/vhost_blk_compat.c, and examples/vhost_crypto/main.c.

rte_vhost_avail_entries()

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

Examples:

examples/tep_termination/main.c.

rte_vhost_enqueue_burst()

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

Examples:

examples/tep_termination/vxlan_setup.c, and examples/vhost/main.c.

rte_vhost_dequeue_burst()

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

Examples:

examples/tep_termination/main.c, and examples/vhost/main.c.

rte_vhost_get_mem_table()

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

Examples:

examples/vhost/virtio_net.c, and examples/vhost_blk/vhost_blk.c.

rte_vhost_get_vhost_vring()

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

Examples:

examples/vhost/virtio_net.c, and examples/vhost_blk/vhost_blk.c.

rte_vhost_get_vhost_ring_inflight()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk.c.

rte_vhost_set_inflight_desc_split()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk.c.

rte_vhost_set_inflight_desc_packed()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk.c.

rte_vhost_set_last_inflight_io_split()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk.c.

rte_vhost_set_last_inflight_io_packed()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk.c.

rte_vhost_clr_inflight_desc_split()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk.c.

rte_vhost_clr_inflight_desc_packed()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk.c.

rte_vhost_vring_call()

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

Examples:

examples/vhost/virtio_net.c, and examples/vhost_blk/vhost_blk.c.

rte_vhost_rx_queue_count()

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

rte_vhost_get_log_base()

__rte_experimental 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

rte_vhost_get_vring_base()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk.c.

rte_vhost_get_vring_base_from_inflight()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk.c.

rte_vhost_set_vring_base()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk.c.

rte_vhost_extern_callback_register()

__rte_experimental 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

Examples:

examples/vhost_blk/vhost_blk_compat.c.

rte_vhost_get_vdpa_device_id()

__rte_experimental int rte_vhost_get_vdpa_device_id

(

int

vid

)

Get vdpa device id for vhost device.

Parameters

vid	vhost device id

Returns

device id