Macros

Several CMake macros and functions are provide to make building for XCORE easier. These macros are located in the file tools/cmake_utils/xmos_macros.cmake and are documented below.

To see what XTC Tools commands the macros and functions are running, add VERBOSE=1 to your build command line. For example:

make run_my_target VERBOSE=1

Common Macros

merge_binaries

merge_binaries combines multiple xcore applications into one by extracting a tile elf and recombining it into another binary. This is used in multitile RTOS applications to enable building unique instances of the FreeRTOS kernel and task sets on a per tile basis. This macro takes an output target name, a base target, a target containing a tile to merge, and the tile number to merge.

This macro can be called in two ways. The 4 argument version is for when the application has only 1 node and therefore only the core needs to be specified.

# create target OUT by replacing tile number 0 in BASE with tile 0 in OTHER
merge_binaries(${OUT} ${BASE} ${OTHER} 0)

The 5 argument version is for multi-node applications. IMPORTANT: node number is not the “Node Id” from the xn file, rather the index of the node in the JTAGChain which is defined in the xn file.

# create target OUT by replacing tile 1 on node 0 in BASE with tile 1 on
# node 0 in OTHER
merge_binaries(${OUT} ${BASE} ${OTHER} 0 1)

create_run_target

create_run_target creates a run target for <TARGET_NAME> with xscope output.

create_run_target(<TARGET_NAME>)

create_run_target allows you to run a binary with the following command instead of invoking xrun --xscope.

make run_my_target

create_debug_target

create_debug_target creates a debug target for <TARGET_NAME>.

create_debug_target(<TARGET_NAME>)

create_debug_target allows you to debug a binary with the following command instead of invoking xgdb. This target implicitly sets up the xscope debug interface as well.

make debug_my_target

create_filesystem_target

create_filesystem_target creates a filesystem file for <TARGET_NAME> using the files in the <FILESYSTEM_INPUT_DIR> directory. <IMAGE_SIZE> specifies the size (in bytes) of the filesystem. The filesystem output filename will end in _fat.fs. Optional argument <OPTIONAL_DEPENDS_TARGETS> can be used to specify other dependency targets, such as filesystem generators.

create_filesystem_target(<TARGET_NAME> <FILESYSTEM_INPUT_DIR> <IMAGE_SIZE> <OPTIONAL_DEPENDS_TARGETS>)

create_data_partition_directory

create_data_partition_directory creates a directory populated with all components related to the data partition. The data partition output folder will end in _data_partition Optional argument <OPTIONAL_DEPENDS_TARGETS> can be used to specify other dependency targets.

create_data_partition_directory(<TARGET_NAME> <FILES_TO_COPY> <OPTIONAL_DEPENDS_TARGETS>)

create_flash_app_target

create_flash_app_target creates a debug target for <TARGET_NAME> with optional arguments <BOOT_PARTITION_SIZE>, <DATA_PARTITION_CONTENTS>, and <OPTIONAL_DEPENDS_TARGETS>. <BOOT_PARTITION_SIZE> specificies the size in bytes of the boot partition. <DATA_PARTITION_CONTENTS> specifies the optional binary contents of the data partition. <OPTIONAL_DEPENDS_TARGETS> specifies CMake targets that should be dependencies of the resulting create_flash_app_target target. This may be used to create recipes that generate the data partition contents.

create_flash_app_target(<TARGET_NAME> <BOOT_PARTITION_SIZE> <DATA_PARTITION_CONTENTS> <OPTIONAL_DEPENDS_TARGETS>)

create_flash_app_target allows you to flash a factory image binary and optional data partition with the following command instead of invoking xflash.

make flash_app_my_target

Less Common Macros

create_install_target

create_install_target creates an install target for <TARGET_NAME>.

create_install_target(<TARGET_NAME>)

create_install_target will copy <TARGET_NAME>.xe to the ${PROJECT_SOURCE_DIR}/dist directory.

make install_my_target

create_run_xscope_to_file_target

create_run_xscope_to_file_target creates a run target for <TARGET_NAME>. <XSCOPE_FILE> specifies the file to save to (no extension).

create_run_xscope_to_file_target(<TARGET_NAME> <XSCOPE_FILE>)

create_run_xscope_to_file_target allows you to run a binary with the following command instead of invoking xrun --xscope-file.

make run_xscope_to_file_my_target

create_upgrade_img_target

create_upgrade_img_target creates an xflash image upgrade target for a provided binary for use in DFU

create_data_partition_directory(<TARGET_NAME> <FACTORY_MAJOR_VER> <FACTORY_MINOR_VER>)

create_erase_all_target

create_erase_all_target creates an xflash erase all target for <TARGET_FILEPATH> target XN file. The full filepath must be specified for XN file

create_filesystem_target(<TARGET_NAME> <TARGET_FILEPATH>)

create_erase_all_target allows you to erase flash with the following command instead of invoking xflash.

make erase_all_my_target

query_tools_version

query_tools_version populates the following CMake variables:

XTC_VERSION_MAJOR XTC_VERSION_MINOR XTC_VERSION_PATCH

query_tools_version()