docs: better docs, mv doxygen to sphinx

This patch refactors the VPP sphinx docs
in order to make it easier to consume
for external readers as well as VPP developers.

It also makes sphinx the single source
of documentation, which simplifies maintenance
and operation.

Most important updates are:

- reformat the existing documentation as rst
- split RELEASE.md and move it into separate rst files
- remove section 'events'
- remove section 'archive'
- remove section 'related projects'
- remove section 'feature by release'
- remove section 'Various links'
- make (Configuration reference, CLI docs,
  developer docs) top level items in the list
- move 'Use Cases' as part of 'About VPP'
- move 'Troubleshooting' as part of 'Getting Started'
- move test framework docs into 'Developer Documentation'
- add a 'Contributing' section for gerrit,
  docs and other contributer related infos
- deprecate doxygen and test-docs targets
- redirect the "make doxygen" target to "make docs"

Type: refactor

Change-Id: I552a5645d5b7964d547f99b1336e2ac24e7c209f
Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
Signed-off-by: Andrew Yourtchenko <ayourtch@gmail.com>

14 files changed, 0 insertions, 1561 deletions

diff --git a/docs/reference/cmdreference/index.rst b/docs/reference/cmdreference/index.rst
deleted file mode 100644
index c791992f779..00000000000
--- a/docs/reference/cmdreference/index.rst
+++ /dev/null
@@ -1,57 +0,0 @@
-.. _cmdreference:
-
-
-Useful Debug CLI
-==================
-
-This is a reference guide for the vpp debug commands that are referenced within these documents. This is **NOT** a complete list. For a complete list refer to the Debug CLI section of the
-`Source Code Documents <https://docs.fd.io/vpp/18.07/clicmd.html>`_.
-
-The debug CLI can be executed from a su (superuser) shell using the vppctl command.
-
-.. code-block:: console
-
-    # sudo bash
-    # vppctl show interface
-
-                  Name               Idx       State          Counter          Count
-    TenGigabitEthernet86/0/0          1         up       rx packets               6569213
-                                                         rx bytes              9928352943
-                                                         tx packets                 50384
-                                                         tx bytes                 3329279
-    TenGigabitEthernet86/0/1          2        down
-    VirtualEthernet0/0/0              3         up       rx packets                 50384
-                                                         rx bytes                 3329279
-                                                         tx packets               6569213
-                                                         tx bytes              9928352943
-                                                         drops                       1498
-    local0                            0        down
-
-Commands can also be executed from the vppctl shell.
-
-.. code-block:: console
-
-    # vppctl
-
-    vpp# show interface
-                  Name               Idx       State          Counter          Count
-    TenGigabitEthernet86/0/0          1         up       rx packets               6569213
-                                                         rx bytes              9928352943
-                                                         tx packets                 50384
-                                                         tx bytes                 3329279
-    TenGigabitEthernet86/0/1          2        down
-    VirtualEthernet0/0/0              3         up       rx packets                 50384
-                                                         rx bytes                 3329279
-                                                         tx packets               6569213
-                                                         tx bytes              9928352943
-                                                         drops                       1498
-    local0                            0        down
-
-.. toctree::
-   :maxdepth: 3
-
-   interface/index.rst
-   ip/index.rst
-   show/index.rst
-   trace/index.rst
-   vhost/index.rst
diff --git a/docs/reference/cmdreference/interface/basic.rst b/docs/reference/cmdreference/interface/basic.rst
deleted file mode 100644
index 9848005502e..00000000000
--- a/docs/reference/cmdreference/interface/basic.rst
+++ /dev/null
@@ -1,89 +0,0 @@
-.. _interface:
-
-.. toctree::
-
-Basic Interface Commands
-=========================
-
-There are several commands that are associated to Basic Interface:
-
-* `Show Interface`_
-* `Clear Interfaces`_
-
-.. 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>`_ .
-
-.. _showintcommand:
-
-Show Interface
-++++++++++++++++
-Shows software interface information including counters and features.
-
-Summary/Usage
--------------
-
-.. code-block:: shell
-
-    show interface [address|addr|features|feat] [<interface> [<interface> [..]]]
-
-Examples
---------
-
-Example of how to show the interface counters:
-
-.. code-block:: console
-
-    vpp# show int
-                  Name               Idx       State          Counter          Count
-    TenGigabitEthernet86/0/0          1         up       rx packets               6569213
-                                                         rx bytes              9928352943
-                                                         tx packets                 50384
-                                                         tx bytes                 3329279
-    TenGigabitEthernet86/0/1          2        down
-    VirtualEthernet0/0/0              3         up       rx packets                 50384
-                                                         rx bytes                 3329279
-                                                         tx packets               6569213
-                                                         tx bytes              9928352943
-                                                         drops                       1498
-    local0                            0        down
-
-Example of how to display the interface placement:
-
-.. code-block:: console
-
-    vpp# show interface rx-placement
-    Thread 1 (vpp_wk_0):
-      node dpdk-input:
-        GigabitEthernet7/0/0 queue 0 (polling)
-      node vhost-user-input:
-        VirtualEthernet0/0/12 queue 0 (polling)
-        VirtualEthernet0/0/12 queue 2 (polling)
-        VirtualEthernet0/0/13 queue 0 (polling)
-        VirtualEthernet0/0/13 queue 2 (polling)
-    Thread 2 (vpp_wk_1):
-      node dpdk-input:
-        GigabitEthernet7/0/1 queue 0 (polling)
-      node vhost-user-input:
-        VirtualEthernet0/0/12 queue 1 (polling)
-        VirtualEthernet0/0/12 queue 3 (polling)
-        VirtualEthernet0/0/13 queue 1 (polling)
-        VirtualEthernet0/0/13 queue 3 (polling)
-
-Clear Interfaces
-+++++++++++++++++
-Clear the statistics for all interfaces (statistics associated with the
-'*show interface*' command).
-
-Summary/Usage
--------------
-
-.. code-block:: shell
-
-    clear interfaces
-
-Example
--------
-Example of how to clear the statistics for all interfaces:
-
-.. code-block:: console
-
-    vpp# clear interfaces
diff --git a/docs/reference/cmdreference/interface/create_interface.rst b/docs/reference/cmdreference/interface/create_interface.rst
deleted file mode 100644
index fa50c6a626c..00000000000
--- a/docs/reference/cmdreference/interface/create_interface.rst
+++ /dev/null
@@ -1,224 +0,0 @@
-.. _interface:
-
-.. toctree::
-
-Create Interfaces Commands
-===========================
-This section contains those interface commands that are associated to creating an interface:
-
-* `Create Host-Interface`_
-* `Create Interface Memif`_
-* `Create Loopback Interface`_
-* `Create Sub-Interfaces`_
-
-.. 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>`_ .
-
-Create Host-Interface
-++++++++++++++++++++++
-Summary/Usage
--------------
-
-create host-interface name <*ifname*> [*hw-addr <*mac-addr*>]
-
-Description
-------------
-
-Create a host interface that will attach to a linux AF_PACKET interface, one side of a veth pair.
-The veth pair must already exist. Once created, a new host interface will exist in VPP with the name
-'host-<*ifname*>', where '<*ifname*>' is the name of the specified veth pair.
-Use the `show interface` command to display host interface details.
-
-This command has the following optional parameters:
-
-    hw-addr <*mac-addr*> - Optional ethernet address, can be in either X:X:X:X:X:X unix or X.X.X cisco format
-
-Example Usage
--------------
-
-Example of how to create a host interface tied to one side of an existing linux veth pair named vpp1:
-
-	.. code-block:: console
-
-		vpp# create host-interface name vpp1
-
-		host-vpp1
-
-Once the host interface is created, enable the interface using:
-
-	.. code-block:: console
-
-		vpp# set interface state host-vpp1 up
-
-Declaration and Implementation
--------------------------------
-
-**Declaration:** af_packet_create_command (src/vnet/devices/af_packet/cli.c line 133)
-
-**Implementation:** af_packet_create_command_fn
-
-Create Interface Memif
-+++++++++++++++++++++++
-
-Summary/Usage
--------------
-
-create interface memif [id <*id*>] [socket-id <*socket-id*>] [ring-size <*size*>] [buffer-size <*size*>] [hw-addr <*mac-address*>] <master|slave> [rx-queues <*number*>] [tx-queues <*number*>] [mode ip] [secret <*string*>]
-
-Declaration and Implementation
--------------------------------
-
-**Declaration:** memif_create_command (src/plugins/memif/cli.c line 258)
-
-**Implementation:** memif_create_command_fn
-
-
-Create Loopback Interface
-++++++++++++++++++++++++++
-
-Summary/Usage
---------------
-
-create loopback interface [mac <*mac-addr*>] [instance <*instance*>]
-
-Description
-------------
-
-Create a loopback interface. Optionally, a MAC Address can be provided. If not provided, de:ad:00:00:00:<*loopId*> will be used.
-
-Example Usage
---------------
-The following two command syntaxes are equivalent:
-
-	.. code-block:: console
-
-		vpp# loopback create-interface [mac <*mac-addr*>] [instance <*instance*>]
-
-		vpp# create loopback interface [mac <*mac-addr*>] [instance <*instance*>]
-
-Example of how to create a loopback interface:
-
-	.. code-block:: console
-
-		vpp# create loopback interface
-
-Declaration and Implementation
--------------------------------
-
-**Declaration:** create_loopback_interface_command (src/vnet/ethernet/interface.c line 879)
-
-**Implementation:** create_simulated_ethernet_interfaces
-
-
-Create Sub-Interfaces
-++++++++++++++++++++++
-
-This command is used to add VLAN IDs to interfaces, also known as
-subinterfaces. The primary input to this command is the *interface*
-and *subId* (subinterface Id) parameters. If no additional VLAN ID is
-provide, the VLAN ID is assumed to be the *subId*. The VLAN ID and
-*subId* can be different, but this is not recommended.
-
-This command has several variations: 
-
--  **create sub-interfaces** <*interface*> <*subId*> - Create a subinterface
-   to process packets with a given 802.1q VLAN ID (same value as the
-   *subId*).
--  **create sub-interfaces** <*interface*> <*subId*> default - Adding the
-   *default* parameter indicates that packets with VLAN IDs that do
-   not match any other subinterfaces should be sent to this
-   subinterface.
--  **create sub-interfaces** <*interface*> <*subId*> untagged - Adding the
-   *untagged* parameter indicates that packets no VLAN IDs should be
-   sent to this subinterface.
--  **create sub-interfaces** <*interface*> <*subId*>-<*subId*> - Create a
-   range of subinterfaces to handle a range of VLAN IDs.
--  **create sub-interfaces** <*interface*> <*subId*> dot1q|dot1ad <*vlanId*>|any
-   [exact-match] - Use this command to explicitly specify the outer VLAN ID,
-   or to make the VLAN ID different from the *subId*.
--  **create sub-interfaces** <*interface*> <*subId*> dot1q|dot1ad <*vlanId*>|any
-   inner-dot1q <*vlanId*>|any [exact-match] - Use this command to
-   specify the outer VLAN ID and the inner VLAN ID.
-
-When *dot1q* or *dot1ad* is explicitly entered, subinterfaces can be
-configured as either *exact-match* or *non-exact match*. *Non-exact match* is
-the CLI default. If *exact-match* is specified, packets must have the
-same number of VLAN tags as the configuration. For *non-exact-match*,
-packets must at least that number of tags. L3 (routed) interfaces must
-be configured as exact-match. L2 interfaces are typically configured as
-non-exact-match. If *dot1q* or *dot1ad* is NOT entered, then the
-default behavior is *exact-match*.
-
-Use the **show interface** command to display all subinterfaces.
-
-Summary/Usage
--------------
-
-.. code-block:: shell
-
-    create sub-interfaces <interface> {<subId> [default|untagged]} | {<subId>-<subId>} | {<subId> dot1q|dot1ad <vlanId>|any [inner-dot1q <vlanId>|any] [exact-match]}
-
-Example Usage
---------------
-
-Example of how to create a VLAN subinterface 11 to process packets on 802.1q VLAN ID 11:
-
-.. code-block:: console
-
-    vpp# create sub-interfaces GigabitEthernet2/0/0 11
-
-The previous example is shorthand and is equivalent to:
-
-.. code-block:: console
-
-    vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 11 exact-match
-
-Example of how to create a subinterface number that is different from the VLAN ID:
-
-.. code-block:: console
-
-    vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100
-
-Examples of how to create q-in-q and q-in-any subinterfaces:
-
-.. code-block:: console
-
-    vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100 inner-dot1q 200
-    vpp# create sub-interfaces GigabitEthernet2/0/0 12 dot1q 100 inner-dot1q any
-
-Examples of how to create dot1ad interfaces:
-
-.. code-block:: console
-
-    vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1ad 11
-    vpp# create sub-interfaces GigabitEthernet2/0/0 12 dot1ad 100 inner-dot1q 200
-
-Examples of *exact-match* versus non-exact match. A packet with outer VLAN 100 and inner VLAN 200 would match this interface, because the default is non-exact match:
-
-.. code-block:: console
-
-    vpp# create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100
-
-However, the same packet would NOT match this interface because *exact-match* is specified and only one VLAN is configured, but packet contains two VLANs:
-
-.. code-block:: console
-
-    vpp# create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100 exact-match
-
-Example of how to created a subinterface to process untagged packets:
-
-.. code-block:: console
-
-   vpp# create sub-interfaces GigabitEthernet2/0/0 5 untagged
-
-Example of how to created a subinterface to process any packet with a VLAN ID that does not match any other subinterface:
-
-.. code-block:: console
-
-    vpp# create sub-interfaces GigabitEthernet2/0/0 7 default
-
-When subinterfaces are created, they are in the down state. Example of how to enable a newly created subinterface:
-
-.. code-block:: console
-
-    vpp# set interface GigabitEthernet2/0/0.7 up
-        
diff --git a/docs/reference/cmdreference/interface/hardware.rst b/docs/reference/cmdreference/interface/hardware.rst
deleted file mode 100644
index 2c28d655c4a..00000000000
--- a/docs/reference/cmdreference/interface/hardware.rst
+++ /dev/null
@@ -1,167 +0,0 @@
-.. _interface:
-
-.. toctree::
-
-Hardware-Interfaces Commands
-============================
-This section contains those interface commands that are related to hardware-interfaces: 
-
-
-* `Show Bridge-Domain`_
-* `Show Hardware-Interfaces`_
-* `Clear Hardware-Interfaces`_
-
-.. 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>`_ .
-
-Show Bridge-Domain
-+++++++++++++++++++
-
-Summary/Usage
--------------
-
-show bridge-domain [*bridge-domain-id* [detail|int|arp| *bd-tag* ]]
-
-Description
------------
-
-Show a summary of all the bridge-domain instances or detailed view of a single bridge-domain.
-Bridge-domains are created by adding an interface to a bridge using the **set interface l2 bridge** command.
-
-Example Usage
--------------
-.. code-block:: console
-
-    Example of displaying all bridge-domains:
-
-    vpp# show bridge-domain
-
-     ID   Index   Learning   U-Forwrd   UU-Flood   Flooding   ARP-Term     BVI-Intf
-     0      0        off        off        off        off        off        local0
-    200     1        on         on         on         on         off          N/A
-
-    Example of displaying details of a single bridge-domains:
-
-    vpp# show bridge-domain 200 detail
-
-     ID   Index   Learning   U-Forwrd   UU-Flood   Flooding   ARP-Term     BVI-Intf
-    200     1        on         on         on         on         off          N/A
-
-             Interface           Index  SHG  BVI        VLAN-Tag-Rewrite
-     GigabitEthernet0/8/0.200      3     0    -               none
-     GigabitEthernet0/9/0.200      4     0    -               none
-
-Declaration and Implementation
-------------------------------
-
-**Declaration:** bd_show_cli (src/vnet/l2/l2_bd.c line 1151)
-
-**Implementation:** bd_show
-
-Show Hardware-Interfaces
-+++++++++++++++++++++++++
-Display more detailed information about all or a list of given
-interfaces. The verboseness of the output can be controlled by the
-following optional parameters:
-
--  **brief**: Only show name, index and state (default for bonded
-   interfaces).
--  **verbose**: Also display additional attributes (default for all other
-   interfaces).
--  **detail**: Also display all remaining attributes and extended
-   statistics.
-
-.. note:: 
-	To limit the output of the command to bonded interfaces and their
-	slave interfaces, use the '*bond*' optional parameter.
-
-Summary/Usage
--------------
-
-.. code-block:: shell
-
-    show hardware-interfaces [brief|verbose|detail] [bond] [<interface> [<interface> [..]]] [<sw_idx> [<sw_idx> [..]]].
-
-Examples
---------
-Example of how to display default data for all interfaces:
-
-.. code-block:: console
-
-    vpp# show hardware-interfaces
-                  Name                Idx   Link  Hardware
-    GigabitEthernet7/0/0               1     up   GigabitEthernet7/0/0
-      Ethernet address ec:f4:bb:c0:bc:fc
-      Intel e1000
-        carrier up full duplex speed 1000 mtu 9216
-        rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
-        cpu socket 0
-    GigabitEthernet7/0/1               2     up   GigabitEthernet7/0/1
-      Ethernet address ec:f4:bb:c0:bc:fd
-      Intel e1000
-        carrier up full duplex speed 1000 mtu 9216
-        rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
-        cpu socket 0
-    VirtualEthernet0/0/0               3     up   VirtualEthernet0/0/0
-      Ethernet address 02:fe:a5:a9:8b:8e
-    VirtualEthernet0/0/1               4     up   VirtualEthernet0/0/1
-      Ethernet address 02:fe:c0:4e:3b:b0
-    VirtualEthernet0/0/2               5     up   VirtualEthernet0/0/2
-      Ethernet address 02:fe:1f:73:92:81
-    VirtualEthernet0/0/3               6     up   VirtualEthernet0/0/3
-      Ethernet address 02:fe:f2:25:c4:68
-    local0                             0    down  local0
-      local
-
-Example of how to display *verbose* data for an interface by name and software index
-(where 2 is the software index):
-
-.. code-block:: console
-
-    vpp# show hardware-interfaces GigabitEthernet7/0/0 2 verbose
-                   Name                Idx   Link  Hardware
-    GigabitEthernet7/0/0               1     up   GigabitEthernet7/0/0
-      Ethernet address ec:f4:bb:c0:bc:fc
-      Intel e1000
-        carrier up full duplex speed 1000 mtu 9216
-        rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
-        cpu socket 0
-    GigabitEthernet7/0/1               2    down  GigabitEthernet7/0/1
-      Ethernet address ec:f4:bb:c0:bc:fd
-      Intel e1000
-        carrier up full duplex speed 1000 mtu 9216
-        rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
-        cpu socket 0
-
-Clear Hardware-Interfaces
-+++++++++++++++++++++++++
-
-Clear the extended statistics for all or a list of given interfaces
-(statistics associated with the **show hardware-interfaces** command).
-
-
-Summary/Usage
--------------
-
-.. code-block:: shell
-
-    clear hardware-interfaces [<interface> [<interface> [..]]] [<sw_idx> [<sw_idx> [..]]].
-                
-
-Examples
---------
-
-Example of how to clear the extended statistics for all interfaces:
-
-
-.. code-block:: console
-
-        vpp# clear hardware-interfaces
-
-Example of how to clear the extended statistics for an interface by name and software index
-(where 2 is the software index): 
-
-.. code-block:: console
-
-        vpp# clear hardware-interfaces GigabitEthernet7/0/0 2
-
-
diff --git a/docs/reference/cmdreference/interface/index.rst b/docs/reference/cmdreference/interface/index.rst
deleted file mode 100644
index 9e7fd17a00a..00000000000
--- a/docs/reference/cmdreference/interface/index.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-.. _interface:
-
-.. 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>`_ .
-
-.. _intcommands:
-
-Interface Commands
-==================
-This section identifies the following types of interface commands:
-
-.. toctree::
-   :maxdepth: 2
-   
-   basic
-   hardware
-   create_interface
-   setinterface
-   
\ No newline at end of file
diff --git a/docs/reference/cmdreference/interface/setinterface.rst b/docs/reference/cmdreference/interface/setinterface.rst
deleted file mode 100644
index 69063582dcf..00000000000
--- a/docs/reference/cmdreference/interface/setinterface.rst
+++ /dev/null
@@ -1,193 +0,0 @@
-.. _interface:

