做BSP调试这些年以太网这块一直是个熟面孔但每次板子不一样它总能整出点新花样。这篇是RK3588平台BSP调试系列的第三篇聊的就是Ethernet从完全不通到稳定跑满千兆的完整过程。RK3588这颗SoC自带两个GMAC控制器玩法灵活但也埋了不少雷从设备树配置、PHY驱动加载到RGMII时序调优每一步都有可能让你卡上一整天。这篇东西适合正在做RK3588或类似平台底层移植的工程师也适合刚入门BSP、想把以太网调试脉络彻底理清楚的朋友——我会把硬件核对、设备树编写、内核配置、时序调优、问题排查这些环节全部串起来讲附带上我实际踩过的坑和验证过的方法。1. 动手之前的硬件功课GMAC资源与原理图核对1.1 RK3588的GMAC资源盘点RK3588一共有两个GMAC控制器通常叫GMAC0和GMAC1。每个控制器都可以工作在RGMII模式千兆或者RMII模式百兆具体用哪种取决于你的板级设计。这两个GMAC从软件角度看是独立的各自有独立的时钟、独立的MDIO控制器、独立的复位和中断所以理论上你可以把GMAC0做成千兆以太网口GMAC1做成百兆的另一个口互不干扰。但是别高兴太早两个控制器是独立的没错引脚却是共享的。RK3588的GMAC引脚可以复用分配给不同的功能组如果你在设备树里把某个引脚组配成了SDIO或者UART那GMAC就只能干瞪眼。所以拿到一块新板子的第一件事不是急着写代码而是打开原理图把GMAC相关的引脚走线逐一核对清楚。我一般习惯列一张表把这两个控制器需要关注的信号线全部列出来TX_CLK、TX_CTL、TXD[3:0]、RX_CLK、RX_CTL、RXD[3:0]、MDC、MDIO再加上PHY的中断引脚和复位引脚。确认每一项都接到了正确的位置同时确认这些引脚没有被周边其它功能占用。这一步看着繁琐实际上能帮你省下一整天的调试时间。1.2 PHY芯片选型与地址确认PHY芯片是调试过程中的核心对象它负责把MAC发过来的数据转换成物理层信号。RK3588的板子上常见的PHY有很多种比如Realtek RTL8211F、裕太微YT8531系列、以及各种国产PHY。不同的PHY它的寄存器布局、驱动支持、延时可调范围都不一样但好消息是绝大多数PHY都遵守IEEE 802.3标准寄存器0到6是通用寄存器所以内核的PHYLIB框架能处理大部分情况。PHY地址这东西是第一个坑。每颗PHY芯片都有一个5位二进制地址范围0到31由芯片的地址配置引脚通常是PHYAD[4:0]的上下拉状态决定。地址配置错了MDIO总线上根本扫描不到PHY后面的一切都无从谈起。我遇到过不止一次原理图上明明画的是0x01结果实际量出来的电平组合是0x04原因就是某个引脚漏画了上拉电阻。拿到板子后直接用万用表量PHY地址引脚的电压是最稳妥的。高电平为1低电平为0组合出来就是实际地址。然后把这个地址跟你设备树里设置的phy-node对一下确保一致。最好再做一件事查一下这颗PHY的datasheet看看它支不支持MDIO地址自动回退一些PHY有fallback机制会在地址冲突时跳到其它地址不然你扫不到的时候会非常困惑。1.3 时钟、复位与供电时序以太网的时钟配置直接决定了PHY能不能起来。RGMII模式下GTX_CLK即TX时钟必须是125MHz这是千兆以太网的硬性要求。RMII模式下则是50MHz因为数据只有两位宽速率减半。这个时钟来源有两种常见方案一是由SoC的某个时钟输出引脚直接提供给PHY二是由PHY自己的晶振生成然后反向提供给MAC。RK3588平台一般推荐前者由SoC的REF_CLK引脚输出125MHz这样MAC和PHY共享同一个时钟源时钟相位偏差更好控制。复位时序也是经常出问题的地方。PHY的复位引脚不能跟SoC的复位共用也不能跟其它外设共用更不能没有RC延时电路直接接上去。这是因为PHY的上电时序要求很严格必须先有供电然后等待电源稳定再释放复位。如果复位和供电同时到达PHY内部的PLL可能会锁不住导致PHY启动后状态异常。我踩过的坑是复位引脚直接接在了SoC的GPIO上驱动加载时拉高复位但PHY供电还没稳定到规定电平结果PHY一直都起不来直到我在驱动里加了延时才解决。所以硬件上最好有RC延时比如10ms级别软件上驱动也要注意复位后必须有足够的等待时间一般建议至少等10ms再开始访问PHY寄存器。2. 设备树配置与驱动框架解读2.1 设备树节点结构拆解RK3588平台的内核设备树里以太网控制器的节点长这样基于我的实际项目已脱敏gmac0 { status okay; phy-mode rgmii-id; clock_in_out input; snps,reset-gpio gpio3 RK_PB0 GPIO_ACTIVE_LOW; snps,reset-active-low; snps,reset-delays-us 0 10000 100000; assigned-clocks cru CLK_GMAC0, cru CLK_GMAC0_PTP; assigned-clock-rates 125000000, 125000000; pinctrl-names default; pinctrl-0 gmac0_rgmii_miim_pins, gmac0_rgmii_bus_pins; tx_delay 0x2b; rx_delay 0x2b; phy-handle phy0; phy-mode rgmii-id; phy: phy0 { reg 0x1; compatible ethernet-phy-ieee802.15.4; ... }; };注意这里面有两处phy-mode一个在MAC节点里一个在PHY节点里但我实际项目里只用MAC节点的那个就够了。phy-mode的取值很重要rgmii-id表示MAC内部不添加额外延迟而由PHY自己处理RGMII的延迟后面会详谈。clock_in_out input表示MAC的时钟是从外部输入的也就是PHY的晶振或参考时钟路径如果是output则相反是SoC输出时钟给PHY。选错了网口有可能通百兆不通千兆或者干脆不通。assigned-clock-rates这个字段也很关键它强制把GMAC的时钟设置为125MHz。有些时候驱动会去读时钟树里配置的默认值是固定的50MHz这就导致RGMII跑起来只有百兆速率。直接在设备树里赋值是最省事也最可靠的方式。2.2 pinctrl与引脚复用RK3588的pinctrl子系统和其它Rockchip芯片类似都是通过设备树中的pinctrl-0字段来设置引脚复用。GMAC有专门的pin groupgmac0_rgmii_miim_pins对应MDC、MDIO两脚gmac0_rgmii_bus_pins对应数据线和时钟线的全部引脚。RMII模式下有另一组引脚定义不能混用。引脚复用出问题时最典型的现象就是dmesg里没有任何以太网报错但网口就是起不来。你去看/sys/kernel/debug/pinctrl下面的引脚分配会发现某些引脚被分配给了别的功能。这种情况下第一件事就是检查pinctrl设置是否有语法错误或者重复定义。还有就是其它设备树节点有没有占用同一组引脚却没有报错这类问题往往隐蔽因为多个节点同时引用同一引脚组时pinctrl框架默认不会主动报错。实际经验告诉我把所有GMAC相关引脚的复用状态先打印出来跟原理图逐一比对远比盯着代码猜快很多。操作用以下命令cat /sys/kernel/debug/pinctrl/pinctrl-handles cat /sys/kernel/debug/pinctrl/pinctrl-devices2.3 时钟树与驱动时序RK3588的GMAC时钟树里涉及几个时钟节点主要就是CLK_GMAC0和CLK_GMAC0_PTP。前者是Gigabit Ethernet的参考时钟后者是PTP精确时间协议用的时钟一般对普通网络功能来说CLK_GMAC0就够了但PTP时钟如果设置的频率不对某些版本的内核驱动干脆加载不了。时钟驱动加载顺序也挺讲究。内核启动时会先解析设备树然后按依赖关系初始化时钟最后才probe MAC驱动。如果时钟频率没设为125MHz你会看到驱动probe成功了但PHY检测不到或者速率不对。之前我试过把assigned-clock-rates误写成25MHz结果以太网完全没有速率PHY能识别、能读寄存器但协商速率永远是10Mbps半双工用ethtool看速率也是怪怪的。当时排查了半天最后才发现是时钟的rate根本没配成125MHz。这一点在新平台调试时尤其值得提前检查。另外RK3588的GMAC驱动是基于STMMAC的这个驱动框架非常成熟但也意味着你要理解它的几个关键时序设备树解析顺序、PHY探测时机、时钟使能时机。很多时候PHY探测失败并不是MDIO本身的问题而是因为在PHY探测发生时时钟还没稳定或者PHY还没完成上电。如果代码里可以用mdio-bus上挂一个reset-gpio加上reset-delays-us就能很好解决时序问题。3. 第一次加载从内核配置到网口出现3.1 内核驱动配置项RK3588的以太网驱动在menuconfig里对应的配置项是CONFIG_STMMAC_ETH这个必须选上。另外还需要CONFIG_PHYLIB以及你用的PHY型号对应的驱动。以RTL8211F为例它对应的驱动配置是CONFIG_PHY_REALTEKYT8531则是CONFIG_PHY_MOTORCOMM实际上是来自Motorcomm的底层驱动后来合入PHYLIB框架里。配置命令大致如下cd kernel make ARCHarm64 menuconfig # Device Drivers - Network device support - Ethernet driver support - Synopsys Designware Ethernet # Device Drivers - PHY Device support and infrastructure - Realtek PHY # Device Drivers - PHY Device support and infrastructure - Motorcomm PHY这里有个经验之谈有些内核版本里PHY驱动的依赖项比较隐蔽比如RTL8211F的驱动可能与MDIO bus的配置有关如果你发现PHY能扫到但驱动加载失败多半是PHY芯片驱动没编进内核而不是PHY本身有问题。用/proc/device-tree看PHY节点的compatible属性是否正确也是排查手段之一。3.2 启动阶段的MDIO探测PHY探测的整个流程是这样MAC驱动probe时会去注册自己的MDIO总线然后在内核的PHY框架里扫描总线上所有5位地址0-31是否有PHY响应。每颗PHY都有一个固定的PHY ID写在寄存器2和3里比如RTL8211F的PHY ID是0x001CC916。如果MDIO总线扫描到了这颗PHY会打印类似这样的一行mdio-bus: phy0: device 0x001cc916, driver RTL8211F如果你的dmesg里没有这行通常说明MDIO通信没建立。先检查设备树里phy-handle指向的是不是正确的PHY节点再看看MDC和MDIO两根线是否真的接对了。有时候线上信号正常但是MDIO上拉电阻缺失也会导致通信失败。MDIO是开漏信号必须有上拉电阻一般2.2k到4.7k左右这个细节很容易被原理图评审漏掉。3.3 首次ifconfig -a网口没出来的排查当你做完内核配置和设备树上电启动后执行的第一个命令应该是ifconfig -a看看有没有eth0。如果没有那就说明MAC驱动的probe都没成功或者probe成功但PHY没有连接上。这时候最有用的信息是dmesg | grep dwmac或者dmesg | grep gmac。我见过的最常见的几种情况stmmaceth_find_pcs或no PHY foundPHY没有扫描到检查MDIO、PHY地址、复位时序。Failed to reset the dma channelDMA初始化失败跟时钟有关。Cannot alloc DMA memory可能是CMA内存配置不足或者IOMMU有问题。No MAC address assignedRK3588本身没有EEPROM或内置MAC地址ROM需要在设备树或uboot里配置。MAC地址缺失是个典型问题。多数开发板的MAC地址在工厂烧录时写进了某个存储区域比如eMMC的某个分区或者板上的EEPROM里。如果你没做这一步驱动会生成一个随机MAC地址每个网口的MAC都不同这也许不影响单板工作但在批量设备联网时会造成问题。建议在uboot阶段读取存储中的MAC地址通过ethaddr变量传给内核。不然将来做固件量产时会哭的。4. 千兆通不通的关键RGMII时序与delay配置4.1 RGMII为什么要关注delayRGMII是一种源同步接口数据在时钟的上升沿和下降沿都传输DDR也就是说千兆模式下125MHz的时钟每个沿传4位数据一共能达到1Gbps。源同步的关键在于接收方需要用时钟边沿来采样数据所以时钟和数据之间的相对延迟要保持在一个很小的窗口内。问题来了从MAC到PHY的走线长度不同时钟线和数据线的延时差异会导致采样失败。RGMII标准规定PHY内部应该提供一个2ns左右的延迟即把时钟相对于数据偏移2ns再进行采样。但这个标准并不是所有PHY都严格遵守有的PHY需要MAC端帮忙加延迟有的PHY自己可以加但需要通过寄存器配置有的PHY内部默认已经加了。这就有了rgmii-id、rgmii-txid、rgmii-rxid这些phy-mode的区分。rgmii-id表示MAC不加延迟由PHY内部处理rgmii-txid表示MAC自己加TX方向的延迟RX方向由PHY处理rgmii-rxid恰恰相反。至于tx_delay和rx_delay这两个字段则是STMMAC驱动里直接控制MAC内部延迟线的寄存器值单位是纳秒的一半。也就是说tx_delay 0x2b几乎是2ns左右的延迟0x2b等于43个时钟周期其实这个值的映射关系在不同SoC上并不完全一样我特意在项目里实测过0x2b就是MAC内部可编程延迟线调到43步对应大约2ns左右具体步长看数据手册里的延迟线特性。4.2 不同delay组合对吞吐的影响延迟配置不合适表现不一定是完全不通更多时候是能通但速度慢千兆协商成百兆高负载下疯狂丢包。我实际测过几组配置用iperf3打流结果差异非常大tx_delayrx_delay协商速率iperf3吞吐结果0x000x001000Mbps Full约250Mbps丢包严重0x2b0x2b1000Mbps Full约940Mbps稳定0x3f0x2b100Mbps约95Mbps协商降级0x2b0x3f1000Mbps Full约600Mbps丢包较多查了数据手册和参考设计0x2b这个数值几乎是Rockchip参考SDK里的标准值。但你要理解为什么TX delay太小PHY采样窗口不满足TX delay太大时钟边沿偏移到了下一个数据眼图的边缘误码率上升重传和丢包随之而来。RX delay同理只不过影响的是MAC端采样。如果你的板子走线特别长或者特别短这个值可能需要微调。调的时候别一次变很多一次只变1到2步然后跑一轮iperf3看看TCP和UDP的结果。我自己调优时习惯先从标准值开始再用二分法把吞吐量压到最高。把网口调到接近940Mbps并且长时间稳定不掉速才算调到位。4.3 用ethtool和寄存器做进一步定位ethtool eth0能告诉你协商速率、双工模式、Auto-Negotiation状态。看到1000Mbps Full并不代表物理层信号没问题因为链路协商成功只能说明PHY之间能握手并不能代表数据采样窗口是正确的。所以我一般还会用ethtool的--phy-statistics或者直接读取PHY寄存器来确认。读PHY寄存器的方法有两种一种是使用mii-tool -v一种是使用内核提供的phytool也可以直接通过MDIO总线用mdio-tools。RTL8211F有几个关键寄存器值得关注寄存器0是控制寄存器bit8到bit13是速度/双工位寄存器1是状态寄存器bit5表示链路是否建立。如果寄存器显示链路已建立但速率不对优先怀疑时钟或delay配置。还有一个比较隐蔽的问题PHY内部可能有自动检测延迟的功能比如RTL8211F的寄存器0x14可以调TX/RX的延时档位而内核PHY驱动在初始化时可能会重置这些寄存器。如果你在uboot里调过PHY的delay但是内核起来后PHY驱动把寄存器重新配置了一遍那之前的调整就白做了。这也是为什么同样的板子有的人在uboot里ping通但进了内核就不通的原因。5. 稳定性问题实录5.1 大流量下的丢包网口能协商上千兆、吞吐也测出900多Mbps但业务跑一段时间后出现断流或者丢包率高这种情况多半不是PHY的问题而是MAC层的DMA或者中断处理出了问题。STMMAC驱动的NAPI流程里有两个参数对吞吐影响很大tx_coalesce和rx_coalesce也就是中断合并阈值。如果中断过于频繁CPU被中断打得满地找牙吞吐就上不去。如果合并过度数据包在驱动队列里等待太久时延就会变大。对一般应用来说默认值就好但如果你的应用对时延敏感可以把合并关了让驱动采用更积极的中断策略ethtool -C eth0 rx-usecs 0 tx-usecs 0还有DMA的ring buffer大小。STMMAC驱动在初始化时会分配固定数量的DMA描述符RX ring默认可能只有256个描述符。如果业务里有突发流量RX buffer不够用就会丢包可以通过ethtool -G eth0 rx 1024调整ring大小。但要注意调整ring size需要驱动支持有些不带CONFIG_STMMAC_RING_SIZE配置的内核可能没法在线修改。5.2 睡眠唤醒后网口恢复失败这个场景在嵌入式Linux下很常见系统进入suspend唤醒后ifconfig eth0看到网口还在但实际已经不通了。dmesg里可能出现stmmac_hwtstamp_set之类奇怪的信息或者干脆什么错误都没有。这种问题的根源大多是PHY在睡眠过程中掉电了唤醒后PHY没有重新初始化。解决办法有两类一类是在suspend/resume的回调里重置PHY另一类是让驱动关闭电源管理。如果你们的系统对功耗不敏感最简单粗暴的方法是修改设备树里的snps,pmt或者驱动里的电源管理回调让以太网控制器不进入suspend状态。如果功耗有要求那就要在resume路径里加上PHY的软件复位时序让PHY重新完成上电和自协商。我用过一个笨办法但很有效在resume脚本里手动执行ip link set eth0 down ip link set eth0 up强制PHY重新初始化。后来觉得这样不优雅最后还是在内核驱动里加了resume时PHY软复位。5.3 MAC地址冲突与随机化RK3588没有内置MAC地址它不像很多MCU那样在出厂时烧录了一个唯一MAC。如果你的板子没有从外部存储加载MAC地址内核会使用一个随机地址。这在测试环境没问题但设备量大了之后同一个局域网里两台设备MAC地址相同的概率就不可忽视了路由器会直接把这两台设备踢来踢去。解决思路是在uboot阶段读取板级信息里的MAC地址通过ethaddr环境变量传给内核。如果没有板级存储也可以在设备树里固定一个MAC地址但这样做每个板子都是一样的仍然有冲突风险。正经做法是产线烧录时把MAC地址写进eMMC的某个分区uboot读出来设置给内核。如果没有产线支持临时方案就是用/etc/network/interfaces里的hwaddress配合systemd或者init脚本设置但这也只适合单台调试不能作为批量方案。6. 经验总结与调试工具速查6.1 调试工具清单以太网调试常用的工具按使用频率排个序工具用途常见用法ethtool查看/修改PHY参数ethtool eth0、ethtool -S eth0mii-tool快速查看链路状态mii-tool -v eth0mdio-tools直接读写PHY寄存器mdio read eth0 0x1tcpdump抓包分析数据链路tcpdump -i eth0 -w dump.pcapiperf3吞吐量测试iperf3 -s/iperf3 -c 192.168.1.10iftop实时流量监控iftop -i eth0ip/ifconfig网络接口管理ip link show eth0这些工具最好提前交叉编译进根文件系统BSP调试过程中没有网络可用再想着装工具就抓瞎了。特别是tcpdump和iperf3基本属于没有它们就不知道该干嘛的级别。6.2 常见问题速查表现象可能原因排查与解决方法ifconfig -a看不到eth0MAC驱动probe失败dmesg查stmmac/phy信息先确认时钟、reset、DMA配置eth0可见但link不通PHY未起/复位时序不对/时钟缺用mdio读PHY reg0确认寄存器可读检查复位延时协商速率只有100MRGMII时钟没有125MHz检查assigned-clock-rates用clk_get_rate确认实际频率协商1000M但iperf3吞吐低delay配置不对依次调整tx_delay/rx_delay每次跑iperf3对比大流量丢包DMA ring不足或中断处理慢调大rx ring size调整中断合并参数休眠唤醒后不通PHY未重新初始化在resume路径中做PHY软复位或关闭以太网电源管理MAC地址随机未从存储介质读取uboot中设置ethaddr通过环境变量传给内核6.3 调好之后建议做的事网口调通之后不要急着收工。我会在块RK3588板子上再压一遍压力测试先是TCP双向打流然后UDP打流同时开着ping观察时延抖动。一条命令iperf3 -c 192.168.1.10 -t 120 -P 4 ping 192.168.1.10 -f -s 1400这两个同时跑上几分钟如果吞吐稳定在900Mbps以上、ping没有连不上基本可以认为物理层和MAC层都是健康的。另外别忘了测一下长包把MTU调到9000测一下jumbo frame是否正常。虽然实际业务不一定用巨帧但巨帧通了能说明DMA缓冲配置和PHY能力都到位。从我个人的经验看RK3588的以太网调试最折磨人的不是驱动本身而是各种外部因素——PHY地址不对、复位时序差一点、时钟频率错一格、delay值偏一步任何一个都能让系统在某个看似正常的边缘状态里崩溃。做这类调试我的体会是不要一上来就怀疑内核代码有bug先按硬件、时钟、设备树、驱动、PHY这个顺序层层推进每一步都用工具确认结论不要凭感觉跳步。网口调通了以后把整套设备树配置和时钟设置记录下来后续做量产或做其它板卡时能省掉大量重复踩坑的时间。最后再提醒一句如果你改用了一颗新的PHY务必先确认它的上电时间、复位时间和自协商时间这些参数有的PHY差异非常大直接把时序参数写死可能会导致板子之间表现不一致。