work / aurascope / step 02

Custom image & recipe

// phase 1 · foundation · Yocto 5.0 "Scarthgap" · meta-xilinx rel-v2025.2 · MACHINE=aurascope-arty-z7

The goal

Step 01 got a machine generated from the real .xsa, but nothing had actually built yet. meta-aurascope was still just a layer skeleton — conf/layer.conf and nothing else — and local.conf still defaulted MACHINE to qemux86-64. The goal here was bitbake aurascope-image succeeding for the real board, not the QEMU stand-in.

The image recipe

meta-aurascope/recipes-core/images/aurascope-image.bb, modeled directly on poky's core-image-minimal.bb:

SUMMARY = "AuraScope base image for the Arty Z7-20 (Zynq-7000)"
LICENSE = "MIT"
inherit core-image
IMAGE_INSTALL = "packagegroup-core-boot ${CORE_IMAGE_EXTRA_INSTALL}"
IMAGE_ROOTFS_SIZE ?= "8192"
IMAGE_ROOTFS_EXTRA_SPACE:append = "..."

Setting MACHINE = "aurascope-arty-z7" in build/conf/local.conf was enough on its own to get this building for QEMU. Pointing it at the real board is where it got interesting.

Bug: XILINX_WITH_ESW ordering in the generated machine conf

First real-board parse failed with virtual/dtb, fsbl, and virtual/bitstream all reporting "Nothing PROVIDES". The cause was inside the generated build/conf/machine/aurascope-arty-z7.conf itself:

# Required generic machine inclusion
require conf/machine/zynq-generic.conf     <- was BEFORE this

# This is an 'XSCT' based BSP
XILINX_WITH_ESW = "xsct"                   <- ...this

zynq-generic.conf's own comment says hardware-specific variables must be set before its require, because several PREFERRED_PROVIDER defaults in meta-xilinx-core/conf/machine/include/machine-xilinx-default.inc key off XILINX_WITH_ESW at parse time:

PREFERRED_PROVIDER_virtual/dtb ??= "${@'device-tree' if d.getVar('XILINX_WITH_ESW') else ''}"

Fix: move the XILINX_WITH_ESW line above the require line.

I re-ran gen-machineconf once meta-aurascope actually had a recipes-* directory to work with — the earlier run had warned "No bb files in default matched BBFILE_PATTERN_meta-aurascope", which is why it never dropped anything useful into the layer the first time:

./meta-xilinx/meta-xilinx-core/gen-machine-conf/gen-machineconf \
  --soc-family zynq \
  --hw-description aurascope/hw/design_2_wrapper.xsa \
  --machine-name aurascope-arty-z7 \
  --xsct-tool /opt/2025.2/Vitis

Device tree

device-tree.bb (in meta-xilinx-core) self-skips unless CONFIG_DTFILE or SYSTEM_DTFILE is set:

def check_devicetree_variables(d):
    if not d.getVar('CONFIG_DTFILE'):
        raise bb.parse.SkipRecipe(...)

Nothing in the "xsct" flow (used for Zynq-7000 — System Device Tree / lopper-based generation is ZynqMP+/Versal only) ever sets this. The YAML_CONSOLE_DEVICE_CONFIG / YAML_MAIN_MEMORY_CONFIG variables that gen-machineconf writes into the machine conf for "xsct" mode are, as far as I can tell, dead in this meta-xilinx release — I grepped the whole tree and nothing outside gen-machineconf itself reads them.

Rather than hand-write a full Zynq-7000 SoC-level device tree from scratch (real risk of subtly wrong clock/interrupt indices, hard to debug without hardware in hand), I added:

• meta-aurascope/recipes-bsp/device-tree/device-tree.bbappend
• meta-aurascope/recipes-bsp/device-tree/files/system-top.dts

