From: Billy McFall Date: Fri, 11 Aug 2017 18:05:11 +0000 (-0400) Subject: VPP-939: Update CLI Helptext for rx-placement commands X-Git-Tag: v17.10-rc1~230 X-Git-Url: https://gerrit.fd.io/r/gitweb?a=commitdiff_plain;h=e9bac6953d03440f2f7437f4e3f0a4e3bf7f8a60;p=vpp.git VPP-939: Update CLI Helptext for rx-placement commands The CLI commands were change from 'set/show interface placement' to 'set/show interface rx-placement', but the associated help text was not updated. On the 'set interface rx-placement', some of the parameters were renamed, which was confusing when looking at the documentation for help. While in the file interface_cli.c, cleaned up several other CLI commands. There are still other commands in the file that need addressing. Change-Id: Ifdc357c73ad9f3362133c495217b5a6b3a411eab Signed-off-by: Billy McFall --- diff --git a/src/vnet/dir.dox b/src/vnet/dir.dox new file mode 100644 index 00000000000..8bc2c4cf1b2 --- /dev/null +++ b/src/vnet/dir.dox @@ -0,0 +1,29 @@ +/* + * Copyright (c) 2017 Red Hat 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. + */ + +/* Doxygen directory documentation */ + +/** +@dir +@brief Interface. + +This is a high level directory which contains sub-directories for all the +networking protocols. Also contained within this directory are more generic +CLI command files such as interface management. + +*/ +/*? %%clicmd:group_label Interface %% ?*/ +/*? %%syscfg:group_label Interface %% ?*/ diff --git a/src/vnet/interface_cli.c b/src/vnet/interface_cli.c index a8aa3056572..f37f139b48a 100644 --- a/src/vnet/interface_cli.c +++ b/src/vnet/interface_cli.c @@ -39,7 +39,10 @@ /** * @file - * Interface CLI. + * @brief Interface CLI. + * + * Source code for several CLI interface commands. + * */ #include @@ -165,46 +168,88 @@ done: return error; } -/* *INDENT-OFF* */ /*? - * Displays various information about the state of the current terminal - * session. + * 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. * * @cliexpar - * @cliexstart{show hardware} - * Name Link Hardware - * GigabitEthernet2/0/0 up GigabitEthernet2/0/0 - * Ethernet address 00:50:56:b7:7c:83 - * Intel 82545em_copper - * link up, media 1000T full-duplex, master, - * 0 unprocessed, 384 total buffers on rx queue 0 ring - * 237 buffers in driver rx cache - * rx total packets 1816 - * rx total bytes 181084 - * rx good packets 1816 - * rx good bytes 181084 - * rx 65 127 byte packets 1586 - * rx 256 511 byte packets 230 - * tx total packets 346 - * tx total bytes 90224 - * tx good packets 346 - * tx good bytes 88840 - * tx 64 byte packets 1 - * tx 65 127 byte packets 115 - * tx 256 511 byte packets 230 + * Example of how to display default data for all interfaces: + * @cliexstart{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 + * @cliexend + * Example of how to display 'verbose' data for an interface by name and + * software index (where 2 is the software index): + * @cliexstart{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 * @cliexend ?*/ +/* *INDENT-OFF* */ VLIB_CLI_COMMAND (show_hw_interfaces_command, static) = { .path = "show hardware-interfaces", - .short_help = "show hardware-interfaces [brief|verbose|detail] [bond] [ ...]", + .short_help = "show hardware-interfaces [brief|verbose|detail] [bond] " + "[ [ [..]]] [ [ [..]]]", .function = show_or_clear_hw_interfaces, }; /* *INDENT-ON* */ + +/*? + * Clear the extended statistics for all or a list of given interfaces + * (statistics associated with the 'show hardware-interfaces' command). + * + * @cliexpar + * Example of how to clear the extended statistics for all interfaces: + * @cliexcmd{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): + * @cliexcmd{clear hardware-interfaces GigabitEthernet7/0/0 2} + ?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (clear_hw_interface_counters_command, static) = { .path = "clear hardware-interfaces", - .short_help = "Clear hardware interfaces statistics", + .short_help = "clear hardware-interfaces " + "[ [ [..]]] [ [ [..]]]", .function = show_or_clear_hw_interfaces, }; /* *INDENT-ON* */ @@ -431,7 +476,7 @@ done: /* *INDENT-OFF* */ VLIB_CLI_COMMAND (show_sw_interfaces_command, static) = { .path = "show interface", - .short_help = "show interface [address|addr|features|feat] [ ...]", + .short_help = "show interface [address|addr|features|feat] [ [ [..]]]", .function = show_sw_interfaces, }; /* *INDENT-ON* */ @@ -500,10 +545,18 @@ clear_interface_counters (vlib_main_t * vm, return 0; } +/*? + * Clear the statistics for all interfaces (statistics associated with the + * 'show interface' command). + * + * @cliexpar + * Example of how to clear the statistics for all interfaces: + * @cliexcmd{clear interfaces} + ?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (clear_interface_counters_command, static) = { .path = "clear interfaces", - .short_help = "Clear interfaces statistics", + .short_help = "clear interfaces", .function = clear_interface_counters, }; /* *INDENT-ON* */ @@ -747,54 +800,97 @@ done: return error; } -/* *INDENT-OFF* */ /*? - * Create vlan subinterfaces + * 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 - Create a subinterface to + * process packets with a given 802.1q VLAN ID (same value as the 'subId'). + * + * - create sub-interfaces 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 untagged - Adding the + * 'untagged' parameter indicates that packets no VLAN IDs should be sent + * to this subinterface. + * + * - create sub-interfaces - - Create a range of + * subinterfaces to handle a range of VLAN IDs. + * + * - create sub-interfaces dot1q|dot1ad |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 dot1q|dot1ad |any inner-dot1q + * |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. * * @cliexpar - * @cliexstart{create sub-interfaces} + * @parblock + * Example of how to create a VLAN subinterface 11 to process packets on 802.1q VLAN ID 11: + * @cliexcmd{create sub-interfaces GigabitEthernet2/0/0 11} * - * To create a vlan subinterface 11 to process packets on 802.1q VLAN id 11, use: + * The previous example is shorthand and is equivalent to: + * @cliexcmd{create sub-interfaces GigabitEthernet2/0/0 11 dot1q 11 exact-match} * - * vpp# create sub GigabitEthernet2/0/0 11 * - * This shorthand is equivalent to: - * vpp# create sub GigabitEthernet2/0/0 11 dot1q 11 exact-match + * Example of how to create a subinterface number that is different from the VLAN ID: + * @cliexcmd{create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100} * - * You can specify a subinterface number that is different from the vlan id: - * vpp# create sub GigabitEthernet2/0/0 11 dot1q 100 * - * You can create qinq and q-in-any interfaces: - * vpp# create sub GigabitEthernet2/0/0 11 dot1q 100 inner-dot1q 200 - * vpp# create sub GigabitEthernet2/0/0 12 dot1q 100 inner-dot1q any + * Examples of how to create q-in-q and q-in-any subinterfaces: + * @cliexcmd{create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100 inner-dot1q 200} + * @cliexcmd{create sub-interfaces GigabitEthernet2/0/0 12 dot1q 100 inner-dot1q any} * - * You can also create dot1ad interfaces: - * vpp# create sub GigabitEthernet2/0/0 11 dot1ad 11 - * vpp# create sub GigabitEthernet2/0/0 12 dot1q 100 inner-dot1q 200 + * Examples of how to create dot1ad interfaces: + * @cliexcmd{create sub-interfaces GigabitEthernet2/0/0 11 dot1ad 11} + * @cliexcmd{create sub-interfaces GigabitEthernet2/0/0 12 dot1ad 100 inner-dot1q 200} * - * 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. * - * For example, a packet with outer vlan 100 and inner 200 would match this interface: - * vpp# create sub GigabitEthernet2/0/0 5 dot1q 100 + * 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: + * @cliexcmd{create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100} * - * but would not match this interface: - * vpp# create sub GigabitEthernet2/0/0 5 dot1q 100 exact-match + * 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: + * @cliexcmd{create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100 exact-match} * - * There are two special subinterfaces that can be configured. Subinterface untagged has no vlan tags: - * vpp# create sub GigabitEthernet2/0/0 5 untagged * - * The subinterface default matches any packet that does not match any other subinterface: - * vpp# create sub GigabitEthernet2/0/0 7 default - * @cliexend + * Example of how to created a subinterface to process untagged packets: + * @cliexcmd{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: + * @cliexcmd{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: + * @cliexcmd{set interface GigabitEthernet2/0/0.7 up} + * @endparblock ?*/ +/* *INDENT-OFF* */ VLIB_CLI_COMMAND (create_sub_interfaces_command, static) = { .path = "create sub-interfaces", - .short_help = "create sub-interfaces [-] [dot1q|dot1ad|default|untagged]", + .short_help = "create sub-interfaces " + "{ [default|untagged]} | " + "{-} | " + "{ dot1q|dot1ad |any [inner-dot1q |any] [exact-match]}", .function = create_sub_interfaces, }; /* *INDENT-ON* */ @@ -831,19 +927,24 @@ done: } -/* *INDENT-OFF* */ /*? - * Interface admin up/down + * 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). * * @cliexpar - * @cliexstart{set interface state} - * vpp# set interface state GigabitEthernet2/0/0 up - * vpp# set interface state GigabitEthernet2/0/0 down - * @cliexend + * Example of how to configure the admin state of an interface to 'updownqueue' is not provided, - * it defaults to 0. + * This command is used to assign the RX packet processing mode (polling, + * interrupt, adaptive) of the a given interface, and optionally a + * given queue. If the 'queue' is not provided, the 'mode' + * is applied to all queues of the interface. Not all interfaces support + * all modes. To display the current rx-mode use the command + * 'show interface rx-placement'. * * @cliexpar - * Example of how to display the interface placement: + * Example of how to assign rx-mode to all queues on an interface: + * @cliexcmd{set interface rx-mode VirtualEthernet0/0/12 polling} + * Example of how to assign rx-mode to one queue of an interface: + * @cliexcmd{set interface rx-mode VirtualEthernet0/0/12 queue 0 interrupt} + * Example of how to display the rx-mode of all interfaces: * @cliexstart{show interface rx-placement} * Thread 1 (vpp_wk_0): - * GigabitEthernet0/8/0 queue 0 - * GigabitEthernet0/9/0 queue 0 + * node dpdk-input: + * GigabitEthernet7/0/0 queue 0 (polling) + * node vhost-user-input: + * VirtualEthernet0/0/12 queue 0 (interrupt) + * VirtualEthernet0/0/12 queue 2 (polling) + * VirtualEthernet0/0/13 queue 0 (polling) + * VirtualEthernet0/0/13 queue 2 (polling) * Thread 2 (vpp_wk_1): - * GigabitEthernet0/8/0 queue 1 - * GigabitEthernet0/9/0 queue 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) * @cliexend - * Example of how to assign a interface and queue to a thread: - * @cliexcmd{set interface placement GigabitEthernet0/8/0 queue 1 thread 1} ?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (cmd_set_if_rx_mode,static) = { @@ -1375,6 +1491,31 @@ show_interface_rx_placement_fn (vlib_main_t * vm, unformat_input_t * input, return 0; } +/*? + * This command is used to display the interface and queue worker + * thread placement. + * + * @cliexpar + * Example of how to display the interface placement: + * @cliexstart{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) + * @cliexend +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (show_interface_rx_placement, static) = { .path = "show interface rx-placement", @@ -1449,30 +1590,59 @@ set_interface_rx_placement (vlib_main_t * vm, unformat_input_t * input, /*? * This command is used to assign a given interface, and optionally a * given queue, to a different thread. If the 'queue' is not provided, - * it defaults to 0. + * it defaults to 0. The 'worker' parameter is zero based and the index + * in the thread name, for example, 0 in the thread name 'vpp_wk_0'. * * @cliexpar * Example of how to display the interface placement: - * @cliexstart{show interface placement} + * @cliexstart{show interface rx-placement} * Thread 1 (vpp_wk_0): - * GigabitEthernet0/8/0 queue 0 - * GigabitEthernet0/9/0 queue 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): - * GigabitEthernet0/8/0 queue 1 - * GigabitEthernet0/9/0 queue 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) + * @cliexend + * Example of how to assign a interface and queue to a worker thread: + * @cliexcmd{set interface rx-placement VirtualEthernet0/0/12 queue 1 worker 0} + * Example of how to display the interface placement: + * @cliexstart{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 1 (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 3 (polling) + * VirtualEthernet0/0/13 queue 1 (polling) + * VirtualEthernet0/0/13 queue 3 (polling) * @cliexend - * Example of how to assign a interface and queue to a thread: - * @cliexcmd{set interface placement GigabitEthernet0/8/0 queue 1 thread 1} ?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (cmd_set_if_rx_placement,static) = { .path = "set interface rx-placement", - .short_help = "set interface rx-placement [queue ] " + .short_help = "set interface rx-placement [queue ] " "[worker | main]", .function = set_interface_rx_placement, .is_mp_safe = 1, }; - /* *INDENT-ON* */ /* * fd.io coding-style-patch-verification: ON