-

-.. toctree::

-

-Set Interface Commands

-=======================

-This section covers those commands that are related to setting an interface:

-

-* `Set Interface`_

-* `Set Interface IP Address`_

-* `Set Interface L2 Bridge`_

-* `Set Interface MTU`_

-* `Set Interface Promiscuous`_

-* `Set Interface State`_

-

-.. 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>`_ .

-

-Set Interface

-++++++++++++++++

-

-Summary/Usage

--------------

-

-Interface commands.

-

-Declaration and Implementation

--------------------------------

-

-**Declaration:** vnet_cli_set_interface_command (src/vnet/interface_cli.c line 484)

-

-Set Interface IP Address

-+++++++++++++++++++++++++

-

-Summary/Usage

--------------

-

-set interface ip address [del] <*interface*> <*ip-addr*>/<*mask*> | [all]

-

-Description

--------------

-

-Add an IP Address to an interface or remove and IP Address from an interface. 

-The IP Address can be an IPv4 or an IPv6 address. Interfaces may have multiple IPv4 and IPv6

-addresses. There is no concept of primary vs. secondary interface addresses; they're just addresses.

-

-To display the addresses associated with a given interface, use the command **show interface address** <*interface*>.

-

-.. note:: 

-	The debug CLI does not enforce classful mask-width / addressing constraints.

-

-Example Usage

---------------

-

-An example of how to add an IPv4 address to an interface:

-

-.. code-block:: console

-

-	vpp# set interface ip address GigabitEthernet2/0/0 172.16.2.12/24

-

-An example of how to add an IPv6 address to an interface:

-

-.. code-block:: console

-

-	vpp# set interface ip address GigabitEthernet2/0/0 ::a:1:1:0:7/126

-

-To delete a specific interface ip address:

-

-.. code-block:: console

-

-	vpp# set interface ip address GigabitEthernet2/0/0 172.16.2.12/24 del

-

-To delete all interfaces addresses (IPv4 and IPv6):

-

-.. code-block:: console

-

-	vpp# set interface ip address GigabitEthernet2/0/0 del all

-

-Declaration and Implementation

--------------------------------

-

-**Declaration:** set_interface_ip_address_command (src/vnet/ip/ip46_cli.c line 216)

-

-**Implementation:** add_del_ip_address

-

-

-Set Interface L2 Bridge	

-+++++++++++++++++++++++++

-

-Summary/Usage

--------------

-

-set interface l2 bridge <*interface*> <*bridge-domain-id*> [bvi|uu-fwd] [shg]

-

-Description

--------------

-

-Use this command put an interface into Layer 2 bridge domain. If a bridge-domain with the provided

-bridge-domain-id does not exist, it will be created. Interfaces in a bridge-domain forward packets

-to other interfaces in the same bridge-domain based on destination mac address. To remove an interface

-from a the Layer 2 bridge domain, put the interface in a different mode, for example Layer 3 mode.

-

-Optionally, an interface can be added to a Layer 2 bridge-domain as a Bridged Virtual Interface (bvi).

-Only one interface in a Layer 2 bridge-domain can be a bvi.

-

-Optionally, a split-horizon group can also be specified. This defaults to 0 if not specified.

-

-Example Usage

---------------

-Example of how to configure a Layer 2 bridge-domain with three interfaces (where 200 is the bridge-domain-id):

-

-.. code-block:: console

-

-	vpp# set interface l2 bridge GigabitEthernet0/8/0.200 200

-

-This interface is added a BVI interface:

-

-.. code-block:: console

-

-	vpp# set interface l2 bridge GigabitEthernet0/9/0.200 200 bvi

-

-This interface also has a split-horizon group of 1 specified:

-

-.. code-block:: console

-

-	vpp# set interface l2 bridge GigabitEthernet0/a/0.200 200 1

-

-Example of how to remove an interface from a Layer2 bridge-domain:

-

-.. code-block:: console

-

-	vpp# set interface l3 GigabitEthernet0/a/0.200

-

-Declaration and Implementation

--------------------------------

-

-**Declaration:** int_l2_bridge_cli (src/vnet/l2/l2_input.c line 949)

-

-**Implementation:** int_l2_bridge

-

-Set Interface MTU

-++++++++++++++++++

-

-Summary/Usage

--------------

-

-.. code-block:: shell

-

-    set interface mtu [packet|ip4|ip6|mpls] <value> <interface>

-

-Set Interface Promiscuous

-++++++++++++++++++++++++++

-

-Summary/Usage

--------------

-

-.. code-block:: shell

-

-    set interface promiscuous [on|off] <interface>.

-

-.. _setintstate:

-

-Set Interface State

-++++++++++++++++++++

-This command is used to change the admin state (up/down) of an

-interface.

-

-If an interface is down, the optional *punt* flag can also be set. The

-*punt* flag implies the interface is disabled for forwarding but punt

-all traffic to slow-path. Use the *enable* flag to clear *punt* flag

-(interface is still down).

-

-Summary/Usage

--------------

-

-.. code-block:: shell

-

-    set interface state <interface> [up|down|punt|enable].

-

-Example Usage

-----------------

-

-Example of how to configure the admin state of an interface to **up**:

-

-.. code-block:: console

-

-    vpp# set interface state GigabitEthernet2/0/0 up

-

-Example of how to configure the admin state of an interface to **down**:

-

-.. code-block:: console

-

-    vpp# set interface state GigabitEthernet2/0/0 down

-

diff --git a/docs/reference/cmdreference/ip/index.rst b/docs/reference/cmdreference/ip/index.rst
deleted file mode 100644
index 1a063210847..00000000000
--- a/docs/reference/cmdreference/ip/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. ip:

-

-.. 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>`_ .

