Add ZCU102 (UltraScale+ A53 EL3) bare-metal wolfIP port with GEM3 + DP83867 + UDP echo

Author: dgarske

src/port/zcu102/.gitignore

@@ -0,0 +1,4 @@
+*.o
+*.elf
+*.bin
+BOOT.BIN

src/port/zcu102/Makefile

@@ -0,0 +1,85 @@
+# Xilinx ZCU102 (UltraScale+ MPSoC, Cortex-A53) wolfIP bare-metal port
+#
+# Build:    make CROSS_COMPILE=aarch64-none-elf-
+# Bootbin:  FSBL_ELF=/path/to/fsbl.elf make bootbin
+#
+# Toolchain: ARM GNU aarch64-none-elf-gcc (tested with 14.3.rel1).
+
+CROSS_COMPILE ?= aarch64-none-elf-
+CC      := $(CROSS_COMPILE)gcc
+OBJCOPY := $(CROSS_COMPILE)objcopy
+SIZE    := $(CROSS_COMPILE)size
+
+ROOT := ../../..
+
+# Cortex-A53, AArch64, EL3 single-EL bare-metal. No SIMD/FP in the
+# wolfIP/driver paths - keep -mgeneral-regs-only to catch any
+# accidental FP use and make the ABI deterministic for cert.
+CFLAGS  := -mcpu=cortex-a53 -mgeneral-regs-only
+CFLAGS  += -Os -ffreestanding -fno-builtin -fno-common
+CFLAGS  += -fdata-sections -ffunction-sections
+CFLAGS  += -g -Wall -Wextra -Werror -Wno-unused-parameter
+CFLAGS  += -std=gnu99
+CFLAGS  += -I. -I$(ROOT) -I$(ROOT)/src -I$(ROOT)/src/port
+CFLAGS  += -DZCU102 -DXILINX_AARCH64
+
+ASFLAGS := -mcpu=cortex-a53
+
+LDSCRIPT := target.ld
+LDFLAGS  := -nostdlib -nostartfiles -T $(LDSCRIPT) -Wl,-gc-sections
+# Replace newlib's aarch64 memset/memcpy (which use 'dc zva' and hang
+# on this Cortex-A53 setup) with our bytewise versions in main.c.
+LDFLAGS  += -Wl,--wrap=memset -Wl,--wrap=memcpy
+
+LOCAL_C := main.c uart.c mmu.c gic.c gem.c phy_dp83867.c
+LOCAL_S := startup.S
+LOCAL_OBJS := $(LOCAL_C:.c=.o) $(LOCAL_S:.S=.o)
+
+# Compile wolfIP core into our directory (don't reuse the upstream .o,
+# which may have been built for a different ABI).
+WOLFIP_OBJ := wolfip.o
+OBJS := $(LOCAL_OBJS) $(WOLFIP_OBJ)
+
+all: app.elf
+	@echo "Built: app.elf"
+	@$(SIZE) app.elf
+
+app.elf: $(OBJS) $(LDSCRIPT)
+	$(CC) $(CFLAGS) $(OBJS) $(LDFLAGS) \
+	    -Wl,--start-group -lc -lgcc -Wl,--end-group -o $@
+
+# wolfIP core: -Wno-zero-length-bounds is needed when MAX_TCPSOCKETS=0
+# because MAX_TIMERS expands to 0 and the timer heap declares a
+# zero-length array. The actual [0] accesses are runtime-guarded by
+# heap->size > 0, so the warning is a false positive in this profile.
+$(WOLFIP_OBJ): $(ROOT)/src/wolfip.c
+	$(CC) $(CFLAGS) -Wno-zero-length-bounds -Wno-type-limits -c $< -o $@
+
+%.o: %.c
+	$(CC) $(CFLAGS) -c $< -o $@
+
+%.o: %.S
+	$(CC) $(ASFLAGS) -c $< -o $@
+
+# Build a bootable BOOT.BIN. Requires FSBL_ELF env var pointing to a
+# pre-built ZCU102 FSBL (built in Vitis or PetaLinux). bootgen itself
+# is part of Vitis or available standalone.
+bootbin: app.elf
+	@if [ -z "$$FSBL_ELF" ]; then \
+	    echo "ERROR: FSBL_ELF must point to a prebuilt ZCU102 FSBL ELF."; \
+	    exit 1; \
+	fi
+	FSBL_ELF=$$FSBL_ELF APP_ELF=$$PWD/app.elf bootgen/build_bootbin.sh
+
+clean:
+	rm -f $(OBJS) app.elf BOOT.BIN
+
+.PHONY: all clean bootbin help
+
+help:
+	@echo "ZCU102 wolfIP build:"
+	@echo "  make                         - build app.elf"
+	@echo "  FSBL_ELF=... make bootbin    - build BOOT.BIN"
+	@echo "  make clean                   - remove artifacts"
+	@echo ""
+	@echo "Override CROSS_COMPILE if your toolchain prefix differs."

