1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2018-2019 HiSilicon Limited.
5 ===============================
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 .
14 Features of the HNS3 PMD are:
16 - Multiple queues for TX and RX
17 - Receive Side Scaling (RSS)
18 - Packet type information
24 - Port hardware statistics
26 - Link state information
27 - Interrupt mode for RX
28 - VLAN stripping and inserting
31 - Scattered and gather for TX and RX
32 - Vector Poll mode driver
40 - IEEE1588/802.1AS timestamping
44 - Get the information about Kunpeng920 chip using
45 `<https://www.hisilicon.com/en/products/Kunpeng>`_.
47 - Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to
48 setup the basic DPDK environment.
51 Pre-Installation Configuration
52 ------------------------------
57 The following options can be modified in the ``config/rte_config.h`` file.
59 - ``RTE_LIBRTE_HNS3_MAX_TQP_NUM_PER_PF`` (default ``256``)
61 Number of MAX queues reserved for PF.
63 Runtime Config Options
64 ~~~~~~~~~~~~~~~~~~~~~~
66 - ``rx_func_hint`` (default ``none``)
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
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.
79 When provided parameter is not supported, ``vec`` usage condition will
80 be first checked, if meets, use the ``vec``. Then, ``simple``, at last
84 -a 0000:7d:00.0,rx_func_hint=simple
86 - ``tx_func_hint`` (default ``none``)
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
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
99 When provided parameter is not supported, ``vec`` usage condition will
100 be first checked, if meets, use the ``vec``. Then, ``simple``, at last
104 -a 0000:7d:00.0,tx_func_hint=common
106 - ``dev_caps_mask`` (default ``0``)
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.
116 -a 0000:7d:00.0,dev_caps_mask=0xF
119 Link status event Pre-conditions
120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
130 Driver compilation and testing
131 ------------------------------
133 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
136 Sample Application Notes
137 ------------------------
142 VLAN filter only works when Promiscuous mode is off.
144 To start ``testpmd``, and add VLAN 10 to port 0:
146 .. code-block:: console
148 ./<build_dir>/app/dpdk-testpmd -l 0-15 -n 4 -- -i --forward-mode=mac
151 testpmd> set promisc 0 off
152 testpmd> vlan set filter on 0
153 testpmd> rx_vlan add 10 0
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.
167 .. code-block:: console
169 ./<build_dir>/app/dpdk-testpmd -l 0-15 -n 4 -- -i --rxq=8 --txq=8 \
170 --nb-cores=8 --nb-ports=1
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:
175 .. code-block:: console
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
186 RSS Flow supports to set hash input set, hash function, enable hash
187 and configure queues.
189 Configure queues as queue 0, 1, 2, 3.
191 .. code-block:: console
193 testpmd> flow create 0 ingress pattern end actions rss types end \
194 queues 0 1 2 3 end / end
196 Enable hash and set input set for IPv4-TCP.
198 .. code-block:: console
200 testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \
201 actions rss types ipv4-tcp l3-src-only end queues end / end
203 Set symmetric hash enable for flow type IPv4-TCP.
205 .. code-block:: console
207 testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \
208 actions rss types ipv4-tcp end queues end func symmetric_toeplitz / end
210 Set hash function as simple xor.
212 .. code-block:: console
214 testpmd> flow create 0 ingress pattern end actions rss types end \
215 queues end func simple_xor / end
220 HNS3 supports various methods to report statistics:
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.
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.
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.
240 Hardware configuration
241 ~~~~~~~~~~~~~~~~~~~~~~
242 32 GB DIMMs is used to ensure that each channel is fully configured.
243 Dynamic CPU Tuning is disabled.
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.
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.
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.
260 Hugepage configuration
261 ~~~~~~~~~~~~~~~~~~~~~~
262 For 4K systems, 1 GB hugepages are recommended. For 64 KB systems, 512 MB
263 hugepages are recommended.
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".
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
279 Build with ICC is not supported yet.
280 X86-32, Power8, ARMv7 and BSD are not supported yet.