This page provides an overview of the MACB driver, which is included in the Zynq, ZynqMP, and Versal Linux distributions, as well as in the mainline.
This page offers a comprehensive collection of links, files, paths, and documentation pertaining to the Linux kernel source tree.

Features

1 Table of Contents
2 Features
- 2.1 HW IP Features
- 2.2 Features Supported in Driver
3 Missing Features, Known Issues and Limitations
- 3.1 Important AR links
4 Build Flow
- 4.1 Kernel Configuration
- 4.2 Devicetree
  - 4.2.1 Related devicetree information
    - 4.2.1.1 Ethernet DT
    - 4.2.1.2 PHY DT
    - 4.2.1.3 Xilinx converter and PHY DT
    - 4.2.1.4 RGMII Tuning in DT
    - 4.2.1.5 TSU clock in DT
    - 4.2.1.6 Fixed link DT
    - 4.2.1.7 Common MDIO DT
    - 4.2.1.8 PS SGMII DTs (ZynqMP only)
  - 4.2.2 Pointers on PHY reset via GPIO
5 Performance
- 5.1 Zynq
  - 5.1.1 Linux 5.4 and above
- 5.2 ZynqMP
- 5.3 Versal
- 5.4 Versal2 - MMI 10G
6 Test Procedure
- 6.1 Diagnostic and Protocol Tests
  - 6.1.1 PING
  - 6.1.2 WebServer
  - 6.1.3 Telnet
  - 6.1.4 FTP & TFTP
  - 6.1.5 Pkt Generator
- 6.2 Performance Tests
  - 6.2.1 Netperf
  - 6.2.2 Iperf
- 6.3 Stress Test
  - 6.3.1 Iperf with option -d
  - 6.3.2 Ping flood test
- 6.4 PTP
7 Mainline status
8 PHY details
9 Change Log
- 9.1 2025.1
- 9.2 2024.2
10 Related Links

HW IP Features

Speed support for 10/100/1000 Mbps
MAC loopback and PHY loopback
Partial store and forward option
Packet buffer option
Flow control - TX/RX pause
Checksum offload support, CRC checking, FCS stripping
Promiscuous mode, Broadcast mode
Collision detection and enforcement - this is an IP feature, no SW support required
MDIO support for PHY layer management
Multicasting support
VLAN tagged frames
Half duplex support
Programmable IPG
External FIFO interface
Wake on LAN
IEEE1588 support for ZynqMP, Versal and Versal Gen 2
Jumbo frame size support for ZynqMP, Versal and Versal Gen 2
64 bit addressing for ZynqMP, Versal and Versal Gen 2
Priority queue support for ZynqMP, Versal and Versal Gen 2
Screeing support ZynqMP, Versal and Versal Gen 2
PS 1000BASE-x SGMII support (hardwired to 1Gbps) is present in ZynqMP
MMI 10GbE
- 1000/2500Mbps Ethernet MAC (1000BASE-X PCS)
- High speed 5G/10G MAC (10GBASE-R PCS)

Features Supported in Driver

(Functional HW IP and stack related features)

Speed support for 10/100/1000 Mbps with clock framework
MMI 10GbE supporting 1000/10G speeds with SFP.
Packet buffer option
Checksum offload support, CRC checking, FCS stripping
MDIO support for PHY layer management
Multicasting support
Programmable IPG
IEEE1588 support for ZynqMP, Versal and Versal Gen 2
Jumbo frame size support for ZynqMP, Versal and Versal Gen 2
64 bit addressing for ZynqMP, Versal and Versal Gen 2
Priority queue support for ZynqMP, Versal and Versal Gen 2
PS SGMII support is present in ZynqMP and supported in the driver
This driver can be used with PL SGMII/1000BaseX driver on Zynq, ZynqMP, Versal and Versal Gen 2
This driver can be used with gmii2rgmii converter driver
Support for EthTool queries
RX NAPI support
Clock adaptation on Zynq, ZynqMP and Versal
Runtime PM and suspend/resume supported on ZynqMP and Versal
Partial store and forward
Wake on LAN support using ARP and Magic packet on ZynqMP and Versal
Dynamic SGMII configuration support on Xilinx Zynq Ultrascale+MPSoC

Missing Features, Known Issues and Limitations