The bbappend re-enables devicetree.bbclass's normal KERNEL_INCLUDE default (device-tree.bb blanks it out by default — "Since we're not based on a kernel default to nothing"), so system-top.dts can #include "zynq-7000.dtsi" and pull in the real, maintained dtsi shipped by linux-xlnx instead of a hand-copied one. This also auto-adds a do_compile dependency on virtual/kernel:do_configure, so the kernel source is staged first.

system-top.dts itself is intentionally minimal for now: a memory node sized for the Arty Z7-20's 1 GiB DDR3L, chosen/stdout-path set to ttyPS0, uart0 forced on. No PL/AXI-GPIO nodes yet — see the bitstream section below.

Bitstream — deferred, not solved

xilinx-bootbin (builds BOOT.bin) pulls in virtual/bitstream by default via BIF_BITSTREAM_ATTR, which defaults to "bitstream" unless MACHINE_FEATURES contains "fpga-overlay". Rather than sourcing an actual .bit file (would need Vivado to build/export one separately from the .xsa, or the .xsa to embed it), I set:

BIF_BITSTREAM_ATTR = ""

in build/conf/local.conf. Meaning:

FSBL — the hard part

fsbl.bb (in meta-xilinx-core) also self-skips unless it's handed a precompiled fsbl.elf via FSBL_FILE, or FSBL_DEPENDS / FSBL_MCDEPENDS point at something that builds one. Three things tried, in order.

a) meta-xilinx-standalone's "fsbl-fw" multiconfig. A ready-made template — conf/multiconfig/fsbl-fw.conf + recipes-bsp/embeddedsw/fsbl-fw-cfg.inc already exist: BBMULTICONFIG += "fsbl-fw", a separate TMPDIR, DISTRO=xilinx-standalone with a real arm-xilinx-eabi toolchain. Wired it up — the multiconfig parsed fine, mc:fsbl-fw context showed TARGET_SYS=arm-xilinx-eabi, DISTRO=xilinx-standalone, correct — but the task graph failed:

ERROR: Task mcdepends on non-existent task
mc:fsbl-fw:.../fsbl-firmware_2025.2.bb:do_deploy

b) Switched XILINX_WITH_ESW from "xsct" to "generic". This mode's fsbl-firmware_generic.inc does have real do_install/do_deploy tasks — compiles zynq_fsbl from embeddedsw source via a Makefile and the multiconfig's cross-compiler. Looked promising, until:

SKIP_MSG:zynq = "Generic support for zynq is not available"

c) Built fsbl.elf directly with Vitis, outside bitbake. Vitis 2025.2 is the "unified" IDE; found a working example at /opt/2025.2/Vitis/cli/examples/embedded/platform_uc4_zynq.py and adapted it — headless, via vitis -s script.py:

client = vitis.create_client()
client.set_workspace(workspace)
platform = client.create_platform_component(
    name='aurascope_platform',
    hw_design='/path/to/aurascope/hw/design_2_wrapper.xsa')
platform.add_domain(name='standalone_a9_0',
                     cpu='ps7_cortexa9_0', os='standalone')
platform.build()

Copied it into the repo and wired it into the recipe:

meta-aurascope/recipes-bsp/embeddedsw/files/fsbl.elf
meta-aurascope/recipes-bsp/embeddedsw/fsbl.bbappend
  FSBL_FILE := "${THISDIR}/files/fsbl"

One more red herring along the way: meta-xilinx-standalone ships its own competing fsbl.bbappend, at higher layer priority than meta-aurascope (7 vs 6), which redefines check_fsbl_variables() with a slightly different error message but the same underlying logic. Not a conflict — just made the error text look like it was coming from somewhere other than expected.

The real build, and a silent board

bitbake -n aurascope-image (dry run) had confirmed the plan: 4637 tasks, 0 missing providers. Running it for real — then flashing to SD and powering up the actual board — was a different story. The board was completely silent on serial for several days.

Everything I could think to suspect turned out correct: SD cards, QSPI, BootROM, PS7 clocks, DDR, MIO routing, the FSBL binary's integrity. The real cause was two missing properties in system-top.dts — the file from the section above.

