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 Driver compilation and testing
119 ------------------------------
121 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
124 Sample Application Notes
125 ------------------------
130 VLAN filter only works when Promiscuous mode is off.
132 To start ``testpmd``, and add VLAN 10 to port 0:
134 .. code-block:: console
136 ./<build_dir>/app/dpdk-testpmd -l 0-15 -n 4 -- -i --forward-mode=mac
139 testpmd> set promisc 0 off
140 testpmd> vlan set filter on 0
141 testpmd> rx_vlan add 10 0
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.
155 .. code-block:: console
157 ./<build_dir>/app/dpdk-testpmd -l 0-15 -n 4 -- -i --rxq=8 --txq=8 \
158 --nb-cores=8 --nb-ports=1
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:
163 .. code-block:: console
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
174 RSS Flow supports to set hash input set, hash function, enable hash
175 and configure queues.
177 Configure queues as queue 0, 1, 2, 3.
179 .. code-block:: console
181 testpmd> flow create 0 ingress pattern end actions rss types end \
182 queues 0 1 2 3 end / end
184 Enable hash and set input set for IPv4-TCP.
186 .. code-block:: console
188 testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \
189 actions rss types ipv4-tcp l3-src-only end queues end / end
191 Set symmetric hash enable for flow type IPv4-TCP.
193 .. code-block:: console
195 testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \
196 actions rss types ipv4-tcp end queues end func symmetric_toeplitz / end
198 Set hash function as simple xor.
200 .. code-block:: console
202 testpmd> flow create 0 ingress pattern end actions rss types end \
203 queues end func simple_xor / end
208 HNS3 supports various methods to report statistics:
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.
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.
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.
228 Hardware configuration
229 ~~~~~~~~~~~~~~~~~~~~~~
230 32 GB DIMMs is used to ensure that each channel is fully configured.
231 Dynamic CPU Tuning is disabled.
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.
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.
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.
248 Hugepage configuration
249 ~~~~~~~~~~~~~~~~~~~~~~
250 For 4K systems, 1 GB hugepages are recommended. For 64 KB systems, 512 MB
251 hugepages are recommended.
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".
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
267 Build with ICC is not supported yet.
268 X86-32, Power8, ARMv7 and BSD are not supported yet.