Linux does not support loopback
Flow control support is absent in the driver. While the IP can receive RX pause frames, it does not offer support for TX pause frames.
External FIFO interface is not supported by the driver - this implementation is DMA based.
The driver currently lacks interrupt support for PHY events, relying instead on a polling method for handling these events.
No IEEE 1588 support for Zynq-7000 as the timestamp implementation in IP is not accurate enough.
- The timestamp generated during a PTP event is stored in a non-latching register, which means it gets overwritten each time a PTP event packet arrives. As a result, there is no reliable method to associate a specific timestamp with its corresponding packet.
- An application that employs synchronization, follow-up, PDelay requests, and PDelay responses within a sync cycle of one second may function without errors. However, its reliability is questionable. The synchronization process is likely to fail at the slightest deviation, such as when multiple PTP event packets are transmitted in the same direction consecutively, or when a short sync interval occurs in a high-traffic system. In such scenarios, the software may struggle to process the timestamp register before it gets overwritten.
WOL is not compatible with warm restart designs due to the requirement of an RX BD scratch area that must remain accessible even during suspend mode. This functionality relies on OCM, which is secure in this design, thus presenting a limitation for this feature.
A warning "unable to generate target frequency" is displayed during macb boot during multiple conditions. Please note
the following scenarios and the validity of the warning:
- Clock source is from internal PLL with GEM in RGMII mode: warning is valid; please check your HW design
  and Devicetree clock entries
- Clock source is external and user defined: warning can be ignored as this clock is not controlled by CCF;
  but to avoid the warning, please ensure that the Devicetree clock entry for tx_clk points to a fixed clock node
  with the frequency that you are supplying
- Clock source is from an internal GT (applicable on ZU+ in SGMII mode only): warning can be ignored as the GT clock
  is already fixed at 125MHz; CCF has no provision to acquire this information or control this clock and hence this
  warning is displayed
MMI_10GbE
- Currently, only fixed links with SFP are supported at 1G and 10G speeds. Users must update the speed in the device tree (dt), as dynamic speed selection is not supported.
- Direct access to MDIO from this IP is restricted. Users must utilise the GEM0 MDIO register to access the common MDIO lines.
If using si570 clock generator as the reference for certain Ethernet designs (for ex., on ZCU102 with GEM + Soft PCS PMA), please check the generated frequency on board before and after loading the open source Linux driver for this component. Reprogramming this clock has led to loss of Ethernet functionality in such designs. Workarounds is to remove the si570 DT node from the devicetree.

Important AR links

WOL does not work on warm restart designs due to some limitations (2018.1/2/3) - AR-71028
PTP time adjustment encounters failure for a significant negative delta in versions 2018.1 and 2018.2, as documented in AR-71332.
MACB MDIO bus support - Please find the patches for 2017.1, 2017.2, 2017.3, 2017.4, 2018.1, 2018.2 and
2018.3 at the AR - AR-69132
ZynqMP PS SGMII GT initialization and related - AR-68866
ZynqMP PS SGMII fixed link - AR-69769 (apllicable till 2021.2 release)
TI PHY design on ZynqMP evaluation board has incorrect straps and can be remedied with a SW workaround
(already implemented in drivers) - AR-70686
PL PCS PMA initialization in fsbl for Zynq and ZynqMP - refer to xapp1026 and xapp130
For custom Versal designs using AIE on 2020.1, make sure the low DDR region is accessible to LPD slaves
(including GEM) using a workaround.
There is a performance drop of approximately 100 Mbps between version 2020.1 (utilising the 5.4 Linux kernel) and version 2019.2 (utilising the 4.19 Linux kernel). This issue has been observed on both GEM and Axi Ethernet on Zynq. Currently, it is suspected that this drop is due to changes in the networking framework, and there is no workaround available at this time. Further updates will be documented in AR-75195.
Macb + PL PCS PMA ifconfig down/up may fail without proper reset and clock reinitialization. Please refer to AR-72806.
Timestamping issue in gPTP master mode (applicable only for 2022.2/2023.1) - AR-000035307
For full list of ARs, search XKB

Build Flow

Kernel Configuration

Mandatory configs

CONFIG_ETHERNET
CONFIG_NET_VENDOR_CADENCE
CONFIG_MACB
CONFIG_NETDEVICES
CONFIG_HAS_DMA

Optional kernel configs

CONFIG_MACB_USE_HWSTAMP

Use IEEE 1588 hwstamp (only supported in ZynqMP and Versal) : This config option supports use of 1588 HW TSTAMP support
in ZynqMP & Versal and depends on MACB.
This option enables IEEE 1588 Precision Time Protocol (PTP) support for MACB.

Devicetree

Compatible strings

Zynq-7000 devices :  "xlnx,zynq-gem"

ZynqMP devices    :  "xlnx,zynqmp-gem"
This compatible string enables the use of jumbo frame sizes, 1588 and
HW timestamping support and any features exclusive to ZynqMP.

