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
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.
131 -a 0000:7d:00.0,mbx_time_limit_ms=600
133 Link status event Pre-conditions
134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
144 Driver compilation and testing
145 ------------------------------
147 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
150 Sample Application Notes
151 ------------------------
156 VLAN filter only works when Promiscuous mode is off.
158 To start ``testpmd``, and add VLAN 10 to port 0:
160 .. code-block:: console
162 ./<build_dir>/app/dpdk-testpmd -l 0-15 -n 4 -- -i --forward-mode=mac
165 testpmd> set promisc 0 off
166 testpmd> vlan set filter on 0
167 testpmd> rx_vlan add 10 0
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.
181 .. code-block:: console
183 ./<build_dir>/app/dpdk-testpmd -l 0-15 -n 4 -- -i --rxq=8 --txq=8 \
184 --nb-cores=8 --nb-ports=1
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:
189 .. code-block:: console
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
200 RSS Flow supports to set hash input set, hash function, enable hash
201 and configure queues.
203 Configure queues as queue 0, 1, 2, 3.
205 .. code-block:: console
207 testpmd> flow create 0 ingress pattern end actions rss types end \
208 queues 0 1 2 3 end / end
210 Enable hash and set input set for IPv4-TCP.
212 .. code-block:: console
214 testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \
215 actions rss types ipv4-tcp l3-src-only end queues end / end
217 Set symmetric hash enable for flow type IPv4-TCP.
219 .. code-block:: console
221 testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \
222 actions rss types ipv4-tcp end queues end func symmetric_toeplitz / end
224 Set hash function as simple xor.
226 .. code-block:: console
228 testpmd> flow create 0 ingress pattern end actions rss types end \
229 queues end func simple_xor / end
234 HNS3 supports various methods to report statistics:
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.
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.
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.
254 Hardware configuration
255 ~~~~~~~~~~~~~~~~~~~~~~
256 32 GB DIMMs is used to ensure that each channel is fully configured.
257 Dynamic CPU Tuning is disabled.
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.
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.
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.
274 Hugepage configuration
275 ~~~~~~~~~~~~~~~~~~~~~~
276 For 4K systems, 1 GB hugepages are recommended. For 64 KB systems, 512 MB
277 hugepages are recommended.
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".
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
293 For sake of Rx/Tx performance, IEEE 1588 is not supported when using vec or
294 sve burst function. When enabling IEEE 1588, Rx/Tx burst mode should be
295 simple or common. It is recommended that enable IEEE 1588 before ethdev
296 start. In this way, the correct Rx/Tx burst function can be selected.
298 Build with ICC is not supported yet.
299 X86-32, Power8, ARMv7 and BSD are not supported yet.