docs: add useful debug CLI Review Updates

Change-Id: I4ebd977672090f2a7fc08bb139832df39614564a
Signed-off-by: Scott Keeler <skeeler@cisco.com>

4 files changed, 222 insertions, 209 deletions

diff --git a/docs/reference/cmdreference/interface/create_interface.rst b/docs/reference/cmdreference/interface/create_interface.rst
index f0e2e6ba115..c646a9947ad 100644
--- a/docs/reference/cmdreference/interface/create_interface.rst
+++ b/docs/reference/cmdreference/interface/create_interface.rst
@@ -23,7 +23,10 @@ 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.
+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:
 
@@ -32,7 +35,7 @@ This command has the following optional parameters:
 Example Usage
 -------------
 
-    Example of how to create a host interface tied to one side of an existing linux veth pair named vpp1:
+Example of how to create a host interface tied to one side of an existing linux veth pair named vpp1:
 
 	.. code-block:: console
 
@@ -40,7 +43,7 @@ Example Usage
 
 		host-vpp1
 
-    Once the host interface is created, enable the interface using:
+Once the host interface is created, enable the interface using:
 
 	.. code-block:: console
 
@@ -84,7 +87,7 @@ Create a loopback interface. Optionally, a MAC Address can be provided. If not p
 
 Example Usage
 --------------
-    The following two command syntaxes are equivalent:
+The following two command syntaxes are equivalent:
 
 	.. code-block:: console
 
@@ -92,7 +95,7 @@ Example Usage
 
 		vpp# create loopback interface [mac <*mac-addr*>] [instance <*instance*>]
 
-    Example of how to create a loopback interface:
+Example of how to create a loopback interface:
 
 	.. code-block:: console
 
@@ -115,7 +118,7 @@ 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:
+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
@@ -219,4 +222,4 @@ When subinterfaces are created, they are in the down state. Example of how to en
 .. 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
index 4ae8fd59559..2c28d655c4a 100644
--- a/docs/reference/cmdreference/interface/hardware.rst
+++ b/docs/reference/cmdreference/interface/hardware.rst
@@ -3,8 +3,8 @@
 .. toctree::
 
 Hardware-Interfaces Commands
-=============================
-This section contains those interface commands that are related to hardware-interfaces:
+============================
+This section contains those interface commands that are related to hardware-interfaces: 
 
 
 * `Show Bridge-Domain`_
@@ -17,17 +17,18 @@ 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.
+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:
@@ -50,7 +51,7 @@ Example Usage
      GigabitEthernet0/9/0.200      4     0    -               none
 
 Declaration and Implementation
--------------------------------
+------------------------------
 
 **Declaration:** bd_show_cli (src/vnet/l2/l2_bd.c line 1151)
 
@@ -69,19 +70,19 @@ following optional parameters:
 -  **detail**: Also display all remaining attributes and extended
    statistics.
 
-.. note::
+.. 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
@@ -111,7 +112,8 @@ Example of how to display default data for all interfaces:
     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):
+Example of how to display *verbose* data for an interface by name and software index
+(where 2 is the software index):
 
 .. code-block:: console
 
@@ -131,7 +133,7 @@ Example of how to display *verbose* data for an interface by name and software i
         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).
@@ -143,7 +145,7 @@ Summary/Usage
 .. code-block:: shell
 
     clear hardware-interfaces [<interface> [<interface> [..]]] [<sw_idx> [<sw_idx> [..]]].
-
+                
 
 Examples
 --------
@@ -155,7 +157,8 @@ Example of how to clear the extended statistics for all interfaces:
 
         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):
+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
 
diff --git a/docs/reference/cmdreference/interface/index.rst b/docs/reference/cmdreference/interface/index.rst
index 7fca8f11df2..9e7fd17a00a 100644
--- a/docs/reference/cmdreference/interface/index.rst
+++ b/docs/reference/cmdreference/interface/index.rst
@@ -10,8 +10,9 @@ 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
index 744263e57f3..69063582dcf 100644
--- a/docs/reference/cmdreference/interface/setinterface.rst
+++ b/docs/reference/cmdreference/interface/setinterface.rst
@@ -1,187 +1,193 @@
-.. _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
-
+.. _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

+