Ubuntu images for Zynq

Koheron SDK V1 documentation. You are reading the documentation for the V1 branch. It uses CFG=.../config.mk, memory.yml, Linux FPGA Manager and device-tree overlays. It is not backward-compatible with 0.x instruments.

Overview

Images provide the runtime environment needed to upload, start and serve instruments.

Generated SD card images use Ubuntu 24.04.3 with a Xilinx 2025.1-based kernel. The runtime uses Linux FPGA Manager and device-tree overlays to load instruments.

Runtime services

An image includes services for:

  • serving the web interface with nginx
  • proxying WebSocket traffic to koheron-server
  • exposing the HTTP API used to upload and run instruments
  • running the selected instrument server
  • loading FPGA bitstreams through FPGA Manager
  • applying the generated pl.dtbo device-tree overlay

Build an image

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

For the ALPHA250 FFT example, this target creates:

tmp/examples/alpha250/fft/alpha250-fft.zip

The release archive contains the SD card image, manifest and SHA256 checksum. The image target builds the root filesystem overlay, boot files and default instrument artefacts for the selected board.

Instrument archive runtime

The instrument archive used by the runtime is separate from the release archive above. For the ALPHA250 FFT example, it is created at:

tmp/examples/alpha250/fft/fft.zip

and copied to:

tmp/alpha250/instruments/fft.zip

The instrument archive contains:

  • runtime FPGA bitstream binary (fft.bit.bin)
  • device-tree overlay (pl.dtbo)
  • Vivado bitstream (fft.bit)
  • server executable (serverd)
  • generated driver metadata (drivers.json)
  • web assets
  • version file

The board can upload and run the instrument archive without rebuilding the full OS.

Compatibility

These images are for the current instrument flow. 0.x instruments should continue to use 0.x images and 0.x documentation.

Some instruments may still run on some 0.x images through the legacy /dev/xdevcfg path, but this is not the current runtime path.

Development workflow

During normal development, rebuild and upload only the instrument archive:

make -j CFG=examples/alpha250/fft/config.mk HOST=192.168.1.100 run

Rebuild the full image only when changing the OS, boot files, kernel, default instrument, services or board support files.

See also

[email protected]