X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fnics%2Fhns3.rst;h=6fbeccddba5141d1b20a3bc9585bd9d0e0b239e3;hb=6be6690127744bb294005bfcf539508b3d5f389e;hp=d96ad5d445f04131911393512a5c6ed01de3e9dc;hpb=68d99d00ae7adc05791625c5e478deb34fd3f4fd;p=dpdk.git diff --git a/doc/guides/nics/hns3.rst b/doc/guides/nics/hns3.rst index d96ad5d445..6fbeccddba 100644 --- a/doc/guides/nics/hns3.rst +++ b/doc/guides/nics/hns3.rst @@ -1,12 +1,12 @@ .. SPDX-License-Identifier: BSD-3-Clause - Copyright(c) 2018-2019 Hisilicon Limited. + Copyright(c) 2018-2019 HiSilicon Limited. HNS3 Poll Mode Driver =============================== -The hns3 PMD (librte_pmd_hns3) provides poll mode driver support -for the inbuilt Hisilicon Network Subsystem(HNS) network engine -found in the Hisilicon Kunpeng 920 SoC. +The hns3 PMD (**librte_net_hns3**) provides poll mode driver support +for the inbuilt HiSilicon Network Subsystem(HNS) network engine +found in the HiSilicon Kunpeng 920 SoC and Kunpeng 930 SoC . Features -------- @@ -29,20 +29,102 @@ Features of the HNS3 PMD are: - QinQ inserting - DCB - Scattered and gather for TX and RX -- Flow director +- Vector Poll mode driver - Dump register - SR-IOV VF - Multi-process - MAC/VLAN filter - MTU update - NUMA support +- Generic flow API +- IEEE1588/802.1AS timestamping Prerequisites ------------- - Get the information about Kunpeng920 chip using - ``_. + ``_. -- Follow the DPDK :ref:`Getting Started Guide for Linux ` to setup the basic DPDK environment. +- Follow the DPDK :ref:`Getting Started Guide for Linux ` to + setup the basic DPDK environment. + + +Pre-Installation Configuration +------------------------------ + +Config File Options +~~~~~~~~~~~~~~~~~~~ + +The following options can be modified in the ``config/rte_config.h`` file. + +- ``RTE_LIBRTE_HNS3_MAX_TQP_NUM_PER_PF`` (default ``256``) + + Number of MAX queues reserved for PF. + +Runtime Config Options +~~~~~~~~~~~~~~~~~~~~~~ + +- ``rx_func_hint`` (default ``none``) + + Used to select Rx burst function, supported value are ``vec``, ``sve``, + ``simple``, ``common``. + ``vec``, if supported use the ``vec`` Rx function which indicates the + default vector algorithm, neon for Kunpeng Arm platform. + ``sve``, if supported use the ``sve`` Rx function which indicates the + sve algorithm. + ``simple``, if supported use the ``simple`` Rx function which indicates + the scalar simple algorithm. + ``common``, if supported use the ``common`` Rx function which indicates + the scalar scattered algorithm. + + When provided parameter is not supported, ``vec`` usage condition will + be first checked, if meets, use the ``vec``. Then, ``simple``, at last + ``common``. + + For example:: + -a 0000:7d:00.0,rx_func_hint=simple + +- ``tx_func_hint`` (default ``none``) + + Used to select Tx burst function, supported value are ``vec``, ``sve``, + ``simple``, ``common``. + ``vec``, if supported use the ``vec`` Tx function which indicates the + default vector algorithm, neon for Kunpeng Arm platform. + ``sve``, if supported use the ``sve`` Tx function which indicates the + sve algorithm. + ``simple``, if supported use the ``simple`` Tx function which indicates + the scalar simple algorithm. + ``common``, if supported use the ``common`` Tx function which indicates + the scalar algorithm. + + When provided parameter is not supported, ``vec`` usage condition will + be first checked, if meets, use the ``vec``. Then, ``simple``, at last + ``common``. + + For example:: + -a 0000:7d:00.0,tx_func_hint=common + +- ``dev_caps_mask`` (default ``0``) + + Used to mask the capability which queried from firmware. + This args take hexadecimal bitmask where each bit represents whether mask + corresponding capability. eg. If the capability is 0xFFFF queried from + firmware, and the args value is 0xF which means the bit0~bit3 should be + masked off, then the capability will be 0xFFF0. + Its main purpose is to debug and avoid problems. + + For example:: + -a 0000:7d:00.0,dev_caps_mask=0xF + + +Link status event Pre-conditions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Firmware 1.8.0.0 and later versions support reporting link changes to the PF. +Therefore, to use the LSC for the PF driver, ensure that the firmware version +also supports reporting link changes. +If the VF driver needs to support LSC, special patch must be added: +``_. +Note: The patch has been uploaded to 5.13 of the Linux kernel mainline. Driver compilation and testing @@ -51,12 +133,148 @@ Driver compilation and testing Refer to the document :ref:`compiling and testing a PMD for a NIC ` for details. +Sample Application Notes +------------------------ + +VLAN filter +~~~~~~~~~~~ + +VLAN filter only works when Promiscuous mode is off. + +To start ``testpmd``, and add VLAN 10 to port 0: + +.. code-block:: console + + .//app/dpdk-testpmd -l 0-15 -n 4 -- -i --forward-mode=mac + ... + + testpmd> set promisc 0 off + testpmd> vlan set filter on 0 + testpmd> rx_vlan add 10 0 + + +Flow Director +~~~~~~~~~~~~~ + +The Flow Director works in receive mode to identify specific flows or sets of +flows and route them to specific queues. +The Flow Director filters can match the different fields for different type of +packet: flow type, specific input set per flow type. + + +Start ``testpmd``: + +.. code-block:: console + + .//app/dpdk-testpmd -l 0-15 -n 4 -- -i --rxq=8 --txq=8 \ + --nb-cores=8 --nb-ports=1 + +Add a rule to direct ``ipv4-udp`` packet whose ``dst_ip=2.2.2.5, src_ip=2.2.2.3, +src_port=32, dst_port=32`` to queue 1: + +.. code-block:: console + + testpmd> flow create 0 ingress pattern eth / ipv4 src is 2.2.2.3 \ + dst is 2.2.2.5 / udp src is 32 dst is 32 / end \ + actions mark id 1 / queue index 1 / end + +Generic flow API +~~~~~~~~~~~~~~~~ + +- ``RSS Flow`` + + RSS Flow supports to set hash input set, hash function, enable hash + and configure queues. + For example: + Configure queues as queue 0, 1, 2, 3. + + .. code-block:: console + + testpmd> flow create 0 ingress pattern end actions rss types end \ + queues 0 1 2 3 end / end + + Enable hash and set input set for IPv4-TCP. + + .. code-block:: console + + testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \ + actions rss types ipv4-tcp l3-src-only end queues end / end + + Set symmetric hash enable for flow type IPv4-TCP. + + .. code-block:: console + + testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \ + actions rss types ipv4-tcp end queues end func symmetric_toeplitz / end + + Set hash function as simple xor. + + .. code-block:: console + + testpmd> flow create 0 ingress pattern end actions rss types end \ + queues end func simple_xor / end + +Statistics +---------- + +HNS3 supports various methods to report statistics: + +Port statistics can be queried using ``rte_eth_stats_get()``. The number +of packets received or sent successfully by the PMD. While the received and +sent packet bytes are through SW only. The imissed counter is the amount of +packets that could not be delivered to SW because a queue was full. The oerror +counter is the amount of packets that are dropped by HW in Tx. + +Extended statistics can be queried using ``rte_eth_xstats_get()``. The extended +statistics expose a wider set of counters counted by the device. The extended +port statistics contains packets statistics per queue, Mac statistics, HW reset +count and IO error count. + +Finally per-flow statistics can by queried using ``rte_flow_query`` when attaching +a count action for specific flow. The flow counter counts the number of packets +received successfully by the port and match the specific flow. + +Performance tuning +------------------ + +Hardware configuration +~~~~~~~~~~~~~~~~~~~~~~ +32 GB DIMMs is used to ensure that each channel is fully configured. +Dynamic CPU Tuning is disabled. + +Queue depth configuration +~~~~~~~~~~~~~~~~~~~~~~~~~ +According to the actual test, the performance is best when the queue depth +ranges from 1024 to 2048. + +IO burst configuration +~~~~~~~~~~~~~~~~~~~~~~ +According to the actual test, the performance is best when IO burst is set to 64. +IO burst is the number of packets per burst. + +Queue number configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~ +When the number of port queues corresponds to the number of CPU cores, the +performance will be better. + +Hugepage configuration +~~~~~~~~~~~~~~~~~~~~~~ +For 4K systems, 1 GB hugepages are recommended. For 64 KB systems, 512 MB +hugepages are recommended. + +CPU core isolation +~~~~~~~~~~~~~~~~~~ +To reduce the possibility of context switching, kernel isolation parameter should +be provided to avoid scheduling the CPU core used by DPDK application threads for +other tasks. Before starting the Linux OS, add the kernel isolation boot parameter. +For example, "isolcpus=1-18 nohz_full=1-18 rcu_nocbs=1-18". + + Limitations or Known issues --------------------------- -Currently, we only support VF device is bound to vfio_pci or -igb_uio and then driven by DPDK driver when PF is driven by -kernel mode hns3 ethdev driver, VF is not supported when PF -is driven by DPDK driver. +Currently, we only support VF device driven by DPDK driver when PF is driven +by kernel mode hns3 ethdev driver. VF is not supported when PF is driven by +DPDK driver. Build with ICC is not supported yet. X86-32, Power8, ARMv7 and BSD are not supported yet.