FD.io VPP  v17.04-9-g99c0734
Vector Packet Processing
vHost User

create vhost-user

Summary/usage

create vhost-user socket <socket-filename> [server] [feature-mask <hex>] [hwaddr <mac-addr>] [renumber <dev_instance>] [mode {interrupt | polling}].

Description

Create a vHost User interface. Once created, a new virtual interface will exist with the name 'VirtualEthernet0/0/x', where 'x' is the next free index.

There are several parameters associated with a vHost interface:

  • socket <socket-filename> - Name of the linux socket used by QEMU/VM and VPP to manage the vHost interface. If socket does not already exist, VPP will create the socket.
  • server - Optional flag to indicate that VPP should be the server for the linux socket. If not provided, VPP will be the client.
  • feature-mask <hex> - Optional virtio/vhost feature set negotiated at startup. By default, all supported features will be advertised. Otherwise, provide the set of features desired.
    • 0x000008000 (15) - VIRTIO_NET_F_MRG_RXBUF
    • 0x000020000 (17) - VIRTIO_NET_F_CTRL_VQ
    • 0x000200000 (21) - VIRTIO_NET_F_GUEST_ANNOUNCE
    • 0x000400000 (22) - VIRTIO_NET_F_MQ
    • 0x004000000 (26) - VHOST_F_LOG_ALL
    • 0x008000000 (27) - VIRTIO_F_ANY_LAYOUT
    • 0x010000000 (28) - VIRTIO_F_INDIRECT_DESC
    • 0x040000000 (30) - VHOST_USER_F_PROTOCOL_FEATURES
    • 0x100000000 (32) - VIRTIO_F_VERSION_1
  • hwaddr <mac-addr> - Optional ethernet address, can be in either X:X:X:X:X:X unix or X.X.X cisco format.
  • renumber <dev_instance> - Optional parameter which allows the instance in the name to be specified. If instance already exists, name will be used anyway and multiple instances will have the same name. Use with caution.
  • mode [interrupt | polling] - Optional parameter specifying the input thread polling policy.
Example usage
Example of how to create a vhost interface with VPP as the client and all features enabled: 
vpp# create vhost-user socket /tmp/vhost1.sock
VirtualEthernet0/0/0
Example of how to create a vhost interface with VPP as the server and with just multiple queues enabled: 
vpp# create vhost-user socket /tmp/vhost2.sock server feature-mask 0x40400000
VirtualEthernet0/0/1
Once the vHost interface is created, enable the interface using: 
vpp# set interface state VirtualEthernet0/0/0 up

Declaration and implementation

Declaration: vhost_user_connect_command (src/vnet/devices/virtio/vhost-user.c line 3400)

Implementation: vhost_user_connect_command_fn.

delete vhost-user

Summary/usage

delete vhost-user {<interface> | sw_if_index <sw_idx>}.

Description

Delete a vHost User interface using the interface name or the software interface index. Use the 'show interface' command to determine the software interface index. On deletion, the linux socket will not be deleted.

Example usage
Example of how to delete a vhost interface by name: 
vpp# delete vhost-user VirtualEthernet0/0/1
 Example of how to delete a vhost interface by software interface index: 
vpp# delete vhost-user sw_if_index 1

Declaration and implementation

Declaration: vhost_user_delete_command (src/vnet/devices/virtio/vhost-user.c line 3422)

Implementation: vhost_user_delete_command_fn.

show vhost-user

Summary/usage

show vhost-user [<interface> [<interface> [..]]] [descriptors].

Description

Display the attributes of a single vHost User interface (provide interface name), multiple vHost User interfaces (provide a list of interface names seperated by spaces) or all Vhost User interfaces (omit an interface name to display all vHost interfaces).

Example usage

Example of how to display a vhost interface: 

vpp# show vhost-user VirtualEthernet0/0/0

Virtio vhost-user interfaces
Global:
  coalesce frames 32 time 1e-3
Interface: VirtualEthernet0/0/0 (ifindex 1)
virtio_net_hdr_sz 12
 features mask (0xffffffffffffffff):
 features (0x50408000):
   VIRTIO_NET_F_MRG_RXBUF (15)
   VIRTIO_NET_F_MQ (22)
   VIRTIO_F_INDIRECT_DESC (28)
   VHOST_USER_F_PROTOCOL_FEATURES (30)
  protocol features (0x3)
   VHOST_USER_PROTOCOL_F_MQ (0)
   VHOST_USER_PROTOCOL_F_LOG_SHMFD (1)

 socket filename /tmp/vhost1.sock type client errno "Success"

rx placement:
   thread 1 on vring 1
   thread 1 on vring 5
   thread 2 on vring 3
   thread 2 on vring 7
 tx placement: spin-lock
   thread 0 on vring 0
   thread 1 on vring 2
   thread 2 on vring 0

