This page gives an overview of the macb driver which is available as part of the Zynq, ZynqMP and Versal Linux distribution and in the mainline.
Paths, files, links and documentation on this page are given relative to the Linux kernel source tree.

Table of Contents

CONFIG_NET_VENDOR_CADENCE
CONFIG_MACB
CONFIG_NETDEVICES
CONFIG_HAS_DMA

• "xlnx,zynq-gem" for Zynq-7000
• "xlnx,zynqmp-gem" for ZynqMP. This compatible string enables use of jumbo frame sizes, 1588 and HW timestamping suport and any features exclusive to ZynqMP.
• "xlnx,versal-gem" for Versal. 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.

Note: 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)

gem0: ethernet@e000b000 {
    compatible = "cdns,gem";
    reg = <0xe000b000 0x1000>;
    status = "disabled";
    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>;
    };
 
};

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

PHY DT

• For PHY related DT information, refer to:

  https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/net/phy.txt

• 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/xilinx_gmii2rgmii.txt)
• 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

Note: 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.

675.79

90.68

759.22

86.45

455.0

62.95

690.1

82.99

988.95

2.34

989.07

7.94

991.9

5.80

992.0

5.54

ping <Remote IP Address>

telnet <Server IP Address>

x86> ftp 192.168.1.10

x86> mput <file_name>

netserver

taskset 2 ./netperf -H <Server IP> -t TCP_STREAM
taskset 2 ./netperf -H <Server IP> -t UDP_STREAM

./iperf_arm -s -u
./iperf_arm -s

./iperf_arm -c <Server IP> -u -b <banwidth>
./iperf_arm -c <Server IP>

./iperf_arm -c <Server IP> -d

ping -f localhost

#ptp4l -i <interface name> -m

#ptp4l -i <interface name> -s -m

• WOL via ARP support (~70 lines)
• Partial store and forward support (~80 lines) - in upstream 6.5 kernel
• Minor differences around PCS PMA handling

• TI DP83867IR
• TI DP83867E (SGMII)
• Marvell 88E1112
• Marvell 88E1510/2
• Realtek RTL8211
• Vitesse VSC8211
• Micrel KSZ9031
• VSC8531_02

Change Log

2023.2

Summary:

• Bugfixes from mainline to support pclk>160MHz and to fix PTP Timestamp failure due to packet padding

Commits:

https://github.com/Xilinx/linux-xlnx/commits/xilinx-v2023.2/drivers/net/ethernet/cadence

2023.1

Summary:

• Fixes for macb SGMII wake source configuration
• Upgrade to 6.1 mainline version including minor updates around napi weight removal, macb phy PM support

Commits:

https://github.com/Xilinx/linux-xlnx/commits/xilinx-v2023.1/drivers/net/ethernet/cadence

2022.2

Summary:

• Macb common MDIO bus enhancements in initialization and suspend/resume flows including SGMII phy handling.
• Fixes on ethtool WOL helper and inclusion of macb pad and fcs support for fragmented packets.
• PTP fixes on one step sync support and to add PTP TX timestamps for all packets in alignment with HWTSTAMP_TX_ON definition.
• Mainline fixes for TX restart handling under TXUBR conditions, compatible string prefix (deprecation of cdns to use xlnx)

Commits:

https://github.com/Xilinx/linux-xlnx/commits/xilinx-v2022.2/drivers/net/ethernet/cadence

2022.1

Summary:

• Align with mainline 5.15 driver to use phylink and PCS functionality.
• Add support for (Internal) SGMII Dynamic Configuration support on Zynq Ultrascale+ MPSoC
• Minor bugfixes including fix for possible rotting packet in RX queue due to NAPI ordering.

Commits:

https://github.com/Xilinx/linux-xlnx/commits/xilinx-v2022.1/drivers/net/ethernet/cadence

2021.2

No Changes

2021.1

Summary:

• New updates from 5.10 including phylink support.
• Minor bugfixes including DMA & coherent DMA mask handling, error handling for WOL ARP etc.

Commits:

https://github.com/Xilinx/linux-xlnx/commits/xilinx-v2021.1/drivers/net/ethernet/cadence

2020.2

Summary:

• Minor bugfix for high memory DMA handling.

Commits:

https://github.com/Xilinx/linux-xlnx/commits/xilinx-v2020.2/drivers/net/ethernet/cadence

2020.1

Summary:

• Minor bug fixes including
  • Workaround for TSO IP errata on Versal GEM.
  • Handle PHY reset for IPs such as PCS PMA phy.
  • Increase halt timeout to accommodate 10Mbps.

Commits:

https://github.com/Xilinx/linux-xlnx/commits/xilinx-v2020.1/drivers/net/ethernet/cadence

2019.2

Summary:

• Minor feature updates

Commits:

https://github.com/Xilinx/linux-xlnx/commits/xilinx-v2019.2.01/drivers/net/ethernet/cadence

2019.1

Summary:

• Bug fixes and enhancements on top of 4.19 kernel

Commits:

https://github.com/Xilinx/linux-xlnx/commits/xilinx-v2019.1/drivers/net/ethernet/cadence

acbe29b net: macb: Apply RXUBR workaround only to versions with errata
7caaf8e net: macb: Fix napi calls in macb_suspend/resume
235128d net: macb: Fix merge error in capabilities in config struct
fee8215 net: macb: Remove repeated tasklet init
95977dd net: macb: Remove unused variables
41f029d net: macb: Remove repeated RBQP assignment
7193098 net: macb: Disable macb pad and fcs for fragmented packets
7d069bc net: macb: Sync RXUBR changes with mainline
d77376c Revert "net: macb: Do not call PM sync in mdio helpers"
d8dd5fe Revert "net: macb: Remove pm calls in mdio timeout function"
f5520f1 macb: Sync PHY reset with mainline
e5c7c2e net: macb: Add separate definition for PPM fraction
24e1145 net: macb: Fix SUBNS increment and increase resolution
b10faf3 net: macb: Optimize reading HW timestamp
e393646 net: macb: Add NULL check for PCLK and HCLK
f22dab1 net: macb: Sync macb_config usage with mainline
9c71c6e net: macb: Change interrupt and napi enable order in open

> 4.19 Mainline fixes pulled in:
af3a961 net: ethernet: cadence: fix socket buffer corruption problem
65f81f2 net: macb: remove unnecessary code
ea79ec6 net: macb: restart tx after tx used bit read
aef9308 net: macb: fix random memory corruption on RX with 64-bit DMA
6b28540 net: macb: fix dropped RX frames due to a race
db8102b net: macb: Check for SKBTX_HW_TSTAMP in macb driver

2018.3

Summary:

• Bug fixes and minor enhancements

Commits:

9caf0ef net: macb: Fix BUG unregistering invalid mdiobus
86bbb72 net: macb: Use devicetree phy-handle if available
41bc0b5 net: macb: Fix warning about uninitialized phy_node
1e7f173 net: macb: Initialize bool to false instead of zero
c5316f6 net: macb: Remove redundant ptp clock selection
0eddb82 macb: refactor the duplicate code to use a shared function
7b2d994 macb: Do not check for timeout when PHY is idle
c241cc8 net: macb: Fix ptp time adjustment for large negative delta
43c7d00 net: macb: Increment rx bd head after allocating skb and buffer
835b617 net: macb: Process tx timestamp only on ptp packets
d2b7486 net: macb: Do not call PM sync in mdio helpers
f4eb775 net: macb: Fix phy path in macb resume
7b7c156 net: macb: Remove pm calls in mdio timeout function