From: Billy McFall Date: Fri, 9 Sep 2016 12:46:40 +0000 (-0400) Subject: VPP-288: Documentation changes via doxygen for vnet/vnet/l2. X-Git-Tag: v17.01-rc0~218 X-Git-Url: https://gerrit.fd.io/r/gitweb?a=commitdiff_plain;h=22aa3e970da0f0c772c5a16103a5dcf1f2875285;p=vpp.git VPP-288: Documentation changes via doxygen for vnet/vnet/l2. Change-Id: I55b552fd054610c993d14078ce048c8c4b676104 Signed-off-by: Billy McFall --- diff --git a/vnet/vnet/l2/dir.dox b/vnet/vnet/l2/dir.dox new file mode 100644 index 00000000000..8497a2f64cc --- /dev/null +++ b/vnet/vnet/l2/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 Layer 2 Forwarding Code. + +This directory contains the source code for basic Layer 2 forwarding. + +*/ +/*? %%clicmd:group_label Layer 2 CLI %% ?*/ diff --git a/vnet/vnet/l2/l2_bd.c b/vnet/vnet/l2/l2_bd.c index ddbe934abeb..0b5656e6d2c 100644 --- a/vnet/vnet/l2/l2_bd.c +++ b/vnet/vnet/l2/l2_bd.c @@ -32,6 +32,14 @@ #include #include +/** + * @file + * @brief Ethernet Bridge Domain. + * + * Code in this file manages Layer 2 bridge domains. + * + */ + bd_main_t bd_main; /** @@ -270,6 +278,17 @@ done: return error; } +/*? + * Layer 2 learning can be enabled and disabled on each + * interface and on each bridge-domain. Use this command to + * manage bridge-domains. It is enabled by default. + * + * @cliexpar + * Example of how to enable learning (where 200 is the bridge-domain-id): + * @cliexcmd{set bridge-domain learn 200} + * Example of how to disable learning (where 200 is the bridge-domain-id): + * @cliexcmd{set bridge-domain learn 200 disable} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (bd_learn_cli, static) = { .path = "set bridge-domain learn", @@ -324,6 +343,18 @@ done: return error; } + +/*? + * Layer 2 unicast forwarding can be enabled and disabled on each + * interface and on each bridge-domain. Use this command to + * manage bridge-domains. It is enabled by default. + * + * @cliexpar + * Example of how to enable forwarding (where 200 is the bridge-domain-id): + * @cliexcmd{set bridge-domain forward 200} + * Example of how to disable forwarding (where 200 is the bridge-domain-id): + * @cliexcmd{set bridge-domain forward 200 disable} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (bd_fwd_cli, static) = { .path = "set bridge-domain forward", @@ -379,6 +410,17 @@ done: return error; } +/*? + * Layer 2 flooding can be enabled and disabled on each + * interface and on each bridge-domain. Use this command to + * manage bridge-domains. It is enabled by default. + * + * @cliexpar + * Example of how to enable flooding (where 200 is the bridge-domain-id): + * @cliexcmd{set bridge-domain flood 200} + * Example of how to disable flooding (where 200 is the bridge-domain-id): + * @cliexcmd{set bridge-domain flood 200 disable} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (bd_flood_cli, static) = { .path = "set bridge-domain flood", @@ -434,6 +476,17 @@ done: return error; } +/*? + * Layer 2 unknown-unicast flooding can be enabled and disabled on each + * bridge-domain. It is enabled by default. + * + * @cliexpar + * Example of how to enable unknown-unicast flooding (where 200 is the + * bridge-domain-id): + * @cliexcmd{set bridge-domain uu-flood 200} + * Example of how to disable unknown-unicast flooding (where 200 is the bridge-domain-id): + * @cliexcmd{set bridge-domain uu-flood 200 disable} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (bd_uu_flood_cli, static) = { .path = "set bridge-domain uu-flood", @@ -486,6 +539,16 @@ done: return error; } +/*? + * Modify whether or not an existing bridge-domain should terminate and respond + * to ARP Requests. ARP Termination is disabled by default. + * + * @cliexpar + * Example of how to enable ARP termination (where 200 is the bridge-domain-id): + * @cliexcmd{set bridge-domain arp term 200} + * Example of how to disable ARP termination (where 200 is the bridge-domain-id): + * @cliexcmd{set bridge-domain arp term 200 disable} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (bd_arp_term_cli, static) = { .path = "set bridge-domain arp term", @@ -579,7 +642,7 @@ bd_add_del_ip_mac (u32 bd_index, /** Set bridge-domain arp entry add/delete. The CLI format is: - set bridge-domain arp entry [del] + set bridge-domain arp entry [del] */ static clib_error_t * bd_arp_entry (vlib_main_t * vm, @@ -649,10 +712,19 @@ done: return error; } +/*? + * Add an ARP entry to an existing bridge-domain. + * + * @cliexpar + * Example of how to add an ARP entry (where 200 is the bridge-domain-id): + * @cliexcmd{set bridge-domain arp entry 200 192.168.72.45 52:54:00:3b:83:1a} + * Example of how to delete an ARP entry (where 200 is the bridge-domain-id): + * @cliexcmd{set bridge-domain arp entry 200 192.168.72.45 52:54:00:3b:83:1a del} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (bd_arp_entry_cli, static) = { .path = "set bridge-domain arp entry", - .short_help = "set bridge-domain arp entry [del]", + .short_help = "set bridge-domain arp entry [del]", .function = bd_arp_entry, }; /* *INDENT-ON* */ @@ -844,6 +916,31 @@ done: return error; } +/*? + * 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. + * + * @cliexpar + * @parblock + * Example of displaying all bridge-domains: + * @cliexstart{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 + * @cliexend + * + * Example of displaying details of a single bridge-domains: + * @cliexstart{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 + * @cliexend + * @endparblock +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (bd_show_cli, static) = { .path = "show bridge-domain", diff --git a/vnet/vnet/l2/l2_efp_filter.c b/vnet/vnet/l2/l2_efp_filter.c index 2038dce2737..2db4dc69c9c 100644 --- a/vnet/vnet/l2/l2_efp_filter.c +++ b/vnet/vnet/l2/l2_efp_filter.c @@ -26,6 +26,21 @@ #include #include +/** + * @file + * @brief EFP-filter - Ethernet Flow Point Filter. + * + * It is possible to transmit a packet out a subinterface with VLAN tags + * that are not compatible with that subinterface. In other words, if that + * packet arrived on the output port, it would not be classified as coming + * from the output subinterface. This can happen in various ways: through + * misconfiguration, by putting subinterfaces with different VLAN encaps in + * the same bridge-domain, etc. The EFP Filter Check detects such packets + * and drops them. It consists of two checks, one that verifies the packet + * prior to output VLAN tag rewrite and one that verifies the packet after + * VLAN tag rewrite. + * + */ typedef struct { @@ -568,6 +583,19 @@ done: } +/*? + * EFP filtering is a basic switch feature which prevents an interface from + * transmitting a packet that doesn't match the interface's ingress match + * criteria. The check has two parts, one performed before egress vlan tag + * rewrite and one after. This command enables or disables the EFP filtering + * for a given sub-interface. + * + * @cliexpar + * Example of how to enable a Layer 2 efp-filter on a sub-interface: + * @cliexcmd{set interface l2 efp-filter GigabitEthernet0/8/0.200} + * Example of how to disable a Layer 2 efp-filter on a sub-interface: + * @cliexcmd{set interface l2 efp-filter GigabitEthernet0/8/0.200 disable} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (int_l2_efp_filter_cli, static) = { .path = "set interface l2 efp-filter", diff --git a/vnet/vnet/l2/l2_fib.c b/vnet/vnet/l2/l2_fib.c index 97620bfba6b..20546763669 100644 --- a/vnet/vnet/l2/l2_fib.c +++ b/vnet/vnet/l2/l2_fib.c @@ -30,6 +30,16 @@ #include +/** + * @file + * @brief Ethernet MAC Address FIB Table Management. + * + * The MAC Address forwarding table for bridge-domains is called the l2fib. + * Entries are added automatically as part of mac learning, but MAC Addresses + * entries can also be added manually. + * + */ + typedef struct { @@ -198,6 +208,27 @@ show_l2fib (vlib_main_t * vm, return 0; } +/*? + * This command dispays 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. + * + * @cliexpar + * Example of how to display the number of MAC Address entries in the L2 + * FIB table: + * @cliexstart{show l2fib} + * 3 l2fib entries + * @cliexend + * Example of how to display all the MAC Address entries in the L2 + * FIB table: + * @cliexstart{show l2fib verbose} + * 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 + * @cliexend +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (show_l2fib_cli, static) = { .path = "show l2fib", @@ -239,10 +270,21 @@ clear_l2fib (vlib_main_t * vm, return 0; } +/*? + * This command clears all the MAC Address entries from the L2 FIB table. + * + * @cliexpar + * Example of how to clear the L2 FIB Table: + * @cliexcmd{clear l2fib} + * Example to show the L2 FIB Table has been cleared: + * @cliexstart{show l2fib verbose} + * no l2fib entries + * @cliexend +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (clear_l2fib_cli, static) = { .path = "clear l2fib", - .short_help = "Clear l2fib mac forwarding entries", + .short_help = "clear l2fib", .function = clear_l2fib, }; /* *INDENT-ON* */ @@ -364,10 +406,37 @@ done: return error; } +/*? + * This command adds a MAC Address entry to the L2 FIB table + * of an existing bridge-domain. The MAC Address can be static + * or dynamic. This command also allows a filter to be added, + * such that packets with given MAC Addresses (source mac or + * destination mac match) are dropped. + * + * @cliexpar + * Example of how to add a dynamic MAC Address entry to the L2 FIB table + * of a bridge-domain (where 200 is the bridge-domain-id): + * @cliexcmd{l2fib add 52:54:00:53:18:33 200 GigabitEthernet0/8/0.200} + * Example of how to add a static MAC Address entry to the L2 FIB table + * of a bridge-domain (where 200 is the bridge-domain-id): + * @cliexcmd{l2fib add 52:54:00:53:18:55 200 GigabitEthernet0/8/0.200 static} + * Example of how to add a filter such that a packet with the given MAC + * Address will be dropped in a given bridge-domain (where 200 is the + * bridge-domain-id): + * @cliexcmd{l2fib add 52:54:00:53:18:77 200 filter} + * Example of show command of the provisioned MAC Addresses and filters: + * @cliexstart{show l2fib verbose} + * 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 + * @cliexend +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (l2fib_add_cli, static) = { .path = "l2fib add", - .short_help = "Add l2fib mac forwarding entry filter | [static | bvi]", + .short_help = "l2fib add filter | [static | bvi]", .function = l2fib_add, }; /* *INDENT-ON* */ @@ -473,10 +542,47 @@ l2fib_test_command_fn (vlib_main_t * vm, return error; } +/*? + * The set of 'test l2fib' commands allow the L2 FIB table of the default + * bridge domain (bridge-domain-id of 0) to be modified. + * + * @cliexpar + * @parblock + * Example of how to add a set of 4 sequential MAC Address entries to L2 + * FIB table of the default bridge-domain: + * @cliexcmd{test l2fib add mac 52:54:00:53:00:00 count 4} + * + * Show the set of 4 sequential MAC Address entries that were added: + * @cliexstart{show l2fib verbose} + * Mac Address BD Idx Interface Index static filter bvi refresh timestamp + * 52:54:00:53:00:00 0 GigabitEthernet0/8/0.300 8 0 0 0 0 0 + * 52:54:00:53:00:01 0 GigabitEthernet0/8/0.300 8 0 0 0 0 0 + * 52:54:00:53:00:03 0 GigabitEthernet0/8/0.300 8 0 0 0 0 0 + * 52:54:00:53:00:02 0 GigabitEthernet0/8/0.300 8 0 0 0 0 0 + * 4 l2fib entries + * @cliexend + * + * Example of how to check that the set of 4 sequential MAC Address + * entries were added to L2 FIB table of the default + * bridge-domain. Used a count of 5 to produce an error: + * + * @cliexcmd{test l2fib check mac 52:54:00:53:00:00 count 5} + * The output of the check command is in the log files. Log file + * location may vary based on your OS and Version: + * + * # tail -f /var/log/messages | grep l2fib_test_command_fn + * + * Sep 7 17:15:24 localhost vnet[4952]: l2fib_test_command_fn:446: key 52:54:00:53:00:04 AWOL + * + * Example of how to delete a set of 4 sequential MAC Address entries + * from L2 FIB table of the default bridge-domain: + * @cliexcmd{test l2fib del mac 52:54:00:53:00:00 count 4} + * @endparblock +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (l2fib_test_command, static) = { .path = "test l2fib", - .short_help = "test l2fib [del] mac count ", + .short_help = "test l2fib [add|del|check] mac count ", .function = l2fib_test_command_fn, }; /* *INDENT-ON* */ @@ -565,10 +671,18 @@ done: return error; } +/*? + * This command deletes an existing MAC Address entry from the L2 FIB + * table of an existing bridge-domain. + * + * @cliexpar + * Example of how to delete a MAC Address entry from the L2 FIB table of a bridge-domain (where 200 is the bridge-domain-id): + * @cliexcmd{l2fib del 52:54:00:53:18:33 200} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (l2fib_del_cli, static) = { .path = "l2fib del", - .short_help = "Delete l2fib mac forwarding entry ", + .short_help = "l2fib del ", .function = l2fib_del, }; /* *INDENT-ON* */ diff --git a/vnet/vnet/l2/l2_flood.c b/vnet/vnet/l2/l2_flood.c index 05df2a014d9..5e9881bff9f 100644 --- a/vnet/vnet/l2/l2_flood.c +++ b/vnet/vnet/l2/l2_flood.c @@ -30,7 +30,10 @@ #include -/* +/** + * @file + * @brief Ethernet Flooding. + * * Flooding uses the packet replication infrastructure to send a copy of the * packet to each member interface. Logically the replication infrastructure * expects two graph nodes: a prep node that initiates replication and sends the @@ -538,6 +541,17 @@ done: return error; } +/*? + * Layer 2 flooding can be enabled and disabled on each + * interface and on each bridge-domain. Use this command to + * manage interfaces. It is enabled by default. + * + * @cliexpar + * Example of how to enable flooding: + * @cliexcmd{set interface l2 flood GigabitEthernet0/8/0} + * Example of how to disable flooding: + * @cliexcmd{set interface l2 flood GigabitEthernet0/8/0 disable} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (int_flood_cli, static) = { .path = "set interface l2 flood", diff --git a/vnet/vnet/l2/l2_fwd.c b/vnet/vnet/l2/l2_fwd.c index 8fa355e01a0..586aa3d4206 100644 --- a/vnet/vnet/l2/l2_fwd.c +++ b/vnet/vnet/l2/l2_fwd.c @@ -31,6 +31,15 @@ #include +/** + * @file + * @brief Ethernet Forwarding. + * + * Code in this file handles forwarding Layer 2 packets. This file calls + * the FIB lookup, packet learning and the packet flooding as necessary. + * Packet is then sent to the next graph node. + */ + typedef struct { @@ -454,6 +463,17 @@ done: return error; } +/*? + * Layer 2 unicast forwarding can be enabled and disabled on each + * interface and on each bridge-domain. Use this command to + * manage interfaces. It is enabled by default. + * + * @cliexpar + * Example of how to enable fowarding: + * @cliexcmd{set interface l2 forward GigabitEthernet0/8/0} + * Example of how to disable fowarding: + * @cliexcmd{set interface l2 forward GigabitEthernet0/8/0 disable} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (int_fwd_cli, static) = { .path = "set interface l2 forward", diff --git a/vnet/vnet/l2/l2_input.c b/vnet/vnet/l2/l2_input.c index 9b827bad347..dca13e30191 100644 --- a/vnet/vnet/l2/l2_input.c +++ b/vnet/vnet/l2/l2_input.c @@ -34,6 +34,17 @@ #include #include +/** + * @file + * @brief Interface Input Mode (Layer 2 Cross-Connect or Bridge / Layer 3). + * + * This file contains the CLI Commands that modify the input mode of an + * interface. For interfaces in a Layer 2 cross-connect, all packets + * received on one interface will be transmitted to the other. For + * interfaces in a bridge-domain, packets will be forwarded to other + * interfaces in the same bridge-domain based on destination mac address. + * For interfaces in Layer 3 mode, the packets will be routed. + */ /* Feature graph node names */ static char *l2input_feat_names[] = { @@ -838,21 +849,36 @@ done: return error; } -/* *INDENT-OFF* */ /*? + * 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. * * @cliexpar - * @cliexstart{set interface l2 bridge} - * Interfaces in a bridge-domain forward packets to other interfaces in the same bridge-domain based on destination mac address. - * To add an interface to bridge-domain 5 use: - * vpp# set interface l2 bridge GigabitEthernet2/0/0 5 - * A split-horizon group can also be specified. This defaults to 0 if not specified. - * vpp# set interface l2 bridge GigabitEthernet2/0/0 5 1 - * @cliexend - ?*/ + * Example of how to configure a Layer 2 bridge-domain with three + * interfaces (where 200 is the bridge-domain-id): + * @cliexcmd{set interface l2 bridge GigabitEthernet0/8/0.200 200} + * This interface is added a BVI interface: + * @cliexcmd{set interface l2 bridge GigabitEthernet0/9/0.200 200 bvi} + * This interface also has a split-horizon group of 1 specified: + * @cliexcmd{set interface l2 bridge GigabitEthernet0/a/0.200 200 1} + * Example of how to remove an interface from a Layer2 bridge-domain: + * @cliexcmd{set interface l3 GigabitEthernet0/a/0.200} +?*/ +/* *INDENT-OFF* */ VLIB_CLI_COMMAND (int_l2_bridge_cli, static) = { .path = "set interface l2 bridge", - .short_help = "set interface to L2 bridging mode in [bvi] [shg]", + .short_help = "set interface l2 bridge [bvi] [shg]", .function = int_l2_bridge, }; /* *INDENT-ON* */ @@ -899,16 +925,22 @@ done: return error; } -/* *INDENT-OFF* */ /*? - * L2 Cross-connect two interfaces + * Use this command put an interface into Layer 2 cross-connect mode. + * Both interfaces must be in this mode for bi-directioal traffic. All + * packets received on one interface will be transmitted to the other. + * To remove the Layer 2 cross-connect, put the interface in a different + * mode, for example Layer 3 mode. + * * @cliexpar - * @cliexstart{set interface l2 xconnect} - * To cross-connect two interfaces, put both into L2 cross-connect mode. All packets received on one interface will be transmitted to the other. - * vpp# set interface l2 xconnect GigabitEthernet2/0/0 GigabitEthernet2/0/1 - * vpp# set interface l2 xconnect GigabitEthernet2/0/1 GigabitEthernet2/0/0 - * @cliexend - ?*/ + * Example of how to configure a Layer2 cross-connect between two interfaces: + * @cliexcmd{set interface l2 xconnect GigabitEthernet0/8/0.300 GigabitEthernet0/9/0.300} + * @cliexcmd{set interface l2 xconnect GigabitEthernet0/9/0.300 GigabitEthernet0/8/0.300} + * Example of how to remove a Layer2 cross-connect: + * @cliexcmd{set interface l3 GigabitEthernet0/8/0.300} + * @cliexcmd{set interface l3 GigabitEthernet0/9/0.300} +?*/ +/* *INDENT-OFF* */ VLIB_CLI_COMMAND (int_l2_xc_cli, static) = { .path = "set interface l2 xconnect", .short_help = "set interface l2 xconnect ", @@ -947,19 +979,20 @@ done: return error; } -/* *INDENT-OFF* */ /*? + * Modify the packet processing mode of the interface to Layer 3, which + * implies packets will be routed. This is the default mode of an interface. + * Use this command to remove an interface from a Layer 2 cross-connect or a + * Layer 2 bridge. * * @cliexpar - * @cliexstart{cmd} - * Interfaces can be set in either L3 (routed) mode or L2 (xconnect or bridged) mode. - * Interfaces are in L3 mode by default. To return an interface to L3 mode, use: - * vpp# set interface l3 GigabitEthernet2/0/0 - * @cliexend - ?*/ + * Example of how to set the mode of an interface to Layer 3: + * @cliexcmd{set interface l3 GigabitEthernet0/8/0.200} +?*/ +/* *INDENT-OFF* */ VLIB_CLI_COMMAND (int_l3_cli, static) = { .path = "set interface l3", - .short_help = "set interface to L3 mode", + .short_help = "set interface l3 ", .function = int_l3, }; /* *INDENT-ON* */ @@ -1050,6 +1083,32 @@ done: return error; } +/*? + * Show the packet processing mode (Layer2 xcross-onnect, Layer 2 bridge, + * Layer 3 routed) of all interfaces and sub-interfaces, or limit the + * output to just the provided list of interfaces and sub-interfaces. + * The output shows the mode, the interface, and if the interface is + * a member of a bridge, the bridge-domain-id and the split horizen group (shg). + * + * @cliexpar + * Example of displaying the mode of all interfaces: + * @cliexstart{show mode} + * l3 local0 + * l3 GigabitEthernet0/8/0 + * l3 GigabitEthernet0/9/0 + * l3 GigabitEthernet0/a/0 + * l2 bridge GigabitEthernet0/8/0.200 bd_id 200 shg 0 + * l2 bridge GigabitEthernet0/9/0.200 bd_id 200 shg 0 + * l2 bridge GigabitEthernet0/a/0.200 bd_id 200 shg 0 + * l2 xconnect GigabitEthernet0/8/0.300 GigabitEthernet0/9/0.300 + * l2 xconnect GigabitEthernet0/9/0.300 GigabitEthernet0/8/0.300 + * @cliexend + * Example of displaying the mode of a seleted list of interfaces: + * @cliexstart{show mode GigabitEthernet0/8/0 GigabitEthernet0/8/0.200} + * l3 GigabitEthernet0/8/0 + * l2 bridge GigabitEthernet0/8/0.200 bd_id 200 shg 0 + * @cliexend +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (show_l2_mode, static) = { .path = "show mode", diff --git a/vnet/vnet/l2/l2_input_classify.c b/vnet/vnet/l2/l2_input_classify.c index 69cd113d093..497df192f39 100644 --- a/vnet/vnet/l2/l2_input_classify.c +++ b/vnet/vnet/l2/l2_input_classify.c @@ -631,18 +631,16 @@ int_l2_input_classify_command_fn (vlib_main_t * vm, * Configure l2 input classification. * * @cliexpar - * @cliexstart {set interface l2 input classify intfc - * [ip4-table ] - * [ip6-table ] - * [other-table ]} + * @cliexstart{set interface l2 input classify intfc [ip4-table ] [ip6-table ] [other-table ]} * @cliexend + * @todo This is incomplete. This needs a detailed description and a + * practical example. ?*/ - /* *INDENT-OFF* */ VLIB_CLI_COMMAND (int_l2_input_classify_cli, static) = { .path = "set interface l2 input classify", .short_help = - "set interface l2 input classify intfc [ip4-table ]\n" + "set interface l2 input classify intfc [ip4-table ]\n" " [ip6-table ] [other-table ]", .function = int_l2_input_classify_command_fn, }; diff --git a/vnet/vnet/l2/l2_learn.c b/vnet/vnet/l2/l2_learn.c index 96d4816e1e6..e34fe7a83c8 100644 --- a/vnet/vnet/l2/l2_learn.c +++ b/vnet/vnet/l2/l2_learn.c @@ -31,7 +31,7 @@ /** * @file - * Ethernet bridge learning. + * @brief Ethernet Bridge Learning. * * Populate the mac table with entries mapping the packet's source mac + bridge * domain ID to the input sw_if_index. @@ -496,6 +496,17 @@ done: return error; } +/*? + * Layer 2 learning can be enabled and disabled on each + * interface and on each bridge-domain. Use this command to + * manage interfaces. It is enabled by default. + * + * @cliexpar + * Example of how to enable learning: + * @cliexcmd{set interface l2 learn GigabitEthernet0/8/0} + * Example of how to disable learning: + * @cliexcmd{set interface l2 learn GigabitEthernet0/8/0 disable} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (int_learn_cli, static) = { .path = "set interface l2 learn", diff --git a/vnet/vnet/l2/l2_output_classify.c b/vnet/vnet/l2/l2_output_classify.c index c04df3c255b..e5c7bd18ae1 100644 --- a/vnet/vnet/l2/l2_output_classify.c +++ b/vnet/vnet/l2/l2_output_classify.c @@ -18,7 +18,7 @@ /** * @file - * @brief L2 input classifier. + * @brief Layer 2 Output Classifier. * * @sa @ref vnet/vnet/classify/vnet_classify.c * @sa @ref vnet/vnet/classify/vnet_classify.h @@ -630,21 +630,19 @@ int_l2_output_classify_command_fn (vlib_main_t * vm, } /*? - * Configure l2 input classification. + * Configure Layer 2 output classification. * * @cliexpar - * @cliexstart {set interface l2 output classify intfc - * [ip4-table ] - * [ip6-table ] - * [other-table ]} + * @cliexstart{set interface l2 output classify intfc [ip4-table ] [ip6-table ] [other-table ]} * @cliexend - ?*/ - + * @todo This is incomplete. This needs a detailed description and a + * practical example. +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (int_l2_output_classify_cli, static) = { .path = "set interface l2 output classify", .short_help = - "set interface l2 output classify intfc [ip4-table ]\n" + "set interface l2 output classify intfc <> [ip4-table ]\n" " [ip6-table ] [other-table ]", .function = int_l2_output_classify_command_fn, }; diff --git a/vnet/vnet/l2/l2_patch.c b/vnet/vnet/l2/l2_patch.c index cc35d32c824..5d097bb792e 100644 --- a/vnet/vnet/l2/l2_patch.c +++ b/vnet/vnet/l2/l2_patch.c @@ -377,11 +377,19 @@ test_patch_command_fn (vlib_main_t * vm, return 0; } +/*? + * Create or delete a Layer 2 patch. + * + * @cliexpar + * @cliexstart{test l2patch rx tx [del]} + * @cliexend + * @todo This is incomplete. This needs a detailed description and a + * practical example. +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (test_patch_command, static) = { .path = "test l2patch", - .short_help = - "rx tx [del]", + .short_help = "test l2patch rx tx [del]", .function = test_patch_command_fn, }; /* *INDENT-ON* */ @@ -421,6 +429,15 @@ show_l2patch (vlib_main_t * vm, return 0; } +/*? + * Show Layer 2 patch entries. + * + * @cliexpar + * @cliexstart{show l2patch} + * @cliexend + * @todo This is incomplete. This needs a detailed description and a + * practical example. +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (show_l2patch_cli, static) = { .path = "show l2patch", diff --git a/vnet/vnet/l2/l2_rw.c b/vnet/vnet/l2/l2_rw.c index 94096291cd0..c54509d048b 100644 --- a/vnet/vnet/l2/l2_rw.c +++ b/vnet/vnet/l2/l2_rw.c @@ -17,6 +17,15 @@ #include #include +/** + * @file + * @brief Layer 2 Rewrite. + * + * Layer 2-Rewrite node uses classify tables to match packets. Then, using + * the provisioned mask and value, modfies the packet header. + */ + + l2_rw_main_t l2_rw_main; vlib_node_registration_t l2_rw_node; @@ -437,6 +446,14 @@ l2_rw_entry_cli_fn (vlib_main_t * vm, return 0; } +/*? + * Layer 2-Rewrite node uses classify tables to match packets. Then, using + * the provisioned mask and value, modfies the packet header. + * + * @cliexpar + * @todo This is incomplete. This needs a detailed description and a + * practical example. +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (l2_rw_entry_cli, static) = { .path = "l2 rewrite entry", @@ -501,6 +518,14 @@ l2_rw_interface_cli_fn (vlib_main_t * vm, return 0; } +/*? + * Layer 2-Rewrite node uses classify tables to match packets. Then, using + * the provisioned mask and value, modfies the packet header. + * + * @cliexpar + * @todo This is incomplete. This needs a detailed description and a + * practical example. +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (l2_rw_interface_cli, static) = { .path = "set interface l2 rewrite", @@ -528,6 +553,14 @@ l2_rw_show_interfaces_cli_fn (vlib_main_t * vm, return 0; } +/*? + * Layer 2-Rewrite node uses classify tables to match packets. Then, using + * the provisioned mask and value, modfies the packet header. + * + * @cliexpar + * @todo This is incomplete. This needs a detailed description and a + * practical example. +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (l2_rw_show_interfaces_cli, static) = { .path = "show l2 rewrite interfaces", @@ -554,6 +587,14 @@ l2_rw_show_entries_cli_fn (vlib_main_t * vm, return 0; } +/*? + * Layer 2-Rewrite node uses classify tables to match packets. Then, using + * the provisioned mask and value, modfies the packet header. + * + * @cliexpar + * @todo This is incomplete. This needs a detailed description and a + * practical example. +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (l2_rw_show_entries_cli, static) = { .path = "show l2 rewrite entries", @@ -596,6 +637,14 @@ l2_rw_set_cli_fn (vlib_main_t * vm, return 0; } +/*? + * Layer 2-Rewrite node uses classify tables to match packets. Then, using + * the provisioned mask and value, modfies the packet header. + * + * @cliexpar + * @todo This is incomplete. This needs a detailed description and a + * practical example. +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (l2_rw_set_cli, static) = { .path = "set bridge-domain rewrite", diff --git a/vnet/vnet/l2/l2_vtr.c b/vnet/vnet/l2/l2_vtr.c index 3ec8b8a7d36..9cb0a7e9da3 100644 --- a/vnet/vnet/l2/l2_vtr.c +++ b/vnet/vnet/l2/l2_vtr.c @@ -29,6 +29,17 @@ #include #include +/** + * @file + * @brief Ethernet VLAN Tag Rewrite. + * + * VLAN tag rewrite provides the ability to change the VLAN tags on a packet. + * Existing tags can be popped, new tags can be pushed, and existing tags can + * be swapped with new tags. The rewrite feature is attached to a subinterface + * as input and output operations. The input operation is explicitly configured. + * The output operation is the symmetric opposite and is automatically derived + * from the input operation. + */ /** Just a placeholder; ensures file is not eliminated by linker. */ clib_error_t * @@ -532,6 +543,58 @@ done: return error; } +/*? + * VLAN tag rewrite provides the ability to change the VLAN tags on a packet. + * Existing tags can be popped, new tags can be pushed, and existing tags can + * be swapped with new tags. The rewrite feature is attached to a subinterface + * as input and output operations. The input operation is explicitly configured. + * The output operation is the symmetric opposite and is automatically derived + * from the input operation. + * + * POP: For pop operations, the subinterface encapsulation (the vlan + * tags specified when it was created) must have at least the number of popped + * tags. e.g. the \"pop 2\" operation would be rejected on a single-vlan interface. + * The output tag-rewrite operation for pops is to push the specified number of + * vlan tags onto the packet. The pushed tag values are the ones in the + * subinterface encapsulation. + * + * PUSH: For push operations, the ethertype is also specified. The + * output tag-rewrite operation for pushes is to pop the same number of tags + * off the packet. If the packet doesn't have enough tags it is dropped. + * + * + * @cliexpar + * @parblock + * By default a subinterface has no tag-rewrite. To return a subinterface to + * this state use: + * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 disable} + * + * To pop vlan tags off packets received from a subinterface, use: + * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 pop 1} + * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 pop 2} + * + * To push one or two vlan tags onto packets received from an interface, use: + * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 push dot1q 100} + * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 push dot1ad 100 150} + * + * Tags can also be translated, which is basically a combination of a pop and push. + * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 translate 1-1 dot1ad 100} + * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 translate 2-2 dot1ad 100 150} + * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 translate 1-2 dot1q 100} + * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 translate 2-1 dot1q 100 150} + * + * To display the VLAN Tag settings, show the associate bridge-domain: + * @cliexstart{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 5 0 - trans-1-1 dot1ad 100 + * GigabitEthernet0/9/0.200 4 0 - none + * GigabitEthernet0/a/0.200 6 0 - none + * @cliexend + * @endparblock +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (int_l2_vtr_cli, static) = { .path = "set interface l2 tag-rewrite", diff --git a/vnet/vnet/l2/l2_xcrw.c b/vnet/vnet/l2/l2_xcrw.c index 344a8b96506..70610a853d3 100644 --- a/vnet/vnet/l2/l2_xcrw.c +++ b/vnet/vnet/l2/l2_xcrw.c @@ -475,11 +475,23 @@ set_l2_xcrw_command_fn (vlib_main_t * vm, return 0; } +/*? + * Add or delete a Layer 2 to Layer 3 rewrite cross-connect. This is + * used to hook Layer 2 interface(s) up to the Layer 3 stack in + * arbitrary ways. For example, cross-connect an L2 interface or + * (future) bridge to an mpls-o-gre tunnel. Set up the L2 rewrite + * string as shown in mpls_gre_rewrite, and use \"mpls-post-rewrite\" + * to fix the GRE IP header checksum and length fields. + * + * @cliexpar + * @todo This is incomplete. This needs a detailed description and a + * practical example. +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (set_l2_xcrw_command, static) = { .path = "set interface l2 xcrw", .short_help = - "set int l2 xcrw next \n" + "set interface l2 xcrw next \n" " [del] [tx-fib-id ] [ipv6] rw ", .function = set_l2_xcrw_command_fn, }; @@ -555,10 +567,17 @@ show_l2xcrw_command_fn (vlib_main_t * vm, return 0; } +/*? + * Display a Layer 2 to Layer 3 rewrite cross-connect. This is used to + * hook Layer 2 interface(s) up to the Layer 3 stack in arbitrary ways. + * + * @todo This is incomplete. This needs a detailed description and a + * practical example. +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (show_l2xcrw_command, static) = { .path = "show l2xcrw", - .short_help = "Display L2/L3 rewrite cross-connects", + .short_help = "show l2xcrw", .function = show_l2xcrw_command_fn, }; /* *INDENT-ON* */