A third issue wasn't a bug but the single biggest obstacle to diagnosing the first two: the committed FSBL had debug printing compiled out entirely, so "no output" carried no information about how far boot had actually gotten. More on that below.

Fix 1 — the serial0 alias

zynq-7000.dtsi's aliases node defines uart0 and uart1 — the Xilinx convention. Both U-Boot and Linux resolve stdout-path and console=ttyPS0 through the standard names serial0/serial1. Those aliases didn't exist, so no console device was ever bound. Confirmed by decompiling the generated u-boot.dtb: its aliases block listed uart0, uart1, spi0, qspi, gem0, sdhci0, clkc … — no serial0 — while chosen still referenced stdout-path = "serial0:115200n8".

/ {
	aliases {
		serial0 = &uart0;
		serial1 = &uart1;
	};
};

Verification:

dtc -I dtb -O dts \
  tmp/deploy/images/aurascope-arty-z7/u-boot.dtb 2>/dev/null \
  | grep -A25 aliases | grep serial
# expect: serial0 = "/axi/serial@e0000000";

Fix 2 — the PS clock frequency

The clkc@100 node carried no ps-clk-frequency property, so the Zynq clock driver fell back to its built-in default of 33,333,333 Hz — correct for most Xilinx reference boards, but not the Arty Z7's 50 MHz PS clock. Every derived clock, including uart_ref_clk, was 1.5× off, and the UART baud divisors were computed from the wrong base.

&clkc {
	ps-clk-frequency = <50000000>;
};

Corroborated by reading the divisors live off the hardware, rather than just trusting the fix:

Fix 3 — enabling SDHCI0

With the console working, U-Boot reached its prompt but reported MMC: (empty) and No MMC device available — it couldn't read the very card it had just been loaded from. zynq-7000.dtsi defaults sdhci0 to status = "disabled".

&sdhci0 {
	status = "okay";
};

After this, U-Boot found /boot.scr on mmc 0:1 and the full boot chain completed. Ethernet (gem0) came up in the same rebuild.

The final system-top.dts

All three fixes landed with comments explaining why, since neither is self-evident from the symptom:

/dts-v1/;
#include "zynq-7000.dtsi"

/ {
	model = "AuraScope Arty Z7-20";
	compatible = "digilent,zynq-artyz7", "xlnx,zynq-7000";

	/* REQUIRED: zynq-7000.dtsi provides only the Xilinx-style
	 * uart0/uart1 aliases. U-Boot and Linux resolve the console
	 * through the standard serial0/serial1 names. Without these,
	 * stdout-path cannot resolve, no console binds, and
	 * CONFIG_REQUIRE_SERIAL_CONSOLE=y resets the board in a loop. */
	aliases {
		serial0 = &uart0;
		serial1 = &uart1;
	};

	/* Arty Z7-20: 1 GiB DDR3L. */
	memory@0 {
		device_type = "memory";
		reg = <0x0 0x40000000>;
	};

	chosen {
		bootargs = "console=ttyPS0,115200 root=/dev/mmcblk0p2 rw rootwait";
		stdout-path = "serial0:115200n8";
	};
};

&uart0 {
	status = "okay";
};

/* REQUIRED: zynq-7000.dtsi defaults ps-clk-frequency to 33.333 MHz.
 * The Arty Z7 PS clock is 50 MHz. Without this override every derived
 * clock is 1.5x low and the UART transmits at ~172800 baud. */
&clkc {
	ps-clk-frequency = <50000000>;
};

&sdhci0 {
	status = "okay";
};

The real obstacle: an FSBL that couldn't tell me anything

Not a boot bug, but the single largest reason this took days instead of hours: the committed fsbl.elf (from the Vitis build in the section above) had debug printing compiled out.

