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/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 as follows: 44 45* ``drvinfo``: Print driver info 46* ``eeprom``: Dump EEPROM to file 47* ``link``: Print port link states 48* ``macaddr``: Gets/sets MAC address 49* ``mtu``: Set NIC MTU 50* ``open``: Open port 51* ``pause``: Get/set port pause state 52* ``portstats``: Print port statistics 53* ``regs``: Dump port register(s) to file 54* ``ringparam``: Get/set ring parameters 55* ``rxmode``: Toggle port Rx mode 56* ``stop``: Stop port 57* ``validate``: Check that given MAC address is valid unicast address 58* ``vlan``: Add/remove VLAN id 59* ``quit``: Exit program 60 61 62Explanation 63----------- 64 65The sample program has two parts: A background `packet reflector`_ 66that runs on a slave core, and a foreground `Ethtool Shell`_ that 67runs on the master core. These are described below. 68 69Packet Reflector 70~~~~~~~~~~~~~~~~ 71 72The background packet reflector is intended to demonstrate basic 73packet processing on NIC ports controlled by the Ethtool shim. 74Each incoming MAC frame is rewritten so that it is returned to 75the sender, using the port in question's own MAC address as the 76source address, and is then sent out on the same port. 77 78Ethtool Shell 79~~~~~~~~~~~~~ 80 81The foreground part of the Ethtool sample is a console-based 82interface that accepts commands as described in `using the 83application`_. Individual call-back functions handle the detail 84associated with each command, which make use of the functions 85defined in the `Ethtool interface`_ to the DPDK functions. 86 87Ethtool interface 88----------------- 89 90The Ethtool interface is built as a separate library, and implements 91the following functions: 92 93- ``rte_ethtool_get_drvinfo()`` 94- ``rte_ethtool_get_regs_len()`` 95- ``rte_ethtool_get_regs()`` 96- ``rte_ethtool_get_link()`` 97- ``rte_ethtool_get_eeprom_len()`` 98- ``rte_ethtool_get_eeprom()`` 99- ``rte_ethtool_set_eeprom()`` 100- ``rte_ethtool_get_pauseparam()`` 101- ``rte_ethtool_set_pauseparam()`` 102- ``rte_ethtool_net_open()`` 103- ``rte_ethtool_net_stop()`` 104- ``rte_ethtool_net_get_mac_addr()`` 105- ``rte_ethtool_net_set_mac_addr()`` 106- ``rte_ethtool_net_validate_addr()`` 107- ``rte_ethtool_net_change_mtu()`` 108- ``rte_ethtool_net_get_stats64()`` 109- ``rte_ethtool_net_vlan_rx_add_vid()`` 110- ``rte_ethtool_net_vlan_rx_kill_vid()`` 111- ``rte_ethtool_net_set_rx_mode()`` 112- ``rte_ethtool_get_ringparam()`` 113- ``rte_ethtool_set_ringparam()`` 114