/
Macb Driver

Macb Driver

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.

Table of Contents

Features

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

    • HW timestamping - please refer to the respective TRM for detailed list of packets supported. PTP one-step Sync is supported only with L2 packets.

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

Device-tree

Compatible strings

Device family

Compatible string

What it enables

Device family

Compatible string

What it enables

Zynq-7000

"xlnx,zynq-gem"

Base GEM support for Zynq-7000 devices.

ZynqMP

"xlnx,zynqmp-gem"

Jumbo frames, IEEE 1588, hardware timestamping, and ZynqMP-specific features.

Versal

"xlnx,versal-gem"

Jumbo frames, IEEE 1588, hardware timestamping, automatic flow control, 802.1AS, and Versal-specific features.

Versal Gen 2

"amd,versal2-10gbe"

MMI_10GbE support with jumbo frames, IEEE 1588, hardware timestamping, automatic flow control, 802.1AS, and Versal Gen 2-specific features.

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

Device-tree quick guide

Use this section as a checklist when creating or reviewing MACB/GEM device-tree nodes. Start with the MAC node and compatible string, then select the link model, PHY/MDIO arrangement, clocks, and any board-specific reset or tuning requirements.

Configuration area

Use when

Key properties / references

Configuration area

Use when

Key properties / references

Ethernet controller node

Defining the GEM/MAC instance.

compatible, reg, interrupts, clocks, clock-names, phy-mode, phy-handle or fixed-link.

PHY node

External PHY is connected through MDIO.

Use reg for PHY address. Add a PHY compatible string only when required by the PHY binding.

Fixed link

MAC-to-MAC, SFP/no-MDIO, or MMI_10GbE fixed-speed designs.

Use fixed-link with explicit speed and duplex settings.

Common MDIO

Multiple MACs share one MDIO controller.

Keep PHY nodes under the MDIO producer and point each MAC to the correct phy-handle.

RGMII tuning

Board requires TX/RX delay insertion for RGMII.

Select the correct phy-mode: rgmii-id, rgmii-txid, or rgmii-rxid. GEM does not tune delays internally.

PHY reset

PHY requires reset sequencing through GPIO or MDIO bus reset.

Use the generic PHY/MDIO reset bindings and match reset polarity/timing to the PHY data sheet.

Ethernet DT

  • Generic Ethernet controller binding: ethernet-controller.yaml

  • Use this binding to validate common MAC properties such as phy-mode, phy-handle, fixed-link, MAC address properties, and queue-related properties.

PHY DT

  • PHY binding reference: ethernet-phy.yaml

  • For normal PHYs, prefer the mandatory reg property to describe the PHY address. Linux identifies Ethernet PHYs using PHY identifier registers and the MDIO address.

  • Add a PHY compatible string only when the PHY reports an incorrect identifier or needs a specific initialisation sequence. If used, follow the documented ethernet-phy-id.... pattern in the binding.

  • When selecting PHY-specific settings, explicitly describe the interface type, any fixed/limited speed, and the PHY address.

Xilinx converter and PHY DT

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

Device

When to use

Binding

Device

When to use

Binding

Xilinx GMII2RGMII converter

Use when a GMII MAC interface is converted to RGMII.

xlnx,gmii-to-rgmii.yaml

Xilinx PCS PMA PHY

Use for PL SGMII / 1000BASE-X PCS/PMA based designs.

xilinx-phy.txt

RGMII Tuning in DT

Rule of thumb: choose the phy-mode value that matches where the RGMII delay is inserted on your board.

phy-mode

Delay behaviour

Use when

phy-mode

Delay behaviour

Use when

rgmii-id

PHY inserts both TX and RX internal delays.

Most RGMII boards that need both delays.

rgmii-txid

PHY inserts TX delay only.

RX delay is already handled by board routing or another component.

rgmii-rxid

PHY inserts RX delay only.

TX delay is already handled by board routing or another component.

Some PHYs also expose delay values through device-tree properties. Refer to the specific PHY binding and tune the values according to board timing requirements.

GEM does not provide device-tree controlled RGMII TX/RX delay tuning. For most RGMII boards, configure the required delay in the PHY using one of the rgmii-* modes above.

TSU clock in DT

  • Clock adaptation is enabled by default for all supported device families.

  • Use the device-tree clock bindings and the relevant platform wiki pages to define the reference clocks.

  • ZynqMP and Versal also support tsu_clk adaptation in addition to the other reference clocks.

Fixed link DT

  • Use fixed link for MAC-to-MAC connections, SFP/no-MDIO designs, or other designs where link parameters are not discovered through a PHY.

  • Define the fixed-link node using the generic Ethernet controller binding: ethernet-controller.yaml fixed-link reference.

  • Specify the intended speed and duplex explicitly, for example speed = <1000> or speed = <10000> with full-duplex.

Common MDIO DT

