Synopsys(R) 以太网控制器 “stmmac” 的 Linux 驱动

作者：Giuseppe Cavallaro <peppe.cavallaro@st.com>，Alexandre Torgue <alexandre.torgue@st.com>，Jose Abreu <joabreu@synopsys.com>

目录

• 此版本中

• 功能列表

• 内核配置

• 命令行参数

• 驱动信息和注意事项

• 调试信息

• 支持

此版本中

本文件描述了所有 Synopsys(R) 以太网控制器的 stmmac Linux 驱动。

目前，此网络设备驱动支持所有 STi 嵌入式 MAC/GMAC (即 7xxx/5xxx SoC)、SPEAr (arm)、Loongson1B (mips) 和 XILINX XC2V3000 FF1152AMT0221 D1215994A VIRTEX FPGA 板。Synopsys Ethernet QoS 5.0 IPK 也受支持。

开发此驱动使用了 DesignWare(R) Cores Ethernet MAC 10/100/1000 Universal version 3.70a（及更早版本）和 DesignWare(R) Cores Ethernet Quality-of-Service version 4.0（及更高版本），以及 DesignWare(R) Cores XGMAC - 10G 以太网 MAC 和 DesignWare(R) Cores Enterprise MAC - 100G 以太网 MAC。

此驱动同时支持平台总线和 PCI。

此驱动包含对以下 Synopsys(R) DesignWare(R) Cores 以太网控制器及其对应最低和最高版本的支持

控制器名称	最小版本	最大版本	缩写名称
以太网 MAC 通用版	不适用	3.73a	GMAC
以太网服务质量	4.00a	不适用	GMAC4+
XGMAC - 10G 以太网 MAC	2.10a	不适用	XGMAC2+
XLGMAC - 100G 以太网 MAC	2.00a	不适用	XLGMAC2+

有关硬件要求的问题，请参阅随以太网适配器提供的文档。所有列出的硬件要求均适用于 Linux 环境。

功能列表

此驱动提供以下功能：

• GMII/MII/RGMII/SGMII/RMII/XGMII/XLGMII 接口

• 半双工 / 全双工操作

• 节能以太网 (EEE)

• IEEE 802.3x PAUSE 包（流控制）

• RMON/MIB 计数器

• IEEE 1588 时间戳 (PTP)

• 每秒脉冲输出 (PPS)

• MDIO Clause 22 / Clause 45 接口

• MAC 回环

• ARP 卸载

• 自动 CRC / PAD 插入和检查

• 接收和传输数据包的校验和卸载

• 标准或巨型以太网数据包

• 源地址插入 / 替换

• VLAN TAG 插入 / 替换 / 删除 / 过滤 (HASH 和 PERFECT)

• 可编程 TX 和 RX 看门狗和聚合设置

• 目的地址过滤 (PERFECT)

• HASH 过滤（组播）

• 第 3 层 / 第 4 层过滤

• 远程唤醒检测

• 接收端扩展 (RSS)

• TX 和 RX 的帧抢占

• 可编程突发长度、阈值、队列大小

• 多队列（最多 8 个）

• 多种调度算法（TX：WRR, DWRR, WFQ, SP, CBS, EST, TBS；RX：WRR, SP）

• 灵活的 RX 解析器

• TCP / UDP 分段卸载 (TSO, USO)

• 分段头 (SPH)

• 安全功能（ECC 保护，数据奇偶校验保护）

• 使用 Ethtool 进行自检

内核配置

内核配置选项为 CONFIG_STMMAC_ETH

• CONFIG_STMMAC_PLATFORM：用于启用平台驱动。

• CONFIG_STMMAC_PCI：用于启用 PCI 驱动。

命令行参数

如果驱动作为模块构建，可以通过在命令行上使用 modprobe 命令并采用以下语法（例如对于 PCI 模块）来输入以下可选参数

modprobe stmmac_pci [<option>=<VAL1>,<VAL2>,...]

驱动参数也可以通过命令行传递。

stmmaceth=watchdog:100,chain_mode=1

除非另有说明，每个参数的默认值通常是推荐设置。

看门狗

有效范围:

5000-无

默认值:

5000

此参数覆盖以毫秒为单位的传输超时。

调试

有效范围:

0-16 (0=无,...,16=全部)

默认值:

0

此参数调整系统日志中显示的调试消息级别。

phyaddr

有效范围:

0-31

默认值:

-1

此参数覆盖 PHY 设备的物理地址。

flow_ctrl

有效范围:

0-3 (0=关闭,1=rx,2=tx,3=rx/tx)

默认值:

3

此参数更改默认的流控制能力。

暂停

