doc/guides/sample_app_ug/ethtool.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2015 Intel Corporation.
   3
   4 Ethtool Sample Application
   5 ==========================
   6
   7 The Ethtool sample application shows an implementation of an
   8 ethtool-like API and provides a console environment that allows
   9 its use to query and change Ethernet card parameters. The sample
  10 is based upon a simple L2 frame reflector.
  11
  12 Compiling the Application
  13 -------------------------
  14
  15 To compile the sample application see :doc:`compiling`.
  16
  17 The application is located in the ``ethtool`` sub-directory.
  18
  19 Running the Application
  20 -----------------------
  21
  22 The application requires an available core for each port, plus one.
  23 The only available options are the standard ones for the EAL:
  24
  25 .. code-block:: console
  26
  27     ./<build_dir>/examples/dpdk-ethtool [EAL options]
  28
  29 Refer to the *DPDK Getting Started Guide* for general information on
  30 running applications and the Environment Abstraction Layer (EAL)
  31 options.
  32
  33 Using the application
  34 ---------------------
  35
  36 The application is console-driven using the cmdline DPDK interface:
  37
  38 .. code-block:: console
  39
  40         EthApp>
  41
  42 From this interface the available commands and descriptions of what
  43 they 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
  63 Explanation
  64 -----------
  65
  66 The sample program has two parts: A background `packet reflector`_
  67 that runs on a worker core, and a foreground `Ethtool Shell`_ that
  68 runs on the main core. These are described below.
  69
  70 Packet Reflector
  71 ~~~~~~~~~~~~~~~~
  72
  73 The background packet reflector is intended to demonstrate basic
  74 packet processing on NIC ports controlled by the Ethtool shim.
  75 Each incoming MAC frame is rewritten so that it is returned to
  76 the sender, using the port in question's own MAC address as the
  77 source address, and is then sent out on the same port.
  78
  79 Ethtool Shell
  80 ~~~~~~~~~~~~~
  81
  82 The foreground part of the Ethtool sample is a console-based
  83 interface that accepts commands as described in `using the
  84 application`_. Individual call-back functions handle the detail
  85 associated with each command, which make use of the functions
  86 defined in the `Ethtool interface`_ to the DPDK functions.
  87
  88 Ethtool interface
  89 -----------------
  90
  91 The Ethtool interface is built as a separate library, and implements
  92 the 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()``