docs/reference/cmdreference/vhost/vhostuser.rst

   1 .. _vhostusercommands:
   2
   3 .. toctree::
   4
   5 .. _createvhostuser:
   6
   7 Create Vhost-User
   8 =================
   9
  10 Create a vHost User interface. Once created, a new virtual interface
  11 will exist with the name '*VirtualEthernet0/0/x*', where '*x*' is the
  12 next free index.
  13
  14 There are several parameters associated with a vHost interface:
  15
  16 -  **socket <socket-filename>** - Name of the linux socket used by
  17    hypervisor and VPP to manage the vHost interface. If in '*server*'
  18    mode, VPP will create the socket if it does not already exist. If in
  19    '*client*' mode, hypervisor will create the socket if it does not
  20    already exist. The VPP code is indifferent to the file location.
  21    However, if SELinux is enabled, then the socket needs to be created
  22    in '*/var/run/vpp/*'.
  23 -  **server** - Optional flag to indicate that VPP should be the server
  24    for the linux socket. If not provided, VPP will be the client. In
  25    '*server*' mode, the VM can be reset without tearing down the vHost
  26    Interface. In '*client*' mode, VPP can be reset without bringing down
  27    the VM and tearing down the vHost Interface.
  28 -  **feature-mask <hex>** - Optional virtio/vhost feature set negotiated
  29    at startup. **This is intended for degugging only.** It is
  30    recommended that this parameter not be used except by experienced
  31    users. By default, all supported features will be advertised.
  32    Otherwise, provide the set of features desired.
  33
  34    -  0x000008000 (15) - VIRTIO_NET_F_MRG_RXBUF
  35    -  0x000020000 (17) - VIRTIO_NET_F_CTRL_VQ
  36    -  0x000200000 (21) - VIRTIO_NET_F_GUEST_ANNOUNCE
  37    -  0x000400000 (22) - VIRTIO_NET_F_MQ
  38    -  0x004000000 (26) - VHOST_F_LOG_ALL
  39    -  0x008000000 (27) - VIRTIO_F_ANY_LAYOUT
  40    -  0x010000000 (28) - VIRTIO_F_INDIRECT_DESC
  41    -  0x040000000 (30) - VHOST_USER_F_PROTOCOL_FEATURES
  42    -  0x100000000 (32) - VIRTIO_F_VERSION_1
  43
  44 -  **hwaddr <mac-addr>** - Optional ethernet address, can be in either
  45    X:X:X:X:X:X unix or X.X.X cisco format.
  46 -  **renumber <dev_instance>** - Optional parameter which allows the
  47    instance in the name to be specified. If instance already exists,
  48    name will be used anyway and multiple instances will have the same
  49    name. Use with caution.
  50
  51
  52 Summary/Usage
  53 -------------
  54
  55 .. code-block:: shell
  56
  57     create vhost-user socket <socket-filename> [server] [feature-mask <hex>] [hwaddr <mac-addr>] [renumber <dev_instance>]
  58
  59
  60 Examples
  61 --------
  62
  63     Example of how to create a vhost interface with VPP as the client
  64     and all features enabled:
  65
  66 .. code-block:: console
  67
  68     vpp# create vhost-user socket /var/run/vpp/vhost1.sock
  69     VirtualEthernet0/0/0
  70
  71 Example of how to create a vhost interface with VPP as the server
  72 and with just multiple queues enabled:
  73
  74 .. code-block:: console
  75
  76     vpp# create vhost-user socket /var/run/vpp/vhost2.sock server feature-mask 0x40400000
  77     VirtualEthernet0/0/1
  78
  79 Once the vHost interface is created, enable the interface using:
  80
  81 .. code-block:: console
  82
  83     vpp# set interface state VirtualEthernet0/0/0 up
  84
  85 .. _showvhost:
  86
  87 Show Vhost-User
  88 ===============
  89
  90 Display the attributes of a single vHost User interface (provide
  91 interface name), multiple vHost User interfaces (provide a list of
  92 interface names seperated by spaces) or all Vhost User interfaces (omit
  93 an interface name to display all vHost interfaces).
  94
  95 Summary/Usage
  96 -------------
  97
  98 .. code-block:: shell
  99
 100     show vhost-user [<interface> [<interface> [..]]] [descriptors].
 101
 102 Examples
 103 --------
 104 Example of how to display a vhost interface:
 105
 106 .. code-block:: console
 107
 108     vpp# show vhost-user VirtualEthernet0/0/0
 109     Virtio vhost-user interfaces
 110     Global:
 111       coalesce frames 32 time 1e-3
 112     Interface: VirtualEthernet0/0/0 (ifindex 1)
 113     virtio_net_hdr_sz 12
 114      features mask (0xffffffffffffffff):
 115      features (0x50408000):
 116        VIRTIO_NET_F_MRG_RXBUF (15)
 117        VIRTIO_NET_F_MQ (22)
 118        VIRTIO_F_INDIRECT_DESC (28)
 119        VHOST_USER_F_PROTOCOL_FEATURES (30)
 120       protocol features (0x3)
 121        VHOST_USER_PROTOCOL_F_MQ (0)
 122        VHOST_USER_PROTOCOL_F_LOG_SHMFD (1)
 123
 124      socket filename /var/run/vpp/vhost1.sock type client errno "Success"
 125
 126     rx placement:
 127        thread 1 on vring 1
 128        thread 1 on vring 5
 129        thread 2 on vring 3
 130        thread 2 on vring 7
 131      tx placement: spin-lock
 132        thread 0 on vring 0
 133        thread 1 on vring 2
 134        thread 2 on vring 0
 135
 136     Memory regions (total 2)
 137     region fd    guest_phys_addr    memory_size        userspace_addr     mmap_offset        mmap_addr
 138     ====== ===== ================== ================== ================== ================== ==================
 139       0     60    0x0000000000000000 0x00000000000a0000 0x00002aaaaac00000 0x0000000000000000 0x00002aab2b400000
 140       1     61    0x00000000000c0000 0x000000003ff40000 0x00002aaaaacc0000 0x00000000000c0000 0x00002aababcc0000
 141
 142      Virtqueue 0 (TX)
 143       qsz 256 last_avail_idx 0 last_used_idx 0
 144       avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
 145       kickfd 62 callfd 64 errfd -1
 146
 147      Virtqueue 1 (RX)
 148       qsz 256 last_avail_idx 0 last_used_idx 0
 149       avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
 150       kickfd 65 callfd 66 errfd -1
 151
 152      Virtqueue 2 (TX)
 153       qsz 256 last_avail_idx 0 last_used_idx 0
 154       avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
 155       kickfd 63 callfd 70 errfd -1
 156
 157      Virtqueue 3 (RX)
 158       qsz 256 last_avail_idx 0 last_used_idx 0
 159       avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
 160       kickfd 72 callfd 74 errfd -1
 161
 162      Virtqueue 4 (TX disabled)
 163       qsz 256 last_avail_idx 0 last_used_idx 0
 164       avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
 165       kickfd 76 callfd 78 errfd -1
 166
 167      Virtqueue 5 (RX disabled)
 168       qsz 256 last_avail_idx 0 last_used_idx 0
 169       avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
 170       kickfd 80 callfd 82 errfd -1
 171
 172      Virtqueue 6 (TX disabled)
 173       qsz 256 last_avail_idx 0 last_used_idx 0
 174      avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
 175       kickfd 84 callfd 86 errfd -1
 176
 177      Virtqueue 7 (RX disabled)
 178       qsz 256 last_avail_idx 0 last_used_idx 0
 179       avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
 180       kickfd 88 callfd 90 errfd -1
 181
 182 The optional '*descriptors*' parameter will display the same output as the
 183 previous example but will include the descriptor table for each queue. The output is truncated below:
 184
 185 .. code-block:: console
 186
 187     vpp# show vhost-user VirtualEthernet0/0/0 descriptors
 188
 189     Virtio vhost-user interfaces
 190     Global:
 191       coalesce frames 32 time 1e-3
 192     Interface: VirtualEthernet0/0/0 (ifindex 1)
 193     virtio_net_hdr_sz 12
 194      features mask (0xffffffffffffffff):
 195      features (0x50408000):
 196        VIRTIO_NET_F_MRG_RXBUF (15)
 197        VIRTIO_NET_F_MQ (22)
 198     :
 199      Virtqueue 0 (TX)
 200       qsz 256 last_avail_idx 0 last_used_idx 0
 201       avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
 202       kickfd 62 callfd 64 errfd -1
 203
 204       descriptor table:
 205        id          addr         len  flags  next      user_addr
 206       ===== ================== ===== ====== ===== ==================
 207       0     0x0000000010b6e974 2060  0x0002 1     0x00002aabbc76e974
 208       1     0x0000000010b6e034 2060  0x0002 2     0x00002aabbc76e034
 209       2     0x0000000010b6d6f4 2060  0x0002 3     0x00002aabbc76d6f4
 210       3     0x0000000010b6cdb4 2060  0x0002 4     0x00002aabbc76cdb4
 211       4     0x0000000010b6c474 2060  0x0002 5     0x00002aabbc76c474
 212       5     0x0000000010b6bb34 2060  0x0002 6     0x00002aabbc76bb34
 213       6     0x0000000010b6b1f4 2060  0x0002 7     0x00002aabbc76b1f4
 214       7     0x0000000010b6a8b4 2060  0x0002 8     0x00002aabbc76a8b4
 215       8     0x0000000010b69f74 2060  0x0002 9     0x00002aabbc769f74
 216       9     0x0000000010b69634 2060  0x0002 10    0x00002aabbc769634
 217       10    0x0000000010b68cf4 2060  0x0002 11    0x00002aabbc768cf4
 218     :
 219       249   0x0000000000000000 0     0x0000 250   0x00002aab2b400000
 220       250   0x0000000000000000 0     0x0000 251   0x00002aab2b400000
 221       251   0x0000000000000000 0     0x0000 252   0x00002aab2b400000
 222       252   0x0000000000000000 0     0x0000 253   0x00002aab2b400000
 223       253   0x0000000000000000 0     0x0000 254   0x00002aab2b400000
 224       254   0x0000000000000000 0     0x0000 255   0x00002aab2b400000
 225       255   0x0000000000000000 0     0x0000 32768 0x00002aab2b400000
 226
 227      Virtqueue 1 (RX)
 228       qsz 256 last_avail_idx 0 last_used_idx 0
 229
 230
 231 Debug Vhost-User
 232 ================
 233 Turn on/off debug for vhost
 234
 235
 236 Summary/Usage
 237 -------------
 238
 239 .. code-block:: shell
 240
 241     debug vhost-user <on | off>.
 242
 243 Delete Vhost-User
 244 ========================
 245 Delete a vHost User interface using the interface name or the software
 246 interface index. Use the '*show interface*' command to determine the
 247 software interface index. On deletion, the linux socket will not be
 248 deleted.
 249
 250 Summary/Usage
 251 -------------
 252
 253 .. code-block:: shell
 254
 255     delete vhost-user {<interface> | sw_if_index <sw_idx>}.
 256
 257 Examples
 258 --------
 259 Example of how to delete a vhost interface by name:
 260
 261 .. code-block:: console
 262
 263     vpp# delete vhost-user VirtualEthernet0/0/1
 264
 265 Example of how to delete a vhost interface by software interface index:
 266
 267 .. code-block:: console
 268
 269     vpp# delete vhost-user sw_if_index 1