# Advanced: project structure and customization

This section is intended for users who want to modify the reference
designs — adding IP to the block design, changing constraints, modifying
the standalone application, or adding packages or drivers to the
PetaLinux project. It describes how the repository is laid out, how the
Make-driven build flow works, how the Vitis and PetaLinux sides are
organised, and what modifications have been added on top of the stock
AMD BSPs.

The actual *build* instructions are in [build_instructions](build_instructions);
this section is about understanding the project well enough to modify
it.

## Repository layout

```
.
├── Makefile                   <- Top-level build entry point
├── README.md
├── config/                    <- Source-of-truth design metadata and auto-generation
│   ├── data.json
│   └── update.py
├── docs/                      <- This documentation (Sphinx + Read the Docs)
├── EmbeddedSw/                <- Vendored AMD BSP libraries used by the Vitis build
├── PetaLinux/
│   ├── Makefile               <- PetaLinux build orchestration
│   └── bsp/                   <- Per-board and per-port-config BSP fragments
│       ├── uzev/, zcu102/, vck190/, …   <- board-specific overlays
│       └── ports-0123/, ports-0xxx/     <- port-config overlays
├── submodules/                <- Vendor board definition files (BDFs)
├── Vivado/
│   ├── Makefile               <- Vivado build orchestration
│   ├── scripts/
│   │   ├── build.tcl          <- Project creation + block design assembly
│   │   └── xsa.tcl            <- Synthesis, implementation, XSA export
│   └── src/
│       ├── bd/
│       │   ├── bd_mb.tcl      <- Block design for MicroBlaze targets
│       │   ├── bd_zynqmp.tcl  <- Block design for Zynq UltraScale+ targets
│       │   ├── bd_versal.tcl  <- Block design for Versal targets
│       │   └── gt_locs.tcl    <- Per-target GT-quad placement constants
│       └── constraints/
│           └── <target>.xdc   <- One XDC per target (pin assignments, timing)
└── Vitis/
    ├── Makefile               <- Vitis workspace + boot-image orchestration
    ├── py/
    │   ├── args.json          <- Repo-specific Vitis flow configuration
    │   ├── build-vitis.py     <- Universal Vitis Python build driver
    │   ├── make-boot.py       <- BOOT.BIN / .mcs packaging
    │   ├── pre_build.py       <- Per-build hook (e.g. constants generation)
    │   └── pre_platform_build.py
    ├── common/
    │   └── src/               <- Standalone application source (echo_server + VADJ)
    └── <target>_workspace/    <- Per-target Vitis workspace (generated)
```

Per-target build outputs are written to `Vivado/<target>/`,
`Vitis/<target>_workspace/`, and `PetaLinux/<target>/`; packaged
boot-image zips are written to `bootimages/`. None of these are
committed.

## Target naming

A `TARGET` is the canonical handle for a single design and is the only
parameter passed through the build flow. It encodes the board and, for
boards with multiple FMC connectors, the connector:

```
<board>[_<connector>]
```

Examples: `uzev`, `vck190_fmcp1`, `zcu102_hpc0`, `kcu105_hpc`,
`vcu118_fmcp`. The first underscore-delimited token is taken as the
*target board* and is what `PetaLinux/Makefile` uses to select the BSP
under `PetaLinux/bsp/<board>/`.

The complete list of valid targets is in the `UPDATER START` block of
each Makefile and is generated from `config/data.json` (see below).

## `config/data.json` and `config/update.py`

`config/data.json` is the canonical source of truth for the set of
supported designs and their per-target metadata (board name, processor
family, FMC connector, port lane mapping, baremetal-vs-PetaLinux
support, etc.). `config/update.py` reads `data.json` and regenerates
the auto-managed sections of the four Makefiles, the top-level
`README.md`, and `.gitignore` — the sections delimited by
`UPDATER START` / `UPDATER END` comment markers.

When adding or modifying a target, edit `data.json` and re-run
`update.py`. Do not hand-edit content between the `UPDATER START` /
`UPDATER END` markers; it will be overwritten on the next regeneration.

## Make-driven build flow

There are four Makefiles in the repository, each scoped to a stage of
the build:

| Makefile              | Scope                                                                                          |
|-----------------------|------------------------------------------------------------------------------------------------|
| `./Makefile`          | Top-level orchestration; assembles boot-image zips for one or all targets.                     |
| `./Vivado/Makefile`   | Creates the Vivado project, runs synthesis and implementation, exports the XSA.                |
| `./Vitis/Makefile`    | Creates the Vitis workspace and platform from the XSA, builds the standalone application, packages BOOT.BIN/.mcs. |
| `./PetaLinux/Makefile`| Creates the PetaLinux project from the XSA, applies BSP overlays, builds, packages.            |

