docs/reference/cmdreference/vhost/vhostuser.rst

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