aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/manual/config_files.txt117
-rw-r--r--doc/manual/helper.txt2
-rw-r--r--doc/manual/jtag.txt4
-rw-r--r--doc/manual/main.txt2
-rw-r--r--doc/manual/primer/docs.txt2
-rw-r--r--doc/manual/primer/tcl.txt28
-rw-r--r--doc/manual/scripting.txt14
-rw-r--r--doc/manual/server.txt34
-rw-r--r--doc/manual/style.txt6
-rw-r--r--doc/openocd.texi160
10 files changed, 263 insertions, 106 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
diff --git a/doc/openocd.texi b/doc/openocd.texi
index 1dcb7f3..6d9c198 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -62,7 +62,7 @@ Documentation License''.
* About:: About OpenOCD
* Developers:: OpenOCD Developer Resources
* Debug Adapter Hardware:: Debug Adapter Hardware
-* About Jim-Tcl:: About Jim-Tcl
+* About Jim Tcl:: About Jim Tcl
* Running:: Running OpenOCD
* OpenOCD Project Setup:: OpenOCD Project Setup
* Config File Guidelines:: Config File Guidelines
@@ -629,43 +629,43 @@ This is deprecated from Linux v5.3; prefer using @b{linuxgpiod}.
@end itemize
-@node About Jim-Tcl
-@chapter About Jim-Tcl
-@cindex Jim-Tcl
+@node About Jim Tcl
+@chapter About Jim Tcl
+@cindex Jim Tcl
@cindex tcl
-OpenOCD uses a small ``Tcl Interpreter'' known as Jim-Tcl.
+OpenOCD uses a small ``Tcl Interpreter'' known as Jim Tcl.
This programming language provides a simple and extensible
command interpreter.
-All commands presented in this Guide are extensions to Jim-Tcl.
+All commands presented in this Guide are extensions to Jim Tcl.
You can use them as simple commands, without needing to learn
much of anything about Tcl.
Alternatively, you can write Tcl programs with them.
You can learn more about Jim at its website, @url{http://jim.tcl.tk}.
There is an active and responsive community, get on the mailing list
-if you have any questions. Jim-Tcl maintainers also lurk on the
+if you have any questions. Jim Tcl maintainers also lurk on the
OpenOCD mailing list.
@itemize @bullet
@item @b{Jim vs. Tcl}
-@* Jim-Tcl is a stripped down version of the well known Tcl language,
-which can be found here: @url{http://www.tcl.tk}. Jim-Tcl has far
-fewer features. Jim-Tcl is several dozens of .C files and .H files and
+@* Jim Tcl is a stripped down version of the well known Tcl language,
+which can be found here: @url{http://www.tcl.tk}. Jim Tcl has far
+fewer features. Jim Tcl is several dozens of .C files and .H files and
implements the basic Tcl command set. In contrast: Tcl 8.6 is a
4.2 MB .zip file containing 1540 files.
@item @b{Missing Features}
@* Our practice has been: Add/clone the real Tcl feature if/when
-needed. We welcome Jim-Tcl improvements, not bloat. Also there
-are a large number of optional Jim-Tcl features that are not
+needed. We welcome Jim Tcl improvements, not bloat. Also there
+are a large number of optional Jim Tcl features that are not
enabled in OpenOCD.
@item @b{Scripts}
-@* OpenOCD configuration scripts are Jim-Tcl Scripts. OpenOCD's
+@* OpenOCD configuration scripts are Jim Tcl Scripts. OpenOCD's
command interpreter today is a mixture of (newer)
-Jim-Tcl commands, and the (older) original command interpreter.
+Jim Tcl commands, and the (older) original command interpreter.
@item @b{Commands}
@* At the OpenOCD telnet command line (or via the GDB monitor command) one
@@ -674,10 +674,10 @@ Some of the commands documented in this guide are implemented
as Tcl scripts, from a @file{startup.tcl} file internal to the server.
@item @b{Historical Note}
-@* Jim-Tcl was introduced to OpenOCD in spring 2008. Fall 2010,
-before OpenOCD 0.5 release, OpenOCD switched to using Jim-Tcl
-as a Git submodule, which greatly simplified upgrading Jim-Tcl
-to benefit from new features and bugfixes in Jim-Tcl.
+@* Jim Tcl was introduced to OpenOCD in spring 2008. Fall 2010,
+before OpenOCD 0.5 release, OpenOCD switched to using Jim Tcl
+as a Git submodule, which greatly simplified upgrading Jim Tcl
+to benefit from new features and bugfixes in Jim Tcl.
@item @b{Need a crash course in Tcl?}
@*@xref{Tcl Crash Course}.
@@ -796,7 +796,7 @@ those channels.
If you are having problems, you can enable internal debug messages via
the @option{-d} option.
-Also it is possible to interleave Jim-Tcl commands w/config scripts using the
+Also it is possible to interleave Jim Tcl commands w/config scripts using the
@option{-c} command line switch.
To enable debug output (when reporting problems or working on OpenOCD
@@ -962,7 +962,7 @@ that can be tested in a later script.
@end quotation
Here we will focus on the simpler solution: one user config
-file, including basic configuration plus any TCL procedures
+file, including basic configuration plus any Tcl procedures
to simplify your work.
@section User Config Files
@@ -1432,7 +1432,7 @@ In addition to target-specific utility code, another way that
board and target config files communicate is by following a
convention on how to use certain variables.
-The full Tcl/Tk language supports ``namespaces'', but Jim-Tcl does not.
+The full Tcl/Tk language supports ``namespaces'', but Jim Tcl does not.
Thus the rule we follow in OpenOCD is this: Variables that begin with
a leading underscore are temporary in nature, and can be modified and
used at will within a target configuration file.
@@ -1552,7 +1552,7 @@ configuration files for other JTAG tools
Some of this code could probably be shared between different boards.
For example, setting up a DRAM controller often doesn't differ by
much except the bus width (16 bits or 32?) and memory timings, so a
-reusable TCL procedure loaded by the @file{target.cfg} file might take
+reusable Tcl procedure loaded by the @file{target.cfg} file might take
those as parameters.
Similarly with oscillator, PLL, and clock setup;
and disabling the watchdog.
@@ -2137,7 +2137,7 @@ corresponding subsystems:
@end deffn
At last, @command{init} executes all the commands that are specified in
-the TCL list @var{post_init_commands}. The commands are executed in the
+the Tcl list @var{post_init_commands}. The commands are executed in the
same order they occupy in the list. If one of the commands fails, then
the error is propagated and OpenOCD fails too.
@example
@@ -2222,7 +2222,7 @@ cause initialization to fail with "Unknown remote qXfer reply: OK".
@deffn {Config Command} {tcl port} [number]
Specify or query the port used for a simplified RPC
-connection that can be used by clients to issue TCL commands and get the
+connection that can be used by clients to issue Tcl commands and get the
output from the Tcl engine.
Intended as a machine interface.
When not specified during the configuration stage,
@@ -2233,7 +2233,7 @@ When specified as "disabled", this service is not activated.
@deffn {Config Command} {telnet port} [number]
Specify or query the
port on which to listen for incoming telnet connections.
-This port is intended for interaction with one human through TCL commands.
+This port is intended for interaction with one human through Tcl commands.
When not specified during the configuration stage,
the port @var{number} defaults to 4444.
When specified as "disabled", this service is not activated.
@@ -2304,7 +2304,7 @@ The file name is @i{target_name}.xml.
Hardware debuggers are parts of asynchronous systems,
where significant events can happen at any time.
The OpenOCD server needs to detect some of these events,
-so it can report them to through TCL command line
+so it can report them to through Tcl command line
or to GDB.
Examples of such events include:
@@ -2345,7 +2345,7 @@ specific information about the current state is printed.
An optional parameter
allows background polling to be enabled and disabled.
-You could use this from the TCL command shell, or
+You could use this from the Tcl command shell, or
from GDB using @command{monitor poll} command.
Leave background polling enabled while you're using GDB.
@example
@@ -2414,6 +2414,17 @@ target.
@deffn {Command} {adapter list}
List the debug adapter drivers that have been built into
the running copy of OpenOCD.
+
+The output is formatted as a Tcl dictionary indexed by the adapter name
+and containing the transports in a Tcl list.
+@example
+dummy @{ jtag @}
+ftdi @{ jtag swd @}
+@end example
+This format is easily handled by Tcl scripts:
+@example
+dict get [adapter list] ftdi
+@end example
@end deffn
@anchor{adapter gpio}
@@ -2486,7 +2497,7 @@ This command is only available if your libusb1 is at least version 1.0.16.
Specifies the @var{serial_string} of the adapter to use.
If this command is not specified, serial strings are not checked.
Only the following adapter drivers use the serial string from this command:
-arm-jtag-ew, cmsis_dap, esp_usb_jtag, ft232r, ftdi, hla (ti-icdi), jlink, kitprog, opendus,
+arm-jtag-ew, cmsis_dap, esp_usb_jtag, ft232r, ftdi, hla (stlink, ti-icdi), jlink, kitprog, opendus,
openjtag, osbdm, presto, rlink, st-link, usb_blaster (ublast2), usbprog, vsllink, xds110.
@end deffn
@@ -3223,16 +3234,19 @@ that OpenOCD would normally use to access the target.
Currently supported adapters include the STMicroelectronics ST-LINK, TI ICDI
and Nuvoton Nu-Link.
+
ST-LINK firmware version >= V2.J21.S4 recommended due to issues with earlier
versions of firmware where serial number is reset after first use. Suggest
using ST firmware update utility to upgrade ST-LINK firmware even if current
version reported is V2.J21.S4.
+The ST-LINK firmware update utility is available for download from
+@url{https://www.st.com/en/development-tools/stsw-link007.html, ST website}.
@deffn {Config Command} {hla device_desc} description
Currently Not Supported.
@end deffn
-@deffn {Config Command} {hla layout} (@option{icdi}|@option{nulink})
+@deffn {Config Command} {hla layout} (@option{stlink}|@option{icdi}|@option{nulink})
Specifies the adapter layout to use.
@end deffn
@@ -3240,6 +3254,15 @@ Specifies the adapter layout to use.
Pairs of vendor IDs and product IDs of the device.
@end deffn
+@deffn {Config Command} {hla stlink_backend} (usb | tcp [port])
+@emph{ST-Link only:} Choose between 'exclusive' USB communication (the default backend) or
+'shared' mode using ST-Link TCP server (the default port is 7184).
+
+@emph{Note:} ST-Link TCP server is a binary application provided by ST
+available from @url{https://www.st.com/en/development-tools/st-link-server.html,
+ST-LINK server software module}.
+@end deffn
+
@deffn {Command} {hla command} command
Execute a custom adapter-specific command. The @var{command} string is
passed as is to the underlying adapter layout handler.
@@ -3254,6 +3277,11 @@ directly access the arm ADIv5 DAP.
The older API that requires HLA transport is deprecated and will be dropped
from OpenOCD. In mean time it's still available by using @file{interface/stlink-hla.cfg}.
+The HLA interface file can be put as first command line argument to
+force using is in place of the default DAP API.
+@example
+openocd -f interface/stlink-hla.cfg -f board/st_nucleo_f4.cfg
+@end example
The new API provide access to multiple AP on the same DAP, but the
maximum number of the AP port is limited by the specific firmware version
@@ -3801,10 +3829,8 @@ JTAG supports both debugging and boundary scan testing.
Flash programming support is built on top of debug support.
JTAG transport is selected with the command @command{transport select
-jtag}. Unless your adapter uses either @ref{hla_interface,the hla interface
-driver} (in which case the command is @command{transport select hla_jtag})
-or @ref{st_link_dap_interface,the st-link interface driver} (in which case
-the command is @command{transport select dapdirect_jtag}).
+jtag}. This command has to be used also for @ref{hla_interface,the hla interface
+driver} and @ref{st_link_dap_interface,the st-link interface driver}.
@subsection SWD Transport
@cindex SWD
@@ -3817,10 +3843,8 @@ Flash programming support is built on top of debug support.
(Some processors support both JTAG and SWD.)
SWD transport is selected with the command @command{transport select
-swd}. Unless your adapter uses either @ref{hla_interface,the hla interface
-driver} (in which case the command is @command{transport select hla_swd})
-or @ref{st_link_dap_interface,the st-link interface driver} (in which case
-the command is @command{transport select dapdirect_swd}).
+swd}. This command has to be used also for @ref{hla_interface,the hla interface
+driver} and @ref{st_link_dap_interface,the st-link interface driver}.
@deffn {Config Command} {swd newdap} ...
Declares a single DAP which uses SWD transport.
@@ -4532,7 +4556,7 @@ mechanism for debugger targets.)
See the next section for information about the available events.
The @code{configure} subcommand assigns an event handler,
-a TCL string which is evaluated when the event is triggered.
+a Tcl string which is evaluated when the event is triggered.
The @code{cget} subcommand returns that handler.
@end deffn
@@ -4791,7 +4815,7 @@ The instance number is in bits 28..31 of DLPIDR value.
@deffn {Command} {dap names}
This command returns a list of all registered DAP objects. It it useful mainly
-for TCL scripting.
+for Tcl scripting.
@end deffn
@deffn {Command} {dap info} [@var{num}|@option{root}]
@@ -5780,7 +5804,7 @@ until the programming session is finished.
If you use @ref{programmingusinggdb,,Programming using GDB},
the target is prepared automatically in the event gdb-flash-erase-start
-The jimtcl script @command{program} calls @command{reset init} explicitly.
+The Tcl script @command{program} calls @command{reset init} explicitly.
@section Erasing, Reading, Writing to Flash
@cindex flash erasing
@@ -7467,18 +7491,18 @@ mspm0_board_reset
@end itemize
-@deffn {TCL proc} {mspm0_board_reset}
+@deffn {Tcl proc} {mspm0_board_reset}
Performs an nRST toggle on the device.
@end deffn
-@deffn {TCL proc} {mspm0_mass_erase}
+@deffn {Tcl proc} {mspm0_mass_erase}
Sends the mass erase command to the SEC-AP mailbox and then performs
an nRST toggle. Once the command has been fully processed by the ROM,
all MAIN memory will be erased. NOTE: This command is not supported
on MSPM0C* family of devices.
@end deffn
-@deffn {TCL proc} {mspm0_factory_reset}
+@deffn {Tcl proc} {mspm0_factory_reset}
Sends the factory reset command to the SEC-AP mailbox and then performs
an nRST toggle. Once the command has been fully processed by the ROM,
all MAIN memory will be erased and NONMAIN will be reset to its default
@@ -7777,7 +7801,7 @@ flash bank super_flash_toc2_cm4 psoc6 0x16007C00 0 0 0 \
psoc6-specific commands
@deffn {Command} {psoc6 reset_halt}
-Command can be used to simulate broken Vector Catch from gdbinit or tcl scripts.
+Command can be used to simulate broken Vector Catch from gdbinit or Tcl scripts.
When invoked for CM0+ target, it will set break point at application entry point
and issue SYSRESETREQ. This will reset both cores and all peripherals. CM0+ will
reset CM4 during boot anyway so this is safe. On CM4 target, VECTRESET is used
@@ -7901,15 +7925,29 @@ locked, but can still mass erase the whole flash.
@end deffn
@end deffn
-@deffn {Flash Driver} {rp2040}
-Supports RP2040 "Raspberry Pi Pico" microcontroller.
-RP2040 is a dual-core device with two CM0+ cores. Both cores share the same
-Flash/RAM/MMIO address space. Non-volatile storage is achieved with an
-external QSPI flash; a Boot ROM provides helper functions.
+@deffn {Flash Driver} {rp2xxx}
+Supports RP2040 "Raspberry Pi Pico" microcontroller and RP2350 Pico 2
+RP2040 is a dual-core device with two CM0+ cores.
+RP2350 is a dual-core device with two slots switched to either Cortex-M33
+or Hazard3 RISC-V core.
+Both cores share the same Flash/RAM/MMIO address space.
+Non-volatile storage is achieved with an external QSPI flash;
+a Boot ROM provides helper functions.
@example
-flash bank $_FLASHNAME rp2040_flash $_FLASHBASE $_FLASHSIZE 1 32 $_TARGETNAME
+flash bank $_FLASHNAME rp2xxx $_FLASHBASE $_FLASHSIZE 0 0 $_TARGETNAME
@end example
+
+@deffn {Command} {rp2xxx rom_api_call} fc [p0 [p1 [p2 [p3]]]]
+A utility for calling ROM API function with two characters lookup code
+@var{fc} and up to 4 optional parameters @var{p0 p1 p2 p3}.
+The call is supported on the target where the flash bank is configured
+(core0).
+@end deffn
+
+@deffn {Command} {rp2xxx _switch_target} old_target new_target
+A command used internally by rp2350.cfg when the core type is switched.
+@end deffn
@end deffn
@deffn {Flash Driver} {rsl10}
@@ -8978,7 +9016,7 @@ OpenOCD implements numerous ways to program the target flash, whether internal o
Programming can be achieved by either using @ref{programmingusinggdb,,Programming using GDB},
or using the commands given in @ref{flashprogrammingcommands,,Flash Programming Commands}.
-@*To simplify using the flash commands directly a jimtcl script is available that handles the programming and verify stage.
+@*To simplify using the flash commands directly a Tcl script is available that handles the programming and verify stage.
OpenOCD will program/verify/reset the target and optionally shutdown.
The script is executed as follows and by default the following actions will be performed.
@@ -9260,7 +9298,7 @@ non-zero exit code to the parent process.
If user types CTRL-C or kills OpenOCD, the command @command{shutdown}
will be automatically executed to cause OpenOCD to exit.
-It is possible to specify, in the TCL list @var{pre_shutdown_commands} , a
+It is possible to specify, in the Tcl list @var{pre_shutdown_commands} , a
set of commands to be automatically executed before @command{shutdown} , e.g.:
@example
lappend pre_shutdown_commands @{echo "Goodbye, my friend ..."@}
@@ -9849,7 +9887,7 @@ Add or replace usage text on the given @var{command_name}.
@deffn {Command} {ms}
Returns current time since the Epoch in ms
(See: @url{https://en.wikipedia.org/wiki/Epoch_(computing)}).
-Useful to compute delays in TCL.
+Useful to compute delays in Tcl.
@end deffn
@node Architecture and Core Commands
@@ -10166,7 +10204,7 @@ of the CTI.
@deffn {Command} {cti names}
Prints a list of names of all CTI objects created. This command is mainly
-useful in TCL scripting.
+useful in Tcl scripting.
@end deffn
@section Generic ARM
@@ -10810,7 +10848,7 @@ protocol used for trace data:
@end itemize
@item @code{-event} @var{event_name} @var{event_body} -- assigns an event handler,
-a TCL string which is evaluated when the event is triggered. The events
+a Tcl string which is evaluated when the event is triggered. The events
@code{pre-enable}, @code{post-enable}, @code{pre-disable} and @code{post-disable}
are defined for TPIU/SWO.
A typical use case for the event @code{pre-enable} is to enable the trace clock
@@ -10893,7 +10931,7 @@ baud with our custom divisor to get 12MHz)
@item OpenOCD invocation line:
@example
openocd -f interface/stlink.cfg \
--c "transport select dapdirect_swd" \
+-c "transport select swd" \
-f target/stm32l1.cfg \
-c "stm32l1.tpiu configure -protocol uart" \
-c "stm32l1.tpiu configure -traceclk 24000000 -pin-freq 12000000" \
@@ -11850,7 +11888,7 @@ capabilities than most of the other processors and in addition there is an
extension interface that allows SoC designers to add custom registers and
instructions. For the OpenOCD that mostly means that set of core and AUX
registers in target will vary and is not fixed for a particular processor
-model. To enable extensibility several TCL commands are provided that allow to
+model. To enable extensibility several Tcl commands are provided that allow to
describe those optional registers in OpenOCD configuration files. Moreover
those commands allow for a dynamic target features discovery.
@@ -12005,12 +12043,12 @@ configuration comprises two categories:
@end enumerate
All common Xtensa support is built into the OpenOCD Xtensa target layer and
-is enabled through a combination of TCL scripts: the target-specific
+is enabled through a combination of Tcl scripts: the target-specific
@file{target/xtensa.cfg} and a board-specific @file{board/xtensa-*.cfg},
similar to other target architectures.
Importantly, core-specific configuration information must be provided by
-the user, and takes the form of an @file{xtensa-core-XXX.cfg} TCL script that
+the user, and takes the form of an @file{xtensa-core-XXX.cfg} Tcl script that
defines the core's configurable features through a series of Xtensa
configuration commands (detailed below).
@@ -13591,7 +13629,7 @@ learning Tcl, the intent of this chapter is to give you some idea of
how the Tcl scripts work.
This chapter is written with two audiences in mind. (1) OpenOCD users
-who need to understand a bit more of how Jim-Tcl works so they can do
+who need to understand a bit more of how Jim Tcl works so they can do
something useful, and (2) those that want to add a new command to
OpenOCD.
@@ -13751,7 +13789,7 @@ Often many of those parameters are in @{curly-braces@} - thus the
variables inside are not expanded or replaced until later.
Remember that every Tcl command looks like the classic ``main( argc,
-argv )'' function in C. In JimTCL - they actually look like this:
+argv )'' function in C. In Jim Tcl - they actually look like this:
@example
int
generated by cgit v1.1 at 2025-09-27 09:13:09 +0000