有效范围:

0-65535

默认值:

65535

此参数更改默认的流控制暂停时间。

tc

有效范围:

64-256

默认值:

64

此参数更改默认的硬件 FIFO 阈值控制值。

buf_sz

有效范围:

1536-16384

默认值:

1536

此参数更改默认的 RX DMA 数据包缓冲区大小。

eee_timer

有效范围:

0-无

默认值:

1000

此参数更改以毫秒为单位的默认 LPI TX 过期时间。

chain_mode

有效范围:

0-1 (0=关闭,1=开启)

默认值:

0

此参数将默认操作模式从环形模式更改为链式模式。

驱动信息和注意事项

传输过程

当内核需要传输数据包时，会调用 xmit 方法；它在环中设置描述符，并通知 DMA 引擎有数据包准备好传输。

默认情况下，驱动在 net_device 结构的 features 字段中设置 NETIF_F_SG 位，启用散列-收集功能。这对于能够在硬件中完成校验和的芯片和配置是真实的。

一旦控制器完成数据包传输，将调度计时器以释放传输资源。

接收过程

当接收到一个或多个数据包时，会发生中断。中断不排队，因此驱动必须在接收过程中扫描环中的所有描述符。

这基于 NAPI，因此中断处理程序只在有工作要做时发出信号，然后退出。然后轮询方法将在未来的某个时刻被调度。

传入的数据包由 DMA 存储在预分配的套接字缓冲区列表中，以避免内存拷贝 (零拷贝)。

中断缓解

驱动能够使用 NAPI 对早于 3.50 版本的芯片的接收进行 DMA 中断数量缓解。新芯片具有用于此缓解的硬件 RX 看门狗。

缓解参数可以通过 ethtool 进行调整。

WoL

GMAC、GMAC4/5 和 XGMAC 核心支持通过魔术帧和单播帧唤醒 LAN 功能。

DMA 描述符

驱动支持普通描述符和备用描述符。后者仅在 DesignWare(R) Cores Ethernet MAC Universal version 3.41a 及更高版本上进行过测试。

stmmac 支持 DMA 描述符在双缓冲区 (RING) 和链表 (CHAINED) 模式下操作。在 RING 模式下，每个描述符指向两个数据缓冲区指针，而在 CHAINED 模式下，它们只指向一个数据缓冲区指针。RING 模式是默认模式。

在 CHAINED 模式下，每个描述符将具有指向列表中下一个描述符的指针，从而在描述符本身中创建显式链式结构，而在 RING 模式下无法实现此类显式链式结构。

扩展描述符

当以太网负载携带 PTP 包或 IP 上的 TCP/UDP/ICMP 时，扩展描述符提供有关以太网负载的信息。这些在早于 3.50 版本的 GMAC Synopsys(R) 芯片上不可用。在探测时，驱动将决定这些是否可以实际使用。此支持对于 PTPv2 也是强制性的，因为额外的描述符用于保存硬件时间戳和扩展状态。

Ethtool 支持

Ethtool 受支持。例如，可以使用以下命令获取驱动统计信息（包括 RMON）、内部错误：

ethtool -S ethX

Ethtool 自检也受支持。这允许使用 MAC 和 PHY 回环机制对硬件进行一些早期健全性检查。

ethtool -t ethX

巨型帧和分段卸载

GMAC 支持并测试了巨型帧。GSO 也已添加，但通过软件执行。LRO 不受支持。

TSO 支持

GMAC > 4.x 和 XGMAC 芯片系列支持 TSO (TCP 分段卸载) 功能。当数据包通过 TCP 协议发送时，TCP 栈确保提供给低级驱动 (本例中为 stmmac) 的 SKB 与最大帧长度 (IP 头 + TCP 头 + 有效载荷 <= 1500 字节 (MTU 设置为 1500 时)) 匹配。这意味着，如果应用程序使用 TCP 想要发送一个长度 (添加头后) > 1514 的数据包，该数据包将被分割成多个 TCP 数据包：数据有效载荷被分割并添加头 (TCP/IP ..)。这由软件完成。

当 TSO 启用时，TCP 栈不关心最大帧长度，并将 SKB 数据包原样提供给 stmmac。GMAC IP 将自行执行分段以匹配最大帧长度。

此功能可以通过设备树中的 snps,tso 条目启用。

节能以太网

节能以太网 (EEE) 允许 IEEE 802.3 MAC 子层与一系列物理层一起在低功耗空闲 (LPI) 模式下运行。EEE 模式支持 IEEE 802.3 MAC 在 100Mbps、1000Mbps 和 1Gbps 下运行。

