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