A `make bootimage TARGET=<t>` invocation at the top level cascades:

```
make bootimage TARGET=t
  -> Vitis side:
       Vitis/Makefile workspace TARGET=t -> bootfile TARGET=t
         -> ensures Vivado XSA exists
              Vivado/Makefile xsa TARGET=t
                -> vivado -mode batch -source scripts/build.tcl   (creates project)
                -> vivado -mode batch -source scripts/xsa.tcl     (synth, impl, XSA export)
         -> python3 py/build-vitis.py  ... (creates platform + app, builds)
         -> python3 py/make-boot.py    ... (packages BOOT.BIN / .mcs)
  -> PetaLinux side:
       PetaLinux/Makefile petalinux TARGET=t
         -> petalinux-create --template <microblaze|zynqMP|versal> --name t
         -> petalinux-config --get-hw-description <XSA>
         -> copy bsp/<board>/project-spec/* into the project       (if a board BSP exists)
         -> copy bsp/<port-config>/project-spec/* into the project (overlay)
         -> petalinux-config --silentconfig
         -> petalinux-build
         -> petalinux-package boot ...
  -> zip the resulting boot files into bootimages/
```

Per-target lock files (`.<target>.lock` in each Makefile's directory)
prevent two concurrent builds of the same target from clobbering each
other.

## Vivado side

### Block design

The block-design scripts live under `Vivado/src/bd/`, one per
processor family, plus a shared GT-placement helper:

* `bd_mb.tcl`     — MicroBlaze targets (auboard, kcu105_hpc, vcu118_fmcp).
* `bd_zynqmp.tcl` — Zynq UltraScale+ targets.
* `bd_versal.tcl` — Versal targets.
* `gt_locs.tcl`   — Tcl dictionary mapping each target to its per-port
  GT coordinates (e.g. `dict get $gt_loc_dict uzev 0` returns `X0Y8`),
  sourced from `bd_mb.tcl` to drive the AXI Ethernet Subsystem IP
  configuration. Edit this dictionary when adding a new MicroBlaze
  target or changing its GT-quad placement.

Each script contains per-board conditional blocks where a target needs
to deviate from the family defaults — typically for clock-source
selection, PS configuration, or FMC connector routing.

After sourcing the BD script, `scripts/build.tcl` runs
`validate_bd_design -force`, which triggers parameter propagation and
fills in connection-automation rules. As a result the final
implemented design may contain nets that aren't visible in the BD TCL
source — to see the actual netlist as built, inspect the saved `.bd`
file under `Vivado/<target>/<target>.srcs/sources_1/bd/<bd_name>/` or
use `write_bd_tcl` to export a complete script from an open project.

### Constraints

`Vivado/src/constraints/<target>.xdc` contains pin assignments and any
target-specific timing constraints. Constraints common to all targets
of a given family are not factored out — each target's XDC is
self-contained.

### Build scripts

* `Vivado/scripts/build.tcl` creates the Vivado project, adds the
  target's XDC, sources the appropriate `bd_*.tcl`, and validates the
  block design. Invoked via `make project TARGET=<t>`.
* `Vivado/scripts/xsa.tcl` opens the existing project, runs synthesis
  and implementation, exports the XSA, and writes the bitstream into
  the implementation run directory. Invoked via `make xsa TARGET=<t>`.

Both scripts check `XILINX_VIVADO` to confirm the installed Vivado
version matches the `version_required` constant at the top of the
file. Bumping the project to a new Vivado release means changing those
constants and re-testing — the BD TCL APIs are not stable across major
releases.

### Modifying the block design

Edit the block-design script for the appropriate processor family
directly. If the change applies only to some targets in the family,
wrap the additions in the appropriate per-board conditional block.

Once the script is edited, delete any existing per-target Vivado
project directory (`rm -rf Vivado/<target>`) and re-run the Vivado
build through the Makefile:

```
make -C Vivado xsa TARGET=<target>
```

This re-creates the project, sources the modified BD script, runs
`validate_bd_design`, synthesises, implements, and re-exports the XSA.
Downstream Vitis / PetaLinux / boot-image steps will pick up the new
XSA on the next `make` at the top level.

### Adding or modifying constraints

Edit `Vivado/src/constraints/<target>.xdc` directly. If a constraint
applies to all targets in a family, it still needs to be replicated to
each target's XDC — there is no shared XDC.

## Vitis side

The standalone (baremetal) build runs the lwIP echo-server example on
the target, exercising the AXI Ethernet ports. The application source
is shared across all targets; per-target specialisation is handled by
the build driver, not by per-target source.

The Ethernet FMC Max requires the FMC adjustable I/O voltage rail (VADJ)
to be programmed to 1.5V before the on-board PHYs come out of reset. On
Versal targets that do not enable VADJ from the platform itself, the
standalone application performs that programming at startup via the
`vadj.c` / `vadj.h` files in `common/src` (the entry point in `main.c`
calls `vadj_enable(VADJ_1V5)`). VEK280 already enables VADJ by default
and this call is a no-op. Non-Versal boards rely on the FSBL (ZCU102/
ZCU106) or board-default rails to bring VADJ up; the ZCU104 FSBL needs
the patch listed under the ZCU104 BSP section below.

### Layout

```
Vitis/
├── Makefile
├── py/
│   ├── args.json
│   ├── build-vitis.py        <- Universal Vitis Python build driver
│   ├── make-boot.py          <- BOOT.BIN / .mcs packaging
│   ├── pre_build.py          <- Hook run before each app build
│   └── pre_platform_build.py <- Hook run before each platform build
├── common/
│   └── src/                  <- Application source: main.c + vadj.c/h
├── boot/<target>/            <- Per-target packaged boot files
└── <target>_workspace/       <- Generated Vitis workspace per target
```

### `args.json`

`Vitis/py/args.json` is the repo-specific configuration that drives
the universal `build-vitis.py` driver. The key fields are:

* `bd_name` — block-design name (`axieth`).
* `app_name` — name of the Vitis application (`echo_server`).
* `app_template` — the Vitis app template the build driver uses to
  scaffold the application (`lwip_echo_server`).
* `bsp_libs` — BSP libraries to add and configure (`lwip220` with
  DHCP + ACD check + an enlarged pbuf pool, and `xiltimer` with the
  interval timer enabled).
* `src` — application source mapping. `"all": "common/src"` means
  every target uses the same source directory.
* `pre_platform_build_script` / `pre_build_script` — hooks invoked at
  the appropriate point in the workspace build.

### Modifying the standalone application

Edit `Vitis/common/src/*.c` directly. The next `make -C Vitis bootfile
TARGET=<t>` rebuilds the application against the existing platform; if
you've changed the hardware (XSA) you'll need a fresh workspace
(`make -C Vitis clean TARGET=<t>` first).

### Modifying BSP libraries or build hooks

Adjust the corresponding entry in `Vitis/py/args.json`. Configuration
changes propagate through the next `pre_platform_build` run. The two
hook scripts in `py/` are repo-specific Python; edit them when the
change is more elaborate than a `bsp_libs` config tweak.

## PetaLinux side

### BSP composition

The PetaLinux project for a given target is composed at build time
from up to two BSP fragments copied into the target's project
directory:

1. A **board BSP** at `PetaLinux/bsp/<board>/` (for example `uzev/`,
   `zcu102/`, `vck190/`). Provides board-specific kernel and U-Boot
   configuration, the system device-tree fragment for the board, and
   any board-specific patches. **MicroBlaze targets (auboard,
   kcu105_hpc, vcu118_fmcp) do not have a board BSP**; only the
   port-config overlay is applied to them.
2. A **port-config overlay** at `PetaLinux/bsp/<port-config>/` (one
   of `ports-0123/` or `ports-0xxx/`). Provides `port-config.dtsi` —
   the device-tree fragment that wires up the AXI Ethernet ports
   active on this target.

The mapping from target to (board BSP, port-config overlay) is encoded
in `PetaLinux/Makefile`'s `UPDATER` block. The last column names the
port-config overlay; the board BSP is derived from the first token of
the target name.

The two port-config variants are:

* `ports-0123` — four-port designs (all multi-port targets).
* `ports-0xxx` — single-port designs (currently `zcu104`). Configures
  only port 0, and overrides the AXI Ethernet PHY to SGMII with an
  explicit MDIO PHY node (the ZCU104 routes only one Ethernet lane
  through the FMC).

### Layout of a board BSP

```
PetaLinux/bsp/<board>/project-spec/
├── configs/
│   ├── config                <- petalinux-config: bootargs, rootfs, hostname
│   ├── rootfs_config         <- petalinux-config -c rootfs: included packages
│   ├── init-ifupdown/
│   │   └── interfaces        <- /etc/network/interfaces
│   └── busybox/
│       └── inetd.conf
└── meta-user/
    ├── conf/
    │   ├── user-rootfsconfig <- declares additional rootfs config options
    │   ├── petalinuxbsp.conf
    │   └── layer.conf
    ├── recipes-bsp/
    │   ├── device-tree/
    │   │   ├── device-tree.bbappend
    │   │   └── files/
    │   │       └── system-user.dtsi    <- board-specific DT additions
    │   ├── u-boot/
    │   │   ├── u-boot-xlnx_%.bbappend
    │   │   └── files/
    │   │       ├── bsp.cfg             <- U-Boot Kconfig additions
    │   │       ├── platform-top.h
    │   │       └── *.patch             <- U-Boot source patches
    │   └── embeddedsw/                 <- (zcu104 only)
    │       ├── fsbl-firmware_%.bbappend
    │       └── files/
    │           └── zcu104_vadj_fsbl.patch
    └── recipes-kernel/
        └── linux/
            ├── linux-xlnx_%.bbappend
            └── linux-xlnx/
                └── bsp.cfg             <- kernel Kconfig additions
```

### Adding a package to the root filesystem

1. Append the new option to `bsp/<board>/project-spec/configs/rootfs_config`:

   ```
   CONFIG_<package>=y
   ```

2. If the package is not in the default `petalinux-config -c rootfs`
   menu, also append a declaration line to
   `bsp/<board>/project-spec/meta-user/conf/user-rootfsconfig`.

3. If the package is not provided by an existing meta-layer, add a
   recipe under
   `bsp/<board>/project-spec/meta-user/recipes-apps/<package>/<package>.bb`.

### Adding a kernel config option

Append the option to
`bsp/<board>/project-spec/meta-user/recipes-kernel/linux/linux-xlnx/bsp.cfg`:

```
CONFIG_<name>=y
```

The corresponding bbappend at `recipes-kernel/linux/linux-xlnx_%.bbappend`
registers `bsp.cfg` as a kernel configuration fragment.

### Adding a device-tree fragment

For per-board fragments, edit
`bsp/<board>/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi`.
For per-port-config fragments, edit the corresponding
`bsp/<port-config>/project-spec/meta-user/recipes-bsp/device-tree/files/port-config.dtsi`.

If you add new files, ensure they are listed in `SRC_URI:append` in
`device-tree.bbappend`.

### Adding a kernel patch or out-of-tree driver

1. Drop the patch file into
   `bsp/<board>/project-spec/meta-user/recipes-kernel/linux/linux-xlnx/`.
2. Add a line to `recipes-kernel/linux/linux-xlnx_%.bbappend`:

   ```
   SRC_URI:append = " file://<your-patch>.patch"
   ```

### Modifying U-Boot

The same pattern as the kernel, under
`bsp/<board>/project-spec/meta-user/recipes-bsp/u-boot/`. `bsp.cfg`
adds U-Boot Kconfig options; `platform-top.h` overrides the U-Boot
platform header; patches are listed in `SRC_URI:append` in
`u-boot-xlnx_%.bbappend`.

## Modifications layered on the stock BSPs

The board BSPs in this repository started as the corresponding stock
AMD reference BSPs and have been modified in the following ways. This
list is the answer to *"what would I lose if I overwrote the BSP with
the stock one?"* — it is what to re-apply if you ever do that.

### All BSPs

* **Root filesystem additions** in `configs/rootfs_config`:
  `ethtool`, `iperf3`, `phytool` (plus `ethtool-dev` and `ethtool-dbg`
  on ZynqMP).
* **Hostname / product name** set in `configs/config` via
  `CONFIG_SUBSYSTEM_HOSTNAME` and `CONFIG_SUBSYSTEM_PRODUCT`.
* **`system-user.dtsi`** includes `port-config.dtsi`. The matching
  `device-tree.bbappend` adds both files to `SRC_URI:append`.
* **Kernel configs** in `linux-xlnx/bsp.cfg`:
  `CONFIG_AMD_PHY`, `CONFIG_XILINX_PHY` (needed for the PHYs used by
  the AXI Ethernet ports).

### ZynqMP BSPs

* **SD-card root filesystem** configured in `configs/config`:
  `CONFIG_SUBSYSTEM_ROOTFS_EXT4`, `CONFIG_SUBSYSTEM_SDROOT_DEV`,
  `CONFIG_SUBSYSTEM_USER_CMDLINE` (with `cma=1536M` for the AXI DMA
  buffers — except the UZ-EV, which overrides this to `cma=1000M` to fit
  the smaller SoM DDR budget; see the UZ-EV section below).
* **DMA-engine kernel configs**:
  `CONFIG_XILINX_DMA_ENGINES`, `CONFIG_XILINX_DPDMA`,
  `CONFIG_XILINX_ZYNQMP_DMA`.
* **U-Boot patch `0001-ubifs-distroboot-support.patch`** (one copy lives in
  each ZynqMP board BSP under `recipes-bsp/u-boot/files/`).

### UltraZed-EV (uzev) BSP

* **`CONFIG_YOCTO_MACHINE_NAME="zynqmp-generic"`** in `configs/config`
  (the UZ-EV is not a stock Xilinx eval board).
* **SD-card device set to `/dev/mmcblk1p2`** rather than the ZynqMP
  default `mmcblk0p2`.
* **`PRIMARY_SD_PSU_SD_1_SELECT=y`** to route the boot SD interface
  through PSU SD1 instead of SD0.
* **Custom `system-user.dtsi`** with UZ-EV-specific peripheral
  configuration (overwrites the file copied in from a stock UZ-EV BSP).
* **`meta-xilinx-tools/recipes-bsp/uboot-device-tree/`** overlay that
  overrides the U-Boot device tree.

### ZCU104 BSP

* **FSBL patch `zcu104_vadj_fsbl.patch`** in
  `recipes-bsp/embeddedsw/files/`, registered via
  `fsbl-firmware_%.bbappend`. The stock 2025.2 ZCU104 FSBL reads the wrong
  EEPROM (the board EEPROM at I2C address 0x54 on TCA9548A channel 1
  instead of the FMC EEPROM at 0x50 on channel 6) and only reads 32 bytes,
  which is not enough to reach the VADJ voltage record. The patch fixes
  the EEPROM address (0x50), the mux channel (channel 6 = 0x20), the
  buffer size (256 bytes), and adds the missing "set read address to zero"
  write, so the FSBL can correctly detect the FMC's VADJ requirement and
  program the on-board IRPS5401 PMBus regulator accordingly.
* Standard ZynqMP SD-root configs and U-Boot ubifs patch as above.

### Versal BSPs (vck190, vmk180, vpk120, vpk180, vhk158, vek280)

* **`meta-xilinx-tools/recipes-bsp/uboot-device-tree/`** overlay that
  overrides the U-Boot device tree — required because the stock U-Boot
  device tree does not describe the FMC-side AXI Ethernet ports.
* **U-Boot patch `0001-xilinx_versal.h-ubifs-distroboot-support.patch`**.

### Port-config overlays

The two overlays in `PetaLinux/bsp/ports-*/` are not derived from any
stock BSP — they exist solely to add the device-tree fragment that
wires up the AXI Ethernet ports. Each contains a single
`port-config.dtsi` (the surrounding directory structure is needed so
that Yocto picks it up via the `SRC_URI:append = " file://port-config.dtsi"`
line in `device-tree.bbappend`).

## Where build outputs land

| Path                                | Contents                                                                       |
|-------------------------------------|--------------------------------------------------------------------------------|
| `Vivado/<target>/`                  | Vivado project. `<bd_name>_wrapper.xsa` is the export.                          |
| `Vivado/<target>/<target>.runs/impl_1/<bd_name>_wrapper.bit` | Bitstream.                                              |
| `Vivado/logs/`                      | Per-target Vivado build logs (xpr + xsa).                                       |
| `Vitis/<target>_workspace/`         | Per-target Vitis workspace (platform + application + BSP).                      |
| `Vitis/boot/<target>/`              | Packaged Vitis boot files (`BOOT.BIN` for Zynq/ZynqMP/Versal, `.mcs` for MicroBlaze). |
| `PetaLinux/<target>/`               | PetaLinux project. All Yocto build state lives here.                            |
| `PetaLinux/<target>/images/linux/`  | `BOOT.BIN`, `image.ub`, `boot.scr`, `rootfs.tar.gz`, etc.                       |
| `PetaLinux/<target>/build/build.log`| PetaLinux build log.                                                            |
| `bootimages/`                       | Per-target zipped boot files (`<prj>_<target>_petalinux-<ver>.zip` and `<prj>_<target>_standalone-<ver>.zip`). |

None of these directories are committed to the repository.