doc/guides/nics/hns3.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018-2019 HiSilicon Limited.
   3
   4 HNS3 Poll Mode Driver
   5 ===============================
   6
   7 The hns3 PMD (**librte_net_hns3**) provides poll mode driver support
   8 for the inbuilt HiSilicon Network Subsystem(HNS) network engine
   9 found in the HiSilicon Kunpeng 920 SoC and Kunpeng 930 SoC .
  10
  11 Features
  12 --------
  13
  14 Features of the HNS3 PMD are:
  15
  16 - Multiple queues for TX and RX
  17 - Receive Side Scaling (RSS)
  18 - Packet type information
  19 - Checksum offload
  20 - TSO offload
  21 - LRO offload
  22 - Promiscuous mode
  23 - Multicast mode
  24 - Port hardware statistics
  25 - Jumbo frames
  26 - Link state information
  27 - Interrupt mode for RX
  28 - VLAN stripping and inserting
  29 - QinQ inserting
  30 - DCB
  31 - Scattered and gather for TX and RX
  32 - Vector Poll mode driver
  33 - Dump register
  34 - SR-IOV VF
  35 - Multi-process
  36 - MAC/VLAN filter
  37 - MTU update
  38 - NUMA support
  39 - Generic flow API
  40 - IEEE1588/802.1AS timestamping
  41
  42 Prerequisites
  43 -------------
  44 - Get the information about Kunpeng920 chip using
  45   `<https://www.hisilicon.com/en/products/Kunpeng>`_.
  46
  47 - Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to
  48   setup the basic DPDK environment.
  49
  50
  51 Pre-Installation Configuration
  52 ------------------------------
  53
  54 Config File Options
  55 ~~~~~~~~~~~~~~~~~~~
  56
  57 The following options can be modified in the ``config/rte_config.h`` file.
  58
  59 - ``RTE_LIBRTE_HNS3_MAX_TQP_NUM_PER_PF`` (default ``256``)
  60
  61   Number of MAX queues reserved for PF.
  62
  63 Runtime Config Options
  64 ~~~~~~~~~~~~~~~~~~~~~~
  65
  66 - ``rx_func_hint`` (default ``none``)
  67
  68   Used to select Rx burst function, supported value are ``vec``, ``sve``,
  69   ``simple``, ``common``.
  70   ``vec``, if supported use the ``vec`` Rx function which indicates the
  71   default vector algorithm, neon for Kunpeng Arm platform.
  72   ``sve``, if supported use the ``sve`` Rx function which indicates the
  73   sve algorithm.
  74   ``simple``, if supported use the ``simple`` Rx function which indicates
  75   the scalar simple algorithm.
  76   ``common``, if supported use the ``common`` Rx function which indicates
  77   the scalar scattered algorithm.
  78
  79   When provided parameter is not supported, ``vec`` usage condition will
  80   be first checked, if meets, use the ``vec``. Then, ``simple``, at last
  81   ``common``.
  82
  83   For example::
  84   -a 0000:7d:00.0,rx_func_hint=simple
  85
  86 - ``tx_func_hint`` (default ``none``)
  87
  88   Used to select Tx burst function, supported value are ``vec``, ``sve``,
  89   ``simple``, ``common``.
  90   ``vec``, if supported use the ``vec`` Tx function which indicates the
  91   default vector algorithm, neon for Kunpeng Arm platform.
  92   ``sve``, if supported use the ``sve`` Tx function which indicates the
  93   sve algorithm.
  94   ``simple``, if supported use the ``simple`` Tx function which indicates
  95   the scalar simple algorithm.
  96   ``common``, if supported use the ``common`` Tx function which indicates
  97   the scalar algorithm.
  98
  99   When provided parameter is not supported, ``vec`` usage condition will
 100   be first checked, if meets, use the ``vec``. Then, ``simple``, at last
 101   ``common``.
 102
 103   For example::
 104   -a 0000:7d:00.0,tx_func_hint=common
 105
 106 - ``dev_caps_mask`` (default ``0``)
 107
 108   Used to mask the capability which queried from firmware.
 109   This args take hexadecimal bitmask where each bit represents whether mask
 110   corresponding capability. eg. If the capability is 0xFFFF queried from
 111   firmware, and the args value is 0xF which means the bit0~bit3 should be
 112   masked off, then the capability will be 0xFFF0.
 113   Its main purpose is to debug and avoid problems.
 114
 115   For example::
 116   -a 0000:7d:00.0,dev_caps_mask=0xF
 117
 118 Driver compilation and testing
 119 ------------------------------
 120
 121 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 122 for details.
 123
 124 Sample Application Notes
 125 ------------------------
 126
 127 VLAN filter
 128 ~~~~~~~~~~~
 129
 130 VLAN filter only works when Promiscuous mode is off.
 131
 132 To start ``testpmd``, and add VLAN 10 to port 0:
 133
 134 .. code-block:: console
 135
 136     ./<build_dir>/app/dpdk-testpmd -l 0-15 -n 4 -- -i --forward-mode=mac
 137     ...
 138
 139     testpmd> set promisc 0 off
 140     testpmd> vlan set filter on 0
 141     testpmd> rx_vlan add 10 0
 142
 143
 144 Flow Director
 145 ~~~~~~~~~~~~~
 146
 147 The Flow Director works in receive mode to identify specific flows or sets of
 148 flows and route them to specific queues.
 149 The Flow Director filters can match the different fields for different type of
 150 packet: flow type, specific input set per flow type.
 151
 152
 153 Start ``testpmd``:
 154
 155 .. code-block:: console
 156
 157    ./<build_dir>/app/dpdk-testpmd -l 0-15 -n 4 -- -i --rxq=8 --txq=8 \
 158                                   --nb-cores=8 --nb-ports=1
 159
 160 Add a rule to direct ``ipv4-udp`` packet whose ``dst_ip=2.2.2.5, src_ip=2.2.2.3,
 161 src_port=32, dst_port=32`` to queue 1:
 162
 163 .. code-block:: console
 164
 165    testpmd> flow create 0 ingress pattern eth / ipv4 src is 2.2.2.3 \
 166             dst is 2.2.2.5 / udp src is 32 dst is 32 / end \
 167             actions mark id 1 / queue index 1 / end
 168
 169 Generic flow API
 170 ~~~~~~~~~~~~~~~~
 171
 172 - ``RSS Flow``
 173
 174   RSS Flow supports to set hash input set, hash function, enable hash
 175   and configure queues.
 176   For example:
 177   Configure queues as queue 0, 1, 2, 3.
 178
 179   .. code-block:: console
 180
 181     testpmd> flow create 0 ingress pattern end actions rss types end \
 182       queues 0 1 2 3 end / end
 183
 184   Enable hash and set input set for IPv4-TCP.
 185
 186   .. code-block:: console
 187
 188     testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \
 189       actions rss types ipv4-tcp l3-src-only end queues end / end
 190
 191   Set symmetric hash enable for flow type IPv4-TCP.
 192
 193   .. code-block:: console
 194
 195     testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \
 196       actions rss types ipv4-tcp end queues end func symmetric_toeplitz / end
 197
 198   Set hash function as simple xor.
 199
 200   .. code-block:: console
 201
 202     testpmd> flow create 0 ingress pattern end actions rss types end \
 203       queues end func simple_xor / end
 204
 205 Statistics
 206 ----------
 207
 208 HNS3 supports various methods to report statistics:
 209
 210 Port statistics can be queried using ``rte_eth_stats_get()``. The number
 211 of packets received or sent successfully by the PMD. While the received and
 212 sent packet bytes are through SW only. The imissed counter is the amount of
 213 packets that could not be delivered to SW because a queue was full. The oerror
 214 counter is the amount of packets that are dropped by HW in Tx.
 215
 216 Extended statistics can be queried using ``rte_eth_xstats_get()``. The extended
 217 statistics expose a wider set of counters counted by the device. The extended
 218 port statistics contains packets statistics per queue, Mac statistics, HW reset
 219 count and IO error count.
 220
 221 Finally per-flow statistics can by queried using ``rte_flow_query`` when attaching
 222 a count action for specific flow. The flow counter counts the number of packets
 223 received successfully by the port and match the specific flow.
 224
 225 Performance tuning
 226 ------------------
 227
 228 Hardware configuration
 229 ~~~~~~~~~~~~~~~~~~~~~~
 230 32 GB DIMMs is used to ensure that each channel is fully configured.
 231 Dynamic CPU Tuning is disabled.
 232
 233 Queue depth configuration
 234 ~~~~~~~~~~~~~~~~~~~~~~~~~
 235 According to the actual test, the performance is best when the queue depth
 236 ranges from 1024 to 2048.
 237
 238 IO burst configuration
 239 ~~~~~~~~~~~~~~~~~~~~~~
 240 According to the actual test, the performance is best when IO burst is set to 64.
 241 IO burst is the number of packets per burst.
 242
 243 Queue number configuration
 244 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 245 When the number of port queues corresponds to the number of CPU cores, the
 246 performance will be better.
 247
 248 Hugepage configuration
 249 ~~~~~~~~~~~~~~~~~~~~~~
 250 For 4K systems, 1 GB hugepages are recommended. For 64 KB systems, 512 MB
 251 hugepages are recommended.
 252
 253 CPU core isolation
 254 ~~~~~~~~~~~~~~~~~~
 255 To reduce the possibility of context switching, kernel isolation parameter should
 256 be provided to avoid scheduling the CPU core used by DPDK application threads for
 257 other tasks. Before starting the Linux OS, add the kernel isolation boot parameter.
 258 For example, "isolcpus=1-18 nohz_full=1-18 rcu_nocbs=1-18".
 259
 260
 261 Limitations or Known issues
 262 ---------------------------
 263 Currently, we only support VF device driven by DPDK driver when PF is driven
 264 by kernel mode hns3 ethdev driver. VF is not supported when PF is driven by
 265 DPDK driver.
 266
 267 Build with ICC is not supported yet.
 268 X86-32, Power8, ARMv7 and BSD are not supported yet.