-

-IP Commands

-============

-This section identifies the following types of IP commands:

-

-.. toctree::

-   :maxdepth: 2

-   

-   ip
\ No newline at end of file
diff --git a/docs/reference/cmdreference/ip/ip.rst b/docs/reference/cmdreference/ip/ip.rst
deleted file mode 100644
index a709215f45b..00000000000
--- a/docs/reference/cmdreference/ip/ip.rst
+++ /dev/null
@@ -1,151 +0,0 @@
-.. _ip1:

-

-.. toctree::

-

-.. 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>`_ .

-

-IP Route

-==========

-

-Summary/Usage

---------------

-

-`ip route [add|del] [count <*n*>] <*dst-ip-addr*>/<*width*> [table <*table-id*>] via [next-hop-address[next-hop-interface] [next-hop-table <*value*>] [weight <*value*>] [preference <*value*>] [udp-encap-id <*value*>] [ip4-lookup-in-table <*value*>] [ip6-lookup-in-table <*value*>] [mpls-lookup-in-table <*value*>] [resolve-via-host] [resolve-via-connected] [rx-ip4 <*interface*>] [out-labels <*value value value*>]`

-

-Description

-------------

-

-This command is used to add or delete IPv4 or IPv6 routes. All IP Addresses

-('<*dst-ip-addr*>/<*width*>', '<*next-hop-ip-addr*>' and '<*adj-hop-ip-addr*>') can be IPv4 or IPv6,

-but all must be of the same form in a single command. To display the current set of routes,

-use the commands 'show ip fib' and 'show ip6 fib'.

-

-Example Usage

---------------

-

-Example of how to add a straight forward static route:

-

-.. code-block:: console

-

-    vpp# ip route add 6.0.1.2/32 via 6.0.0.1 GigabitEthernet2/0/0

-

-Example of how to delete a straight forward static route:

-

-.. code-block:: console

-

-    vpp# ip route del 6.0.1.2/32 via 6.0.0.1 GigabitEthernet2/0/0

-

-Mainly for route add/del performance testing, one can add or delete multiple routes by adding

-'count N' to the previous item:

-

-.. code-block:: console

-

-    vpp# ip route add count 10 7.0.0.0/24 via 6.0.0.1 GigabitEthernet2/0/0

-

-Add multiple routes for the same destination to create equal-cost multipath:

-

-.. code-block:: console

-

-    vpp# ip route add 7.0.0.1/32 via 6.0.0.1 GigabitEthernet2/0/0

-

-    vpp# ip route add 7.0.0.1/32 via 6.0.0.2 GigabitEthernet2/0/0

-

-For unequal-cost multipath, specify the desired weights. This combination of weights

-results in 3/4 of the traffic following the second path, 1/4 following the first path:

-

-.. code-block:: console

-

-    vpp# ip route add 7.0.0.1/32 via 6.0.0.1 GigabitEthernet2/0/0 weight 1

-

-    vpp# ip route add 7.0.0.1/32 via 6.0.0.2 GigabitEthernet2/0/0 weight 3

-

-To add a route to a particular FIB table (VRF), use:

-

-.. code-block:: console

-

-    vpp# ip route add 172.16.24.0/24 table 7 via GigabitEthernet2/0/0

-

-Declaration and Implementation

----------------------------------

-

-**Declaration:** ip_route_command (src/vnet/ip/lookup.c line 641)

-

-**Implementation:** vnet_ip_route_cmd

-

-Ping

-=====

-

-Summary/Usage

---------------

-

-ping {<*ip-addr*> | ipv4 <*ip4-addr*> | ipv6 <*ip6-addr*>} [ipv4 <*ip4-addr*> | ipv6 <*ip6-addr*>] [source <*interface*>] [size <*pktsize*>] [interval <*sec*>] [repeat <*cnt*>] [table-id <*id*>] [verbose]

-

-Description

-------------

-

-This command sends an ICMP ECHO_REQUEST to network hosts. The address can be an IPv4 or IPv6

-address (or both at the same time).

-

-Example Usage

---------------

-

-Example of how ping an IPv4 address:

-

-.. code-block:: console

-

-    vpp# ping 172.16.1.2 source GigabitEthernet2/0/0 repeat 2

-

-    64 bytes from 172.16.1.2: icmp_seq=1 ttl=64 time=.1090 ms

-    64 bytes from 172.16.1.2: icmp_seq=2 ttl=64 time=.0914 ms

-

-    Statistics: 2 sent, 2 received, 0% packet loss

-

-    Example of how ping both an IPv4 address and IPv6 address at the same time:

-

-    vpp# ping 172.16.1.2 ipv6 fe80::24a5:f6ff:fe9c:3a36 source GigabitEthernet2/0/0 repeat 2 verbose

-

-    Adjacency index: 10, sw_if_index: 1

-    Adj: ip6-discover-neighbor

-    Adj Interface: 0

-    Forced set interface: 1

-    Adjacency index: 0, sw_if_index: 4294967295

-    Adj: ip4-miss

-    Adj Interface: 0

-    Forced set interface: 1

-    Source address: 172.16.1.1

-    64 bytes from 172.16.1.2: icmp_seq=1 ttl=64 time=.1899 ms

-    Adjacency index: 10, sw_if_index: 1

-    Adj: ip6-discover-neighbor

-    Adj Interface: 0

-    Forced set interface: 1

-    Adjacency index: 0, sw_if_index: 4294967295

-    Adj: ip4-miss

-    Adj Interface: 0

-    Forced set interface: 1

-    Source address: 172.16.1.1

-    64 bytes from 172.16.1.2: icmp_seq=2 ttl=64 time=.0910 ms

-

-    Statistics: 4 sent, 2 received, 50% packet loss

-

-Declaration and Implementation

--------------------------------

-

-Declaration: ping_command (src/vnet/ip/ping.c line 899)

-

-Implementation: ping_ip_address

-

-Set Interface IP Address

-=========================

-

-`Set Interface IP Address <../interface/setinterface.html#set-interface-ip-address>`_

-

-Show IP Arp

-=============

-

-`Show IP-Arp <../show/show.html#show-ip-arp>`_

-

-

-Show IP Fib

-============

-

-`Show IP-Fib <../show/show.html#show-ip-fib>`_

diff --git a/docs/reference/cmdreference/show/index.rst b/docs/reference/cmdreference/show/index.rst
deleted file mode 100644
index 6f1e01284b2..00000000000
--- a/docs/reference/cmdreference/show/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. _interface:

-

-.. 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>`_ .

-

-Show Commands

-==================

-This section identifies the following types of show commands:

-

-.. toctree::

-   :maxdepth: 2

-   

-   show
\ No newline at end of file
diff --git a/docs/reference/cmdreference/show/show.rst b/docs/reference/cmdreference/show/show.rst
deleted file mode 100644
index 61c53604594..00000000000
--- a/docs/reference/cmdreference/show/show.rst
+++ /dev/null
@@ -1,286 +0,0 @@
-.. _interface:

-

-.. toctree::

-

-.. 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>`_ .

-

-Show Bridge-Domain

-===================

-

-`Show Bridge-Domain <../interface/hardware.html#show-bridge-domain>`_

-

-Show Interface

-================

-

-`Show Interface <../interface/basic.html#show-interface>`_

-

-Show IP Arp

-============

-

-Summary/Usage

----------------

-

-show ip arp

-

-Description

-------------

-

-Display all the IPv4 ARP entries.

-

-Example Usage

---------------

-Example of how to display the IPv4 ARP table:

-

-.. code-block:: console

-

-   vpp# **show ip arp**

-       Time      FIB        IP4       Flags      Ethernet              Interface

-       346.3028   0       6.1.1.3            de:ad:be:ef:ba:be   GigabitEthernet2/0/0

-      3077.4271   0       6.1.1.4       S    de:ad:be:ef:ff:ff   GigabitEthernet2/0/0

-      2998.6409   1       6.2.2.3            de:ad:be:ef:00:01   GigabitEthernet2/0/0

-    Proxy arps enabled for:

-    Fib_index 0   6.0.0.1 - 6.0.0.11

-

-	

-Declaration and Implementation

--------------------------------

-

-**Declaration:** show_ip4_arp_command (src/vnet/ethernet/arp.c line 1465)

-

-**Implementation:** show_ip4_arp

-

-Show IP Fib

-=============

-

-Summary/Usage

----------------

-

-show ip fib [summary] [table <*table-id*>] [index <*fib-id*>] [<*ip4-addr*>[/<*mask*>]] [mtrie] [detail]

-

-Description

-------------

-

-This command displays the IPv4 FIB Tables (VRF Tables) and the route entries for each table.

-

-.. note:: 

-	This command will run for a long time when the FIB tables are comprised of

-	millions of entries. For those scenarios, consider displaying a single table or summary mode.

-

-Example Usage

---------------

-Example of how to display all the IPv4 FIB tables:

-

-.. code-block:: console

-

-    vpp# **show ip fib**

-

-    ipv4-VRF:0, fib_index 0, flow hash: src dst sport dport proto

-    0.0.0.0/0

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:0 buckets:1 uRPF:0 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    0.0.0.0/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:1 buckets:1 uRPF:1 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    6.0.1.2/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:30 buckets:1 uRPF:29 to:[0:0]]

