sample_app_ug/ethtool.rst

   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
  32 Ethtool Sample Application
  33 ==========================
  34
  35 The Ethtool sample application shows an implementation of an
  36 ethtool-like API and provides a console environment that allows
  37 its use to query and change Ethernet card parameters. The sample
  38 is based upon a simple L2 frame reflector.
  39
  40 Compiling the Application
  41 -------------------------
  42
  43 To 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
  66 Running the Application
  67 -----------------------
  68
  69 The application requires an available core for each port, plus one.
  70 The 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
  76 Refer to the *DPDK Getting Started Guide* for general information on
  77 running applications and the Environment Abstraction Layer (EAL)
  78 options.
  79
  80 Using the application
  81 ---------------------
  82
  83 The application is console-driven using the cmdline DPDK interface:
  84
  85 .. code-block:: console
  86
  87         EthApp>
  88
  89 From this interface the available commands and descriptions of what
  90 they 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
 109 Explanation
 110 -----------
 111
 112 The sample program has two parts: A background `packet reflector`_
 113 that runs on a slave core, and a foreground `Ethtool Shell`_ that
 114 runs on the master core. These are described below.
 115
 116 Packet Reflector
 117 ~~~~~~~~~~~~~~~~
 118
 119 The background packet reflector is intended to demonstrate basic
 120 packet processing on NIC ports controlled by the Ethtool shim.
 121 Each incoming MAC frame is rewritten so that it is returned to
 122 the sender, using the port in question's own MAC address as the
 123 source address, and is then sent out on the same port.
 124
 125 Ethtool Shell
 126 ~~~~~~~~~~~~~
 127
 128 The foreground part of the Ethtool sample is a console-based
 129 interface that accepts commands as described in `using the
 130 application`_. Individual call-back functions handle the detail
 131 associated with each command, which make use of the functions
 132 defined in the `Ethtool interface`_ to the DPDK functions.
 133
 134 Ethtool interface
 135 -----------------
 136
 137 The Ethtool interface is built as a separate library, and implements
 138 the 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()``