doc: doxygen documentation for vhost-user CLI Commmands (VPP-279)
Change-Id: I1f3cf7c786b0a86b56a1cd7d9650e446515f1504 Signed-off-by: Billy McFall <bmcfall@redhat.com>
This commit is contained in:
Billy McFall
27
vnet/vnet/devices/virtio/dir.dox
Normal file
27
vnet/vnet/devices/virtio/dir.dox
Normal file
@ -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 %% ?*/
|
||||
@ -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",
|
||||
|
||||
Reference in New Issue
Block a user