-      [0] [@3]: arp-ipv4: via 6.0.0.1 af_packet0

-    7.0.0.1/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:31 buckets:4 uRPF:30 to:[0:0]]

-      [0] [@3]: arp-ipv4: via 6.0.0.2 af_packet0

-      [1] [@3]: arp-ipv4: via 6.0.0.2 af_packet0

-      [2] [@3]: arp-ipv4: via 6.0.0.2 af_packet0

-      [3] [@3]: arp-ipv4: via 6.0.0.1 af_packet0

-    224.0.0.0/8

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:3 buckets:1 uRPF:3 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    240.0.0.0/8

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:2 buckets:1 uRPF:2 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    255.255.255.255/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:4 buckets:1 uRPF:4 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    ipv4-VRF:7, fib_index 1, flow hash: src dst sport dport proto

-    0.0.0.0/0

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:12 buckets:1 uRPF:11 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    0.0.0.0/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:13 buckets:1 uRPF:12 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    172.16.1.0/24

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:17 buckets:1 uRPF:16 to:[0:0]]

-      [0] [@4]: ipv4-glean: af_packet0

-    172.16.1.1/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:18 buckets:1 uRPF:17 to:[1:84]]

-      [0] [@2]: dpo-receive: 172.16.1.1 on af_packet0