LPI 模式通过在没有数据传输和接收时关闭部分通信设备功能来节省电量。链路两端的系统都可以禁用某些功能，并在链路利用率低期间节省电量。MAC 控制系统是否应该进入或退出 LPI 模式，并将其传达给 PHY。

接口一打开，驱动就会验证是否支持 EEE。这是通过查看 DMA 硬件能力寄存器和 PHY 设备 MCD 寄存器来完成的。

要进入 TX LPI 模式，驱动需要一个软件定时器，以便在没有数据要传输时启用和禁用 LPI 模式。

精确时间协议 (PTP)

驱动支持 IEEE 1588-2002 精确时间协议 (PTP)，该协议能够精确同步使用网络通信等技术实现的测量和控制系统中的时钟。

除了 IEEE 1588-2002 时间戳中提及的基本时间戳功能外，新的 GMAC 核心还支持高级时间戳功能。配置内核时可以启用 IEEE 1588-2008。

SGMII/RGMII 支持

新的 GMAC 设备提供了管理 RGMII/SGMII 的自身方式。此信息在运行时通过查看硬件能力寄存器获得。这意味着 stmmac 可以管理自动协商和链路状态，而无需使用 PHYLIB。实际上，硬件提供了一组扩展寄存器来重启 ANE，验证全/半双工模式和速度。通过这些寄存器，可以查看自动协商的链路伙伴能力。

物理层

驱动与物理抽象层兼容，可连接 PHY 和 GPHY 设备。

平台信息

可以通过平台和设备树传递多项信息。

struct plat_stmmacenet_data {

1. 总线标识符

   int bus_id;
   

2) PHY 物理地址。如果设置为 -1，驱动将选择它找到的第一个 PHY

int phy_addr;

3. PHY 设备接口

   int interface;
   

4. MDIO 总线的特定平台字段

   struct stmmac_mdio_bus_data *mdio_bus_data;
   

5. 内部 DMA 参数

   struct stmmac_dma_cfg *dma_cfg;
   

6. 固定 CSR 时钟范围选择

   int clk_csr;
   

7. 硬件使用 GMAC 核心

   int has_gmac;
   

8. 如果设置，MAC 将使用增强描述符

   int enh_desc;
   

9. 核心能够在硬件中执行 TX 校验和和/或 RX 校验和

   int tx_coe;
   int rx_coe;
   

11) 由于缓冲区大小有限，某些硬件无法对超大帧在硬件中执行校验和。设置此标志后，巨型帧的校验和将在软件中完成。

int bugged_jumbo;

12. 核心具有嵌入式电源模块

    int pmt;
    

13. 强制 DMA 使用存储转发模式或阈值模式

    int force_sf_dma_mode;
    int force_thresh_dma_mode;
    

15. 强制禁用 RX 看门狗功能并切换到 NAPI 模式

    int riwt_off;
    

16. 限制最大运行速度和 MTU

    int max_speed;
    int maxmtu;
    

18. 组播/单播过滤器的数量

    int multicast_filter_bins;
    int unicast_filter_entries;
    

20. 限制最大 TX 和 RX FIFO 大小

    int tx_fifo_size;
    int rx_fifo_size;
    

21. 使用指定数量的 TX 和 RX 队列

    u32 rx_queues_to_use;
    u32 tx_queues_to_use;
    

22. 使用指定的 TX 和 RX 调度算法

    u8 rx_sched_algorithm;
    u8 tx_sched_algorithm;
    

23. 内部 TX 和 RX 队列参数

    struct stmmac_rxq_cfg rx_queues_cfg[MTL_MAX_RX_QUEUES];
    struct stmmac_txq_cfg tx_queues_cfg[MTL_MAX_TX_QUEUES];
    

24) 此回调用于根据物理层协商的链路速度修改某些 syscfg 寄存器（在 ST SoC 上）

void (*fix_mac_speed)(void *priv, unsigned int speed);

25) 用于调用自定义初始化的回调；这在某些平台（例如 ST 盒子）上有时是必要的，因为硬件需要设置一些 PIO 线或系统配置寄存器。init/exit 回调不应使用或修改平台数据

int (*init)(struct platform_device *pdev, void *priv);
void (*exit)(struct platform_device *pdev, void *priv);

26) 执行总线的硬件设置。例如，在某些 ST 平台上，此字段用于配置 AMBA 桥以生成更高效的 STBus 流量

struct mac_device_info *(*setup)(void *priv);
void *bsp_priv;

27. 内部时钟和速率

    struct clk *stmmac_clk;
    struct clk *pclk;
    struct clk *clk_ptp_ref;
    unsigned int clk_ptp_rate;
    unsigned int clk_ref_rate;
    s32 ptp_max_adj;
    

