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
 119 Link status event Pre-conditions
 120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 121
 122 Firmware 1.8.0.0 and later versions support reporting link changes to the PF.
 123 Therefore, to use the LSC for the PF driver, ensure that the firmware version
 124 also supports reporting link changes.
 125 If the VF driver needs to support LSC, special patch must be added:
 126 `<https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/drivers/net/ethernet/hisilicon/hns3?h=next-20210428&id=18b6e31f8bf4ac7af7b057228f38a5a530378e4e>`_.
 127 Note: The patch has been uploaded to 5.13 of the Linux kernel mainline.
 128
 129
 130 Driver compilation and testing
 131 ------------------------------
 132
 133 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 134 for details.
 135
 136 Sample Application Notes
 137 ------------------------
 138
 139 VLAN filter
 140 ~~~~~~~~~~~
 141
 142 VLAN filter only works when Promiscuous mode is off.
 143
 144 To start ``testpmd``, and add VLAN 10 to port 0:
 145
 146 .. code-block:: console
 147
 148     ./<build_dir>/app/dpdk-testpmd -l 0-15 -n 4 -- -i --forward-mode=mac
 149     ...
 150
 151     testpmd> set promisc 0 off
 152     testpmd> vlan set filter on 0
 153     testpmd> rx_vlan add 10 0
 154
 155
 156 Flow Director
 157 ~~~~~~~~~~~~~
 158
 159 The Flow Director works in receive mode to identify specific flows or sets of
 160 flows and route them to specific queues.
 161 The Flow Director filters can match the different fields for different type of
 162 packet: flow type, specific input set per flow type.
 163
 164
 165 Start ``testpmd``:
 166
 167 .. code-block:: console
 168
 169    ./<build_dir>/app/dpdk-testpmd -l 0-15 -n 4 -- -i --rxq=8 --txq=8 \
 170                                   --nb-cores=8 --nb-ports=1
 171
 172 Add a rule to direct ``ipv4-udp`` packet whose ``dst_ip=2.2.2.5, src_ip=2.2.2.3,
 173 src_port=32, dst_port=32`` to queue 1:
 174
 175 .. code-block:: console
 176
 177    testpmd> flow create 0 ingress pattern eth / ipv4 src is 2.2.2.3 \
 178             dst is 2.2.2.5 / udp src is 32 dst is 32 / end \
 179             actions mark id 1 / queue index 1 / end
 180
 181 Generic flow API
 182 ~~~~~~~~~~~~~~~~
 183
 184 - ``RSS Flow``
 185
 186   RSS Flow supports to set hash input set, hash function, enable hash
 187   and configure queues.
 188   For example:
 189   Configure queues as queue 0, 1, 2, 3.
 190
 191   .. code-block:: console
 192
 193     testpmd> flow create 0 ingress pattern end actions rss types end \
 194       queues 0 1 2 3 end / end
 195
 196   Enable hash and set input set for IPv4-TCP.
 197
 198   .. code-block:: console
 199
 200     testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \
 201       actions rss types ipv4-tcp l3-src-only end queues end / end
 202
 203   Set symmetric hash enable for flow type IPv4-TCP.
 204
 205   .. code-block:: console
 206
 207     testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \
 208       actions rss types ipv4-tcp end queues end func symmetric_toeplitz / end
 209
 210   Set hash function as simple xor.
 211
 212   .. code-block:: console
 213
 214     testpmd> flow create 0 ingress pattern end actions rss types end \
 215       queues end func simple_xor / end
 216
 217 Statistics
 218 ----------
 219
 220 HNS3 supports various methods to report statistics:
 221
 222 Port statistics can be queried using ``rte_eth_stats_get()``. The number
 223 of packets received or sent successfully by the PMD. While the received and
 224 sent packet bytes are through SW only. The imissed counter is the amount of
 225 packets that could not be delivered to SW because a queue was full. The oerror
 226 counter is the amount of packets that are dropped by HW in Tx.
 227
 228 Extended statistics can be queried using ``rte_eth_xstats_get()``. The extended
 229 statistics expose a wider set of counters counted by the device. The extended
 230 port statistics contains packets statistics per queue, Mac statistics, HW reset
 231 count and IO error count.
 232
 233 Finally per-flow statistics can by queried using ``rte_flow_query`` when attaching
 234 a count action for specific flow. The flow counter counts the number of packets
 235 received successfully by the port and match the specific flow.
 236
 237 Performance tuning
 238 ------------------
 239
 240 Hardware configuration
 241 ~~~~~~~~~~~~~~~~~~~~~~
 242 32 GB DIMMs is used to ensure that each channel is fully configured.
 243 Dynamic CPU Tuning is disabled.
 244
 245 Queue depth configuration
 246 ~~~~~~~~~~~~~~~~~~~~~~~~~
 247 According to the actual test, the performance is best when the queue depth
 248 ranges from 1024 to 2048.
 249
 250 IO burst configuration
 251 ~~~~~~~~~~~~~~~~~~~~~~
 252 According to the actual test, the performance is best when IO burst is set to 64.
 253 IO burst is the number of packets per burst.
 254
 255 Queue number configuration
 256 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 257 When the number of port queues corresponds to the number of CPU cores, the
 258 performance will be better.
 259
 260 Hugepage configuration
 261 ~~~~~~~~~~~~~~~~~~~~~~
 262 For 4K systems, 1 GB hugepages are recommended. For 64 KB systems, 512 MB
 263 hugepages are recommended.
 264
 265 CPU core isolation
 266 ~~~~~~~~~~~~~~~~~~
 267 To reduce the possibility of context switching, kernel isolation parameter should
 268 be provided to avoid scheduling the CPU core used by DPDK application threads for
 269 other tasks. Before starting the Linux OS, add the kernel isolation boot parameter.
 270 For example, "isolcpus=1-18 nohz_full=1-18 rcu_nocbs=1-18".
 271
 272
 273 Limitations or Known issues
 274 ---------------------------
 275 Currently, we only support VF device driven by DPDK driver when PF is driven
 276 by kernel mode hns3 ethdev driver. VF is not supported when PF is driven by
 277 DPDK driver.
 278
 279 Build with ICC is not supported yet.
 280 X86-32, Power8, ARMv7 and BSD are not supported yet.