-    172.16.1.2/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:21 buckets:1 uRPF:20 to:[0:0]]

-      [0] [@5]: ipv4 via 172.16.1.2 af_packet0: IP4: 02:fe:9e:70:7a:2b -> 26:a5:f6:9c:3a:36

-    172.16.2.0/24

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:19 buckets:1 uRPF:18 to:[0:0]]

-      [0] [@4]: ipv4-glean: af_packet1

-    172.16.2.1/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:20 buckets:1 uRPF:19 to:[0:0]]

-      [0] [@2]: dpo-receive: 172.16.2.1 on af_packet1

-    224.0.0.0/8

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:15 buckets:1 uRPF:14 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    240.0.0.0/8

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:14 buckets:1 uRPF:13 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    255.255.255.255/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:16 buckets:1 uRPF:15 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-

-Example of how to display a single IPv4 FIB table:

-

-.. code-block:: console

-

-    vpp# **show ip fib table 7**

-

-    ipv4-VRF:7, fib_index 1, flow hash: src dst sport dport proto

-    0.0.0.0/0

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:12 buckets:1 uRPF:11 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    0.0.0.0/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:13 buckets:1 uRPF:12 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    172.16.1.0/24

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:17 buckets:1 uRPF:16 to:[0:0]]

-      [0] [@4]: ipv4-glean: af_packet0

