DPDK: Data Plane Development Kit

18.02.0-rc0
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>

Go to the source code of this file.

Data Structures

struct  rte_vhost_mem_region
struct  rte_vhost_memory
struct  vhost_device_ops

Functions

static __rte_always_inline uint64_t rte_vhost_gpa_to_vva (struct rte_vhost_memory *mem, uint64_t gpa)
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)
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_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)
uint32_t rte_vhost_rx_queue_count (int vid, uint16_t qid)

Detailed Description

Interface to vhost-user

Definition in file rte_vhost.h.

Function Documentation

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

Parameters
memthe guest memory regions
gpathe guest physical address for querying
Returns
the host virtual address on success, 0 on failure
Examples:
examples/vhost/virtio_net.c, and examples/vhost_scsi/vhost_scsi.c.

Definition at line 128 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
vidvhost device ID
addrthe starting address for write
lenthe 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
vidvhost device ID
vring_idxthe vring index
offsetthe offset inside the used ring
lenthe length to write
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/vhost/main.c, and examples/vhost_scsi/vhost_scsi.c.
int rte_vhost_driver_set_features ( const char *  path,
uint64_t  features 
)

Set the feature bits the vhost-user driver supports.

Parameters
pathThe vhost-user socket file path
featuresSupported features
Returns
0 on success, -1 on failure
Examples:
examples/vhost/main.c, and examples/vhost_scsi/vhost_scsi.c.
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
pathThe vhost-user socket file path
featuresFeatures to enable
Returns
0 on success, -1 on failure
Examples:
examples/vhost/main.c.
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
pathThe vhost-user socket file path
featuresFeatures to disable
Returns
0 on success, -1 on failure
Examples:
examples/tep_termination/main.c, and examples/vhost/main.c.
int rte_vhost_driver_get_features ( const char *  path,
uint64_t *  features 
)

Get the feature bits before feature negotiation.

Parameters
pathThe vhost-user socket file path
featuresA pointer to store the queried feature bits
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
vidVhost device ID
featuresA pointer to store the queried feature bits
Returns
0 on success, -1 on failure
Examples:
examples/vhost/virtio_net.c.
int rte_vhost_driver_start ( const char *  path)

Start the vhost-user driver.

This function triggers the vhost-user negotiation.

Parameters
pathThe vhost-user socket file path
Returns
0 on success, -1 on failure
Examples:
examples/tep_termination/main.c, examples/vhost/main.c, and examples/vhost_scsi/vhost_scsi.c.
int rte_vhost_get_mtu ( int  vid,
uint16_t *  mtu 
)

Get the MTU value of the device if set in QEMU.

Parameters
vidvirtio-net device ID
mtuThe 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
vidvhost device ID
Returns
The numa node, -1 on failure
__rte_deprecated uint32_t rte_vhost_get_queue_num ( int  vid)

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
vidvhost device ID
Returns
The number of queues, 0 on failure
uint16_t rte_vhost_get_vring_num ( int  vid)

Get the number of vrings the device supports.

Parameters
vidvhost device ID
Returns
The number of vrings, 0 on failure
Examples:
examples/vhost/virtio_net.c, and examples/vhost_scsi/vhost_scsi.c.
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
vidvhost device ID
bufThe buffer to stored the queried ifname
lenThe length of buf
Returns
0 on success, -1 on failure
Examples:
examples/vhost_scsi/vhost_scsi.c.
uint16_t rte_vhost_avail_entries ( int  vid,
uint16_t  queue_id 
)

Get how many avail entries are left in the queue

Parameters
vidvhost device ID
queue_idvirtio queue index
Returns
num of avail entires left
Examples:
examples/tep_termination/main.c, and examples/vhost/main.c.
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
vidvhost device ID
queue_idvirtio queue index in mq case
pktsarray to contain packets to be enqueued
countpackets num to be enqueued
Returns
num of packets enqueued
Examples:
examples/tep_termination/vxlan_setup.c, and examples/vhost/main.c.
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
vidvhost device ID
queue_idvirtio queue index in mq case
mbuf_poolmbuf_pool where host mbuf is allocated.
pktsarray to contain packets to be dequeued
countpackets num to be dequeued
Returns
num of packets dequeued
Examples:
examples/tep_termination/main.c, and examples/vhost/main.c.
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 internaly, to hold the guest memory regions. Application should free it at destroy_device() callback.

Parameters
vidvhost device ID
memTo store the returned mem regions
Returns
0 on success, -1 on failure
Examples:
examples/vhost/virtio_net.c, and examples/vhost_scsi/vhost_scsi.c.
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
vidvhost device ID
vring_idxvring index
vringthe structure to hold the requested vring info
Returns
0 on success, -1 on failure
Examples:
examples/vhost/virtio_net.c, and examples/vhost_scsi/vhost_scsi.c.
uint32_t rte_vhost_rx_queue_count ( int  vid,
uint16_t  qid 
)

Get vhost RX queue avail count.

Parameters
vidvhost device ID
qidvirtio queue index in mq case
Returns
num of desc available