Macb Driver
- Confluence Wiki Admin (Unlicensed)
- Katakam, Harini
- Karumanchi, Vineeth
This page provides links, files, paths, and documentation in relation 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 and Versal
Jumbo frame size support for ZynqMP and Versal
64 bit addressing for ZynqMP and Versal
Priority queue support for ZynqMP and Versal
PS SGMII support (hardwired to 1Gbps) is present in ZynqMP
Features Supported in Driver
(Functional HW IP and stack related features)
Speed support for 10/100/1000 Mbps with clock framework
Packet buffer option
Checksum offload support, CRC checking, FCS stripping
MDIO support for PHY layer management
Multicasting support
Programmable IPG
IEEE1588 support for ZynqMP and Versal
Jumbo frame size support for ZynqMP and Versal
64 bit addressing for ZynqMP and Versal
Priority queue support for ZynqMP and Versal
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 and Versal
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 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
CONFIG_ETHERNET CONFIG_NET_VENDOR_CADENCE CONFIG_MACB CONFIG_NETDEVICES CONFIG_HAS_DMA
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
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.
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 = <ðernet_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-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.yamlWhen 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) Link Speed 1000Mbps, Full duplex DDR 533MHz CCU: No | ||||||||
| 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) Link Speed 1000Mbps, Full duplex DDR MHz CCU: No | ||||||||
| 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 machineOpen 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
x86> mput <file_name>
Pkt Generator
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_arm -s -u ./iperf_arm -s # Launch below commands on client ./iperf_arm -c <Server IP> -u -b <banwidth> ./iperf_arm -c <Server IP> # For more info : http://en.wikipedia.org/wiki/Iperf
Stress Test
Iperf with option -d
Run iperf in dual testing mode. This will cause the server to connect back to the client on the port specified in the -L option (or defaults to the port the client connected to the server on). This is done immediately therefore running the tests simultaneously../iperf_arm -c <Server IP> -d
Ping flood test
Users can send hundred or more packets per second using -f option. It prints a ‘.’ when a packet is sent, and a backspace is printed when a packet is receivedping -f localhost
PTP
1588 synchronization can be tested on ZynqMP and Versal using open source linuxptp application.http://linuxptp.sourceforge.net/
The setup requires a master with precise clock and timstamping capabilities, typically a NIC or another 1588 capable device.
How to run
master:
#ptp4l -i <interface name> -m
#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
PHY details
TI DP83867IR
TI DP83867E (SGMII)
Marvell 88E1112
Marvell 88E1510/2
Realtek RTL8211
Vitesse VSC8211
Micrel KSZ9031
VSC8531_02