Memory regions (total 2)
region fd    guest_phys_addr    memory_size        userspace_addr     mmap_offset        mmap_addr
====== ===== ================== ================== ================== ================== ==================
  0     60    0x0000000000000000 0x00000000000a0000 0x00002aaaaac00000 0x0000000000000000 0x00002aab2b400000
  1     61    0x00000000000c0000 0x000000003ff40000 0x00002aaaaacc0000 0x00000000000c0000 0x00002aababcc0000

 Virtqueue 0 (TX)
  qsz 256 last_avail_idx 0 last_used_idx 0
  avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
  kickfd 62 callfd 64 errfd -1

 Virtqueue 1 (RX)
  qsz 256 last_avail_idx 0 last_used_idx 0
  avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
  kickfd 65 callfd 66 errfd -1

 Virtqueue 2 (TX)
  qsz 256 last_avail_idx 0 last_used_idx 0
  avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
  kickfd 63 callfd 70 errfd -1

 Virtqueue 3 (RX)
  qsz 256 last_avail_idx 0 last_used_idx 0
  avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
  kickfd 72 callfd 74 errfd -1

 Virtqueue 4 (TX disabled)
  qsz 256 last_avail_idx 0 last_used_idx 0
  avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
  kickfd 76 callfd 78 errfd -1

 Virtqueue 5 (RX disabled)
  qsz 256 last_avail_idx 0 last_used_idx 0
  avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
  kickfd 80 callfd 82 errfd -1

 Virtqueue 6 (TX disabled)
  qsz 256 last_avail_idx 0 last_used_idx 0
 avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
  kickfd 84 callfd 86 errfd -1

 Virtqueue 7 (RX disabled)
  qsz 256 last_avail_idx 0 last_used_idx 0
  avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
  kickfd 88 callfd 90 errfd -1



The optional 'descriptors' parameter will display the same output as the previous example but will include the descriptor table for each queue. The output is truncated below: 
vpp# show vhost-user VirtualEthernet0/0/0 descriptors
Virtio vhost-user interfaces
Global:
  coalesce frames 32 time 1e-3
Interface: VirtualEthernet0/0/0 (ifindex 1)
virtio_net_hdr_sz 12
 features mask (0xffffffffffffffff):
 features (0x50408000):
   VIRTIO_NET_F_MRG_RXBUF (15)
   VIRTIO_NET_F_MQ (22)
:
 Virtqueue 0 (TX)
  qsz 256 last_avail_idx 0 last_used_idx 0
  avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
  kickfd 62 callfd 64 errfd -1


  descriptor table:
   id          addr         len  flags  next      user_addr
  ===== ================== ===== ====== ===== ==================
  0     0x0000000010b6e974 2060  0x0002 1     0x00002aabbc76e974
  1     0x0000000010b6e034 2060  0x0002 2     0x00002aabbc76e034
  2     0x0000000010b6d6f4 2060  0x0002 3     0x00002aabbc76d6f4
  3     0x0000000010b6cdb4 2060  0x0002 4     0x00002aabbc76cdb4
  4     0x0000000010b6c474 2060  0x0002 5     0x00002aabbc76c474
  5     0x0000000010b6bb34 2060  0x0002 6     0x00002aabbc76bb34
  6     0x0000000010b6b1f4 2060  0x0002 7     0x00002aabbc76b1f4
  7     0x0000000010b6a8b4 2060  0x0002 8     0x00002aabbc76a8b4
  8     0x0000000010b69f74 2060  0x0002 9     0x00002aabbc769f74
  9     0x0000000010b69634 2060  0x0002 10    0x00002aabbc769634
  10    0x0000000010b68cf4 2060  0x0002 11    0x00002aabbc768cf4
:
  249   0x0000000000000000 0     0x0000 250   0x00002aab2b400000
  250   0x0000000000000000 0     0x0000 251   0x00002aab2b400000
  251   0x0000000000000000 0     0x0000 252   0x00002aab2b400000
  252   0x0000000000000000 0     0x0000 253   0x00002aab2b400000
  253   0x0000000000000000 0     0x0000 254   0x00002aab2b400000
  254   0x0000000000000000 0     0x0000 255   0x00002aab2b400000
  255   0x0000000000000000 0     0x0000 32768 0x00002aab2b400000


 Virtqueue 1 (RX)
  qsz 256 last_avail_idx 0 last_used_idx 0
:

 




Declaration and implementation


Declaration: show_vhost_user_command (src/vnet/devices/virtio/vhost-user.c line 3562)


Implementation: show_vhost_user_command_fn.



vhost thread


Summary/usage


vhost thread <iface> <worker-index> [del].

Description


This command is used to move the RX processing for the given interfaces to the provided thread. If the 'del' option is used, the forced thread assignment is removed and the thread assigment is reassigned automatically. Use 'show vhost-user <interface>' to see the thread assignment.


Example usage
Example of how to move the RX processing for a given interface to a given thread: 
vpp# vhost thread VirtualEthernet0/0/0 1
 Example of how to remove the forced thread assignment for a given interface: 
vpp# vhost thread VirtualEthernet0/0/0 1 del


Declaration and implementation


Declaration: vhost_user_thread_command (src/vnet/devices/virtio/vhost-user.c line 3663)


Implementation: vhost_thread_command_fn.