1 2.. BSD LICENSE 3 Copyright(c) 2015 Intel Corporation. All rights reserved. 4 All rights reserved. 5 6 Redistribution and use in source and binary forms, with or without 7 modification, are permitted provided that the following conditions 8 are met: 9 10 * Redistributions of source code must retain the above copyright 11 notice, this list of conditions and the following disclaimer. 12 * Redistributions in binary form must reproduce the above copyright 13 notice, this list of conditions and the following disclaimer in 14 the documentation and/or other materials provided with the 15 distribution. 16 * Neither the name of Intel Corporation nor the names of its 17 contributors may be used to endorse or promote products derived 18 from this software without specific prior written permission. 19 20 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 24 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 25 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 26 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 32Ethtool Sample Application 33========================== 34 35The Ethtool sample application shows an implementation of an 36ethtool-like API and provides a console environment that allows 37its use to query and change Ethernet card parameters. The sample 38is based upon a simple L2 frame reflector. 39 40Compiling the Application 41------------------------- 42 43To compile the application: 44 45#. Go to the sample application directory: 46 47 .. code-block:: console 48 49 export RTE_SDK=/path/to/rte_sdk 50 cd ${RTE_SDK}/examples/ethtool 51 52#. Set the target (a default target is used if not specified). For example: 53 54 .. code-block:: console 55 56 export RTE_TARGET=x86_64-native-linuxapp-gcc 57 58 See the *DPDK Getting Started Guide* for possible RTE_TARGET values. 59 60#. Build the application: 61 62 .. code-block:: console 63 64 make 65 66Running the Application 67----------------------- 68 69The application requires an available core for each port, plus one. 70The only available options are the standard ones for the EAL: 71 72.. code-block:: console 73 74 ./ethtool-app/ethtool-app/${RTE_TARGET}/ethtool [EAL options] 75 76Refer to the *DPDK Getting Started Guide* for general information on 77running applications and the Environment Abstraction Layer (EAL) 78options. 79 80Using the application 81--------------------- 82 83The application is console-driven using the cmdline DPDK interface: 84 85.. code-block:: console 86 87 EthApp> 88 89From this interface the available commands and descriptions of what 90they do as as follows: 91 92* ``drvinfo``: Print driver info 93* ``eeprom``: Dump EEPROM to file 94* ``link``: Print port link states 95* ``macaddr``: Gets/sets MAC address 96* ``mtu``: Set NIC MTU 97* ``open``: Open port 98* ``pause``: Get/set port pause state 99* ``portstats``: Print port statistics 100* ``regs``: Dump port register(s) to file 101* ``ringparam``: Get/set ring parameters 102* ``rxmode``: Toggle port Rx mode 103* ``stop``: Stop port 104* ``validate``: Check that given MAC address is valid unicast address 105* ``vlan``: Add/remove VLAN id 106* ``quit``: Exit program 107 108 109Explanation 110----------- 111 112The sample program has two parts: A background `packet reflector`_ 113that runs on a slave core, and a foreground `Ethtool Shell`_ that 114runs on the master core. These are described below. 115 116Packet Reflector 117~~~~~~~~~~~~~~~~ 118 119The background packet reflector is intended to demonstrate basic 120packet processing on NIC ports controlled by the Ethtool shim. 121Each incoming MAC frame is rewritten so that it is returned to 122the sender, using the port in question's own MAC address as the 123source address, and is then sent out on the same port. 124 125Ethtool Shell 126~~~~~~~~~~~~~ 127 128The foreground part of the Ethtool sample is a console-based 129interface that accepts commands as described in `using the 130application`_. Individual call-back functions handle the detail 131associated with each command, which make use of the functions 132defined in the `Ethtool interface`_ to the DPDK functions. 133 134Ethtool interface 135----------------- 136 137The Ethtool interface is built as a separate library, and implements 138the following functions: 139 140- ``rte_ethtool_get_drvinfo()`` 141- ``rte_ethtool_get_regs_len()`` 142- ``rte_ethtool_get_regs()`` 143- ``rte_ethtool_get_link()`` 144- ``rte_ethtool_get_eeprom_len()`` 145- ``rte_ethtool_get_eeprom()`` 146- ``rte_ethtool_set_eeprom()`` 147- ``rte_ethtool_get_pauseparam()`` 148- ``rte_ethtool_set_pauseparam()`` 149- ``rte_ethtool_net_open()`` 150- ``rte_ethtool_net_stop()`` 151- ``rte_ethtool_net_get_mac_addr()`` 152- ``rte_ethtool_net_set_mac_addr()`` 153- ``rte_ethtool_net_validate_addr()`` 154- ``rte_ethtool_net_change_mtu()`` 155- ``rte_ethtool_net_get_stats64()`` 156- ``rte_ethtool_net_vlan_rx_add_vid()`` 157- ``rte_ethtool_net_vlan_rx_kill_vid()`` 158- ``rte_ethtool_net_set_rx_mode()`` 159- ``rte_ethtool_get_ringparam()`` 160- ``rte_ethtool_set_ringparam()`` 161