Instrument configuration

Role of the configuration files

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

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

The instrument configuration is split into two 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.

Keep build composition in config.mk and hardware/software interface definitions in memory.yml.

Typical instrument directory

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

The files are used in this order:

1. config.mk selects the board and all input files.
2. memory.yml generates Tcl, C++ and device-tree identifiers.
3. block_design.tcl uses the generated Tcl definitions to create the FPGA design.
4. C++ drivers use the generated memory.hpp identifiers.
5. The runtime loads the generated bitstream and device-tree overlay.

config.mk

Example structure from the ALPHA250 FFT instrument:

NAME := fft
VERSION := 0.2.1

BOARD_PATH := $(SDK_PATH)/boards/alpha250

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/cores/psd_counter_v1_0

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

WEB_FILES += $(SDK_PATH)/web/jquery.flot.d.ts
WEB_FILES += $(SDK_PATH)/web/dds-frequency/dds-frequency.html
WEB_FILES += $(SDK_PATH)/web/dds-frequency/dds-frequency.ts
WEB_FILES += $(SDK_PATH)/web/plot-basics/plot-basics.ts
WEB_FILES += $(SDK_PATH)/web/plot-basics/plot-basics.html
WEB_FILES += $(shell find "$(PROJECT_PATH)/web" -type f \( -name '*.ts' -o -name '*.html' -o -name '*.css' \))

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 points to the SDK root. PROJECT_PATH points to the directory containing the selected config.mk. Do not put memory regions or registers in config.mk; keep them in memory.yml so the Tcl, C++ and device-tree outputs stay synchronized.

memory.yml

memory.yml is the contract between FPGA, C++ drivers and Linux runtime.

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: status
    offset: 0x5000_0000
    range: 4K
    registers:
    - adc[n_adc]
    - cycle_index
    - digital_inputs

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

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

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.

This keeps the FPGA design, C++ driver and Linux overlay synchronized from a single memory definition.

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

Do not mix configuration formats. This branch uses CFG=.../config.mk and memory.yml; 0.x instruments use CONFIG=.../config.yml.

See also

• Documentation
• Commands
• FPGA design