-    172.16.1.1/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:18 buckets:1 uRPF:17 to:[1:84]]

-      [0] [@2]: dpo-receive: 172.16.1.1 on af_packet0

-    172.16.1.2/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:21 buckets:1 uRPF:20 to:[0:0]]

-      [0] [@5]: ipv4 via 172.16.1.2 af_packet0: IP4: 02:fe:9e:70:7a:2b -*> 26:a5:f6:9c:3a:36

-    172.16.2.0/24

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:19 buckets:1 uRPF:18 to:[0:0]]

-      [0] [@4]: ipv4-glean: af_packet1

-    172.16.2.1/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:20 buckets:1 uRPF:19 to:[0:0]]

-      [0] [@2]: dpo-receive: 172.16.2.1 on af_packet1

-    224.0.0.0/8

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:15 buckets:1 uRPF:14 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    240.0.0.0/8

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:14 buckets:1 uRPF:13 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-    255.255.255.255/32

-      unicast-ip4-chain

-      [@0]: dpo-load-balance: [index:16 buckets:1 uRPF:15 to:[0:0]]

-      [0] [@0]: dpo-drop ip6

-

-Example of how to display a summary of all IPv4 FIB tables:

-

-.. code-block:: console

-

-    vpp# **show ip fib summary**

-

