CMake API Reference

Below you find a list of CMake Modules included in this project.

Chimera Build System

add_device_binary(TARGET_NAME)

Compile a device binary for one execution domain (e.g. a Snitch cluster) and expose its public symbols for the host to link against.

This function drives the first two stages of the three-stage heterogeneous compilation pipeline:

• Stage 1 — Compile the device ELF with the device ISA/ABI.

• Stage 2 — Extract public symbols with llvm-nm and write an assembly stub (_symbols.s) and C header (_symbols.h) that the host links against. A placement header (_placement.ldh) recording the 4 KiB-aligned end address of the device binary is also written.

The resulting ${TARGET_NAME}_symbols INTERFACE library is consumed by add_host_binary().

Param TARGET_NAME:

CMake target name for this device binary.

Param DEVICE_NAME:

Short prefix applied to every exported symbol, e.g. device produces device_main. Must be unique across all devices in a build to avoid host link-time collisions.

Param TARGET_DIR:

Directory containing common.ldh and other target-wide shared files (e.g. targets/<target>/).

Param DEVICE_DIR:

Directory containing the device linker script template link.ld.in and device-specific startup code (e.g. targets/<target>/devices/snitch_cluster/).

Param ISA:

RISC-V march string for the device (e.g. rv32imafd).

Param ABI:

RISC-V mabi string for the device (e.g. ilp32d).

Param COMPILER:

LLVM target triple for the device (e.g. riscv32-unknown-elf).

Param COMPIERT_RT:

compiler-rt baremetal subdirectory for this ABI (e.g. rv32imafd).

Param SOURCES:

C and assembly source files compiled into the device ELF.

Param PREV_DEVICE:

(optional) CMake target name of the preceding device in memisl order. When set, the generated linker script INCLUDEs that device’s placement header so this binary starts immediately after it.

Param PICOLIBC:

(optional) Picolibc library variant to link (e.g. rv32imafd).

Linker script template placeholders substituted by this function:

• @CHIMERA_PREV_INCLUDE@ — empty, or INCLUDE <prev>_placement.ldh

• @CHIMERA_RESERVED_SECTION@ — empty, or a NOLOAD .reserved section advancing the location counter past the previous device’s memory region

Build outputs (all in CMAKE_CURRENT_BINARY_DIR):

• ${TARGET_NAME}.elf — device ELF

• ${TARGET_NAME}.dump — disassembly

• ${TARGET_NAME}.sections — section headers (input for overlap checker)

• ${TARGET_NAME}.symbols — full symbol table

• ${TARGET_NAME}_symbols.s — absolute-address assembly for the host linker

• ${TARGET_NAME}_symbols.h — extern declarations for host C code

• ${TARGET_NAME}_symbols — INTERFACE library consumed by add_host_binary()

• ${TARGET_NAME}_placement.ldh — placement header read by the next binary

Example Usage

add_device_binary(${TEST_NAME}_device
    DEVICE_NAME  device
    ISA          ${ISA_CLUSTER_SNITCH}
    ABI          ${ABI_CLUSTER_SNITCH}
    COMPILER     ${CROSS_COMPILE_DEVICE_SNITCH_CLUSTER}
    COMPIERT_RT  ${COMPILERRT_CLUSTER_SNITCH}
    PICOLIBC     ${PICOLIB_CLUSTER_SNITCH}
    TARGET_DIR   ${CHIMERA_TARGET_DIR}
    DEVICE_DIR   ${CHIMERA_TARGET_DIR}/devices/snitch_cluster
    SOURCES      ${TEST_SNITCH_SRCS}
)

add_host_binary(TARGET_NAME)

Compile the host binary and link the device symbol stubs produced by add_device_binary().

This function drives Stage 3 of the three-stage heterogeneous compilation pipeline: the host ELF is compiled with the host ISA/ABI and linked with the absolute-address symbol stubs from every attached device. A post-build step runs the section-overlap checker and, when CHIMERA_UNIFIED_ELF is enabled, merges all ELFs into a single mixed-ISA file for simulation.

Param TARGET_NAME:

CMake target name for this host binary.

Param TARGET_DIR:

Directory containing common.ldh and other target-wide shared files (e.g. targets/<target>/).

Param DEVICE_DIR:

Directory containing the host linker script template link.ld.in and host-specific startup code (e.g. targets/<target>/host/).

Param ISA:

RISC-V march string for the host (e.g. rv64imc).

Param ABI:

RISC-V mabi string for the host (e.g. lp64).

Param COMPILER:

LLVM target triple for the host (e.g. riscv64-unknown-elf).

