doc/guides/nics/txgbe.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2015-2020 Beijing WangXun Technology Co., Ltd.
   3
   4 TXGBE Poll Mode Driver
   5 ======================
   6
   7 The TXGBE PMD (librte_pmd_txgbe) provides poll mode driver support
   8 for Wangxun 10 Gigabit Ethernet NICs.
   9
  10 Features
  11 --------
  12
  13 - Multiple queues for TX and RX
  14 - Receiver Side Scaling (RSS)
  15 - MAC/VLAN filtering
  16 - Packet type information
  17 - Checksum offload
  18 - VLAN/QinQ stripping and inserting
  19 - TSO offload
  20 - Promiscuous mode
  21 - Multicast mode
  22 - Port hardware statistics
  23 - Jumbo frames
  24 - Link state information
  25 - Link flow control
  26 - Interrupt mode for RX
  27 - Scattered and gather for TX and RX
  28 - DCB
  29 - IEEE 1588
  30 - FW version
  31 - LRO
  32 - Generic flow API
  33
  34 Prerequisites
  35 -------------
  36
  37 - Learning about Wangxun 10 Gigabit Ethernet NICs using
  38   `<https://www.net-swift.com/a/383.html>`_.
  39
  40 - Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
  41
  42 Pre-Installation Configuration
  43 ------------------------------
  44
  45 Build Options
  46 ~~~~~~~~~~~~~
  47
  48 The following build-time options may be enabled on build time using.
  49
  50 ``-Dc_args=`` meson argument (e.g. ``-Dc_args=-DRTE_LIBRTE_TXGBE_DEBUG_RX``).
  51
  52 Please note that enabling debugging options may affect system performance.
  53
  54 - ``RTE_LIBRTE_TXGBE_DEBUG_RX`` (undefined by default)
  55
  56   Toggle display of receive fast path run-time messages.
  57
  58 - ``RTE_LIBRTE_TXGBE_DEBUG_TX`` (undefined by default)
  59
  60   Toggle display of transmit fast path run-time messages.
  61
  62 - ``RTE_LIBRTE_TXGBE_DEBUG_TX_FREE`` (undefined by default)
  63
  64   Toggle display of transmit descriptor clean messages.
  65
  66 - ``RTE_LIBRTE_TXGBE_PF_DISABLE_STRIP_CRC`` (undefined by default)
  67
  68   Decide to enable or disable HW CRC in VF PMD.
  69
  70 Dynamic Logging Parameters
  71 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  72
  73 One may leverage EAL option "--log-level" to change default levels
  74 for the log types supported by the driver. The option is used with
  75 an argument typically consisting of two parts separated by a colon.
  76
  77 TXGBE PMD provides the following log types available for control:
  78
  79 - ``pmd.net.txgbe.driver`` (default level is **notice**)
  80
  81   Affects driver-wide messages unrelated to any particular devices.
  82
  83 - ``pmd.net.txgbe.init`` (default level is **notice**)
  84
  85   Extra logging of the messages during PMD initialization.
  86
  87 - ``pmd.net.txgbe.bp`` (default level is **notice**)
  88
  89   Extra logging of auto-negotiation process for backplane NICs.
  90   Supply ``--log-level=pmd.net.txgbe.bp:debug`` to view messages.
  91
  92 Runtime Options
  93 ~~~~~~~~~~~~~~~
  94
  95 The following ``devargs`` options can be enabled at runtime. They must
  96 be passed as part of EAL arguments. For example,
  97
  98 .. code-block:: console
  99
 100    dpdk-testpmd -a 01:00.0,auto_neg=1 -- -i
 101
 102 Please note that following ``devargs`` are only set for backplane NICs.
 103
 104 - ``auto_neg`` (default **1**)
 105
 106   Toggle behavior to use auto-negotiation mode or force mode to
 107   link up backplane NICs.
 108
 109 - ``poll`` (default **0**)
 110
 111   Toggle behavior to enable/disable polling mode to receive AN interrupt.
 112
 113 - ``present`` (default **1**)
 114
 115   Toggle behavior to use present mode or init mode.
 116
 117 - ``sgmii`` (default **0**)
 118
 119   Special treatment for KX SGMII cards.
 120
 121 - ``ffe_set`` (default **0**)
 122
 123   Use to set PHY link mode and enable FFE parameters for user debugging.
 124   If disabled, the FFE parameters will not take effect. Otherwise, set 1
 125   for SFI mode, set 2 for KR mode, set 3 for KX4 mode, set 4 for KX mode.
 126
 127 - ``ffe_main`` (default **27**)
 128
 129   PHY parameter used for user debugging. Setting other values to
 130   take effect requires setting the ``ffe_set``.
 131
 132 - ``ffe_pre`` (default **8**)
 133
 134   PHY parameter used for user debugging. Setting other values to
 135   take effect requires setting the ``ffe_set``.
 136
 137 - ``ffe_post`` (default **44**)
 138
 139   PHY parameter used for user debugging. Setting other values to
 140   take effect requires setting the ``ffe_set``.
 141
 142 Driver compilation and testing
 143 ------------------------------
 144
 145 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 146 for details.
 147
 148 Sample Application Notes
 149 ------------------------
 150
 151 Generic flow API
 152 ~~~~~~~~~~~~~~~~
 153
 154 TXGBE PMD supports generic flow API which configures hardware to match specific
 155 ingress or egress traffic, alter its fate and query related counters according
 156 to any number of user-defined rules.
 157
 158 A flow rule is the combination of attributes with a matching pattern and a list of
 159 actions. Theoretically one rule can match more than one filters, which named for
 160 different patterns and actions. Like ethertype filter defines a rule in pattern:
 161 the first not void item can be ETH, and the next not void item must be END.
 162
 163 For example, create a flow rule:
 164
 165 .. code-block:: console
 166
 167         testpmd> flow create 0 ingress pattern eth type is 0x0806 / end actions queue index 2 / end
 168
 169 For a detailed usage description please refer to "Flow rules management" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`.
 170
 171 Traffic Management API
 172 ~~~~~~~~~~~~~~~~~~~~~~
 173
 174 TXGBE PMD supports generic DPDK Traffic Management API which allows to
 175 configure the following features: hierarchical scheduling, traffic shaping,
 176 congestion management, packet marking.
 177
 178 For example, add shaper profile
 179
 180 .. code-block:: console
 181
 182         testpmd> add port tm node shaper profile 0 0 0 0 25000000 0 0
 183
 184 For a detailed usage description please refer to "Traffic Management" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`.
 185
 186 Limitations or Known issues
 187 ---------------------------
 188
 189 Build with ICC is not supported yet.
 190 Power8, ARMv7 and BSD are not supported yet.