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 以太网 MAC 10/100/1000 通用版 3.70a（及更旧版本）和 DesignWare(R) Cores 以太网服务质量版本 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 标签插入/替换/删除/过滤（哈希和完美）

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

• 目标地址过滤（完美）

• 哈希过滤（多播）

• 第 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

除非另有说明，否则每个参数的默认值通常是建议的设置。

watchdog

有效范围:

5000-无

默认值:

5000

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

debug

有效范围:

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

默认值:

0

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

phyaddr

有效范围:

0-31

默认值:

-1

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

flow_ctrl

有效范围:

0-3 (0=关闭,1=接收,2=发送,3=接收/发送)

默认值:

3

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

pause

有效范围:

0-65535

默认值:

65535

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

tc

有效范围:

64-256

默认值:

64

此参数会更改默认的 HW 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，因此只有在有工作要做时，中断处理程序才会发出信号，然后退出。然后，将在未来的某个时间点安排 poll 方法。

传入的数据包由 DMA 存储在预先分配的套接字缓冲区列表中，以避免 memcpy（零复制）。

中断缓解

对于 3.50 之前的芯片，驱动程序能够使用 NAPI 缓解其 DMA 中断的数量。新芯片具有用于此缓解的 HW RX 看门狗。

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

WoL

GMAC、GMAC4/5 和 XGMAC 内核支持通过 Magic 和单播帧进行 LAN 唤醒功能。

DMA 描述符

驱动程序处理正常描述符和备用描述符。后者仅在 DesignWare(R) Cores 以太网 MAC 通用版 3.41a 及更高版本上进行了测试。

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

在 CHAINED 模式下，每个描述符都将具有指向列表中下一个描述符的指针，从而在描述符本身中创建显式链接，而在 RING 模式下则无法进行这种显式链接。

扩展描述符

扩展描述符为我们提供了以太网有效载荷在携带 PTP 数据包或 TCP/UDP/ICMP over IP 时的信息。这些信息在 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 模式支持 100Mbps、1000Mbps 和 1Gbps 的 IEEE 802.3 MAC 操作。

当没有数据要发送和接收时，LPI 模式可以通过关闭部分通信设备功能来节省功耗。链路两侧的系统都可以在低链路利用率期间禁用某些功能并节省功耗。MAC 控制系统是否应进入或退出 LPI 模式，并将此信息传递给 PHY。

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

要进入 TX LPI 模式，驱动程序需要有一个软件定时器，当没有要发送的数据时，该定时器启用和禁用 LPI 模式。

精确时间协议 (PTP)

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

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

SGMII/RGMII 支持

新的 GMAC 设备提供了自己的方式来管理 RGMII/SGMII。通过查看 HW 能力寄存器，可以在运行时获得此信息。这意味着 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) 由于缓冲器大小有限，某些硬件无法在硬件中对超大帧执行校验和。设置此标志后，将在 JUMBO 帧上使用软件执行校验和

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. IRQ 列表，每个 PHY 一个

   int *irqs;
   

3. 如果 IRQ 为 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 Msg Level）。

支持

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