You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page gives an overview of the different configuration files, what purpose they serve and how they are structured.
4
+
The goal of this guide is to ensure well-structured and consistent configuration files.
5
+
6
+
All configuration files are stored in the @c tcl directory of the project directory.
7
+
These files must follow the @ref styletcl and @ref naming_convention.
8
+
There are different types of configuration files:
9
+
10
+
- @ref interface_configs
11
+
- @ref target_configs
12
+
- @ref board_configs
13
+
14
+
@note This guideline must be followed for new configuration files.
15
+
There may be configuration files that do not comply with this guide for legacy reasons.
16
+
17
+
18
+
@section interface_configs Interface
19
+
20
+
This configuration file represents a debug (interface) adapter.
21
+
This is usually a USB device that provides an interface to one or more transports such as JTAG or SWD.
22
+
Other interfaces like ethernet or parallel port are also represented.
23
+
24
+
A debug adapter configuration file must use the following scheme:
25
+
26
+
@verbatim
27
+
tcl/interface/[vendor]/<adapter name>.cfg
28
+
@endverbatim
29
+
30
+
The `vendor` directory for debug adapters is often omitted because multiple adapters from the same vendor can be represented by a common configuration file.
31
+
One counter example are FTDI-based debug adapters.
32
+
There are various devices, either standalone or development boards which use FTDI chips but use different chip models or settings.
33
+
Their corresponding configuration files are stored in the `ftdi` folder.
34
+
35
+
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.
36
+
37
+
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.
38
+
This prevents that files have to be moved in the future.
39
+
40
+
@section target_configs Target
41
+
42
+
This configuration file represents an actual chip.
43
+
For example, a microcontroller, FPGA, CPLD, or system on chip (SoC).
44
+
A target configuration file always represents an entire device series or family.
45
+
46
+
A target configuration file must use the following scheme:
47
+
48
+
@verbatim
49
+
tcl/target/<vendor>/<target name>.cfg
50
+
@endverbatim
51
+
52
+
Use the device series or family as `target name`.
53
+
For example, the configuration file for the nRF54L series from Nordic Semiconductor is located here:
54
+
55
+
@verbatim
56
+
tcl/target/nordic/nrf54l.cfg
57
+
@endverbatim
58
+
59
+
If there are many similarities between different targets, use a common file to share large pieces of code.
60
+
Do not use a single file to represent multiple device series or families.
61
+
62
+
@section board_configs Board
63
+
64
+
This configuration file represents a circuit board, for example, a development board.
65
+
A board may also contain an on-board debug adapter.
66
+
67
+
A board configuration file includes existing target and, if available, interface configuration files, since a target is used on many boards.
68
+
69
+
Reuse existing target and interface configuration files whenever possible.
70
+
If a board needs an external debug adapter, do @b not write adapter specific configuration files.
71
+
72
+
73
+
A board configuration file must use the following scheme:
74
+
75
+
@verbatim
76
+
tcl/board/<vendor>/<board name>[-suffix].cfg
77
+
@endverbatim
78
+
79
+
For example, the board configuration file for the NUCLEO-U083RC from STMicroelectronics is located here:
80
+
81
+
@verbatim
82
+
tcl/board/st/nucleo-u083rc.cfg
83
+
@endverbatim
84
+
85
+
In case a board supports different features, a `suffix` can be used to indicate this.
86
+
Make sure that the suffix is short and meaningful.
87
+
88
+
For example, the on-board debug adapter of the FRDM-KV11Z development board can be flashed with a SEGGER J-Link compatible firmware.
89
+
Hence, there is the following configuration file:
90
+
91
+
@verbatim
92
+
tcl/board/nxp/frdm-kv11z-jlink.cfg
93
+
@endverbatim
94
+
95
+
The use of a suffix should be chosen carefully.
96
+
In many cases it is sufficient to make a certain feature accessible via a variable.
97
+
98
+
Use a single configuration file for each board.
99
+
If there are many similarities between different boards, use a common file to share large pieces of code.
100
+
101
+
102
+
@section naming_convention Naming Convention
103
+
104
+
105
+
The following naming conventions for configuration files and directories must be used:
106
+
107
+
- Use only lower-case letters and digits for directory and filenames
108
+
- Use hyphen characters between consecutive words in identifiers (e.g. `more-than-one-word`)
109
+
110
+
- Use a common abbreviation for the vendor name, such as
111
+
- @c ti for Texas Instruments
112
+
- @c st for STMicroelectronics
113
+
- @c silabs for Silicon Labs
114
+
115
+
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).
0 commit comments