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
- 1 Features
- 2 Missing Features, Known Issues and Limitations
- 3 Build Flow
- 3.1 Kernel Configuration
- 3.2 Devicetree
- 3.2.1 Related devicetree information
- 3.2.1.1 Ethernet DT
- 3.2.1.2 PHY DT
- 3.2.1.3 Xilinx converter and PHY DT
- 3.2.1.4 RGMII Tuning in DT
- 3.2.1.5 TSU clock in DT
- 3.2.1.6 Fixed link DT
- 3.2.1.7 Common MDIO DT
- 3.2.1.8 PS SGMII DTs (ZynqMP only)
- 3.2.2 Pointers on PHY reset via GPIO
- 3.2.1 Related devicetree information
- 4 Performance
- 4.1 Zynq
- 4.1.1 Linux 5.4 and above
- 4.2 ZynqMP
- 4.3 Versal
- 4.1 Zynq
- 5 Test Procedure
- 5.1 Diagnostic and Protocol Tests
- 5.1.1 PING
- 5.1.2 WebServer
- 5.1.3 Telnet
- 5.1.4 FTP & TFTP
- 5.1.5 Pkt Generator
- 5.2 Performance Tests
- 5.3 Stress Test
- 5.3.1 Iperf with option -d
- 5.3.2 Ping flood test
- 5.4 PTP
- 5.1 Diagnostic and Protocol Tests
- 6 Mainline status
- 7 PHY details
- 8 Change Log
- 9 Related Links
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
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
Important AR links
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 = <ðernet_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:
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) |
Linux version: 6.6 | ||||||||
TCP (Mbps) | UDP(Mbps) | |||||||
---|---|---|---|---|---|---|---|---|
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) | |||||||
---|---|---|---|---|---|---|---|---|
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 |
Linux version: 5.10 | ||||||||
TCP (Mbps) | UDP(Mbps) | |||||||
---|---|---|---|---|---|---|---|---|
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
ZCU102 | ||||||||
CPU Freq 1100MHz (A53) | ||||||||
Linux version: 6.6 | ||||||||
TCP (Mbps) | UDP (Mbps) | |||||||
---|---|---|---|---|---|---|---|---|
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 | 992 | 5.80 | 992 | 5.54 |
Versal
VCK190 | ||||||||
CPU Freq 1350MHz (A72) | ||||||||
Linux version: 6.6 | ||||||||
TCP (Mbps) | UDP (Mbps) | |||||||
---|---|---|---|---|---|---|---|---|
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 |
Test Procedure
Diagnostic and Protocol Tests
PING
This utility used to test the reachability of a host on an Internet Protocol(IP) network and to measure the round trip time for messages sent from the originating host to a destination computer.
ping <Remote IP Address>
WebServer
Connect zynq board to a Linux x86 machine. Ensure that telnet server is running on the Zynq board. It tests for remote access for Zynq board on host machine
Open a web browser on host machine and enter the static IP assigned to zynq board. Webpage is expected to be displayed properly.
Telnet
telnet <Server IP Address>
FTP & TFTP
Open a ftp client on the host with the Zynq.
x86> ftp 192.168.1.10
Transfer a big enough file (in MBs) using mput command.
x86> mput <file_name>
File transfer should be completed without any error.
Pkt Generator
Please refer to link below for how to run and various options
https://www.kernel.org/doc/Documentation/networking/pktgen.txt
Performance Tests
Netperf
# Launch netserver on server side
netserver
# Commands on client
taskset 2 ./netperf -H <Server IP> -t TCP_STREAM
taskset 2 ./netperf -H <Server IP> -t UDP_STREAM
# For more info : http://www.netperf.org/netperf/
Iperf
# Launch below commands on server
./iperf -s -u
./iperf -s
# Launch below commands on client
./iperf -c <Server IP> -u -b <banwidth>
./iperf -c <Server IP>
# For more info : http://en.wikipedia.org/wiki/Iperf
Stress Test
Iperf with option -d
To run iperf in dual testing mode, initiate the server to connect back to the client on the port specified by the -L option, or default to the port that the client used to connect to the server. This process occurs immediately, allowing the tests to run simultaneously.
./iperf -c <Server IP> -d
Ping flood test
Users can transmit hundreds or even more packets per second by utilizing the -f option. This feature displays a ‘.’ each time a packet is sent, while a backspace is shown when a packet is received.
ping -f localhost
PTP
1588 synchronization can be tested on ZynqMP, Versal and Versal Gen 2 using open source linuxptp application. http://linuxptp.sourceforge.net/
The setup necessitates a master device equipped with accurate clock and timestamping functionalities, commonly a Network Interface Card (NIC) or another device that is compliant with the IEEE 1588 standard.
# Run below command on Master
ptp4l -i <interface name> -m
# Run below command on DUT as Slave
ptp4l -i <interface name> -s -m
Mainline status
The macb driver is currently at mainline kernel 6.6 with some patches pulled in from later kernels. The patches that not yet in any mainline kernel are as follows:
Minor differences around PCS PMA handling and GMII2RGMII handling
Minor patch in the probe order for netdev registration and mii init
Any further changes will be upstreamed
PHY details
TI DP83867IR
TI DP83867E (SGMII)
Marvell 88E1112
Marvell 88E1510/2
Realtek RTL8211
Vitesse VSC8211
Micrel KSZ9031
VSC8531_02
Change Log
2025.1
MMI 10GbE functionality has been integrated for Versal Gen2 platforms.
1000BASEX and 10GBASER speeds supported.
History for drivers/net/ethernet/cadence - Xilinx/linux-xlnx
Related Links
© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy