PYNQ-Z1/Z2 v3.x: stale /amba path in system-user.dtsi causes 38s boot hang, random MAC address, and inaccessible QSPI flash

[klopyrev]

Summary

boards/Pynq-Z2/petalinux_bsp/meta-user/recipes-bsp/device-tree/files/system-user.dtsi
(and the Pynq-Z1 equivalent) adds the ethernet PHY under the absolute path
/amba/ethernet@e000b000. The Linux kernel renamed the Zynq-7000 bus node
amba -> axi (~v5.8, present in the 6.6.10-xilinx kernel shipped in PYNQ
v3.x images). The overlay therefore no longer amends the real ethernet node —
it silently creates a dead orphan /amba node that nothing binds to.

Verified on a PYNQ-Z2 running the current v3.x SD image
(kernel 6.6.10-xilinx-v2024.1-g3c0eca68c652).

Symptom 1: +38 seconds boot time

With no phy-handle on the real node, the macb driver falls back to
scanning all 32 MDIO addresses; on Zynq-7000 GEM each Clause-45 probe hits
a ~1s MDIO timeout:

[    1.870394] macb e000b000.ethernet: invalid hw address, using random
[   39.947339] macb e000b000.ethernet eth0: Cadence GEM rev 0x00020118 ...
               ^^^^^^^ 38.1 s inside macb probe

The orphan node is visible on a stock image:

$ ls /proc/device-tree/amba/ethernet@e000b000/   # orphan, unused
$ ls /proc/device-tree/axi/ethernet@e000b000/    # real node, no phy-handle

The PHY registers with the tell-tale "no firmware node" name:

macb e000b000.ethernet eth0: PHY [e000b000.ethernet-ffffffff:00] ...

Symptom 2: random MAC address every boot

Compounding: PYNQ-Z2 has no MAC EEPROM; the factory MAC is stored in the
QSPI flash OTP region and was historically read by U-Boot (PR #1157, 2020,
via read opcode 0x4b at OTP offset 0x20, CONFIG_ZYNQ_GEM_SPI_MAC_OFFSET).
The v3.x U-Boot no longer performs this read and its environment is also
broken ("*** Error - No Valid Environment Area found"), so ethaddr is
never set, nothing is injected into the DT, and macb generates a random
MAC each boot ("invalid hw address, using random").

Symptom 3: QSPI flash inaccessible from Linux

The flash node reaches the final DT with partitions but without
compatible/reg/spi-max-frequency (lost in the same overlay-path rot):

spi_master spi0: cannot find modalias for /axi/spi@e000d000/flash@0
spi_master spi0: Failed to create SPI device for /axi/spi@e000d000/flash@0

so no /dev/mtd* exist. Applying a runtime overlay with
compatible = "jedec,spi-nor"; reg = <0>; spi-max-frequency = <50000000>;
immediately probes an S25FL128S (16 MiB) and exposes the qspi-boot /
qspi-kernel / qspi-bootenv partitions — hardware is fine, DT is not.

Fix

Use label references instead of absolute paths in system-user.dtsi, e.g.:

&gem0 {
    phy-handle = <&ethernet_phy>;
    ethernet_phy: ethernet-phy@1 {   /* RTL8211E, MDIO addr 1 */
        reg = <1>;
    };
};

Label references resolve regardless of the bus node's name, so this also
protects against future renames. The flash properties need the same
treatment (via &qspi / flash@0 with jedec,spi-nor).

Same bug in boards/Pynq-Z1/.../system-user.dtsi.

Verification of the fix

Patching the shipped image.ub's FDT accordingly on a PYNQ-Z2:

• GEM probes at 2.0s instead of 39.9s (boot ~38s faster)
• PHY binds via DT: PHY [...ethernet-ffffffff:01] at the correct address
• with local-mac-address set, MAC is stable across reboots
• with the flash properties, spi-nor probes and /proc/mtd is populated

Environment

• Board: TUL PYNQ-Z2
• Image: PYNQ v3.x SD image, kernel 6.6.10-xilinx-v2024.1-g3c0eca68c652
• U-Boot: xilinx-v2024.1 (from BOOT.BIN in the image)

[jogomojo]

Hi @klopyrev

Thanks for this. Could you make a pull request targeting the pynq-next branch?