-    ipv4-VRF:0, fib_index 0, flow hash: src dst sport dport proto

-        Prefix length         Count

-                       0               1

-                       8               2

-                      32               4

-    ipv4-VRF:7, fib_index 1, flow hash: src dst sport dport proto

-        Prefix length         Count

-                       0               1

-                       8               2

-                      24               2

-                      32               4

-

-Declaration and Implementation

--------------------------------

-

-**Declaration:** ip4_show_fib_command (src/vnet/fib/ip4_fib.c line 873)

-

-**Implementation:** ip4_show_fib

-

-Show L2fib  

-============

-

-Summary/Usage 

-------------------

-

-show l2fib [all] | [bd_id <*nn*> | bd_index <*nn*>] [learn | add] | [raw]

-

-Description

-------------

-

-This command displays the MAC Address entries of the L2 FIB table. 

-Output can be filtered to just get the number of MAC Addresses or display each 

-MAC Address for all bridge domains or just a single bridge domain.

-

-Example Usage

---------------

-Example of how to display the number of MAC Address entries in the L2 FIB table:

-

-

-.. code-block:: console

-

-    vpp# **show l2fib**

-

-    3 l2fib entries

-

-    Example of how to display all the MAC Address entries in the L2 FIB table:

-

-    vpp# **show l2fib all**

-

-        Mac Address     BD Idx           Interface           Index  static  filter  bvi  refresh  timestamp

-     52:54:00:53:18:33    1      GigabitEthernet0/8/0.200      3       0       0     0      0         0

-     52:54:00:53:18:55    1      GigabitEthernet0/8/0.200      3       1       0     0      0         0

-     52:54:00:53:18:77    1                 N/A                -1      1       1     0      0         0

-    3 l2fib entries

-

-Declaration and Implementation

--------------------------------

-

-**Declaration:** show_l2fib_cli (src/vnet/l2/l2_fib.c line 311)

-

-**Implementation:** show_l2fib

-

-Show Trace

-===========

-

-Summary/Usage

---------------

-

-show trace buffer [max COUNT]

-

-Declaration and Implementation

-------------------------------

-

-**Declaration:** show_trace_cli (src/vlib/trace.c line 347)

-

-**Implementation:** cli_show_trace_buffer

-

-Show Vhost-User

-================

-

-`Show Vhost-User <../vhost/vhostuser.html#show-vhost-user>`_

-

diff --git a/docs/reference/cmdreference/trace/index.rst b/docs/reference/cmdreference/trace/index.rst
deleted file mode 100644
index 1dbbe2e7b3e..00000000000
--- a/docs/reference/cmdreference/trace/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. _interface:

-