$ strings fsbl.elf | grep -i fsbl_dbg
fsbl_printf(type,...) if (((type) & fsbl_dbg_current_types)) { xil_printf(...); }
fsbl_dbg_current_types 0

Rebuilt with FSBL_DEBUG_INFO defined (Vitis: project → C/C++ Build Settings → ARM v7 gcc compiler → Symbols; equivalent headless flow):

xsct
platform create -name arty_fsbl -hw hw/design_2_wrapper.xsa \
  -os standalone -proc ps7_cortexa9_0
app create -name fsbl -template {Zynq FSBL} -platform arty_fsbl \
  -domain standalone_ps7_cortexa9_0
app config -name fsbl -add define-compiler-symbols FSBL_DEBUG_INFO
app build -name fsbl
# verify before installing:
strings fsbl.elf | grep -i "first stage"   # must return the banner string

U-Boot notes

A temporary debug-UART config fragment bypassed U-Boot's driver model and device-tree probing entirely, to get an early console. It's what produced the decisive No serial driver found message that pointed at the alias problem in the first place. Removed once the real fix landed, but worth keeping in the layer, commented out, for future early-boot debugging:

# meta-aurascope/recipes-bsp/u-boot/files/debug-uart.cfg  (removed)
CONFIG_DEBUG_UART=y
CONFIG_DEBUG_UART_ZYNQ=y
CONFIG_DEBUG_UART_BASE=0xe0000000
CONFIG_DEBUG_UART_CLOCK=100000000
CONFIG_DEBUG_UART_ANNOUNCE=y

Everything else in the U-Boot config was already correct and didn't need touching:

Diagnostic pitfalls worth not repeating

Several observations were actively misleading during the investigation:

Result

Board boots end to end: FSBL → U-Boot → boot.scr → uImage + system.dtb → Linux → login prompt. Root filesystem mounts r/w on mmcblk0p2, Ethernet links at 100 Mbps, console on ttyPS0. Two device-tree properties were responsible for the entire multi-day failure; everything else investigated (SD cards, QSPI, BootROM, PS7 clocks, DDR, MIO routing, FSBL integrity, bare-metal toolchain) was ruled out by direct evidence, not inference, and didn't need fixing.

Still outstanding

Nothing here blocks the next step, but all of it is real and worth tracking rather than rediscovering later:

SSH is in. USB isn't — yet

With the board on the network, dropbear came up cleanly — no separate debug session needed anymore, just SSH from a normal terminal:

$ ssh root@192.168.1.155
The authenticity of host '192.168.1.155' can't be established.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '192.168.1.155' (ED25519) to the list of known hosts.

WARNING: Poky is a reference Yocto Project distribution that should be used for
testing and development purposes only. It is recommended that you create your
own distribution for production use.

root@aurascope-arty-z7:~#

Next thing to check was whether the nRF5340 audio receiver — plugged into the board's USB host port — was visible at all. It wasn't, and the first attempt didn't even get far enough to say so properly:

root@aurascope-arty-z7:~# lsusb
-sh: lsusb: not found
root@aurascope-arty-z7:~# ls /dev/tty*
/dev/tty    /dev/tty18  /dev/tty28  /dev/tty38  /dev/tty48  /dev/tty58
... (tty0-tty63, all virtual consoles) ...
/dev/ttyPS0

The likely cause isn't software: the board was still running powered from the JTAG/prog USB connector during this test, which is enough to boot Linux but not enough current to also power a downstream USB host port and whatever the nRF5340 dev kit draws while acting as a UAC device. Two things to change before re-testing:

• Switch the board to the dedicated 12 V wall power supply instead of USB/JTAG power.
• Move the JP5 jumper to select that external supply as the power source.

With real power behind the USB host port, the next check is whether the nRF5340 receiver's UAC firmware actually enumerates as a USB sound card — that's the real goal of the wireless audio phase, and the natural next step once power is sorted.

Code

Tagged at v0.2-custom-recipe · code: meta-aurascope