Param COMPIERT_RT:

compiler-rt baremetal subdirectory for this ABI (e.g. rv64imc).

Param SOURCES:

C and assembly source files compiled into the host ELF.

Param DEVICE_DEPS:

(optional) Device ELF targets that must finish building before symbol extraction begins. Used for build ordering only; no object code is pulled from these targets.

Param DEVICE_SYMBOLS:

(optional) ${dev}_symbols INTERFACE libraries produced by add_device_binary(). Their compiled object files (the .set stubs) are linked into the host ELF so that device symbols resolve to their correct absolute addresses.

Param LAST_DEVICE:

(optional) Name of the device at the tail of the placement chain. Its _placement.ldh is included by the host linker script so host .text is placed immediately after all device code. Omit or leave empty for host-only builds.

Param PICOLIBC:

(optional) Picolibc library variant to link (e.g. rv64imc).

Linker script template placeholders substituted by this function:

• @CHIMERA_PLACEMENT_INCLUDE@ — empty when LAST_DEVICE is unset, or INCLUDE <last_device>_placement.ldh otherwise

• @CHIMERA_RESERVED_SECTION@ — empty when LAST_DEVICE is unset, or a NOLOAD .reserved section advancing the LC past all device memory

Post-build targets created:

• chimera_check_overlaps — memory map printer and VMA conflict checker (scripts/check_section_overlaps.py)

• chimera_merge_elf — (optional, requires CHIMERA_UNIFIED_ELF=ON ) merges device + host ELFs into one mixed-ISA file via lief

• chimera_footer — prints the build summary

Example Usage

add_host_binary(${TEST_NAME}
    ISA          ${ISA_HOST}
    ABI          ${ABI_HOST}
    COMPILER     ${CROSS_COMPILE_HOST}
    COMPIERT_RT  ${COMPILERRT_HOST}
    PICOLIBC     ${PICOLIB_HOST}
    TARGET_DIR   ${CHIMERA_TARGET_DIR}
    DEVICE_DIR   ${CHIMERA_TARGET_DIR}/host
    SOURCES      ${TEST_HOST_SRCS}
    DEVICE_DEPS    ${TEST_NAME}_device
    DEVICE_SYMBOLS ${TEST_NAME}_device_symbols
    LAST_DEVICE    ${TEST_NAME}_device
)

Utility Modules

chimera_select_shape(OPTION <var> DEFAULT <shape> HEADER_PREFIXES <prefix>...)

Pick one data shape for a test at configure time. Shapes are discovered from the headers matching the first HEADER_PREFIXES entry, so adding <prefix><shape>.h is enough to make a new shape selectable.

Sets SELECTED_SHAPE and SELECTED_SHAPE_SOURCE in the caller’s scope.

Param OPTION:

Cache variable exposed to the user. Required.

Param DEFAULT:

Shape used when OPTION is unset. Required.

Param HEADER_PREFIXES:

Prefixes of the per-shape headers. The first discovers the shapes; all must exist for the selected one. Required.

Param HEADER_DIR:

Where the headers live. Defaults to include.

Param SOURCE_PREFIX:

If given, also select <SOURCE_DIR>/<prefix><shape>.c.

Param SOURCE_DIR:

Where the sources live. Defaults to src_cluster.

Example Usage

chimera_select_shape(
  OPTION          ITA_MATMUL_L1_SHAPE
  DEFAULT         64x128x64
  HEADER_PREFIXES ITA_dims_
  SOURCE_PREFIX   ITA_mem_
)

chimera_test_vector_generator(GENERATOR <script> OUTPUTS <file>...)

Register a test’s generate_vectors.py. Fails configure with an actionable message when the vectors have not been generated yet, and adds them to the regenerate-test-vectors target.

Param GENERATOR:

Path to the generator script. Required.

Param OUTPUTS:

Files the generator writes. Required. Used for the missing-vector check and as the target’s byproducts.

Param ARGS:

Optional generator arguments. Omit when the generator already defaults to the right paths, which is the usual case.

add_chimera_subdirectories(target_platform, category, mappings)

Add subdirectories based on a mapping of target platforms to folders. The mappings are expected to be in the format target_platform:folder1,folder2,.... :param target_platform: The target platform to build for. :param category: The category of the subdirectories. :param mappings: A list of mappings from target platforms to folders. Make sure to wrap the list in quotes!

Example Usage

set(MAPPINGS
    chimera-convolve:snitch_cluster
    chimera-open:snitch_cluster
    chimera-host:
)
add_chimera_subdirectories(${TARGET_PLATFORM} "Device" "${MAPPINGS}")