work / aurascope / step 01

Yocto setup & the dependency maze

// phase 1 · foundation · Yocto 5.0 "Scarthgap" · meta-xilinx rel-v2025.2

The goal

Take the verified .xsa from the hardware step and turn it into a real Yocto machine — a named, reproducible build target generated directly from this project's own hardware description, not a generic or community board definition.

Matching the branches first

Rather than guess a branch, I listed what actually exists upstream before cloning anything:

git ls-remote --heads https://github.com/Xilinx/meta-xilinx | grep rel-v

rel-v2025.2 matches the Vivado version used to produce the .xsa. But a branch existing isn't the same as it being compatible with the Yocto release already chosen (Scarthgap). The authoritative check is what each sub-layer declares about itself — not the README:

git clone -b rel-v2025.2 https://github.com/Xilinx/meta-xilinx
find . -name "layer.conf" -exec grep -H "LAYERSERIES_COMPAT" {} \;

./meta-xilinx-core/conf/layer.conf:LAYERSERIES_COMPAT_xilinx = "scarthgap"
./meta-xilinx-bsp/conf/layer.conf:LAYERSERIES_COMPAT_xilinx-bsp = "scarthgap"
... (every sub-layer, same result)

Confirmed. Branch locked in before writing anything that depended on it.

Registering layers — a cascade, not a list

What looked like "add five layers" turned into a round of dependency errors, each one naming a layer I hadn't added yet:

bitbake-layers add-layer ../meta-arm/meta-arm

ERROR: Layer 'meta-arm' depends on layer 'arm-toolchain', but this layer is not enabled

meta-arm is a multi-layer repo — its toolchain sub-layer has to go in first. Fixed that, then hit the next one:

bitbake-layers add-layer ../meta-xilinx/meta-xilinx-core

ERROR: Layer 'xilinx' depends on layer 'meta-arm', but this layer is not enabled

This confirmed that meta-arm isn't optional — meta-xilinx-core genuinely requires it (for the ARM Trusted Firmware / secure-boot plumbing under the Zynq boot chain). Once both were in, everything else registered cleanly.

The dead end: following a deprecated layer's own advice

Once the layers were registered I noticed meta-xilinx-bsp's own README:

This layer is deprecated. All BSP components have been moved to other layers.
SDT based machines are in meta-amd-adaptive-socs-bsps.

Reasonable to follow that pointer. I cloned meta-amd-adaptive-socs and tried registering it. Each fix surfaced a new, deeper dependency rather than terminating:

ERROR: depends on 'xilinx-microblaze', 'xilinx-standalone', 'xilinx-standalone-sdt'
ERROR: 'xilinx-standalone-sdt' depends on 'virtualization-layer'
ERROR: 'xilinx-virtualization' depends on 'security', 'tpm-layer', 'virtualization-layer'

I stepped back rather than keep pulling in unrelated infrastructure because a deprecated README pointed there. The question was whether the older, simpler tool for consuming a .xsa directly was still around.

# revert the entire detour
bitbake-layers remove-layer '*/meta-amd-adaptive-socs-bsp'
bitbake-layers remove-layer '*/meta-amd-adaptive-socs-core'
bitbake-layers remove-layer '*/meta-xilinx-standalone-sdt'
bitbake-layers remove-layer '*/meta-xilinx-virtualization'

What actually worked: gen-machineconf

meta-xilinx-core still ships gen-machineconf — a standalone Python tool that consumes a .xsa directly. It was a git submodule that hadn't been initialized:

cd meta-xilinx
git submodule status
-e1bc2ac3... meta-xilinx-core/gen-machine-conf  # leading '-' = uninitialized

git submodule update --init --recursive

The tool's own docs confirmed the classic .xsa flow is still present — marked deprecated, but documented and functional. Three attempts to actually run it:

# attempt 1 — missing XSCT entirely
./gen-machineconf --soc-family zynq \
  --hw-description ~/aurascope-yocto/aurascope/hw/design_2_wrapper.xsa \
  --machine-name aurascope-arty-z7
[ERROR] xsct command not found, use --xsct-tool option to specify path

# attempt 2 — pointed at the binary, still failed
./gen-machineconf ... --xsct-tool /opt/2025.2/Vitis/bin/xsct
[ERROR] XSCT_TOOL path not found: /opt/2025.2/Vitis/bin/xsct

# attempt 3 — installation root, not the binary
./gen-machineconf --soc-family zynq \
  --hw-description ~/aurascope-yocto/aurascope/hw/design_2_wrapper.xsa \
  --machine-name aurascope-arty-z7 \
  --xsct-tool /opt/2025.2/Vitis
[INFO] Getting Platform info from HW file
[INFO] Generating Kconfig for project
[INFO] Silentconfig project
[INFO] Generating configuration files
[INFO] Generating machine conf file
[NOTE] Add to your local.conf:
MACHINE = "aurascope-arty-z7"

One thing worth clarifying

gen-machineconf prints "Starting bitbake server" and looks like a BitBake command. It isn't. It's a standalone Python script that reuses BitBake's config-parsing library internally — it reads the .xsa offline and writes a machine .conf as plain text. No build happens at this step. bitbake proper only enters once the generated machine is wired into local.conf and an image target is actually built.

The honest lesson

The officially recommended path isn't always the one that fits the job. The deprecated BSP layer pointed at an SDT migration that pulled in four layers of unrelated infrastructure. Recognizing that and stepping back to a simpler tool that still worked collapsed the whole problem down to a submodule init and a path-format surprise.

Code

Tagged at v0.1 · full command-by-command log: docs/notes/phase1-log.md