以太网 GMAC 驱动

本文档介绍 RK3588 内置的千兆以太网 GMAC 控制器驱动在 Linux 6.1 内核中的配置与测试方法。

适用范围： RK3588 Linux 6.1 Debian 12 / Ubuntu 22.04 系统，C-3588LQ V1.0 + SHIMETAPI-M5-R2A V1.0 底板。 接口名说明： 本文以 Debian 镜像的 end1 为例；Ubuntu 镜像的千兆网口名为 eth0（另有 eth1），操作时替换即可，详见Debian 与 Ubuntu 镜像差异。

1. 概念基础

1.1 什么是 GMAC

GMAC（Gigabit MAC）是千兆以太网媒体访问控制器。RK3588 内置的 GMAC 本身不直接连网线，而是通过 RGMII/RMII 接口（MAC 芯片与 PHY 芯片之间的标准连接接口）挂一颗外部 PHY（物理层芯片，负责把数字信号变成网线上的电信号），比如 RTL8211F。

特性说明
速率10/100/1000Mbps 自适应
接口RGMII / RMII
PHY外部 PHY 芯片（如 RTL8211F）
DMA支持 DMA 传输
TSOTCP Segmentation Offload

RK3588 GMAC 控制器基地址：GMAC@fe1c0000，由 rk_gmac-dwmac 驱动管理（驱动源码：drivers/net/ethernet/stmicro/stmmac/dwmac-rk3588.c）。

1.2 必须知道：接口命名

注意：出厂镜像使用 systemd 的可预测接口命名（按网卡所在总线位置生成接口名，替代传统的 eth0/eth1），实际有线网卡不叫 eth0，而是 end1。本文中的 eth0 仅作传统占位，请替换为实际接口名。

在开发板上验证一下：

ip link show

实机输出如下：

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 ...
2: dummy0: <BROADCAST,NOARP> mtu 1500 state DOWN ...
3: end1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 ...
    link/ether fa:fc:7b:12:bc:96 permaddr 42:46:d0:aa:1a:fa
4: enP2p33s0: <NO-CARRIER,...> state DOWN ...

end1 是千兆以太网 GMAC1。本机无 eth0，与 Debian/Ubuntu 传统命名不同。

2. 准备工作

2.1 硬件 / 软件

项目内容
主控板C-3588LQ 核心板 + SHIMETAPI-M5-R2A 底板
调试串口线USB 转 TTL（3.3V），波特率 1500000（验证）
网线CAT5e/CAT6
路由器/交换机任意

2.2 引脚

底板已集成 RJ45 网口（含网络变压器 + PHY 芯片），直接插网线即可。PHY 与 RK3588 通过 RGMII 4-bit 数据线 + 时钟 + 控制线连接，具体引脚见底板原理图。

3. 硬件确认（开发板）

3.1 接口与链路

# 查看所有网络接口（含 end1/enP2p33s0 等）
ip link show

# 查看详细 IP/MAC（网段 192.168.49.0/24）
ip addr show end1

end1 接入 DHCP 后的实机输出：

3: end1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 ...
    link/ether fa:fc:7b:12:bc:96
    inet 192.168.49.60/24 brd 192.168.49.255 scope global dynamic noprefixroute end1
       valid_lft 86338sec preferred_lft 86338sec

3.2 PHY 信息

# ⚠️ ethtool 默认未安装，需先 apt install -y ethtool
apt install -y ethtool
ethtool end1

预期输出含：Speed / Duplex / Auto-negotiation / Link detected。

4. 软件准备

4.1 内核配置

SDK 默认已启用 RK3588 GMAC 驱动。配置文件位于 kernel/arch/arm64/configs/rockchip_linux_defconfig：

CONFIG_NETDEVICES=y
CONFIG_NET_VENDOR_ROCKCHIP=y
CONFIG_STMMAC_ETH=y                # Synopsys DesignWare MAC 驱动
CONFIG_DWMAC_ROCKCHIP=y            # Rockchip 平台适配层
CONFIG_PHYLIB=y
CONFIG_ROCKCHIP_PHY=y             # Rockchip PHY 驱动
CONFIG_OF=y
CONFIG_OF_NET=y

出厂镜像已自带全部上述模块（CONFIG_STMMAC_ETH=y、CONFIG_DWMAC_ROCKCHIP=y）。

开发板上可以查看当前内核的实际配置：

zcat /proc/config.gz | grep -E 'STMMAC_ETH|DWMAC_ROCKCHIP|PHYLIB' | head -5

4.2 设备树

RK3588 GMAC 在 SoC 级 .dtsi 中定义：

gmac1: ethernet@fe1c0000 {
    compatible = "rockchip,rk3588-gmac", "snps,dwmac";
    reg = <0x0 0xfe1c0000 0x0 0x10000>;
    interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>;
    clocks = <&cru CLK_GMAC0_SRC>, <&cru CLK_GMAC0_PCLK_REF>,
             <&cru CLK_GMAC0_TX_OUT>, <&cru CLK_GMAC0_RX_OUT>,
             <&cru HCLK_GMAC0>, <&cru PCLK_GMAC0>;
    clock-names = "stmmaceth", "pclk", "tx", "rx", "master_bus", "slave_bus";
    resets = <&cru SRST_A_GMAC0>;
    reset-names = "stmmaceth";
    phy-mode = "rgmii";
    phy-handle = <&rgmii_phy0>;
    pinctrl-names = "default";
    pinctrl-0 = <&gmac1_miim &gmac1_tx_bus2 &gmac1_rx_bus2
                 &gmac1_rgmii_clk &gmac1_rgmii_bus>;
    status = "okay";  /* 默认已启用 */

    mdio1: mdio {
        #address-cells = <1>;
        #size-cells = <0>;

        rgmii_phy0: ethernet-phy@0 {
            compatible = "ethernet-phy-ieee802.22-c22";
            reg = <0>;
        };
    };
};

