doc: doxygen documentation for vhost-user CLI Commmands (VPP-279)

Change-Id: I1f3cf7c786b0a86b56a1cd7d9650e446515f1504
Signed-off-by: Billy McFall <bmcfall@redhat.com>

2 files changed, 246 insertions, 3 deletions

diff --git a/vnet/vnet/devices/virtio/dir.dox b/vnet/vnet/devices/virtio/dir.dox
new file mode 100644
index 00000000..50150799
--- /dev/null
+++ b/vnet/vnet/devices/virtio/dir.dox
@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2016 Cisco and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at:
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/* Doxygen directory documentation */
+
+/**
+@dir
+@brief vHost User Interface Implementation.
+
+This directory contains the source code for vHost User driver.
+
+*/
+/*? %%clicmd:group_label vHost User %% ?*/
+/*? %%syscfg:group_label vHost User %% ?*/
diff --git a/vnet/vnet/devices/virtio/vhost-user.c b/vnet/vnet/devices/virtio/vhost-user.c
index 4c228633..d008d387 100644
--- a/vnet/vnet/devices/virtio/vhost-user.c
+++ b/vnet/vnet/devices/virtio/vhost-user.c
@@ -41,6 +41,14 @@
 
 #include <vnet/devices/virtio/vhost-user.h>
 
+/**
+ * @file
+ * @brief vHost User Device Driver.
+ *
+ * This file contains the source code for vHost User interface.
+ */
+
+
 #define VHOST_USER_DEBUG_SOCKET 0
 #define VHOST_DEBUG_VQ 0
 
@@ -2870,22 +2878,217 @@ done:
  * CLI functions
  */
 
+/*?
+ * Create a vHost User interface. Once created, a new virtual interface
+ * will exist with the name '<em>VirtualEthernet0/0/x</em>', where '<em>x</em>'
+ * is the next free index.
+ *
+ * There are several parameters associated with a vHost interface:
+ *
+ * - <b>socket <socket-filename></b> - 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.
+ *
+ * - <b>server</b> - Optional flag to indicate that VPP should be the server for the
+ * linux socket. If not provided, VPP will be the client.
+ *
+ * - <b>feature-mask <hex></b> - 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
+ *
+ * - <b>hwaddr <mac-addr></b> - Optional ethernet address, can be in either
+ * X:X:X:X:X:X unix or X.X.X cisco format.
+ *
+ * - <b>renumber <dev_instance></b> - 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.
+ *
+ * @cliexpar
+ * Example of how to create a vhost interface with VPP as the client and all features enabled:
+ * @cliexstart{create vhost-user socket /tmp/vhost1.sock}
+ * VirtualEthernet0/0/0
+ * @cliexend
+ * Example of how to create a vhost interface with VPP as the server and with just
+ * multiple queues enabled:
+ * @cliexstart{create vhost-user socket /tmp/vhost2.sock server feature-mask 0x40400000}
+ * VirtualEthernet0/0/1
+ * @cliexend
+ * Once the vHost interface is created, enable the interface using:
+ * @cliexcmd{set interface state VirtualEthernet0/0/0 up}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (vhost_user_connect_command, static) = {
     .path = "create vhost-user",
-    .short_help = "create vhost-user socket <socket-filename> [server] [feature-mask <hex>] [renumber <dev_instance>]",
+    .short_help = "create vhost-user socket <socket-filename> [server] [feature-mask <hex>] [hwaddr <mac-addr>] [renumber <dev_instance>]",
     .function = vhost_user_connect_command_fn,
 };
+/* *INDENT-ON* */
 
+/*?
+ * Delete a vHost User interface using the interface name or the
+ * software interface index. Use the '<em>show interfaces</em>'
+ * command to determine the software interface index. On deletion,
+ * the linux socket will not be deleted.
+ *
+ * @cliexpar
+ * Example of how to delete a vhost interface by name:
+ * @cliexcmd{delete vhost-user VirtualEthernet0/0/1}
+ * Example of how to delete a vhost interface by software interface index:
+ * @cliexcmd{delete vhost-user sw_if_index 1}
+?*/
+/* *INDENT-OFF* */
 VLIB_CLI_COMMAND (vhost_user_delete_command, static) = {
     .path = "delete vhost-user",
-    .short_help = "delete vhost-user sw_if_index <nn>",
+    .short_help = "delete vhost-user {<interface> | sw_if_index <sw_idx>}",
     .function = vhost_user_delete_command_fn,
 };
 
+/*?
+ * 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).
+ *
+ * @cliexpar
+ * @parblock
+ * Example of how to display a vhost interface:
+ * @cliexstart{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
+ *
+ * @cliexend
+ *
+ * The optional '<em>descriptors</em>' parameter will display the same output as
+ * the previous example but will include the descriptor table for each queue.
+ * The output is truncated below:
+ * @cliexstart{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
+ * :
+ * @cliexend
+ * @endparblock
+?*/
+/* *INDENT-OFF* */
 VLIB_CLI_COMMAND (show_vhost_user_command, static) = {
     .path = "show vhost-user",
-    .short_help = "show vhost-user interface",
+    .short_help = "show vhost-user [<interface> [<interface> [..]]] [descriptors]",
     .function = show_vhost_user_command_fn,
 };
 /* *INDENT-ON* */
@@ -2963,6 +3166,19 @@ vhost_thread_command_fn (vlib_main_t * vm,
 }
 
 
+/*?
+ * This command is used to move the RX processing for the given
+ * interfaces to the provided thread. If the '<em>del</em>' option is used,
+ * the forced thread assignment is removed and the thread assigment is
+ * reassigned automatically. Use '<em>show vhost-user <interface></em>'
+ * to see the thread assignment.
+ *
+ * @cliexpar
+ * Example of how to move the RX processing for a given interface to a given thread:
+ * @cliexcmd{vhost thread VirtualEthernet0/0/0 1}
+ * Example of how to remove the forced thread assignment for a given interface:
+ * @cliexcmd{vhost thread VirtualEthernet0/0/0 1 del}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (vhost_user_thread_command, static) = {
     .path = "vhost thread",