Use this pattern when multiple GEM instances share one MDIO bus. Keep the MDIO bus and PHY nodes under the GEM instance that owns the MDC/MDIO pins, then reference the required PHY from each MAC using phy-handle.

gem0 { ...... phy-handle = <&phya>; mdio { phya { reg = <0xa>; }; phyb { reg = <0xb>; }; }; }; gem1 { ..... phy-handle = <&phyb>; };

Item

Meaning

Item

Meaning

gem0

MDIO producer. Its MDC/MDIO lines are connected to both PHYs.

phya

PHY used by gem0.

phyb

PHY used by gem1, but managed through the MDIO bus owned by gem0.

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)

Use PS SGMII only on ZynqMP. Choose one of the following models based on whether Linux can access the SGMII PHY over MDIO.

Model

Use when

Device-tree approach

Driver behaviour

Model

Use when

Device-tree approach

Driver behaviour

SGMII PHY over MDIO

The SGMII PHY is accessible through MDIO.

Set phy-mode = "sgmii" and use phy-handle to reference the PHY node.

Linux phylib performs PHY autonegotiation. The GEM PCS also negotiates and reports link status through PCS_status.

SGMII fixed link

No MDIO access is available, or SFPs are used.

Set phy-mode = "sgmii" and use a fixed-link node instead of a PHY node.

PCS autonegotiation is disabled. PCS_status reports link up; read twice because of sticky bits. Supported from 2022.1 onwards.

gem0 { ...... phy-mode = <sgmii>; phy-handle = <&phya>; phya { reg = <0xa>; }; };

For releases before 2022.1, refer to the Important AR links section for PS SGMII fixed-link guidance.

PHY reset via GPIO

  • For boards that require PHY reset through GPIO, use the generic PHY reset properties documented in ethernet-phy.yaml.

  • The same framework supports multiple PHYs with independent GPIO resets.

  • If reset must happen before PHY detection, use the MDIO bus reset provision documented in mdio.yaml.

  • Always verify reset polarity, assert duration, and post-deassert delay in the PHY data sheet before encoding these values in the device tree.

→ 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.

Complete device-tree node example

The following example shows a complete GEM device-tree node for a typical RGMII design with an external PHY on the local MDIO bus. Update the base address, interrupts, clocks, PHY address, reset GPIO, and delay values to match the target board.

/* Example: ZynqMP GEM connected to an external RGMII PHY */ &gem0 { compatible = "xlnx,zynqmp-gem", "cdns,gem"; status = "okay"; reg = <0x0 0xff0b0000 0x0 0x1000>; interrupt-parent = <&gic>; interrupts = <0 57 4>; clocks = <&zynqmp_clk 31>, <&zynqmp_clk 31>, <&zynqmp_clk 45>, <&zynqmp_clk 44>; clock-names = "pclk", "hclk", "tx_clk", "tsu_clk"; phy-mode = "rgmii-id"; phy-handle = <&gem0_phy>; #address-cells = <1>; #size-cells = <0>; mdio { #address-cells = <1>; #size-cells = <0>; gem0_phy: ethernet-phy@7 { reg = <7>; reset-gpios = <&gpio 12 0>; reset-assert-us = <10000>; reset-deassert-us = <30000>; }; }; };

Field to customise

What to check

Field to customise

What to check

compatible

Use the device-family specific string from the compatible strings table above.

reg and interrupts

Match the GEM instance base address and interrupt number from the SoC/device-tree include file.

clocks and clock-names

Keep the order aligned with the MACB binding. Add tsu_clk when IEEE 1588/PTP timestamp support is required and available.

phy-mode

Select rgmii-id, rgmii-txid, rgmii-rxid, sgmii, 1000base-x, or another supported mode based on the board connection.

phy-handle / fixed-link

Use phy-handle for an MDIO-managed PHY. Use fixed-link when there is no discoverable PHY.

reset-gpios and reset delays

Include only when the board requires PHY reset through GPIO. Verify polarity and timing from the PHY data sheet.

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

Board: ZC706 | CPU: 666 MHz (A9) | Link: 1 Gbps, full duplex

Linux

MTU

TCP TX

TCP TX CPU

TCP RX

TCP RX CPU

UDP TX

UDP TX CPU

UDP RX

UDP RX CPU

Linux

MTU

TCP TX

TCP TX CPU

TCP RX

TCP RX CPU

UDP TX

UDP TX CPU

UDP RX

UDP RX CPU

6.6

1500

728.76 Mbps

97.29%

548.70 Mbps

95.96%

565.6 Mbps

65.00%

444.8 Mbps

99.55%

5.4+

1500

654.79 Mbps

93.11%

737.63 Mbps

81.43%

486.8 Mbps

63.56%

303 Mbps

96.23%

5.10

1500

675.79 Mbps

90.68%

759.22 Mbps

86.45%

455.0 Mbps