mirror of
https://git.code.sf.net/p/openocd/code
synced 2025-05-16 03:12:13 +00:00
d567824f2a
The goal of this guideline is to have consistent and well-structured configurations files. The focus of this patch is on filenames and directory structure. A guideline for the content of the files should be included in a subsequent patch. This patch addresses a long outstanding task listed in 'Pending and Open Tasks'. Change-Id: Ib32dd8b9ed15c3f647cd8d74cfc79edf0e79a3df Signed-off-by: Marc Schink <dev@zapb.de> Reviewed-on: https://review.openocd.org/c/openocd/+/8854 Tested-by: jenkins Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>
118 lines
4.6 KiB
Plaintext
118 lines
4.6 KiB
Plaintext
/** @page config_files Configuration Files
|
|
|
|
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 @c tcl directory of the project directory.
|
|
These files must follow the @ref styletcl and @ref naming_convention.
|
|
There are different types of configuration files:
|
|
|
|
- @ref interface_configs
|
|
- @ref target_configs
|
|
- @ref board_configs
|
|
|
|
@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.
|
|
|
|
|
|
@section interface_configs 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:
|
|
|
|
@verbatim
|
|
tcl/interface/[vendor]/<adapter name>.cfg
|
|
@endverbatim
|
|
|
|
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.
|
|
|
|
@section target_configs 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:
|
|
|
|
@verbatim
|
|
tcl/target/<vendor>/<target name>.cfg
|
|
@endverbatim
|
|
|
|
Use the device series or family as `target name`.
|
|
For example, the configuration file for the nRF54L series from Nordic Semiconductor is located here:
|
|
|
|
@verbatim
|
|
tcl/target/nordic/nrf54l.cfg
|
|
@endverbatim
|
|
|
|
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.
|
|
|
|
@section board_configs 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 @b not write adapter specific configuration files.
|
|
|
|
|
|
A board configuration file must use the following scheme:
|
|
|
|
@verbatim
|
|
tcl/board/<vendor>/<board name>[-suffix].cfg
|
|
@endverbatim
|
|
|
|
For example, the board configuration file for the NUCLEO-U083RC from STMicroelectronics is located here:
|
|
|
|
@verbatim
|
|
tcl/board/st/nucleo-u083rc.cfg
|
|
@endverbatim
|
|
|
|
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:
|
|
|
|
@verbatim
|
|
tcl/board/nxp/frdm-kv11z-jlink.cfg
|
|
@endverbatim
|
|
|
|
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.
|
|
|
|
|
|
@section naming_convention 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
|
|
- @c ti for Texas Instruments
|
|
- @c st for STMicroelectronics
|
|
- @c silabs for Silicon Labs
|
|
|
|
An extensive list of abbreviations for vendor names can be found [here](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/vendor-prefixes.yaml).
|
|
|
|
*/
|