Versal Devices    : "xlnx,versal-gem"
This compatible string enables use of jumbo frame sizes, 1588 and HW timestamping suport,
automatic flow control, 802.1AS and any features exclusive to Versal.

Versal Gen 2 Devices : "amd,versal2-10gbe"
This compatible string enables MMI_10GbE with the use of jumbo frame sizes, 1588 and HW timestamping suport,
automatic flow control, 802.1AS and any features exclusive to Versal Gen 2.

Compatible string of format "cdnx,XXXX" is deprecated.

For more details on phy bindings please refer "Documentation/devicetree/bindings/net/cdns,macb.yaml" (macb.txt in older version)

Sample Linux dt-node for gem0/gem1

gem0: ethernet@e000b000 {
    compatible = "cdns,gem";
    reg = <0xe000b000 0x1000>;
    status = "okay";
    interrupt-parent = <&gic>;
    interrupts = <0 22 4>;
    clocks = <&clkc 30>, <&clkc 30>, <&clkc 13>;
    clock-names = "pclk", "hclk", "tx_clk";
    #address-cells = <1>;
    #size-cells = <0>;
    phy-handle = <&ethernet_phy>;
    phy-mode = "rgmii-id";
    ethernet_phy: ethernet-phy@7{
        reg = <7>;
    };
 
};

Sample Linux dt-node for MMI_10GbE

mmi_10gbe: ethernet@ed920000 {
    compatible = "amd,versal2-10gbe", "cdns,gem";
    reg = <0 0xed920000 0 0x1000>;
    interrupts = <0 164 4>, <0 164 4>, <0 164 4>, <0 164 4>;
    clock-names = "pclk", "hclk", "tx_clk", "tsu_clk";
    clocks = <&clk150>, <&clk150>, <&clk150>, <&clk250>;
    status = "okay";
	phy-mode = "10gbase-r";
	fixed-link {
		speed = <10000>;
		full-duplex;
	};
};

Currently MMI_10GbE supports only 1G and 10G speeds with fixed link

Related devicetree information

Ethernet DT

For generic ethernet DT property information, refer to:
https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/net/ethernet-controller.yaml

PHY DT

For PHY related DT information, refer to:
https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/net/ethernet-phy.yaml
When selecting phy specific settings, make sure to mention interface type, speed (if limited/fixed) and phy address properties.
DO NOT set compatible strings in ethernet PHY nodes. Ethernet phy devices are recognized based on identifier registers and phy address; it is not recommended to use compatible string.

Xilinx converter and PHY DT

PHY/Converter devices that may be used with this MAC:

Xilinx GMII2RGMII converter (https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/net/xlnx%2Cgmii-to-rgmii.yaml)
Xilinx PCS PMA PHY ( https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/net/xilinx-phy.txt )

RGMII Tuning in DT

RGMII tuning is driven in phy framework using "rgmii-id", "rgmii-txid", "rgmii-rxid" properties Make sure to set phy-mode to any of these as per your board requirement.
In addition to enabling tuning, some phys also give control of tuning values via devicetree. Please refer to the devicetree bindings documentation of the phy you use in order to tune these according to your board.

TSU clock in DT

Clock adaption is present by default for all device families. For more details refer to devicetree clock bindings and respective wiki pages.
ZynqMP and Versal also have tsu-clk adaption support in addition to all the other reference clocks.

Fixed link DT

This driver can be used for a MAC - MAC fixed link connection. In order to do so, please update the devicetree fixed link node as per
https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/net/ethernet-controller.yaml#L158

Common MDIO DT

To use multiple GEM→PHY connections using a common MDIO bus, please use the following devicetree convention:

gem0 {
......
	phy-handle = <&phya>;

	mdio {
		phya {
			reg = <0xa>;
		};

		phyb {
			reg = <0xb>;
		};
	};
};

gem1 {
.....
	phy-handle = <&phyb>;
};

Where:

→ gem0 is the instance whose phy management is being used (and whose MDC and MDI lines are connected to both PHYs)

→ gem0 is communicating via phya and gem1 is communicating via phyb

For versions upto 2022.1, gem0 needs to come up before gem1 and stay up (because the MDIO interface is expected to be up first; otherwise, the dependent MAC-PHY link (gem1-phyb) will come up on next ifconfig up/down).

As a result of this gem0's runtime PM will not be effective if gem1 is still active in this configuration.

For versions starting 2022.2, probe order and PM suspend/resume order is automatically handled in the driver based on MDIO producer and consumer.

PS SGMII DTs (ZynqMP only)

→ The DT node for PS SGMII is the same as any other configuration with phy-mode property set to "sgmii" and a phy node as seen below. In this case, the Linux SW(currently phylib, NOT phylink) ensures autonegotiation is performed with the PHY. In addition, PCS block inside of GEM will also negotiate and provide link status information in PCS_status register (to be read twice because of stick bits).

