Migration guide

This branch changes both the build configuration model and the runtime FPGA-loading path. It is not backward-compatible with 0.x instruments.

Runtime compatibility

• Instruments built with this branch may still run on some 0.x OS images through the legacy /dev/xdevcfg path.
• Current images use Linux FPGA Manager and device-tree overlays to load the Programmable Logic.
• Current images do not support legacy 0.x instruments.

Build command

The old CONFIG=.../config.yml argument is replaced by CFG=.../config.mk.

# 0.x
make CONFIG=examples/alpha250/fft/config.yml

# Current branch
make CFG=examples/alpha250/fft/config.mk

Configuration files

The old config.yml information is split into two files:

• config.mk contains build settings such as the instrument name, board path, Vivado cores, drivers and web assets.
• memory.yml contains the memory map, register lists, Linux device mappings and build-time parameters.

The build system uses memory.yml to generate memory.tcl, memory.hpp and memory.dtsi.

FPGA Manager and device-tree overlays

The legacy /dev/xdevcfg path is no longer present on current images. Each instrument ships:

• a bitstream binary loaded by FPGA Manager, for example <instrument>.bit.bin
• a device-tree overlay, pl.dtbo
• a compiled server executable, serverd
• generated driver metadata and web assets

The overlay is compiled from generated and user-provided device-tree sources. A typical wrapper includes the Vivado/Vitis-generated PL description, the memory map generated from memory.yml, and an optional user override:

/dts-v1/;
/plugin/;
/include/ "pl.dtsi"
/include/ "memory.dtsi"
/include/ "override.dtsi"

Memory mapped devices

A memory region can request a specific Linux mapping device with the dev attribute. For example, a write-combined memory mapping can be selected with /dev/mem_wc:

memory:
  - name: ram
    offset: 0x1E00_0000
    range: 32M
    compatible: "koheron,mem-wc-1.0"
    dev: /dev/mem_wc

For interrupt-driven userspace access, a memory region can be mapped through /dev/uio and paired with a device-tree override that binds the node to generic-uio.

memory:
  - name: fifo
    offset: 0x43C0_0000
    range: 64K
    dev: /dev/uio

&axi_fifo_mm_s_0 {
    compatible = "generic-uio";
    status = "okay";
    linux,uio-name = "irq-fifo";
    linux,driver-override = "uio_pdrv_genirq";
};

Image build

Image builds can be launched in parallel without sudo:

make -j CFG=examples/alpha250/fft/config.mk image

Porting checklist

1. Create config.mk next to the instrument sources.
2. Move memory regions, registers and parameters to memory.yml.
3. Replace CONFIG=.../config.yml commands with CFG=.../config.mk.
4. Check that the block design uses the generated memory and register names.
5. Add or update dts/override.dtsi when Linux drivers or UIO bindings are needed.
6. Build the instrument archive and verify that the ZIP contains the bitstream binary and pl.dtbo.
7. Test on a current image before removing the old 0.x configuration.

See also

• Documentation
• Documentation