28. 主复位

    struct reset_control *stmmac_rst;
    

29. AXI 内部参数

    struct stmmac_axi *axi;
    

30. 硬件使用 GMAC>4 核心

    int has_gmac4;
    

31. 硬件基于 sun8i

    bool has_sun8i;
    

32. 启用 TSO 功能

    bool tso_en;
    

33. 启用接收端扩展 (RSS) 功能

    int rss_en;
    

34. MAC 端口选择

    int mac_port_sel_speed;
    

35. 启用 TX LPI 时钟门控

    bool en_tx_lpi_clockgating;
    

36. 硬件使用 XGMAC>2.10 核心

    int has_xgmac;
    

}

对于 MDIO 总线数据，我们有：

struct stmmac_mdio_bus_data {

1. MDIO 总线注册时传递的 PHY 掩码

   unsigned int phy_mask;
   

2. 中断列表，每个 PHY 一个

   int *irqs;
   

3. 如果 IRQs 为 NULL，则将其用于探测到的 PHY

   int probed_phy_irq;
   

4. 如果 PHY 需要复位，则设置为 true

   bool needs_reset;
   

}

对于 DMA 引擎配置，我们有：

struct stmmac_dma_cfg {

1. 可编程突发长度（TX 和 RX）

   int pbl;
   

2. 如果设置，DMA TX / RX 将使用此值而不是 pbl

   int txpbl;
   int rxpbl;
   

3. 启用 8xPBL

   bool pblx8;
   

4. 启用固定或混合突发

   int fixed_burst;
   int mixed_burst;
   

5. 启用地址对齐节拍

   bool aal;
   

6. 启用增强寻址（> 32 位）

   bool eame;
   

}

对于 DMA AXI 参数，我们有：

struct stmmac_axi {

1. 启用 AXI LPI

   bool axi_lpi_en;
   bool axi_xit_frm;
   

2. 设置 AXI 写入/读取最大未完成请求数

   u32 axi_wr_osr_lmt;
   u32 axi_rd_osr_lmt;
   

3. 设置 AXI 4KB 突发

   bool axi_kbbe;
   

4. 设置 AXI 最大突发长度映射

   u32 axi_blen[AXI_BLEN];
   

5. 设置 AXI 固定突发/混合突发

   bool axi_fb;
   bool axi_mb;
   

6. 设置 AXI 重建 incrx 模式

   bool axi_rb;
   

}

对于 RX 队列配置，我们有：

struct stmmac_rxq_cfg {

1. 要使用的模式（DCB 或 AVB）

   u8 mode_to_use;
   

2. 要使用的 DMA 通道

   u32 chan;
   

3. 数据包路由，如果适用

   u8 pkt_route;
   

4. 使用优先级路由，以及要路由的优先级

   bool use_prio;
   u32 prio;
   

}

对于 TX 队列配置，我们有：

struct stmmac_txq_cfg {

1. 调度器中的队列权重

   u32 weight;
   

2. 要使用的模式（DCB 或 AVB）

   u8 mode_to_use;
   

3. 信用基于整形器参数

   u32 send_slope;
   u32 idle_slope;
   u32 high_credit;
   u32 low_credit;
   

4. 使用优先级调度和优先级

   bool use_prio;
   u32 prio;
   

}

设备树信息

请参阅以下文档：Documentation/devicetree/bindings/net/snps,dwmac.yaml

硬件能力

请注意，从新芯片开始（如果硬件能力寄存器可用），许多配置在运行时被发现，例如用于了解 EEE、硬件校验和、PTP、增强描述符等是否实际可用。根据本驱动采用的策略，来自硬件能力寄存器的信息可以替代从平台传递的信息。

调试信息

驱动导出了许多信息，即内部统计数据、调试信息、MAC 和 DMA 寄存器等。

这些信息可以根据实际需要的信息类型以多种方式读取。

例如，用户可以使用 ethtool 支持来获取统计信息：例如使用 ethtool -S ethX（如果支持，它会显示管理计数器 (MMC)）或查看 MAC/DMA 寄存器：例如使用 ethtool -d ethX

使用 CONFIG_DEBUG_FS 编译内核后，驱动将导出以下 debugfs 条目：

• descriptors_status：显示 DMA TX/RX 描述符环

• dma_cap：显示硬件能力

开发人员还可以使用 debug 模块参数获取更多调试信息（请参阅：NETIF 消息级别）。

支持

如果在受支持的内核和受支持的适配器上发现已发布源代码的问题，请将与问题相关的具体信息发送电子邮件至 netdev@vger.kernel.org