Instrument configuration

Koheron SDK V1 documentation. The V1 branch is recommended for new instrument development and remains under active development ahead of the major release. Boards currently ship with V0; build and install a V1 OS image to follow this workflow. V1 images do not support legacy V0 instruments.

Role of the configuration files

An instrument is selected with CFG=.../config.mk:

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

Configuration files:

config.mk: selects the board, constraints, FPGA cores, C++ drivers and instrument web files.
memory.yml: defines memory regions, registers, Linux mapping devices and build-time parameters.

Typical instrument directory

examples/<board>/<instrument>/
  config.mk
  memory.yml
  block_design.tcl
  <driver>.hpp
  <driver>.cpp
  dts/
    override.dtsi
  web/

`config.mk`

The ALPHA250 FFT configuration selects its cores, drivers and shared web components:

NAME := fft
VERSION := 0.3.0
ENFORCE_TIMING := 1

BOARD_PATH := $(SDK_PATH)/boards/alpha250

FPGA_LIB_TCL = $(FPGA_TCL_FFT)
FPGA_IMPL_TCL = $(FPGA_TCL_HOLD_FIX)
TCL_EXTRA_FILES += $(SDK_PATH)/fpga/ip/awg_v1_0/integration.tcl

XDC += $(SDK_PATH)/boards/alpha250/config/ports.xdc

include $(SDK_PATH)/boards/alpha250/cores/cores.mk
CORES += $(SDK_PATH)/fpga/cores/axis_constant_v1_0
CORES += $(SDK_PATH)/fpga/cores/latched_mux_v1_0
CORES += $(SDK_PATH)/fpga/ip/axis_accumulator_v1_0
CORES += $(SDK_PATH)/fpga/ip/awg_v1_0

include $(SDK_PATH)/boards/alpha250/drivers/drivers.mk
DRIVERS += $(BOARD_PATH)/drivers/phase-modulator.hpp
DRIVERS += $(PROJECT_PATH)/fft.hpp
DRIVERS += $(PROJECT_PATH)/fft.cpp

include $(SDK_PATH)/web/fft/components.mk
include $(SDK_PATH)/web/board-controls/alpha-fft.mk
WEB_FILES += $(shell find "$(PROJECT_PATH)/web" -type f \( -name '*.ts' -o -name '*.html' -o -name '*.css' \))
WEB_FILES := $(filter-out $(PROJECT_PATH)/web/app.ts,$(WEB_FILES)) $(PROJECT_PATH)/web/app.ts
WEB_FILES += $(SDK_PATH)/web/temperature-sensor/temperature-sensor.html
include $(SDK_PATH)/web/power-monitor/components.mk
include $(SDK_PATH)/web/precision-channels/io-template.mk
include $(SDK_PATH)/web/clock-generator/reference-clock.mk
include $(SDK_PATH)/web/clock-generator/sampling-frequency.mk

Common variables:

NAME: instrument name used for the archive and runtime.
VERSION: instrument version string written to the generated version file.
BOARD_PATH: board definition directory.
XDC: Xilinx Design Constraint files.
CORES: FPGA cores imported into the Vivado project.
DRIVERS: C++ driver sources compiled into the server.
WEB_FILES: extra HTML, CSS, TypeScript and related web assets. The top-level Makefile already initializes WEB_FILES with web/main.css and web/koheron.ts.

SDK_PATH is the SDK root; PROJECT_PATH is the directory containing the selected config.mk.

`memory.yml`

memory.yml is the contract between FPGA, C++ drivers and Linux runtime. The ALPHA250 FFT memory map defines:

memory:
  - name: control
    offset: 0x4000_0000
    range: 4K
    registers:
    - mmcm
    - precision_dac_ctl
    - precision_dac_data[2]
    - ctl_fft
    - psd_valid
    - psd_input_sel
    - phase_incr[2]
    - digital_outputs
  - name: ps_control
    offset: 0x4400_0000
    range: 4K
    registers:
    - spi_cfg_data
    - spi_cfg_cmd
  - name: status
    offset: 0x5000_0000
    range: 4K
    registers:
    - adc[n_adc]
    - cycle_index
    - digital_inputs
  - name: ps_status
    offset: 0x5500_0000
    range: 4K
    registers:
    - spi_cfg_sts
  - name: xadc
    offset: 0x43C0_0000
    range: 64K
  - name: demod
    offset: 0x6000_0000
    range: 32K
    dev: /dev/mem_wc
  - name: awg
    offset: 0x4800_0000
    range: 8K
  - name: psd
    offset: 0x7000_0000
    range: 32K
    dev: /dev/mem_wc

parameters:
  fclk0: 143000000
  adc_clk: 250000000
  dac_width: 16
  adc_width: 16
  n_adc: 2
  fft_size: 8192
  n_cycles: 1023
  cic_differential_delay: 1
  cic_decimation_rate: 500
  cic_n_stages: 6

Memory fields:

name: generated memory identifier, for example mem::control.
offset: physical base address.
range: mapped address range.
registers: optional list of named registers in the region.
dev: optional Linux mapping device, for example /dev/mem_wc or /dev/uio.
compatible: optional device-tree compatible string for generated overlay fragments.

Parameters can be used by generated files and register arrays, for example adc[n_adc].

Generated files

The build system uses memory.yml to generate:

tmp/<project>/fpga/memory.tcl for Vivado block design scripts.
tmp/<project>/server/memory.hpp for C++ server drivers.
tmp/<project>/os/pl-overlay/memory.dtsi for the Linux device-tree overlay.

Linux device mapping

Use dev when a region should be accessed through a specific Linux mapping device:

memory:
  - name: demod
    offset: 0x6000_0000
    range: 32K
    dev: /dev/mem_wc

For interrupt-driven userspace drivers, use /dev/uio together with a matching device-tree override.

Device-tree override

The SDK default override source is fpga/override.dtsi. To use an instrument-specific override, set OVERRIDE_DTSI in config.mk, for example:

OVERRIDE_DTSI := $(PROJECT_PATH)/dts/override.dtsi

The selected file is copied to tmp/<project>/os/pl-overlay/override.dtsi and included in the generated pl.dtbo. Typical uses include UIO bindings, clock settings and driver-specific properties.

Porting note

V1 uses CFG=.../config.mk and memory.yml; 0.x uses CONFIG=.../config.yml. See the migration guide.