From d567824f2ac267f61944aa839911f0b5bee98c4a Mon Sep 17 00:00:00 2001 From: Marc Schink Date: Sat, 17 Aug 2024 12:35:30 +0200 Subject: [PATCH] doc/manual: Add guideline for configuration files 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 Reviewed-on: https://review.openocd.org/c/openocd/+/8854 Tested-by: jenkins Reviewed-by: Antonio Borneo --- doc/manual/config_files.txt | 117 ++++++++++++++++++++++++++++++++++++ doc/manual/main.txt | 2 + 2 files changed, 119 insertions(+) create mode 100644 doc/manual/config_files.txt diff --git a/doc/manual/config_files.txt b/doc/manual/config_files.txt new file mode 100644 index 000000000..db1cc1419 --- /dev/null +++ b/doc/manual/config_files.txt @@ -0,0 +1,117 @@ +/** @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]/.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//.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//[-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). + + */ diff --git a/doc/manual/main.txt b/doc/manual/main.txt index c28fbe228..9da546b6d 100644 --- a/doc/manual/main.txt +++ b/doc/manual/main.txt @@ -21,6 +21,8 @@ check the mailing list archives to find the status of your feature (or bug). - The @subpage releases page describes the project's release process. - The @subpage endianness provides hints about writing and testing endianness independent code for OpenOCD. +- The @subpage config_files page provides a guide for writing configuration files + for OpenOCD. @ref primer provide introductory materials for new developers on various specific topics. -- 2.50.1