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