1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2015 Intel Corporation. 3 4Ethtool Sample Application 5========================== 6 7The Ethtool sample application shows an implementation of an 8ethtool-like API and provides a console environment that allows 9its use to query and change Ethernet card parameters. The sample 10is based upon a simple L2 frame reflector. 11 12Compiling the Application 13------------------------- 14 15To compile the sample application see :doc:`compiling`. 16 17The application is located in the ``ethtool`` sub-directory. 18 19Running the Application 20----------------------- 21 22The application requires an available core for each port, plus one. 23The only available options are the standard ones for the EAL: 24 25.. code-block:: console 26 27 ./ethtool-app/${RTE_TARGET}/ethtool [EAL options] 28 29Refer to the *DPDK Getting Started Guide* for general information on 30running applications and the Environment Abstraction Layer (EAL) 31options. 32 33Using the application 34--------------------- 35 36The application is console-driven using the cmdline DPDK interface: 37 38.. code-block:: console 39 40 EthApp> 41 42From this interface the available commands and descriptions of what 43they do as follows: 44 45* ``drvinfo``: Print driver info 46* ``eeprom``: Dump EEPROM to file 47* ``module-eeprom``: Dump plugin module EEPROM to file 48* ``link``: Print port link states 49* ``macaddr``: Gets/sets MAC address 50* ``mtu``: Set NIC MTU 51* ``open``: Open port 52* ``pause``: Get/set port pause state 53* ``portstats``: Print port statistics 54* ``regs``: Dump port register(s) to file 55* ``ringparam``: Get/set ring parameters 56* ``rxmode``: Toggle port Rx mode 57* ``stop``: Stop port 58* ``validate``: Check that given MAC address is valid unicast address 59* ``vlan``: Add/remove VLAN id 60* ``quit``: Exit program 61 62 63Explanation 64----------- 65 66The sample program has two parts: A background `packet reflector`_ 67that runs on a slave core, and a foreground `Ethtool Shell`_ that 68runs on the master core. These are described below. 69 70Packet Reflector 71~~~~~~~~~~~~~~~~ 72 73The background packet reflector is intended to demonstrate basic 74packet processing on NIC ports controlled by the Ethtool shim. 75Each incoming MAC frame is rewritten so that it is returned to 76the sender, using the port in question's own MAC address as the 77source address, and is then sent out on the same port. 78 79Ethtool Shell 80~~~~~~~~~~~~~ 81 82The foreground part of the Ethtool sample is a console-based 83interface that accepts commands as described in `using the 84application`_. Individual call-back functions handle the detail 85associated with each command, which make use of the functions 86defined in the `Ethtool interface`_ to the DPDK functions. 87 88Ethtool interface 89----------------- 90 91The Ethtool interface is built as a separate library, and implements 92the following functions: 93 94- ``rte_ethtool_get_drvinfo()`` 95- ``rte_ethtool_get_regs_len()`` 96- ``rte_ethtool_get_regs()`` 97- ``rte_ethtool_get_link()`` 98- ``rte_ethtool_get_eeprom_len()`` 99- ``rte_ethtool_get_eeprom()`` 100- ``rte_ethtool_set_eeprom()`` 101- ``rte_ethtool_get_module_info()`` 102- ``rte_ethtool_get_module_eeprom()`` 103- ``rte_ethtool_get_pauseparam()`` 104- ``rte_ethtool_set_pauseparam()`` 105- ``rte_ethtool_net_open()`` 106- ``rte_ethtool_net_stop()`` 107- ``rte_ethtool_net_get_mac_addr()`` 108- ``rte_ethtool_net_set_mac_addr()`` 109- ``rte_ethtool_net_validate_addr()`` 110- ``rte_ethtool_net_change_mtu()`` 111- ``rte_ethtool_net_get_stats64()`` 112- ``rte_ethtool_net_vlan_rx_add_vid()`` 113- ``rte_ethtool_net_vlan_rx_kill_vid()`` 114- ``rte_ethtool_net_set_rx_mode()`` 115- ``rte_ethtool_get_ringparam()`` 116- ``rte_ethtool_set_ringparam()`` 117