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