Examples

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.

Goal

Use a known reference instrument to verify the complete workflow before creating or porting your own design.

The recommended first example is the ALPHA250 FFT instrument. It exercises the main parts of the build system: FPGA bitstream generation, device-tree overlay generation, C++ server compilation, web asset build and instrument packaging.

Source layout

examples/alpha250/fft/
  config.mk
  memory.yml
  block_design.tcl
  fft.hpp
  fft.cpp
  web/

Source code:

Build the reference instrument

git clone -b V1 https://github.com/Koheron/koheron-sdk.git
cd koheron-sdk
make setup
make -j CFG=examples/alpha250/fft/config.mk

The build creates the instrument archive at:

tmp/examples/alpha250/fft/fft.zip

It also copies the same archive to the board-level instrument store used by image builds:

tmp/alpha250/instruments/fft.zip

Run on a board

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

Replace HOST with the board IP address. The run target uploads tmp/examples/alpha250/fft/fft.zip through the HTTP API and starts the instrument.

Build a bootable image

Build an SD card image when you need to regenerate the operating system or default runtime image:

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

For the ALPHA250 FFT example, the image target creates a release archive at:

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

During normal instrument development, rebuilding and uploading the instrument archive is usually enough.

What the example demonstrates

config.mk selects the board, FPGA constraints, cores, C++ drivers and web files:

NAME := fft
VERSION := 0.2.1
BOARD_PATH := $(SDK_PATH)/boards/alpha250

memory.yml defines memory regions, register names and parameters used by generated Tcl, C++ and device-tree files:

parameters:
  fclk0: 200000000
  adc_clk: 250000000
  dac_width: 16
  adc_width: 16
  n_adc: 2
  fft_size: 8192

The generated instrument archive contains:

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

Create a new instrument from the example

Copy the reference example to a new directory:

cp -r examples/alpha250/fft examples/alpha250/my-instrument
make -j CFG=examples/alpha250/my-instrument/config.mk

Then update the project in this order:

  1. Rename NAME and update VERSION in config.mk.
  2. Adjust CORES, DRIVERS, XDC and WEB_FILES in config.mk.
  3. Update memory regions, registers and parameters in memory.yml.
  4. Update the block design connections in block_design.tcl.
  5. Update the C++ driver API.
  6. Update Python or TypeScript clients after the C++ API is stable.

Relationship with 0.x examples

0.x examples use config.yml and are built with CONFIG=.../config.yml. This branch uses config.mk and memory.yml and is built with CFG=.../config.mk. Do not mix the two formats in the same instrument.

See also

[email protected]