# openEuler WayCa SIG 板载网卡驱动(内核态)模块介绍 ## HNS3内核网卡驱动简介 - HNS3 driver是适配鲲鹏920系列处理器网络控制器的驱动模块,提供了完备的ethernet网卡功能。 基础特性已在linux kernel 5.5完成支持。新增重要特性为linux kernel 5.5及以上支持的特性, 涵盖特性简介和社区信息。 - **源码获取路径** linux kernel 仓库:[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git) openeuler 仓库:[https://gitee.com/openeuler/kernel.git](https://gitee.com/openeuler/kernel.git) 源码目录:**drivers/net/ethernet/hisilicon/hns3** - **内核相关配置** - HNS3模块涉及以下5个Config选项: | 配置项 | 功能 | | :---- | :---- | | CONFIG_HNS3 | 必选,基础配置 | | CONFIG_HNS3_ENET | 必选,基础配置 | | CONFIG_HNS3_HCLGE | 必选,基础配置 | | CONFIG_HNS3_HCLGEVF | 可选,HNS3提供的虚拟网卡功能 | | CONFIG_HNS3_DCB | 可选,DCB功能 | - 部分特性依赖的内核Config选项 | 配置项 | 功能 | | :---- | :---- | | CONFIG_RFS_ACCEL | 可选,aRFS功能 | | CONFIG_PCI_IOV | 可选,SRIOV功能 | | CONFIG_VLAN_8021Q | 可选,802.1Q VLAN卸载功能 | - **基础版本特性列表** - **支持多种接口形态** - 支持光口、电口、背板多种形态 - 支持10M/100M/1000M/10G/25G/40G/50G/100GbE多种速率 - 支持光模块自适应 - 支持端口自协商 - 支持端口速率双工配置 - **支持CPU卸载** - 支持TX/RX校验和卸载 - 支持TSO/GRO卸载 - 支持VLAN TAG卸载 - 支持RSS - 支持aRFS - 支持XPS - 支持流表 - **支持QoS** - 支持ETS - 支持PFC - 支持普通流控 - **支持vSwitch** - 支持MAC过滤 - 支持VLAN过滤 - **支持基本配置** - 支持配置mtu - 支持配置mac地址 - 支持配置混杂模式 - 支持中断聚合 - 支持配置队列数 - 支持配置队列深度 - **支持SR-IOV** - 最大支持248个VF,单PF最大支持128个VF - 支持配置VF mac地址 - 支持配置VF link状态 - 支持配置VF防欺诈 - 支持配置VF trust - 支持配置VF 带宽 - 支持配置VF VLAN - **支持故障检测和恢复处理** - 支持RAS - 支持异常中断处理 - 支持环回自检 - **新增重要特性包括** - 支持查询光模块 eeprom 信息 - 支持UDP GSO卸载 - 支持PTP(高精度时钟协议) - 支持硬件tc 卸载 - 支持各层级复位 - 支持 rx pagepool - 支持DSCP - 支持PMU ### 特性1: 支持查询光模块eeprom信息 - 特性介绍 光口上可能会插入不同类型的光模块介质,PF可以向IMP查询介质模块的eeprom信息,供上层应用读取和解析。可以用于识别检查设备介质是否被更换或故障定位。 - 内核相关配置 无 - 软件接口 可通过ethtool -m <pf name> [raw on|off] [hex on|off] [offset N] [length N]命令,来查询当前介质模块的eeprom信息。显示形式由参数决定,可以为二进制、十六进制、或解析后的文本形式。可自定义查询的偏移和长度。 驱动对外接口 <code>int hns3_get_module_eeprom(struct net_device *netdev, struct ethtool_eeprom *ee, u8 *data)</code> - 涉及代码与使能 linux 主线合入信息 | COMMITID | SUBJECT | TAG | | :----: | :----: | :----: | | cb10228d234c | [net: hns3: adds support for reading module eeprom info](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=cb10228d234c49e2035bfce7bdb42c29e1049c5c) | kernel v5.7-rc2 | openEuler OLK-5.10使能信息 | COMMITID | SUBJECT | openeuler OLK-5.10 ENABLED(Y/N) | | :----: | :----: | :----: | | cb10228d234c | net: hns3: adds support for reading module eeprom info | Y | ### 特性2: 支持UDP GSO卸载 - 特性介绍 UDP segment offload(UDP GSO),类似TSO(TCP GSO),使得应用层可能生成比实际MTU更多的网络报文, 实际大小受底层网络和链路层协议限制。网络协议栈能够将大块buffer推送至网卡,由网卡执行分片工作,这样减轻了CPU的负荷。鲲鹏920系列处理器上板载网卡硬件提供了对UDP报文的分片功能。此功能PF/VF可以单独使能,支持UDPv4/UDPv6 以及隧道报文。 - 内核相关配置 无 - 软件接口 驱动要声明支持NETIF_F_GSO_UDP_L4 feature, 方可使能此功能。可通过ethtool -K <devname> tx-udp-segmentation on/off 命令控制该功能的开启和关闭。 UDP协议并不是面向字节流的,如果要支持UDP GSO,它需要通过发送缓冲区的大小隐式地表示了数据报的边界。应用程序必须在send调用时**使用额外参数明确标示这个数据报的gso大小**(socket option SOL_UDP/UDP_SEGMENT 或control message,使用udpgso_bench_tx/rx工具测试时,如果不指定MSS,将由协议栈分段,指定时由硬件分段)。内核构造较大的数据报,并连同相应元数据传递给UDP和IP层。网络设备或GSO层接收大数据报,将有效负载分成gso大小的段,然后复制头部。 - 涉及代码与使能 linux 主线合入信息 | COMMITID | SUBJECT | TAG | | :----: | :----: | :----: | | 507e46ae26ea | [net: hns3: add getting capabilities of gro offload and fd from firmware](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=507e46ae26ea) | v5.18-rc7 | openEuler OLK-5.10使能信息 | COMMITID | SUBJECT | openeuler OLK-5.10 ENABLED(Y/N) | | :----: | :----: | :----: | | 72b042b4288c | net: hns3: add getting capabilities of gro offload and fd from firmware | Y | ### 特性3: 支持PTP - 特性介绍 PTP(precision time protocol),精确时钟协议,又称IEEE 1588(v2)协议,用于对分布式系统提供亚微秒级别的时钟同步功能。PTP作为一种主从同步系统,在系统过程中,主时钟周期性发布PTP时间同步协议及时间信息,从时钟端口接收主时钟端口发来的时间戳信息,系统据此计算出主从线路时间延迟及主从时间差,并利用时间差调整本地时间,使从设备时间保持与主设备时间一致的频率和相位。 - 内核相关配置 | 配置项 | 功能 | | :---- | :---- | | CONFIG_PTP_1588_CLOCK | 可选,ptp功能 | - 软件接口 可通过ethtool -T <pf_name> 查询当前物理设备支持的时钟能力。 驱动侧实现ndo_do_ioctl接口和ethtool_ops. get_ts_info接口,对应SIOCGHWTSTAMP,返回硬件时间戳信息配置,包括hwtstamp_tx_types和hwtstamp_rx_filters。 Linux提供了标准的ptp配置工具,需要安装linuxptp,详见ptp4l/ptp2sys,使用方法可以参考[redhat的帮助文档](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/deployment_guide/s1-starting_ptp4l)。 - 涉及代码与使能 linux 主线合入信息 | COMMITID | SUBJECT | TAG | | :----: | :----: | :----: | | 0bf5eb788512 | [net: hns3: add support for PTP](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0bf5eb788512) | v5.13-rc3 | | b34c157f0cdd | [net: hns3: add debugfs support for ptp info](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=b34c157f0cdd) | v5.13-rc3 | | 8373cd38a888 | [net: hns3: change the method of obtaining default ptp cycle](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=8373cd38a888) | v5.13-rc3 | openEuler OLK-5.10使能信息 | COMMITID | SUBJECT | openeuler OLK-5.10 ENABLED(Y/N) | | :----: | :----: | :----: | | 56acfb181aba | net: hns3: add support for PTP | Y | | 0e093eb72d95 | net: hns3: add debugfs support for ptp info | Y | | f61992ad87f2 | net: hns3: change the method of obtaining default ptp cycle | Y | ### 特性4: 支持硬件tc 卸载 - 特性介绍 基线版本的驱动中,只支持了TC_MQPRIO_MODE_DCB模式,卸载了用户优先级和TC之间的映射关系,新驱动对此进行了增强,通过指定channel模式和hw配置全卸载,即TC_MQPRIO_MODE_CHANNEL模式,可以进一步为每个TC指定队列(各个TC可以不同,但受硬件限制,要求都是2的指数幂)。 - 内核相关配置 | 配置项 | 功能 | | :---- | :---- | | CONFIG_NET_SCH_MQPRIO | 可选,硬件tc卸载功能 | - 软件接口 可通过tc qdisc命令进行配置,参数如下: <code>tc qdisc add dev <pf name> root mqprio num_tc <tc num> map <P0 P1 P2... > queues count1@offset1 count2@offset2 ... hw 1 mode channel</code> 如命令<code>tc qdisc add eth1 root mqprio num_tc 4 map 0 2 4 6 queues 4@0 8@4 8@12 4@20 hw 1 mode channel</code> 表示为eth1配置使能4个tc,优先级2映射tc1, 优先级4映射tc2, 优先级6映射tc3,其余优先级映射tc0, tc0绑定队列0-3,tc1绑定队列4-11,tc2绑定队列12-19,tc3绑定队列20-23。 清除配置命令 <code>tc qdisc del dev eth1 root</code> 查询配置命令 <code>tc filter show dev eth1 parent ffff:</code> - 涉及代码与使能 linux 主线合入信息 | COMMITID | SUBJECT | TAG | | :----: | :----: | :----: | | 35244430d624 | [net: hns3: refine the struct hane3_tc_info](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=35244430d624) | v5.10-rc6 | | 5a5c90917467 | [net: hns3: add support for tc mqprio offload](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=5a5c90917467) | v5.10-rc6 | | ae9e492a3664 | [net: hns3: remove redundant client_setup_tc handle](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ae9e492a3664) | v5.11-rc6 | | 0472e95ffeac | [net: hns3: fix mixed flag HCLGE_FLAG_MQPRIO_ENABLE and HCLGE_FLAG_DCB_ENABLE](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0472e95ffeac) | v5.15-rc2 | | 161ad669e6c2 | [net: hns3: reconstruct function hclge_ets_validate()](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=161ad669e6c2) | v5.14-rc7 | | d82650be60ee | [net: hns3: don't rollback when destroy mqprio fail](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=d82650be60ee) | v5.15-rc2 | | a8e76fefe3de | [net: hns3: remove tc enable checking](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=a8e76fefe3de) | v5.15-rc2 | openEuler OLK-5.10使能信息 | COMMITID | SUBJECT | openeuler OLK-5.10 ENABLED(Y/N) | | :----: | :----: | :----: | | e887fccc775f | net: hns3: refine the struct hane3_tc_info | Y | | 46961be39152 | net: hns3: add support for tc mqprio offload | Y | | bdb36e4c1180 | net: hns3: remove redundant client_setup_tc handle | Y | | 9bb0177d462e | net: hns3: fix mixed flag HCLGE_FLAG_MQPRIO_ENABLE and HCLGE_FLAG_DCB_ENABLE | Y | | 688795be38d6 | net: hns3: reconstruct function hclge_ets_validate | Y | | ba250d23d0c6 | net: hns3: don't rollback when destroy mqprio fail | Y | | dad19338e6a5 | net: hns3: remove tc enable checking | Y | ### 特性5: 支持各层级复位 - 特性介绍 - 支持function复位 function复位包含PF复位和VF复位,PF产生了复位,其管理的所有VF也要一起复位。当VF复位时,仅需复位VF自身。复位前后,网卡的配置保持一致。 - PF支持global复位 global复位是整个DIE上所有PF、VF复位。通常是在硬件发生严重故障时发生,需要通过global复位重置更多硬件模块才可能恢复。 - PF支持IMP复位 IMP复位不仅复位整个DIE上所有PF、VF,同时还复位IMP固件。在硬件处理上,IMP复位重置的硬件模块和global复位一样。 优先级上 IMP复位 > Global复位 > Function复位,同时产生多个复位源时,优先执行高优先级复位 - 支持FLR复位 FLR复位是由PCIE框架下发的复位请求,与function复位类似,区别是触发调用的接口不同。 - 内核相关配置 FLR依赖PCIe的capbility中置位FLR能力,为可选项 - 复位触发源 - 异常中断 当芯片检测到NIC硬件异常时,会上报异常中断,NIC驱动会从IMP查询异常中断源及建议恢复方式,包括仅记录日志、VF复位、PF复位、Global复位和IMP复位。 - tx timeout tx timeout是协议栈的发包超时检测机制,默认单个报文5秒钟未发送完成,则会调用NIC驱动的发包超时处理接口。默认处理为function复位。 - pci框架触发 解绑或绑定pci设备时,会触发FLR复位 AER故障恢复时触发复位 - 用户接口触发 通过ethtool工具可以触发PF复位、VF复位、global复位和imp复位 echo命令触发flr复位 - 软件接口 - 支持function复位 用户可以通过ethtool --reset ethX dedicated对网口发起function复位。 - 支持FLR复位 用户可通过“echo 1 > /sys/class/net/ethx/device/reset”命令直接发起FLR。FLR依赖PCIe的capbility中置位FLR能力,为可选项。需避免FLR复位与其他复位并发。 - PF支持global复位 用户可以通过ethtool --reset ethx all发起global复位。 - PF支持IMP复位 用户可以通过ethtool --reset ethx mgmt发起IMP复位 - 涉及代码与使能 linux 主线合入信息 | COMMITID | SUBJECT | TAG | | :----: | :----: | :----: | | ddccc5e368a3 | [net: hns3: add support for triggering reset by ethtool](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ddccc5e368a3) | v5.14-rc4 | | 82229c4dbb8a | [net: hns3: fix incorrect components info of ethtool --reset command](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=82229c4dbb8a) | v5.16-rc3 | openEuler OLK-5.10使能信息 | COMMITID | SUBJECT | openeuler OLK-5.10 ENABLED(Y/N) | | :----: | :----: | :----: | | 3d489ec0f3a4 | net: hns3: add support for triggering reset by ethtool | Y | | 238a3d250c35 | net: hns3: fix incorrect components info of ethtool --reset command | Y | ### 特性6: 支持DSCP - 特性介绍 DSCP由RFC2474定义,它重新命名了IPv4报头中TOS字节和IPv6报头中数据类(TrafficClass)字节,新的名字称为DS字段(Differentiated ServicesField)。该字段的作用没有变,仍然被QoS工具用来标记数据。DSCP使用高6bit,最低2bit特不用,DSCP范围为0~63。驱动新增配置DSCP和TC的映射。 - 内核相关配置 无 - 软件接口 驱动下发优先级和TC映射命令给IMP时,IMP会将芯片切到priority映射TC模式。驱动下发DSCP和TC映射命令给IMP时,IMP会将芯片切到DSCP映射TC模式。当前dcb标准工具和协议栈支持配置DSCP和priority的映射,驱动新增实现配置DSCP和priority映射的接口,并在驱动中转换成DSCP和TC的映射。 在debugfs的tm目录增加qos_dscp_map文件,用户cat此文件时将DSCP与priority、TC的映射关系打印出来(仅打印用户已配置的DSCP),以及当前TC映射的模式。 - 涉及代码与使能 linux 主线合入信息 | COMMITID | SUBJECT | TAG | | :----: | :----: | :----: | | dfea275e06c2 | [net: hns3: optimize converting dscp to priority process of hns3_nic_select_queue()](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=dfea275e06c2) | v5.18-rc7 | | fddc02eb583a | [net: hns3: debugfs add dump dscp map info](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=fddc02eb583a) | v5.18-rc7 | | f6e32724ca13 | [net: hns3: support ndo_select_queue()](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f6e32724ca13) | v5.18-rc7 | | 0ba22bcb222d | [net: hns3: add support config dscp map to tc](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0ba22bcb222d) | v5.18-rc7 | | cfdcb075048c | [net: hns3: fix get wrong value of function hclge_get_dscp_prio()](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=cfdcb075048c) | v5.18-rc7 | openEuler OLK-5.10使能信息 | COMMITID | SUBJECT | openeuler OLK-5.10 ENABLED(Y/N) | | :----: | :----: | :----: | | 3f0019a0e172 | net: hns3: optimize converting dscp to priority process of hns3_nic_select_queue() | Y | | da7620f6b113 | net: hns3: debugfs add dump dscp map info | Y | | 757d2e9b7454 | net: hns3: support ndo_select_queue() | Y | | 7a1313b356de | net: hns3: add support config dscp map to tc | Y | | fb96fb425027 | net: hns3: fix get wrong value of function hclge_get_dscp_prio() | Y | ### 特性7: 支持PMU - 特性介绍 在分析端到端的性能瓶颈时,需要分析软件和硬件每个处理阶段的耗时。硬件在鲲鹏920系列处理器上为板载网卡提供了IO PMU硬件模块,NIC驱动以实现一个perf驱动的方式将该模块适配到内核的perf框架中,并提供合理的用户接口给perf用户。用户可以用IO PMU模块来收集在实际业务场景下的硬件关键点的耗时点。 - 内核相关配置 | 配置项 | 功能 | | :---- | :---- | | CONFIG_HNS3_PMU | 可选,IO PMU功能 | - 软件接口 功能使能需要加载模块hns3_pmu.ko。设备路径名/sys/devices/hns3_pmu_sicl_\<sicl_id> 。可通过命令进行事件查询perf stat -g -e hns3_pmu_sicl_0/config=0x00002,global=1/ -e hns3_pmu_sicl_0/config=0x10002,global=1/ -I 1000, 其中config=0xXXXXX代表查询事件。查询显示结果为两列查询事件统计信息, 一列是counter数据,主要事件有: 字节数,包个数,时钟数,中断个数; 另一列是ext_counter数据, 主要事件有: 包个数,时钟数。对数据进行统计计算可以计算出事件的检测值, 计算公式为result = counter ÷ ext_counter - 涉及代码与使能 | COMMITID | SUBJECT | TAG | | :----: | :----: | :----: | | aaaee7b55c9e | [docs: perf: Include hns3-pmu.rst in toctree to fix 'htmldocs' WARNING](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=aaaee7b55c9e) | v5.18-rc7 | | 66637ab137b4 | [drivers/perf: hisi: add driver for HNS3 PMU](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=66637ab137b4) | v5.18-rc7 | | 39915b6b5fc2 | [drivers/perf: hisi: Add description for HNS3 PMU driver](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=39915b6b5fc2) | v5.18-rc7 | openEuler OLK-5.10使能信息 | COMMITID | SUBJECT | openeuler OLK-5.10 ENABLED(Y/N) | | :----: | :----: | :----: | | 494f4da5dbc1 | docs: perf: Include hns3-pmu.rst in toctree to fix 'htmldocs' WARNING | Y | | 5766c797a02a | drivers/perf: hisi: add driver for HNS3 PMU | Y | | 36b83702e3cc | drivers/perf: hisi: Add description for HNS3 PMU driver | Y |