-.. 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>`_ .

-

-Trace Commands

-===============

-This section identifies the following types of trace commands:

-

-.. toctree::

-   :maxdepth: 2

-   

-   trace
\ No newline at end of file
diff --git a/docs/reference/cmdreference/trace/trace.rst b/docs/reference/cmdreference/trace/trace.rst
deleted file mode 100644
index 927342fa3d7..00000000000
--- a/docs/reference/cmdreference/trace/trace.rst
+++ /dev/null
@@ -1,59 +0,0 @@
-.. _interface:
-
-.. toctree::
-
-.. 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>`_ .
-
-
-API Trace
-===========
-
-Summary/Usage
---------------
-
-api trace [tx][on|off][first <n>][last <n>][status][free]
-	[post-mortem-on][dump|dump-file|dump-json|save|tojson|save-json|replay <file>][nitems <n>][initializers <file>]
-
-Description
-------------
-
-Display, replay, or save a binary API trace.
-
-Declaration and Implementation
--------------------------------
-
-**Declaration:** api_trace_command (src/vlibmemory/vlib_api_cli.c line 783)
-
-**Implementation:** api_trace_command_fn
-
-Clear Trace
-=============
-
-Summary/Usage
---------------
-Clear trace buffer and free memory.
-Declaration and implementation
-
-**Declaration:** clear_trace_cli (src/vlib/trace.c line 519)
-
-**Implementation:** cli_clear_trace_buffer
-
-Show Trace
-===========
-
-`Show Trace <../show/show.html#show-trace>`_
-
-Trace Add
-===========
-
-Summary/Usage
---------------
-
-Trace given number of packets.
-
-Declaration and Implementation
--------------------------------
-
-**Declaration:** add_trace_cli (src/vlib/trace.c line 405)
-
-**Implementation:** cli_add_trace_buffer
diff --git a/docs/reference/cmdreference/vhost/index.rst b/docs/reference/cmdreference/vhost/index.rst
deleted file mode 100644
index d1cce23ff76..00000000000
--- a/docs/reference/cmdreference/vhost/index.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-.. _vhostcommands:
-
-.. 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>`_ .
-
-Vhost User Commands
-===================
-
-.. toctree::
-
-    vhostuser
diff --git a/docs/reference/cmdreference/vhost/vhostuser.rst b/docs/reference/cmdreference/vhost/vhostuser.rst
deleted file mode 100644
index 0c2498b7f2c..00000000000
--- a/docs/reference/cmdreference/vhost/vhostuser.rst
+++ /dev/null
@@ -1,271 +0,0 @@
-.. vhost:
-
-.. toctree::
-
-.. 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>`_ .
-
-.. _createvhostuser:
-
-Create Vhost-User
-=================
-
-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 <*socket-filename*>** - Name of the linux socket used by
-   hypervisor and VPP to manage the vHost interface. If in '*server*'
-   mode, VPP will create the socket if it does not already exist. If in
-   '*client*' mode, hypervisor will create the socket if it does not
-   already exist. The VPP code is indifferent to the file location.
-   However, if SELinux is enabled, then the socket needs to be created
-   in '*/var/run/vpp/*'.
--  **server** - Optional flag to indicate that VPP should be the server
-   for the linux socket. If not provided, VPP will be the client. In
-   '*server*' mode, the VM can be reset without tearing down the vHost
-   Interface. In '*client*' mode, VPP can be reset without bringing down
-   the VM and tearing down the vHost Interface.
--  **feature-mask <hex>** - Optional virtio/vhost feature set negotiated
-   at startup. **This is intended for debugging only.** It is
-   recommended that this parameter not be used except by experienced
-   users. 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 <mac-addr>** - Optional ethernet address, can be in either
-   X:X:X:X:X:X unix or X.X.X cisco format.
--  **renumber <dev_instance>** - 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.
-
-
-Summary/Usage
--------------
-
-.. code-block:: shell
-
-    create vhost-user socket <socket-filename> [server] [feature-mask <hex>] [hwaddr <mac-addr>] [renumber <dev_instance>]
-
-
-Examples
---------
-
-Example of how to create a vhost interface with VPP as the client
-and all features enabled:
-
-.. code-block:: console
-
-    vpp# create vhost-user socket /var/run/vpp/vhost1.sock
-    VirtualEthernet0/0/0
-
-Example of how to create a vhost interface with VPP as the server
-and with just multiple queues enabled:
-
-.. code-block:: console
-
-    vpp# create vhost-user socket /var/run/vpp/vhost2.sock server feature-mask 0x40400000
-    VirtualEthernet0/0/1
-
-Once the vHost interface is created, enable the interface using:
-
-.. code-block:: console
-
-    vpp# set interface state VirtualEthernet0/0/0 up
-
-.. _showvhost:
-
-Show Vhost-User
-===============
-
-Display the attributes of a single vHost User interface (provide
-interface name), multiple vHost User interfaces (provide a list of
-interface names separated by spaces) or all Vhost User interfaces (omit
-an interface name to display all vHost interfaces).
-
-Summary/Usage
--------------
-
-.. code-block:: shell
-
-    show vhost-user [<interface> [<interface> [..]]] [descriptors].
-
-Examples
---------
-Example of how to display a vhost interface:
-
-.. code-block:: console
-
-    vpp# 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 /var/run/vpp/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
-
-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:
-
-.. code-block:: console
-
-    vpp# 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
-
-
-Debug Vhost-User
-================
-Turn on/off debug for vhost.
-
-
-Summary/Usage
--------------
-
-.. code-block:: shell
-
-    debug vhost-user <on | off>
-
-Delete Vhost-User
-========================
-Delete a vHost User interface using the interface name or the software
-interface index. Use the '*show interface*' command to determine the
-software interface index. On deletion, the linux socket will not be
-deleted.
-
-Summary/Usage
--------------
-
-.. code-block:: shell
-
-    delete vhost-user {<interface> | sw_if_index <sw_idx>}
-
-Examples
---------
-Example of how to delete a vhost interface by name:
-
-.. code-block:: console
-
-    vpp# delete vhost-user VirtualEthernet0/0/1
-
-Example of how to delete a vhost interface by software interface index:
-
-.. code-block:: console
-
-    vpp# delete vhost-user sw_if_index 1