diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/config_files.txt | 117 | ||||
| -rw-r--r-- | doc/manual/helper.txt | 2 | ||||
| -rw-r--r-- | doc/manual/jtag.txt | 4 | ||||
| -rw-r--r-- | doc/manual/main.txt | 2 | ||||
| -rw-r--r-- | doc/manual/primer/docs.txt | 2 | ||||
| -rw-r--r-- | doc/manual/primer/tcl.txt | 28 | ||||
| -rw-r--r-- | doc/manual/scripting.txt | 14 | ||||
| -rw-r--r-- | doc/manual/server.txt | 34 | ||||
| -rw-r--r-- | doc/manual/style.txt | 6 |
9 files changed, 164 insertions, 45 deletions
diff --git a/doc/manual/config_files.txt b/doc/manual/config_files.txt new file mode 100644 index 0000000..db1cc14 --- /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]/<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). + + */ diff --git a/doc/manual/helper.txt b/doc/manual/helper.txt index b59fd66..6cf3c97 100644 --- a/doc/manual/helper.txt +++ b/doc/manual/helper.txt @@ -21,7 +21,7 @@ portability API. /** @page helperjim OpenOCD Jim API -The Jim API provides access to a small-footprint TCL implementation. +The Jim API provides access to a small-footprint Tcl implementation. Visit http://jim.tcl.tk/ for more information on Jim. diff --git a/doc/manual/jtag.txt b/doc/manual/jtag.txt index 2653fc7..5eb9450 100644 --- a/doc/manual/jtag.txt +++ b/doc/manual/jtag.txt @@ -15,7 +15,7 @@ asynchronous transactions. - used by other modules - @subpage jtagtcl - - @b private TCL handling routines + - @b private Tcl handling routines - defined in @c src/jtag/tcl.c - registers and handles Jim commands that configure and use the JTAG core @@ -47,7 +47,7 @@ This section needs to be expanded. */ -/** @page jtagtcl JTAG TCL API +/** @page jtagtcl JTAG Tcl API This section needs to be expanded. diff --git a/doc/manual/main.txt b/doc/manual/main.txt index c28fbe2..9da546b 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. diff --git a/doc/manual/primer/docs.txt b/doc/manual/primer/docs.txt index b1c0531..1aefa17 100644 --- a/doc/manual/primer/docs.txt +++ b/doc/manual/primer/docs.txt @@ -6,7 +6,7 @@ OpenOCD presently produces several kinds of documentation: - The User's Guide: - Focuses on using the OpenOCD software. - Details the installation, usage, and customization. - - Provides descriptions of public Jim/TCL script commands. + - Provides descriptions of public Jim Tcl script commands. - Written using GNU texinfo. - Created with 'make pdf' or 'make html'. - See @subpage primertexinfo and @ref styletexinfo. diff --git a/doc/manual/primer/tcl.txt b/doc/manual/primer/tcl.txt index eba2f55..6874f55 100644 --- a/doc/manual/primer/tcl.txt +++ b/doc/manual/primer/tcl.txt @@ -1,6 +1,6 @@ -/** @page primertcl OpenOCD TCL Primer +/** @page primertcl OpenOCD Tcl Primer -The @subpage scripting page provides additional TCL Primer material. +The @subpage scripting page provides additional Tcl Primer material. @verbatim @@ -8,15 +8,15 @@ The @subpage scripting page provides additional TCL Primer material. **************************************** This is a short introduction to 'un-scare' you about the language -known as TCL. It is structured as a guided tour through the files +known as Tcl. It is structured as a guided tour through the files written by me [Duane Ellis] - in early July 2008 for OpenOCD. Which uses the "JIM" embedded Tcl clone-ish language. -Thing described here are *totally* TCL generic... not Jim specific. +Thing described here are *totally* Tcl generic... not Jim specific. The goal of this document is to encourage you to add your own set of -chips to the TCL package - and most importantly you should know where +chips to the Tcl package - and most importantly you should know where you should put them - so they end up in an organized way. --Duane Ellis. @@ -57,14 +57,14 @@ Definition: Open: at91sam7x256.tcl === TCL TOUR === -A walk through --- For those who are new to TCL. +A walk through --- For those who are new to Tcl. Examine the file: at91sam7x256.tcl It starts with: source [find path/filename.tcl] -In TCL - this is very important. +In Tcl - this is very important. Rule #1 Everything is a string. Rule #2 If you think other wise See #1. @@ -130,7 +130,7 @@ First, there is a "for" loop - at level 0 This means it is evaluated when the file is parsed. == SIDEBAR: About The FOR command == -In TCL, "FOR" is a funny thing, it is not what you think it is. +In Tcl, "FOR" is a funny thing, it is not what you think it is. Syntactically - FOR is a just a command, it is not language construct like for(;;) in C... @@ -191,7 +191,7 @@ proc create_mask { MSB LSB } { Like "for" - PROC is really just a command that takes 3 parameters. The (1) NAME of the function, a (2) LIST of parameters, and a (3) BODY -Again, this is at "level 0" so it is a global function. (Yes, TCL +Again, this is at "level 0" so it is a global function. (Yes, Tcl supports local functions, you put them inside of a function} You'll see in some cases, I nest [brackets] a lot and in others I'm @@ -257,7 +257,7 @@ For example - 'show_mmr32_reg' is given the NAME of the register to display. The assumption is - the NAME is a global variable holding the address of that MMR. -The code does some tricks. The [set [set NAME]] is the TCL way +The code does some tricks. The [set [set NAME]] is the Tcl way of doing double variable interpolation - like makefiles... In a makefile or shell script you may have seen this: @@ -272,7 +272,7 @@ In a makefile or shell script you may have seen this: #BUILD = mac FOO = ${FOO_${BUILD}} -The "double [set] square bracket" thing is the TCL way, nothing more. +The "double [set] square bracket" thing is the Tcl way, nothing more. ---- @@ -352,7 +352,7 @@ tricks with interpretors. Function: show_mmr32_bits() -In this case, we use the special TCL command "upvar" which tcl's way +In this case, we use the special Tcl command "upvar" which is the Tcl way of passing things by reference. In this case, we want to reach up into the callers lexical scope and find the array named "NAMES" @@ -373,7 +373,7 @@ are basically identical... Second - there can be many of them. -In this case - I do some more TCL tricks to dynamically +In this case - I do some more Tcl tricks to dynamically create functions out of thin air. Some assumptions: @@ -409,7 +409,7 @@ And - declare that variable as GLOBAL so the world can find it. Then - we dynamically create a function - based on the register name. Look carefully at how that is done. You'll notice the FUNCTION BODY is -a string - not something in {braces}. Why? This is because we need TCL +a string - not something in {braces}. Why? This is because we need Tcl to evaluate the contents of that string "*NOW*" - when $vn exists not later, when the function "show_FOO" is invoked. diff --git a/doc/manual/scripting.txt b/doc/manual/scripting.txt index f8764e2..48ba99b 100644 --- a/doc/manual/scripting.txt +++ b/doc/manual/scripting.txt @@ -4,11 +4,11 @@ The scripting support is intended for developers of OpenOCD. It is not the intention that normal OpenOCD users will -use tcl scripting extensively, write lots of clever scripts, +use Tcl scripting extensively, write lots of clever scripts, or contribute back to OpenOCD. Target scripts can contain new procedures that end users may -tinker to their needs without really understanding tcl. +tinker to their needs without really understanding Tcl. Since end users are not expected to mess with the scripting language, the choice of language is not terribly important @@ -38,16 +38,16 @@ Default implementation of procedures in tcl/procedures.tcl. and will have no externally visible consequences. Tcl has an advantage in that it's syntax is backwards compatible with the current OpenOCD syntax. -- external scripting. Low level tcl functions will be defined - that return machine readable output. These low level tcl - functions constitute the tcl api. flash_banks is such - a low level tcl proc. "flash banks" is an example of +- external scripting. Low level Tcl functions will be defined + that return machine readable output. These low level Tcl + functions constitute the Tcl api. flash_banks is such + a low level Tcl proc. "flash banks" is an example of a command that has human readable output. The human readable output is expected to change in between versions of OpenOCD. The output from flash_banks may not be in the preferred form for the client. The client then has two choices a) parse the output from flash_banks - or b) write a small piece of tcl to output the + or b) write a small piece of Tcl to output the flash_banks output to a more suitable form. The latter may be simpler. diff --git a/doc/manual/server.txt b/doc/manual/server.txt index 8041c3d..20e48c1 100644 --- a/doc/manual/server.txt +++ b/doc/manual/server.txt @@ -43,7 +43,7 @@ with a script language: What follows hopefully shows how the plans to solve these problems materialized and help to explain the grand roadmap plan. -@subsection serverdocsjim Why JimTCL? The Internal Script Language +@subsection serverdocsjim Why Jim Tcl? The Internal Script Language At the time, the existing "command context schema" was proving itself insufficient. However, the problem was also considered from another @@ -57,14 +57,14 @@ OpenOCD. Yuck. OpenOCD already has a complex enough build system, why make it worse? The goal was to add a simple language that would be moderately easy to -work with and be self-contained. JimTCL is a single C and single H +work with and be self-contained. Jim Tcl is a single C and single H file, allowing OpenOCD to avoid the spider web of dependent packages. -@section serverdocstcl TCL Server Port +@section serverdocstcl Tcl Server Port -The TCL Server port was added in mid-2008. With embedded TCL, we can +The Tcl Server port was added in mid-2008. With embedded Tcl, we can write scripts internally to help things, or we can write "C" code that -interfaces well with TCL. +interfaces well with Tcl. From there, the developers wanted to create an external front-end that would be @a very usable and that @a any language could utilize, @@ -78,7 +78,7 @@ also support a high degree of interoperability with multiple systems. They are not human-centric protocols; more correctly, they are rigid, terse, simple ASCII protocols that are easily parsable by a script. -Thus, the TCL server -- a 'machine' type socket interface -- was added +Thus, the Tcl server -- a 'machine' type socket interface -- was added with the hope was it would output simple "name-value" pair type data. At the time, simple name/value pairs seemed reasonably easier to do at the time, though Maybe it should output JSON; @@ -107,7 +107,7 @@ What works easier and is less work is what is already present in every platform? The answer: A web browser. In other words, OpenOCD could serve out embedded web pages via "localhost" to your browser. -Long before OpenOCD had a TCL command line, Zylin AS built their ZY1000 +Long before OpenOCD had a Tcl command line, Zylin AS built their ZY1000 device with a built-in HTTP server. Later, they were willing to both contribute and integrate most of that work into the main tree. @@ -128,8 +128,8 @@ every language has it's own set of wack-ness, parameter marshaling is painful. What about "callbacks" and structures, and other mess. Imagine -debugging that system. When JimTCL was introduced Spencer Oliver had -quite a few well-put concerns (Summer 2008) about the idea of "TCL" +debugging that system. When Jim Tcl was introduced Spencer Oliver had +quite a few well-put concerns (Summer 2008) about the idea of "Tcl" taking over OpenOCD. His concern is and was: how do you debug something written in 2 different languages? A "SWIG" front-end is unlikely to help that situation. @@ -143,7 +143,7 @@ to Localhost or remote host, however one might want to make it work. A socket interface is very simple. One could write a Java application and serve it out via the embedded web server, could it - or something -like it talk to the built in TCL server? Yes, absolutely! We are on to +like it talk to the built in Tcl server? Yes, absolutely! We are on to something here. @subsection serverdocplatforms Platform Permutations @@ -167,9 +167,9 @@ the Socket Approach is used. @subsection serverdocfuture Development Scale Out -During 2008, Duane Ellis created some TCL scripts to display peripheral -register contents. For example, look at the sam7 TCL scripts, and the -stm32 TCL scripts. The hope was others would create more. +During 2008, Duane Ellis created some Tcl scripts to display peripheral +register contents. For example, look at the sam7 Tcl scripts, and the +stm32 Tcl scripts. The hope was others would create more. A good example of this is display/view the peripheral registers on @@ -208,7 +208,7 @@ upon it, sometimes that is the only scheme available. As a small group of developers, supporting all the platforms and targets in the debugger will be difficult, as there are enough problem with the plethora of Adapters, Chips, and different target boards. -Yes, the TCL interface might be suitable, but it has not received much +Yes, the Tcl interface might be suitable, but it has not received much love or attention. Perhaps it will after you read and understand this. One reason might be, this adds one more host side requirement to make @@ -247,8 +247,8 @@ Altogether, it provides a universally accessible GUI for OpenOCD. @section serverdocshtml Simple HTML Pages -There is (or could be) a simple "Jim TCL" function to read a memory -location. If that can be tied into a TCL script that can modify the +There is (or could be) a simple "Jim Tcl" function to read a memory +location. If that can be tied into a Tcl script that can modify the HTTP text, then we have a simple script-based web server with a JTAG engine under the hood. @@ -275,7 +275,7 @@ bit-banging JTAG Adapter serving web pages. @subsection serverdocshtmladv Advanced HTML Pages -Java or JavaScript could be used to talk back to the TCL port. One +Java or JavaScript could be used to talk back to the Tcl port. One could write a Java, AJAX, FLASH, or some other developer friendly toolbox and get a real cross-platform GUI interface. Sure, the interface is not native - but it is 100% cross-platform! diff --git a/doc/manual/style.txt b/doc/manual/style.txt index dc27e87..f7a1298 100644 --- a/doc/manual/style.txt +++ b/doc/manual/style.txt @@ -27,12 +27,12 @@ providing documentation, either as part of the C code or stand-alone. Feedback would be welcome to improve the OpenOCD guidelines. */ -/** @page styletcl TCL Style Guide +/** @page styletcl Tcl Style Guide -OpenOCD needs to expand its Jim/TCL Style Guide. +OpenOCD needs to expand its Jim Tcl Style Guide. Many of the guidelines listed on the @ref stylec page should apply to -OpenOCD's Jim/TCL code as well. +OpenOCD's Jim Tcl code as well. */ /** @page stylec C Style Guide |