VPP-282: Document changes for vnet/vnet/ethernet

Change-Id: Ie75f43516fdd76ba3720f65f38d66f14749e3e2d
Signed-off-by: Billy McFall <bmcfall@redhat.com>

3 files changed, 146 insertions, 32 deletions

diff --git a/vnet/vnet/ethernet/arp.c b/vnet/vnet/ethernet/arp.c
index 262ccd0b793..56df480ee6f 100644
--- a/vnet/vnet/ethernet/arp.c
+++ b/vnet/vnet/ethernet/arp.c
@@ -22,6 +22,15 @@
 #include <vnet/l2/l2_input.h>
 #include <vppinfra/mhash.h>
 
+/**
+ * @file
+ * @brief IPv4 ARP.
+ *
+ * This file contains code to manage the IPv4 ARP tables (IP Address
+ * to MAC Address lookup).
+ */
+
+
 void vl_api_rpc_call_main_thread (void *fp, u8 * data, u32 data_length);
 
 typedef struct
@@ -1241,11 +1250,25 @@ show_ip4_arp (vlib_main_t * vm,
   return error;
 }
 
+/*?
+ * Display all the IPv4 ARP entries.
+ *
+ * @cliexpar
+ * Example of how to display the IPv4 ARP table:
+ * @cliexstart{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
+ * @cliexend
+ ?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (show_ip4_arp_command, static) = {
   .path = "show ip arp",
   .function = show_ip4_arp,
-  .short_help = "Show ARP table",
+  .short_help = "show ip arp",
 };
 /* *INDENT-ON* */
 
@@ -1786,28 +1809,35 @@ ip_arp_add_del_command_fn (vlib_main_t * vm,
 }
 
 
-/* *INDENT-OFF* */
 /*?
- * Add or delete ip4 ARP cache entries
+ * Add or delete IPv4 ARP cache entries.
+ *
+ * @note 'set ip arp' options (e.g. delete, static, 'fib-id <id>',
+ * 'count <number>', 'interface ip4_addr mac_addr') can be added in
+ * any order and combination.
  *
  * @cliexpar
- * @cliexstart{set ip arp}
- * Add or delete ip4 ARP cache entries as follows:
- *  vpp# set ip arp GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
- *  vpp# set ip arp delete GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
- * Add or delete ip4 ARP cache entries to a specific fib table:
- *  vpp# set ip arp fib-id 1 GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
- *  vpp# set ip arp fib-id 1 delete GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
- * Add or delete ip4 static ARP cache entries as follows:
- *  vpp# set ip arp static GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
- *  vpp# set ip arp static delete GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
- * For testing / debugging purposes, the 'set ip arps command can add or delete multiple entries. Supply the 'count N' parameter:
- *  vpp# set ip arp count 10 GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
- * @NOTE: 'set ip arp' options
- * (e.g. delete, static, 'fib-id <id>', 'count <number>', 'interface ip4_addr mac_addr')
- * can be added in any order and combination.
- * @cliexend
+ * @parblock
+ * Add or delete IPv4 ARP cache entries as follows. MAC Address can be in
+ * either aa:bb:cc:dd:ee:ff format or aabb.ccdd.eeff format.
+ * @cliexcmd{set ip arp GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe}
+ * @cliexcmd{set ip arp delete GigabitEthernet2/0/0 6.0.0.3 de:ad:be:ef:ba:be}
+ *
+ * To add or delete an IPv4 ARP cache entry to or from a specific fib
+ * table:
+ * @cliexcmd{set ip arp fib-id 1 GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe}
+ * @cliexcmd{set ip arp fib-id 1 delete GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe}
+ *
+ * Add or delete IPv4 static ARP cache entries as follows:
+ * @cliexcmd{set ip arp static GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe}
+ * @cliexcmd{set ip arp static delete GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe}
+ *
+ * For testing / debugging purposes, the 'set ip arp' command can add or
+ * delete multiple entries. Supply the 'count N' parameter:
+ * @cliexcmd{set ip arp count 10 GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe}
+ * @endparblock
  ?*/
