1b79aca1984656b78d838f0bfd3b8fa0cb89d259
[dpdk.git] / 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     ./ethtool-app/ethtool-app/${RTE_TARGET}/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 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
62 Explanation
63 -----------
64
65 The sample program has two parts: A background `packet reflector`_
66 that runs on a slave core, and a foreground `Ethtool Shell`_ that
67 runs on the master core. These are described below.
68
69 Packet Reflector
70 ~~~~~~~~~~~~~~~~
71
72 The background packet reflector is intended to demonstrate basic
73 packet processing on NIC ports controlled by the Ethtool shim.
74 Each incoming MAC frame is rewritten so that it is returned to
75 the sender, using the port in question's own MAC address as the
76 source address, and is then sent out on the same port.
77
78 Ethtool Shell
79 ~~~~~~~~~~~~~
80
81 The foreground part of the Ethtool sample is a console-based
82 interface that accepts commands as described in `using the
83 application`_. Individual call-back functions handle the detail
84 associated with each command, which make use of the functions
85 defined in the `Ethtool interface`_ to the DPDK functions.
86
87 Ethtool interface
88 -----------------
89
90 The Ethtool interface is built as a separate library, and implements
91 the 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()``