gem0 {
......
	phy-mode = <sgmii>;
	phy-handle = <&phya>;

	phya {
		reg = <0xa>;
	};
};

→ If there is no MDIO access to the SGMII PHY or if SFPs are used, then the phy-mode should be set to sgmii and fixed link node should be used instead of phy node. PCS autoneg will be disabled and PCS_status register will always report link up (to be read twice because of sticky bits). This solution is available in releases 2022.1 and above. For previous releases, please refer to "Important AR links"

Pointers on PHY reset via GPIO

→ For boards which require a PHY reset via GPIO, please see the generic framework provisions here: https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/net/ethernet-phy.yaml#L141

This can be used for multiple PHYs with independent GPIO resets as well.

→ If reset is required before PHY detection, please see the MDIO bus provision here: https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/net/mdio.yaml#L30

→ When using PHY reset via GPIO, please check manufacturer specific datasheet for the reset polarity, reset assert duration and post de-assert delay for PHY to be functional. These values can then be passed to PHY and MDIO framework via Devicetree documentation above.

Performance

By connecting Xilinx boards to Linux PCs and server machines (Ubuntu/Red Hat Enterprise), these benchmark performance figures were acquired.
Netperf is the tool used (see tool details below).
Netperf/netserver settings allow you to choose the protocol, MTU size, and CPU load note option.

Zynq

ZC706
^{CPU Freq: 666MHz (A9)} ^{Link Speed: 1000Mbps, Full duplex}

	TCP (Mbps)				UDP(Mbps)
Linux version: 6.6
MTU	TX	CPU(%)	RX	CPU(%)	TX	CPU(%)	RX	CPU(%)
1500	728.76	97.29	548.70	95.96	565.6	65.00	444.8	99.55

Linux 5.4 and above

Performance has decreased by about 10% (relative to 2019.2) for 1500 MTU.
This commit enabled CONFIG_OPTIMIZE_INLINING forcibly in the Linux kernel, which is what caused the decline. It can be seen on Zynq's GEM and Xilinx Axi Ethernet drivers.

There are a lot of inline functions in the kernel and networking stack, and some of them may not be optimized (or may rely on the gcc version) and cause performance issues.
The goal is to record this Zynq performance decline and start a conversation with the mainline community so that the relevant kernel maintainers can examine it.

	TCP (Mbps)				UDP(Mbps)

	TCP (Mbps)				UDP(Mbps)
MTU	TX	CPU(%)	RX	CPU(%)	TX	CPU(%)	RX	CPU(%)
1500	654.79	93.11	737.63	81.43	486.8	63.56	303	96.23

	TCP (Mbps)				UDP(Mbps)
Linux version: 5.10
MTU	TX	CPU(%)	RX	CPU(%)	TX	CPU(%)	RX	CPU(%)
1500	^675.79	^90.68	^759.22	^86.45	^455.0	^62.95	^690.1	^82.99

ZynqMP

	TCP (Mbps)				UDP (Mbps)
ZCU102
CPU Freq 1100MHz (A53) Link Speed 1000Mbps, Full duplex DDR 533MHz CCU: No
Linux version: 6.6
MTU	TX	CPU (%)	RX	CPU (%)	TX	CPU (%)	RX	CPU (%)
1500	941.42	5.0	941.41	54.94	961.5	20.3	923.7	22.07
8192	^988.04	^2.34	^989.06	^7.94	⁹⁹²	^5.80	⁹⁹²	^5.54

Versal

	TCP (Mbps)				UDP (Mbps)
VCK190
CPU Freq 1350MHz (A72) Link Speed 1000Mbps, Full duplex DDR MHz CCU: No
Linux version: 6.6
MTU	TX	CPU (%)	RX	CPU (%)	TX	CPU (%)	RX	CPU (%)
1500	936.45	9.67	941.31	50.67	957	42.9	961.4	50.34
8192	^982.42	^3.13	^989.06	^8.37	^991.9	^17.21	^991.9	^12.58

Versal2 - MMI 10G

VEK385
CPU Freq 1866.647949MHz (A78) Link Speed 10000Mbps, Full duplex DDR MHz CCU: No
Linux version: 6.12
	TCP (Gbps)				UDP (Gbps)
MTU	TX	CPU (%)	RX	CPU (%)	TX	CPU (%)	RX	CPU (%)
1500	9.37	2.52	6.26	15.39	3.15	20.52	4.5	20.46
9900	^9.69	^5.53	^9.26	^3.97	^9.91

Macb Driver

Table of Contents