+/* *INDENT-OFF* */
 VLIB_CLI_COMMAND (ip_arp_add_del_command, static) = {
   .path = "set ip arp",
   .short_help =
@@ -1855,22 +1885,26 @@ set_int_proxy_arp_command_fn (vlib_main_t * vm,
 }
 
 
-/* *INDENT-OFF* */
 /*?
- * Enable proxy-arp on an interface.
+ * Enable proxy-arp on an interface. The vpp stack will answer ARP
+ * requests for the indicated address range. Multiple proxy-arp
+ * ranges may be provisioned.
+ *
+ * @note Proxy ARP as a technology is infamous for blackholing traffic.
+ * Also, the underlying implementation has not been performance-tuned.
+ * Avoid creating an unnecessarily large set of ranges.
  *
  * @cliexpar
- * @cliexstart{set interface proxy-arp}
  * To enable proxy arp on a range of addresses, use:
- *  vpp# set ip arp proxy 6.0.0.1 - 6.0.0.11
- * You must specifically enable proxy arp on individual interfaces:
- *  vpp# set interface proxy-arp <intfc> [enable|disable]
- * The vpp stack will answer ARP requests for the indicated address range.
- * Use with caution. Proxy ARP as a technology is infamous for blackholing traffic.
- * Multiple proxy-arp ranges may be provisioned.
- * The underlying implementation has not been performance-tuned; avoid creating an unnecessarily large set of ranges.
- * @cliexend
+ * @cliexcmd{set ip arp proxy 6.0.0.1 - 6.0.0.11}
+ * Append 'del' to delete a range of proxy ARP addresses:
+ * @cliexcmd{set ip arp proxy 6.0.0.1 - 6.0.0.11 del}
+ * You must then specifically enable proxy arp on individual interfaces:
+ * @cliexcmd{set interface proxy-arp GigabitEthernet0/8/0 enable}
+ * To disable proxy arp on an individual interface:
+ * @cliexcmd{set interface proxy-arp GigabitEthernet0/8/0 disable}
  ?*/
+/* *INDENT-OFF* */
 VLIB_CLI_COMMAND (set_int_proxy_enable_command, static) = {
   .path = "set interface proxy-arp",
   .short_help =
diff --git a/vnet/vnet/ethernet/dir.dox b/vnet/vnet/ethernet/dir.dox
new file mode 100644
index 00000000000..a55a73c014b
--- /dev/null
+++ b/vnet/vnet/ethernet/dir.dox
@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2013 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.
+ */
+
+/**
+@dir
+@brief Ethernet ARP and Loopback Code.
+
+This directory contains the source code for ARP and Loopback Interfaces.
+
+*/
+/*? %%clicmd:group_label ARP and Loopback CLI %% ?*/
diff --git a/vnet/vnet/ethernet/interface.c b/vnet/vnet/ethernet/interface.c
index 285fd895f01..0b19b51d3be 100644
--- a/vnet/vnet/ethernet/interface.c
+++ b/vnet/vnet/ethernet/interface.c
@@ -43,6 +43,13 @@
 #include <vnet/ethernet/ethernet.h>
 #include <vnet/l2/l2_input.h>
 
+/**
+ * @file
+ * @brief Loopback Interfaces.
+ *
+ * This file contains code to manage loopback interfaces.
+ */
+
 static uword
 ethernet_set_rewrite (vnet_main_t * vnm,
 		      u32 sw_if_index,
@@ -466,14 +473,36 @@ create_simulated_ethernet_interfaces (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * Create a loopback interface. Optionally, a MAC Address can be
+ * provided. If not provided, de:ad:00:00:00:<loopId> will be used.
+ *
+ * @cliexpar
+ * The following two command syntaxes are equivalent:
+ * @cliexcmd{loopback create-interface [mac <mac-addr>]}
+ * @cliexcmd{create loopback interface [mac <mac-addr>]}
+ * Example of how to create a loopback interface:
+ * @cliexcmd{loopback create-interface}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (create_simulated_ethernet_interface_command, static) = {
   .path = "loopback create-interface",
-  .short_help = "Create Loopback ethernet interface [mac <mac-addr>]",
+  .short_help = "loopback create-interface [mac <mac-addr>]",
   .function = create_simulated_ethernet_interfaces,
 };
 /* *INDENT-ON* */
 
+/*?
+ * Create a loopback interface. Optionally, a MAC Address can be
+ * provided. If not provided, de:ad:00:00:00:<loopId> will be used.
+ *
+ * @cliexpar
+ * The following two command syntaxes are equivalent:
+ * @cliexcmd{loopback create-interface [mac <mac-addr>]}
+ * @cliexcmd{create loopback interface [mac <mac-addr>]}
+ * Example of how to create a loopback interface:
+ * @cliexcmd{create loopback interface}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (create_loopback_interface_command, static) = {
   .path = "create loopback interface",
@@ -593,14 +622,34 @@ delete_sub_interface (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * Delete a loopback interface.
+ *
+ * @cliexpar
+ * The following two command syntaxes are equivalent:
+ * @cliexcmd{loopback delete-interface intfc <interface>}
+ * @cliexcmd{delete loopback interface intfc <interface>}
+ * Example of how to delete a loopback interface:
+ * @cliexcmd{loopback delete-interface intfc loop0}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (delete_simulated_ethernet_interface_command, static) = {
   .path = "loopback delete-interface",
-  .short_help = "Delete Loopback ethernet interface intfc <interface>",
+  .short_help = "loopback delete-interface intfc <interface>",
   .function = delete_simulated_ethernet_interfaces,
 };
 /* *INDENT-ON* */
 
+/*?
+ * Delete a loopback interface.
+ *
+ * @cliexpar
+ * The following two command syntaxes are equivalent:
+ * @cliexcmd{loopback delete-interface intfc <interface>}
+ * @cliexcmd{delete loopback interface intfc <interface>}
+ * Example of how to delete a loopback interface:
+ * @cliexcmd{delete loopback interface intfc loop0}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (delete_loopback_interface_command, static) = {
   .path = "delete loopback interface",
@@ -609,6 +658,13 @@ VLIB_CLI_COMMAND (delete_loopback_interface_command, static) = {
 };
 /* *INDENT-ON* */
 
+/*?
+ * Delete a sub-interface.
+ *
+ * @cliexpar
+ * Example of how to delete a sub-interface:
+ * @cliexcmd{delete sub-interface GigabitEthernet0/8/0.200}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (delete_sub_interface_command, static) = {
   .path = "delete sub-interface",