From: Billy McFall Date: Wed, 23 Nov 2016 17:45:29 +0000 (-0500) Subject: doc: doxygen documentation for vhost-user CLI Commmands (VPP-279) X-Git-Tag: v17.01-rc1~151 X-Git-Url: https://gerrit.fd.io/r/gitweb?a=commitdiff_plain;h=a92501ab703c3009cfdbc646cf8b46b228cfba45;p=vpp.git doc: doxygen documentation for vhost-user CLI Commmands (VPP-279) Change-Id: I1f3cf7c786b0a86b56a1cd7d9650e446515f1504 Signed-off-by: Billy McFall --- diff --git a/vnet/vnet/devices/virtio/dir.dox b/vnet/vnet/devices/virtio/dir.dox new file mode 100644 index 00000000000..50150799e62 --- /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 4c228633cd7..d008d387dd0 100644 --- a/vnet/vnet/devices/virtio/vhost-user.c +++ b/vnet/vnet/devices/virtio/vhost-user.c @@ -41,6 +41,14 @@ #include +/** + * @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 'VirtualEthernet0/0/x', where 'x' + * is the next free index. + * + * There are several parameters associated with a vHost interface: + * + * - socket - 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 - 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 - Optional ethernet address, can be in either + * X:X:X:X:X:X unix or X.X.X cisco format. + * + * - renumber - 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 [server] [feature-mask ] [renumber ]", + .short_help = "create vhost-user socket [server] [feature-mask ] [hwaddr ] [renumber ]", .function = vhost_user_connect_command_fn, }; +/* *INDENT-ON* */ +/*? + * Delete a vHost User interface using the interface name or the + * software interface index. Use the 'show interfaces' + * 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 ", + .short_help = "delete vhost-user { | sw_if_index }", .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 '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: + * @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 [ [ [..]]] [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 'del' option is used, + * the forced thread assignment is removed and the thread assigment is + * reassigned automatically. Use 'show vhost-user ' + * 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",