设备树节点基地址为 0xfe1c0000（GMAC1）。

4.3 SDK 设备树路径

[电脑端] SDK 内设备树源文件：

ls kernel/arch/arm64/boot/dts/rockchip/rk3588*.dts
ls kernel/arch/arm64/boot/dts/rockchip/rk3588*.dtsi

编译后产物：

  • kernel/arch/arm64/boot/Image：内核
  • kernel/arch/arm64/boot/dts/rockchip/rk3588*.dtb：各板型 DTB

5. 设备端操作

5.1 启用网络接口（DHCP 一般已自动启用）

# 启用接口（如已 DOWN）
ip link set end1 up

# DHCP 自动获取 IP
dhclient end1

# 或手动配置静态
ip addr add 192.168.49.60/24 dev end1
ip route add default via 192.168.49.1
echo "nameserver 8.8.8.8" > /etc/resolv.conf

5.2 测试连通性

# ping 网关（192.168.49.1，1ms 内响应）
ping -c 4 192.168.49.1

# ping 外网（8.8.8.8 平均 163ms）
ping -c 4 8.8.8.8

# DNS 解析
nslookup www.baidu.com

# 查看路由
ip route show

实机路由表如下：

default via 192.168.49.1 dev end1 proto dhcp src 192.168.49.60 metric 100
192.168.49.0/24 dev end1 proto kernel scope link src 192.168.49.60 metric 100

5.3 带宽测试（iperf）

出厂镜像装的是 iperf v2（命令 iperf）。如安装 iperf3，两端版本必须保持一致，否则无法通信。

[电脑端] 启动服务端：

iperf -s

开发板 作为客户端：

iperf -c 192.168.49.50 -t 30    # 将 IP 替换为电脑 IP

iperf v2 典型输出：

[  5] local 192.168.49.50 port 5001 connected with 192.168.49.60 port 5001
[ ID] Interval       Transfer     Bandwidth
[  5]  0.0-30.0 sec   345 MBytes  96.5 Mbits/sec

5.4 ethtool 高级

# 查看统计计数
ethtool -S end1

# 调整 Ring Buffer（性能优化）
ethtool -g end1
ethtool -G end1 rx 1024 tx 1024

# 查看驱动信息（含 vermagic、内核模块路径）
ethtool -i end1

# 强制千兆全双工
ethtool -s end1 speed 1000 duplex full autoneg off

6. PC 端设备树微调（性能调优）

如果默认 RGMII 延迟不够好（千兆降为百兆、丢包等），可调 rx/tx_delay：

[电脑端] 编辑板级 .dts：

&gmac1 {
    status = "okay";
    phy-mode = "rgmii";
    phy-handle = <&rgmii_phy0>;
    // 配置 RGMII 延迟（单位：皮秒）
    rx_delay = <0x4f>;
    tx_delay = <0x26>;
};

电脑端 重新编译并烧录：

./build.sh kernel
# 然后用 RKDevTool 烧录 boot.img

延迟值与具体 PHY 芯片、电路板走线、线缆长度相关，需微调。

7. 代码解读（驱动原理）

7.1 驱动注册结构

// drivers/net/ethernet/stmicro/stmmac/dwmac-rk3588.c（简化）

static struct platform_driver rockchip_gmac_driver = {
    .probe  = rockchip_gmac_probe,
    .remove = rockchip_gmac_remove,
    .driver = {
        .name = "rockchip-gmac",
        .of_match_table = rockchip_gmac_match,
    },
};

static const struct of_device_id rockchip_gmac_match[] = {
    { .compatible = "rockchip,rk3588-gmac" },
    { /* sentinel */ }
};

7.2 发送链路调用链

用户空间 send()
  → sock_sendmsg()
    → dev_queue_xmit()
      → stmmac_xmit()
        → 设置 DMA 描述符
          → 写入 DMA 发送缓冲区
            → 触发 PHY 发送

8. 故障排除

8.1 网络不通

现象：接口显示 state DOWN 或 NO-CARRIER。

按顺序检查：

# 1. 接口状态
ip link show end1

# 2. PHY 链路（需 ethtool）
ethtool end1

# 3. GMAC 时钟
cat /sys/kernel/debug/clk/clk_gmac_src/clk_rate

# 4. 设备树节点状态
cat /proc/device-tree/soc/ethernet@fe1c0000/status

最后确认设备树中 gmac1 节点 status = "okay"。

8.2 千兆降为百兆

现象：ethtool 显示 Speed: 100Mb/s。

解决：

# 强制千兆
ethtool -s end1 speed 1000 duplex full autoneg off

# 调整 RGMII 延迟（设备树）
# rx_delay = <0x4f>;  tx_delay = <0x26>;

8.3 网络丢包

# 查看 errors / dropped 计数
ip -s link show end1

# 调大 Ring Buffer
ethtool -G end1 rx 1024

# 检查网线质量（电磁干扰 / 长度）

相关文档