This page gives an overview of the different configuration files, what purpose they serve and how they are structured.

The goal of this guide is to ensure well-structured and consistent configuration files.

All configuration files are stored in the tcl directory of the project directory. These files must follow the Tcl Style Guide and Naming Convention. There are different types of configuration files:

Note: This guideline must be followed for new configuration files. There may be configuration files that do not comply with this guide for legacy reasons.

Interface

This configuration file represents a debug (interface) adapter. This is usually a USB device that provides an interface to one or more transports such as JTAG or SWD. Other interfaces like ethernet or parallel port are also represented.

A debug adapter configuration file must use the following scheme:

tcl/interface/[vendor]/<adapter name>.cfg

The vendor directory for debug adapters is often omitted because multiple adapters from the same vendor can be represented by a common configuration file. One counter example are FTDI-based debug adapters. There are various devices, either standalone or development boards which use FTDI chips but use different chip models or settings. Their corresponding configuration files are stored in the ftdi folder.

The name of the vendor folder can also be a more generic term such as parport as it is used for parallel port based debug adapters.

If it is foreseeable that new configuration files will be added in the future, create a vendor directory even if there is only a single file at the moment. This prevents that files have to be moved in the future.

Target

This configuration file represents an actual chip. For example, a microcontroller, FPGA, CPLD, or system on chip (SoC). A target configuration file always represents an entire device series or family.

A target configuration file must use the following scheme:

tcl/target/<vendor>/<target name>.cfg

Use the device series or family as target name. For example, the configuration file for the nRF54L series from Nordic Semiconductor is located here:

tcl/target/nordic/nrf54l.cfg

If there are many similarities between different targets, use a common file to share large pieces of code. Do not use a single file to represent multiple device series or families.

Board

This configuration file represents a circuit board, for example, a development board. A board may also contain an on-board debug adapter.

A board configuration file includes existing target and, if available, interface configuration files, since a target is used on many boards.

Reuse existing target and interface configuration files whenever possible. If a board needs an external debug adapter, do not write adapter specific configuration files.

A board configuration file must use the following scheme:

tcl/board/<vendor>/<board name>[-suffix].cfg

For example, the board configuration file for the NUCLEO-U083RC from STMicroelectronics is located here:

tcl/board/st/nucleo-u083rc.cfg

In case a board supports different features, a suffix can be used to indicate this. Make sure that the suffix is short and meaningful.

For example, the on-board debug adapter of the FRDM-KV11Z development board can be flashed with a SEGGER J-Link compatible firmware. Hence, there is the following configuration file:

tcl/board/nxp/frdm-kv11z-jlink.cfg

The use of a suffix should be chosen carefully. In many cases it is sufficient to make a certain feature accessible via a variable.

Use a single configuration file for each board. If there are many similarities between different boards, use a common file to share large pieces of code.

Naming Convention

The following naming conventions for configuration files and directories must be used:

Use only lower-case letters and digits for directory and filenames
Use hyphen characters between consecutive words in identifiers (e.g. more-than-one-word)
Use a common abbreviation for the vendor name, such as
- ti for Texas Instruments
- st for STMicroelectronics
- silabs for Silicon Labs

An extensive list of abbreviations for vendor names can be found here.