src/port/zcu102/README.md

@@ -0,0 +1,198 @@
+# wolfIP port: Xilinx ZCU102 (UltraScale+ MPSoC)
+
+Bare-metal wolfIP port for the AMD/Xilinx Zynq UltraScale+ MPSoC, demoed
+on the ZCU102 dev board. Targets a single Cortex-A53 core (APU 0) at
+EL3, GCC bare-metal, no Xilinx Standalone BSP, no FreeRTOS, no wolfBoot.
+
+This first milestone is aimed at a deterministic UDP-only profile
+suitable for DO-178C DAL-C qualification. The application opens a
+UDP echo socket on port 7 and runs a DHCP client to acquire a lease.
+
+## What this port covers
+
+- PS-GEM3 (on-board RJ45) at 1 Gbps via the TI DP83867IR PHY (RGMII).
+- Polled RX + polled TX (GIC-400 SPI 63 latches correctly, but the
+  Cortex-A53 IRQ exception is not delivered in our EL3 single-EL setup;
+  `eth_poll()` drives `gem_isr()` directly from the main loop).
+- Clean-room Cadence GEM driver - no XEmacPs, no Xilinx Standalone BSP,
+  no `xparameters.h`. All register base addresses live in `board.h`.
+- MMU at EL3 with a static page table: DDR Normal WB, a Normal-NC DMA
+  carve-out for GEM BDs/buffers, peripherals Device-nGnRnE, and an
+  OCM (0xFFFC0000+) Normal-WB executable block.
+- PS-UART0 polled console (USB-UART on the ZCU102 board, channel 0).
+- DHCP client and a UDP echo demo (port 7); ICMP echo reply works
+  through the wolfIP core.
+
+## What is explicitly NOT in this port yet
+
+- Software VLAN (Daniele has a separate wolfIP-core PR in flight).
+- uC/OS-II socket port (planned follow-up; trivially adapts an existing
+  `bsd_socket.c`).
+- Additional GEM instances (GEM0/1/2). Driver is single-instance.
+- Versal Gen 1, Zynq-7000.
+- wolfBoot integration. Stock Xilinx FSBL hands control directly to
+  `app.elf`.
+- TLS / wolfSSL.
+
+## Hardware
+
+- AMD/Xilinx ZCU102 evaluation board (XCZU9EG-2FFVB1156). Rev 1.0 or
+  1.1 are both fine.
+- USB-UART via the on-board FTDI FT4232 (host sees four `/dev/ttyUSB*`
+  channels; UART0 is the standard one, typically `/dev/ttyUSB0` or the
+  channel labelled "MIO" depending on board / udev).
+- Ethernet via the on-board RJ45 (PS-GEM3 -> DP83867 PHY @ MDIO 0x0C).
+
+## Build
+
+Toolchain: ARM GNU `aarch64-none-elf-gcc`. The default is on `$PATH`;
+override with `CROSS_COMPILE=...-` if needed.
+
+```
+cd src/port/zcu102
+make CROSS_COMPILE=aarch64-none-elf-
+```
+
+Output: `app.elf`. Section sizes are printed at the end of the build.
+
+## Build BOOT.BIN
+
+You need a pre-built ZCU102 FSBL ELF. The simplest way to obtain one
+is the Vitis "zynqmp_fsbl" template (single-click build), or PetaLinux
+`petalinux-build -c bootloader`. We deliberately do NOT vendor FSBL
+sources here; FSBL is a Xilinx-provided component and stock works.
+
+Source Vitis first (so `bootgen` is on `$PATH`), then:
+
+```
+FSBL_ELF=/path/to/zynqmp_fsbl.elf make bootbin
+```
+
+Output: `BOOT.BIN` in the port directory.
+
+## Boot
+
+### SD card boot
+
+1. Format a microSD as FAT32.
+2. Copy `BOOT.BIN` to the root of the SD card.
+3. Set ZCU102 boot mode DIP SW6 to SD (positions 1-4 = ON, OFF, OFF, OFF).
+4. Insert the card and power-cycle the board.
+
+### JTAG boot (Vitis xsct)
+
+```
+xsct
+% connect
+% targets -set -filter {name =~ "PSU"}
+% rst -system
+% loadhw -hw /path/to/your-design.xsa
+% targets -set -filter {name =~ "Cortex-A53 #0"}
+% dow /path/to/wolfip/src/port/zcu102/app.elf
+% con
+```
+
+If you do not have an XSA from your own design, the stock ZCU102 base
+design from Vitis is fine - we only depend on the PS configuration
+(DDR controller, MIO pinmuxing, IOPLL clocks) which is identical
+across base designs.
+
+### JTAG iteration (no SD swap)
+
+This port ships a self-contained xsdb loader under `jtag/` that
+power-cycles the board (via remote Pi GPIO, optional), forces JTAG
+boot mode, runs `psu_init`, loads `app.elf` into OCM, and releases
+A53-0 at the OCM entry. The whole app + BSS + page tables + DMA
+buffers fit in the 256 KB OCM, so DDR-via-JTAG flakiness is avoided.
+
+```
+./jtag/boot.sh                  # one-shot
+./jtag/boot_iter.sh             # build + power-cycle + load loop
+```
+
+See `jtag/boot.tcl` for the actual xsdb sequence.
+
+## Expected UART output
+
+```
+=== wolfIP ZCU102 (UltraScale+ A53-0 EL3) ===
+MMU on, caches on. Bringing up GIC-400...
+Initializing wolfIP stack...
+Bringing up GEM3 (RGMII, DP83867)...
+GEM3: PHY at MDIO addr=0x0000000C
+DP83867: ID1=0x00002000 ID2=0x0000A231
+DP83867 link: 1000 Mbps FD
+  link UP, PHY=0x0000000C
+Starting DHCP client...
+DHCP bound:
+  IP: 192.168.1.50
+  Mask: 255.255.255.0
+  GW:   192.168.1.1
+Opening UDP echo socket on port 7
+Ready. Try: nc -u <leased-ip> 7
+```
+
+## Verification
+
+From a host on the same subnet as the board:
+
+```
+$ ping -c 3 192.168.1.50
+$ echo "hello wolfip" | nc -u -w1 192.168.1.50 7
+hello wolfip
+```
+
+UART capture via the `uart-monitor` skill (add a board entry pointing
+at `/dev/ttyUSB0` and 115200 8N1).
+
+## Files
+
+| File                | Purpose |
+|---------------------|---------|
+| `Makefile`          | Build app.elf and BOOT.BIN |
+| `target.ld`         | aarch64 EL3 linker script - separate RX/RW segments, 2 MB DMA region |
+| `startup.S`         | EL3 vectors, BSS clear, MMU/main bring-up, IRQ trampoline |
+| `board.h`           | PS register base addresses, GIC SPI IDs |
+| `mmu.c` / `.h`      | EL3 page tables (T0SZ=32, 1 GB L1 + 2 MB L2 for DDR + DMA carve-out) |
+| `gic.c` / `.h`      | GIC-400 (GICv2) minimal driver |
+| `uart.c` / `.h`     | PS-UART0 polled console |
+| `gem.c` / `.h`      | Cadence GEM driver (PS-GEM3): BDs, polled-RX/TX, MDIO, cache maintenance |
+| `phy_dp83867.c` / `.h` | TI DP83867IR init + RGMII skew + AN + RX_CTRL strap quirk |
+| `main.c`            | wolfIP init, DHCP client, UDP echo on port 7, memset/memcpy wrappers |
+| `config.h`          | wolfIP build profile (UDP-only intent) |
+| `bootgen/boot.bif`  | bootgen template (substitutes `${FSBL_ELF}` and `${APP_ELF}`) |
+| `bootgen/build_bootbin.sh` | renders the bif and invokes bootgen |
+| `jtag/boot.sh` / `.tcl` | xsdb loader for OCM-only JTAG iteration |
+
+## Notes for cert / DAL-C
+
+- No Xilinx Standalone BSP linked in. `aarch64-none-elf-gcc` newlib
+  provides `memcpy`/`memset` only.
+- No dynamic allocation. All buffers static in BSS or `.dma_buffers`.
+- No floating point (`-mgeneral-regs-only`).
+- The MAC address is hard-coded in `board.h`. Replace with a
+  per-board value (e.g., read from EEPROM or PS_VERSION fuses) for
+  production; we keep static for repeatability in the lab.
+- The wolfIP core currently sizes its timer heap as
+  `MAX_TIMERS = MAX_TCPSOCKETS * 3`. This port sets `MAX_TCPSOCKETS=2`
+  in `config.h` so DHCP / ARP can schedule timers; the application
+  does not open any TCP sockets. A core wolfIP follow-up should
+  decouple the timer count from TCP so the TCP code can be fully
+  excluded from a DAL-C build.
+- The wolfIP core triggers two false-positive GCC warnings
+  (`-Wzero-length-bounds`, `-Wtype-limits`) when `MAX_TCPSOCKETS`
+  reaches its lower bound. We suppress them on the wolfip.c compile
+  only; the diagnostics on this port's source remain at `-Wall -Wextra
+  -Werror`.
+- newlib's aarch64 `memset`/`memcpy` use `dc zva`, which hangs on this
+  Cortex-A53 setup even with `SCTLR_EL3.DZE=1`. We override both with
+  bytewise versions in `main.c` via `-Wl,--wrap`.
+
+## Known issues
+
+- The A53 IRQ exception is not delivered (GIC latches the SPI/SGI and
+  `GICC_IAR` ack works when polled, but the IRQ vector never fires).
+  Worked around by polling `gem_isr()` from `eth_poll()` in the main
+  loop. Real root cause is open.
+- `MAX_TCPSOCKETS=2` is the minimum for the current wolfIP core - see
+  the timer-heap note above.

src/port/zcu102/board.h

@@ -0,0 +1,92 @@
+/* board.h
+ *
+ * Copyright (C) 2026 wolfSSL Inc.
+ *
+ * This file is part of wolfIP TCP/IP stack.
+ *
+ * wolfIP is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * wolfIP is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
+ *
+ * Xilinx UltraScale+ MPSoC PS register base addresses, GIC SPI IDs,
+ * and clock parents for the ZCU102 board. All values are derived from
+ * the ZynqMP TRM (UG1085) and the ZCU102 board user guide (UG1182).
+ * No Xilinx BSP header (xparameters.h) is required.
+ */
+#ifndef ZCU102_BOARD_H
+#define ZCU102_BOARD_H
+
+#include <stdint.h>
+
+/* ---------------------------------------------------------------------
+ * Memory map (ZynqMP PS)
+ * ------------------------------------------------------------------- */
+#define DDR_BASE                0x00000000UL
+#define DDR_SIZE                0x80000000UL   /* 2 GB lower bank */
+
+#define OCM_BASE                0xFFFC0000UL
+#define OCM_SIZE                0x00040000UL   /* 256 KB */
+
+/* ---------------------------------------------------------------------
+ * PS peripherals
+ * ------------------------------------------------------------------- */
+#define UART0_BASE              0xFF000000UL
+#define UART1_BASE              0xFF010000UL
+
+#define GEM0_BASE               0xFF0B0000UL
+#define GEM1_BASE               0xFF0C0000UL
+#define GEM2_BASE               0xFF0D0000UL
+#define GEM3_BASE               0xFF0E0000UL
+
+#define CRL_APB_BASE            0xFF5E0000UL
+#define IOU_SLCR_BASE           0xFF180000UL
+
+/* GIC-400 distributor and CPU interface (per ZynqMP TRM). */
+#define GICD_BASE               0xF9010000UL
+#define GICC_BASE               0xF9020000UL
+
+/* ---------------------------------------------------------------------
+ * GIC SPI numbers (ZynqMP TRM Table 13-1)
+ * ------------------------------------------------------------------- */
+#define IRQ_GEM0                57   /* SPI 57 */
+#define IRQ_GEM1                59   /* SPI 59 */
+#define IRQ_GEM2                61   /* SPI 61 */
+#define IRQ_GEM3                63   /* SPI 63 - on-board ZCU102 RJ45 */
+
+/* ---------------------------------------------------------------------
+ * CRL_APB clock and reset registers
+ * ------------------------------------------------------------------- */
+#define CRL_APB_GEM3_REF_CTRL   (CRL_APB_BASE + 0x5C)
+#define CRL_APB_RST_LPD_IOU0    (CRL_APB_BASE + 0x230)  /* GEM3 reset bit 3 */
+
+/* ---------------------------------------------------------------------
+ * PS UART0 (Cadence) - on-board USB-UART on ZCU102 via U104 FT4232
+ * ------------------------------------------------------------------- */
+#define UART_BAUD               115200
+
+/* Default A53-0 EL3 stack location (set in startup.S, mirrored here for
+ * any C code that needs to know). */
+#define A53_STACK_TOP           0x00100000UL   /* 1 MB - 8 B */
+
+/* MAC address for eth0. Locally-administered, even first octet:
+ * 02:00:5A:11:22:33. Customer can replace via build-time -D. */
+#ifndef WOLFIP_MAC_ADDR
+#define WOLFIP_MAC_0            0x02
+#define WOLFIP_MAC_1            0x00
+#define WOLFIP_MAC_2            0x5A
+#define WOLFIP_MAC_3            0x11
+#define WOLFIP_MAC_4            0x22
+#define WOLFIP_MAC_5            0x33
+#endif
+
+#endif /* ZCU102_BOARD_H */

src/port/zcu102/bootgen/boot.bif

@@ -0,0 +1,14 @@
+// ZCU102 BOOT.BIN definition for wolfIP bare-metal app.
+//
+// Variables expanded by build_bootbin.sh:
+//   ${FSBL_ELF}    - path to a pre-built ZynqMP FSBL (A53-0, EL3, NS)
+//   ${APP_ELF}     - path to the wolfIP app ELF (this directory's app.elf)
+//
+// bootgen consumes this file with:
+//   bootgen -arch zynqmp -image boot.bif -w on -o BOOT.BIN
+
+the_ROM_image:
+{
+    [bootloader, destination_cpu=a53-0]    ${FSBL_ELF}
+    [destination_cpu=a53-0]                ${APP_ELF}
+}