From 06dcd45ff81e06bc8cf40ed487c0b2652d346a5a Mon Sep 17 00:00:00 2001
From: John DeNisco <jdenisco@cisco.com>
Date: Thu, 26 Jul 2018 12:45:10 -0400
Subject: Initial commit of Sphinx docs
Change-Id: I9fca8fb98502dffc2555f9de7f507b6f006e0e77
Signed-off-by: John DeNisco <jdenisco@cisco.com>
---
docs/reference/cmdreference/interface/hardware.rst | 109 ++++++++++++++
docs/reference/cmdreference/interface/index.rst | 10 ++
.../reference/cmdreference/interface/interface.rst | 165 +++++++++++++++++++++
.../cmdreference/interface/subinterface.rst | 117 +++++++++++++++
4 files changed, 401 insertions(+)
create mode 100644 docs/reference/cmdreference/interface/hardware.rst
create mode 100644 docs/reference/cmdreference/interface/index.rst
create mode 100644 docs/reference/cmdreference/interface/interface.rst
create mode 100644 docs/reference/cmdreference/interface/subinterface.rst
(limited to 'docs/reference/cmdreference/interface')
diff --git a/docs/reference/cmdreference/interface/hardware.rst b/docs/reference/cmdreference/interface/hardware.rst
new file mode 100644
index 00000000000..f4d334fd935
--- /dev/null
+++ b/docs/reference/cmdreference/interface/hardware.rst
@@ -0,0 +1,109 @@
+.. _hardwarecommands:
+
+.. toctree::
+
+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.
+
+**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
new file mode 100644
index 00000000000..db4aa44bba2
--- /dev/null
+++ b/docs/reference/cmdreference/interface/index.rst
@@ -0,0 +1,10 @@
+.. _interfacecommands:
+
+Interface Commands
+==================
+
+.. toctree::
+
+ hardware
+ interface
+ subinterface
diff --git a/docs/reference/cmdreference/interface/interface.rst b/docs/reference/cmdreference/interface/interface.rst
new file mode 100644
index 00000000000..a3429037e8b
--- /dev/null
+++ b/docs/reference/cmdreference/interface/interface.rst
@@ -0,0 +1,165 @@
+.. _intcommands:
+
+Interface Commands
+==================
+
+.. toctree::
+
+.. _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
+
+Set Interface Mac Address
+=========================
+The '*set interface mac address* ' command allows to set MAC address of
+given interface. In case of NIC interfaces the one has to support MAC
+address change. A side effect of MAC address change are changes of MAC
+addresses in FIB tables (ipv4 and ipv6).
+
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+ set interface mac address <interface> <mac-address>.
+
+Examples
+--------
+
+Examples of how to change MAC Address of interface:
+
+.. code-block:: console
+
+ vpp# set interface mac address GigabitEthernet0/8/0 aa:bb:cc:dd:ee:01
+ vpp# set interface mac address host-vpp0 aa:bb:cc:dd:ee:02
+ vpp# set interface mac address tap-0 aa:bb:cc:dd:ee:03
+ vpp# set interface mac address pg0 aa:bb:cc:dd:ee:04
+
+Set Interface Mtu
+=================
+
+.. toctree::
+
+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].
+
+Examples
+--------
+
+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/interface/subinterface.rst b/docs/reference/cmdreference/interface/subinterface.rst
new file mode 100644
index 00000000000..24519bc1a26
--- /dev/null
+++ b/docs/reference/cmdreference/interface/subinterface.rst
@@ -0,0 +1,117 @@
+.. _subinterfacecommands:
+
+.. toctree::
+
+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 specify the outer VLAN ID, to
+ either be explicited 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 innner VLAN ID.
+
+When '*dot1q*' or '*dot1ad*' is explictly 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]}.
+
+Examples
+--------
+
+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
+
--
cgit