做BSP调试的时间长了你会发现一个很典型的规律几乎每一块新打样的板子最先卡住你的往往不是CPU主频、不是DDR初始化而是最不起眼的网口。系统能起来串口有输出但SSH连不上、NFS挂不上后续所有工作全部卡壳。这次要讲的是一块RK3588平台的Ethernet调试过程现象并不复杂核心板能跑配套底板的网口就是不出来ifconfig下面孤零零一个lo。整个排查链路从设备树查到驱动日志从驱动日志查到MDIO再从MDIO查到板级原理图上的一颗漏贴上拉电阻前后花了大概半天。过程里用到的排查思路和踩过的坑对同样在做RK3588或者其他平台BSP调试的人应该有挺多可复用的地方。这篇内容主要围绕RK3588 Ethernet相关的三个层面展开硬件数据链路与PHY管理通道、设备树配置的细节、以及从“网口出不来”到“千兆吞吐稳定”的完整调试方法。适合正在做嵌入式底层开发、Linux BSP移植或者刚拿到RK3588开发板想彻底搞懂网口原理的工程师参考。如果你只是调个应用层网络这篇文章对你可能有点深但理解MAC和PHY的分工之后排查网络问题的思路也会清晰很多。1. RK3588 Ethernet调试前必须想清楚的硬件链路1.1 数据路径一个数据包从CPU到网线的完整旅程RK3588内部集成的是GMAC控制器也就是MAC层。MAC负责组帧、校验、流控、中断处理、地址过滤但它自己不直接驱动网线。MAC通过RGMII接口和一颗外部PHY芯片相连RGMII负责搬运数据同时有一根125MHz的时钟线做同步参考。PHY才是真正干“物理层脏活累活”的角色编码、符号映射、载波侦听、自动协商全部是它的事。从PHY出来之后信号经过网络变压器耦合进RJ45座再经过网线进入对端设备的PHY。你可以简单理解成MAC是负责写信封、写信的人RGMII是递信的路PHY是邮递员变压器是防雷雨的保护伞RJ45是小区门口的信箱。BSP调试的边界通常就划在“MAC到PHY”这一段变压器和RJ45的硬件问题一般扔给硬件测试去查。这块RK3588平台一共有两个GMAC控制器多数方案只用一个接千兆以太网另一个可能空着或者接内部交换芯片。调试前我习惯先看一眼原理图确认当前用的是gmac0还是gmac1以及PHY挂在哪路MDIO下。不要小看这一步很多人设备树改了半天结果发现使能错节点了。1.2 容易被忽略的MDIO一条决定成败的慢速管理总线除了RGMII数据线MAC和PHY之间还有一条MDIO总线它由两根线组成MDC时钟和MDIO数据。RGMII上跑的是业务流量MDIO上跑的是管理信息。MAC通过MDIO读写PHY内部的寄存器去配置速率、双工模式、协商方式、中断、EEE省电功能等等。调试网口时很多找不到头绪的问题根子就在MDIO上PHY ID读不到、寄存器写不进去、PHY驱动绑定不上全部和这条慢速总线有关。MDIO本身是一根双向数据线空闲时需要保持高电平因此PHY侧必须有上拉电阻。这块板子最终的问题就是原理图上画了上拉但BOM漏贴导致MDIO电平被拉不起来MAC永远读不到PHY的ID。这里有个对BSP工程师来说救命级的认知只要能通过MDIO读到PHY的ID和基本寄存器就说明MAC到PHY的物理链路已经成立剩下的问题都可以靠配置解决如果读不到问题基本锁定在硬件连接、PHY供电、复位电平或者上拉电阻这一类板级因素上。1.3 从启动日志快速判断MAC驱动到底有没有起来RK3588的网口驱动使用的是Linux内核里的stmmac驱动设备树中节点名一般是gmac0或者gmac1。开机后可以用一句话过滤出所有相关信息dmesg | grep -E eth|stmmac|phy|mdio正常的启动日志会包含类似这样的行stmmaceth eth0: PHY [0x0044] driver [YT8512] (IRQPOLL)看到PHY ID和驱动名说明MDIO链路通、PHY被正确识别后面如果link不起来问题在配置或者PHY寄存器如果看到的是stmmaceth eth0: no PHY found那问题就出在PHY探测阶段。更麻烦的是连“no PHY found”都没有这时候要优先怀疑设备树节点是否使能、引脚复用是否正确、驱动是否真的被编译进内核。拿到新板子别急着改代码先把这条日志流程跑通能省掉后面一大半的弯路。2. 设备树里的Ethernet节点每一行配置都值得较真2.1 一个最小可用的gmac0配置与逐行解释RK3588的网口设备树配置看起来不难翻来覆去就十几个字段但每个字段背后都对应着一个真实的硬件行为。下面是一个最小可用的gmac0配置我逐条解释。gmac0 { status okay; phy-mode rgmii; clock_in_out input; snps,reset-gpio gpio3 RK_PB5 GPIO_ACTIVE_LOW; snps,reset-active-low; snps,reset-delays-us 0 10000 30000; phy-handle phy0; pinctrl-names default; pinctrl-0 gmac0_rgmii_bus; };phy-mode rgmii声明MAC和PHY之间的接口类型。RK3588最常见的是RGMII因为它能跑千兆。后面我会专门讲rgmii/rgmii-id/rgmii-rxid这几个值的差别这一行选错就会出现“能link但ping不通”这种玄学问题。clock_in_out input决定125MHz参考时钟由谁提供。设为“input”表示MAC接收PHY送来的时钟由PHY做主时钟源设为“output”则反过来。这个必须和原理图上的时钟走线方向保持一致。snps,reset-gpioPHY复位脚对应的GPIO。GPIO_ACTIVE_LOW表示低电平复位snps,reset-active-low是配套的标志位。这两个东西不匹配PHY可能永远被按在复位状态里。snps,reset-delays-us 0 10000 30000三个数分别是复位前延时、复位脉冲宽度、复位后延时。PHY芯片通常要求上电稳定后等待若干毫秒才能访问MDIO这个字段就是在设备树层面保证时序。phy-handle phy0指向下面mdio子节点里定义的具体PHY。pinctrl-0 gmac0_rgmii_bus配置RGMII所有信号线的引脚复用包括TX/RX数据线、控制线和时钟线。对应的mdio子节点长得是这样mdio0 { compatible snps,dwmac-mdio; #address-cells 1; #size-cells 0; phy0: ethernet-phy0 { reg 0; }; };ethernet-phy0里的reg地址就是这颗PHY在MDIO总线上的地址它由PHY芯片的地址引脚决定不是随便写的。2.2 phy-mode的四种典型取值与延迟补偿逻辑RGMII接口在电气上有一个历史遗留问题标准RGMII要求数据信号相对于参考时钟有大约2ns的 skew但不同芯片的实现方式不一样。MAC侧可能已经做了内部延迟PHY侧也可能做了两边都做或者都不做信号就会错位表现出来就是链路协商成功、收发灯在闪但ping就是不通或者丢包率达到两位数。常见的四种取值rgmiiMAC和PHY都不做内部延迟依赖PCB走线等长来保证时序。原型板阶段很容易翻车。rgmii-idMAC和PHY都做内部延迟通常是最省心的选择。rgmii-txid只做TX方向延迟适合PHY侧RX已经自带延迟的情况。rgmii-rxid只做RX方向延迟适合PHY侧TX已经自带延迟的情况。调试时先看PHY芯片手册里关于延迟控制的说明再看参考设计的接法。多数公板方案用rgmii-id能跑通千兆但如果PHY本身自带rx delay而MAC也打开了就会过补偿。我自己习惯先用rgmii-id跑一遍如果TX方向误码率偏高就改成rgmii-rxid再在PHY寄存器里微调。2.3 PHY地址、引脚复用和复位引脚的联动关系很多人改设备树时会忽略一个细节ethernet-phy0的reg值必须和PHY芯片地址引脚上的电平一致。PHY的地址引脚通常有5位硬件通过上下拉将地址固定成某个值常见是0到7。MAC在MDIO总线上扫描时会轮询每个地址只有地址匹配的PHY才会回应。如果reg值写错现象同样是“no PHY found”但MDIO物理链路其实完全正常。区分方法也简单在uboot里执行mdio list它能扫描出MDIO上真实存在的PHY及其地址。设备树reg和硬件地址对不上时改reg即可不用动硬件。复位引脚则是另一个“改了就好”的经典问题。Linux的stmmac驱动会在probe阶段按照设备树里的reset配置去拉复位线但前提是这个GPIO没有被别的驱动占用也没有被pinctrl复用成别的功能。某些板子的复位脚和调试串口、SD卡等功能引脚靠得很近mux配置冲突会导致复位时序完全错乱PHY时而正常时而失联。这种问题最难排查因为你看到的日志是随机的PHY ID错误而不是一次性的启动失败。3. 实战排查一块底板从“没有eth0”到跑通千兆3.1 第一阶段确认软件层面MAC到底起来没有拿到这块出问题的底板我先跑了一遍开头那条dmesg过滤命令结果是stmmaceth eth0: no PHY found这个输出其实是个好消息MAC控制器已经成功probe设备树节点、时钟、引脚复用这些基础配置都是对的问题收敛到了PHY探测环节。为了进一步确认我查看了MDIO总线上的设备列表ls /sys/bus/mdio_bus/devices/输出是空的说明在Linux侧一个PHY都没注册上来。到这里问题可以完全聚焦在MDIO链路和PHY本身后面的排查就不需要再碰设备树和驱动源码了。3.2 第二阶段uboot阶段用mdio命令直接读PHY软件层面足够干净之后下一步是把战线拉到uboot绕过Linux驱动直接和硬件对话。uboot里提供了mii/mdio命令可以完成PHY寄存器的底层读写 mdio list正常情况下列出MDIO总线上所有PHY但这块板子没有任何输出。再试试直接按地址读 mii read 0 0 FFFF FFFF读到的寄存器值全是FFFF等于说PHY根本没有应答。到这里基本可以断定PHY ID读不到不是Linux驱动的问题而是硬件链路上存在断点。剩下的工作就是用示波器和万用表去定位断点在哪。3.3 第三阶段万用表测供电、复位和上拉电阻硬件定位的顺序很重要别上来就查RGMII高速信号先查PHY能不能正常工作。第一步查供电量PHY芯片的电源引脚3.3V和1.0V或者1.05V都在说明供电没断。第二步查复位量复位脚电平正常应该处于非复位状态实测是高电平说明复位也是正常的。第三步查MDIO数据线的空闲电平MDIO是双向线空闲必须被上拉到高电平结果万用表显示电压只有0.2V左右明显不对。顺着MDIO信号往回找原理图上PHY的MDIO引脚附近画了一个2.2k欧姆的上拉电阻到3.3V但PCB板上这个位置是空的。对照BOM单才发现是贴片漏料这个电阻根本没贴。MDIO线没有被上拉MAC自然无法和PHY建立管理通道。原因找到之后补上一颗2.2k电阻重新上电dmesg里立刻出现了PHY ID和驱动绑定信息。前后花了半天真正的根因就是一颗电阻。3.4 第四阶段修复后的完整验证流程修完电阻不代表万事大吉网口要真正能用必须走一套完整的验证流程。第一步确认PHY识别和链路协商ifconfig eth0 up dmesg | tail -20能看到类似Link is up - 1Gbps/Full - flow control rx/tx的输出说明千兆协商成功。第二步配置IP并验证二层连通性ifconfig eth0 192.168.1.10 netmask 255.255.255.0 up ping -c 4 192.168.1.1第三步打流验证吞吐iperf3 -c 192.168.1.1 -t 30这一步是为了确认不只是“能通”而是真正达到千兆性能。如果只能跑到百兆后面大概率还有延迟补偿方面的坑等着你。4. 比“PHY ID读不到”更隐蔽的四个坑4.1 能link但ping不通先检查phy-mode的延迟补偿PHY ID能读到、链路也能协商成1000M但ping就是丢包这是调试过程中最容易让人烦躁的一类问题。根因绝大多数是RGMII的延迟补偿没有配对。你可以这么理解RGMII的数据线和时钟线就像两个人打电话一个人抢拍半句另一个人拖拍半句两边都觉得对方说得快内容全是乱的。解决办法是在设备树phy-mode里选择合适的模式或者在PHY寄存器里打开/关闭内部延迟。如果手头有uboot可以先用mdio命令直接改PHY寄存器做验证确认某个寄存器组合能跑通再回设备树固化配置效率比反复改设备树重启高得多。4.2 复位引脚悬空或者被复用冷启动正常reboot之后eth0消失这个坑的典型现象是第一次开机网口正常reboot之后eth0没了再reboot一次可能又好了。PHY复位脚如果悬空电平状态会在各种噪声干扰下跳变导致PHY在初始化过程中被意外复位。解决办法是设备树里明确配置snps,reset-gpio并确保该GPIO没有被pinctrl复用成其他功能。另外要注意snps,reset-active-low和GPIO_ACTIVE_LOW必须搭配使用。只写其中一个驱动可能在拉高拉低的方向上搞反时序完全错乱。4.3 MAC地址不唯一DHCP随机分配导致网段里“撞车”调试阶段很多人不关心MAC地址但一旦多块板子接在同一个交换机上问题立刻暴露。如果设备树或驱动里没定义唯一MAC部分平台会从随机数生成导致重启一次换个IP更坑的是某些板子直接用全0或者全FF对端交换机会直接拒绝转发。量产时必须从eFuse或OTP里读取烧录好的唯一MAC在bootloader阶段写入设备树。调试阶段至少手动固定一下ifconfig eth0 hw ether 00:30:64:11:22:33注意不要用全0、全1或者组播地址这属于基本网络常识但BSP调试时确实有人这么干过然后排查了一下午为什么ping不通。4.4 休眠唤醒后PHY失联suspend/resume流程中的常见翻车点系统休眠后网卡进入suspend状态PHY通常会被下电或者复位。resume之后如果MAC和PHY的初始化顺序不对PHY会一直处于失联状态。现象是休眠再唤醒后网络不通ifconfig eth0还在但ping不通网关。一个常用的绕行方案是在resume脚本里强制重新初始化网卡ifconfig eth0 down ifconfig eth0 up udhcpc长期项目里更推荐检查内核里stmmac驱动的suspend/resume回调确认resume后PHY有没有重新probe。这个坑在不同内核版本上表现不太一样遇到一次做完记录比每次重新排查强得多。5. 千兆性能调优把网口从“能通”调到“好用”5.1 确认内核配置里stmmac相关的开关先确认内核配置CONFIG_STMMAC_ETHy CONFIG_VLAN_8021Qy如果你用VLAN同时确认NAPI和GRO是开启的这直接影响中断处理和大包收发的效率。在驱动层面设备树里可以给mac节点增加snps,multiquad等配置来打开多队列支持具体要看内核版本的驱动能力。5.2 ring buffer和队列参数调整网口跑起来之后先用ethtool看看当前队列和ring缓冲的状态ethtool -l eth0 ethtool -G eth0 rx 4096 tx 4096RK3588的GMAC支持多队列默认可能只开了单个队列。开启多队列后不同队列的中断可以分发到不同CPU核上配合RPS/RSS可以显著降低单核压力。ethtool -L eth0 combined 4这一步不是越大越好每个队列都会占用内存ring buffer太大会对吞吐帮助不大反而增加延迟。实际测试下来接收ring从默认512调到4096大包多并发场景下的丢包率明显下降但内存占用也会增加几MB在内存紧张的嵌入式产品里需要权衡。5.3 中断合并参数用延迟换CPU中断合并是典型的“用延迟换CPU占用”的手段。默认配置下网卡每收到一个包就触发一次中断高流量场景下CPU大量时间耗在处理中断上。调整合并参数ethtool -C eth0 rx-usecs 100 rx-frames 16这样网卡会攒够16个包或者100微秒才上报一次中断CPU占用能下降不少。代价是单包延迟增加对实时性要求高的业务需要谨慎。实测下来一块RK3588平台在默认配置下跑iperf3双向CPU占用大概35%合并参数调到100us之后CPU占用降到15%左右吞吐反而因为中断减少稍微提升了一点。5.4 实测不同配置的吞吐与CPU占用配置项默认值调优值实测效果RX ring buffer5124096大包高并发场景丢包率下降约60%接收队列数14多核负载更均衡CPU峰值下降rx-usecs0100CPU占用从35%降到15%单包延迟略有增加双向吞吐700Mbps940Mbps达到千兆预期这套参数适合NVR、边缘网关这类对吞吐要求高、对延迟不敏感的产品。如果做工业实时控制建议关闭中断合并把延迟优先放在第一位。调优没有银弹一切以业务模型为准。6. 量产阶段躲不开的网口杂症6.1 网口指示灯不亮但业务完全正常这类问题往往不影响功能但很影响用户心情和产线判断。PHY芯片的LED引脚由PHY内部寄存器控制默认配置可能是“linkactivity”模式和板级LED的连接逻辑不一定对得上。解决办法是查PHY手册里的LED配置寄存器把LED行为改成“千兆link常亮、有流量闪烁”。如果量产后才发现灯不亮可以先在uboot里用mdio工具改寄存器验证 mii write 0 27 0x0010不同的PHY寄存器布局不同这里只是举例。改成正确配置后把PHY的初始化固化在uboot里设备树驱动probe时自动执行避免每个板子在Linux启动后被驱动重新打回默认配置。6.2 EEE省电模式在部分交换机上导致的偶发断流EEE是802.3az标准里的节能以太网物理层在低流量时可以进入低功耗模式。它在现代高端交换机上工作很好但接入一些老交换机或者长距离网线时兼容性会出现问题表现是长时间空闲后的第一包数据要等很久或者高流量时偶发断流。这种问题极难复现因为它在轻负载下才出现。排查时可以先关闭PHY的EEE功能设备树里可以用eee-disable标志或者通过ethtoolethtool --set-eee eth0 eee off确认有效后固化到配置里。EEE省的电在嵌入式产品上其实微不足道为了兼容性直接关掉是很多批量项目的常规操作。6.3 高低温环境下千兆协商失败延迟余量不足的真实案例有一次做高低温测试常温下一切正常环境温度升到60度时网口协商从1000M掉到100M偶尔还会彻底掉线。这种温度相关的link不稳多数是RGMII延迟余量不足温度漂移导致信号时序偏离阈值。处理手段是尽量把延迟补偿从依赖PCB走线的外部模式改成PHY/MAC内部的rgmii-id模式让芯片内部的延迟单元跟随时钟自适应余量好很多。再把设备树里的phy-mode从rgmii改成rgmii-id同一块板子在60度环境下跑满千兆就稳定了。所以量产项目我一般直接建议参考设计优先选rgmii-id虽然不能解决所有问题但大部分温度漂移导致的时序问题都能规避。6.4 批量板一致性不同批次PHY表现不一产线反馈偶尔会有几块板子网口慢复现发现是PHY芯片供货批次不同内部寄存器默认值有差异。这种问题在研发阶段很难遇到因为手里就那么几颗料。量产固件里建议在uboot阶段统一初始化PHY把速率、延迟、LED、EEE等寄存器显式写一遍不依赖芯片默认值。这样即使供应商切换批次甚至替换型号板级行为也能保持一致。这一步可以在uboot的board_late_init里实现所有板卡出厂前自动完成出厂后各板之间行为差异最小。做BSP调试这些年Ethernet始终是出现频率最高的调试对象。我个人的经验是先分层定位、再动手改。硬件上检查复位、供电、上拉、时钟软件上先确认设备树、再确认驱动、再确认PHY寄存器。任何一个环节的检查顺序颠倒都会浪费大量时间。另外建议把常用命令整理成脚本遇到新板子第一时间跑一遍能省下至少一个小时的重复劳动。我自己的脚本依次执行dmesg过滤、mdio扫描、PHY寄存器dump、ethtool settings、iperf3打流。新板到手直接验证省下的时间用来多喝杯咖啡比敲命令舒服多了。
