forked from auracaster/openocd
doc/manual: Fix Tcl spelling
Use 'Tcl' because it is the official spelling. While at it, fix some misspellings of 'Jim Tcl'. Change-Id: I2d96f63b0dbc96ae62fe00ae41d2eb16897250fb Signed-off-by: Marc Schink <dev@zapb.de> Reviewed-on: https://review.openocd.org/c/openocd/+/8853 Tested-by: jenkins Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>
This commit is contained in:
Marc Schink
committed by
Antonio Borneo
Antonio Borneo
parent
98c95df228
commit
efafdd3c55
4
README
4
README
@@ -8,10 +8,10 @@ layered architecture of JTAG interface and TAP support including:
|
||||
- debug target support (e.g. ARM, MIPS): single-stepping,
|
||||
breakpoints/watchpoints, gprof profiling, etc;
|
||||
- flash chip drivers (e.g. CFI, NAND, internal flash);
|
||||
- embedded TCL interpreter for easy scripting.
|
||||
- embedded Tcl interpreter for easy scripting.
|
||||
|
||||
Several network interfaces are available for interacting with OpenOCD:
|
||||
telnet, TCL, and GDB. The GDB server enables OpenOCD to function as a
|
||||
telnet, Tcl, and GDB. The GDB server enables OpenOCD to function as a
|
||||
"remote target" for source-level debugging of embedded systems using
|
||||
the GNU GDB program (and the others who talk GDB protocol, e.g. IDA
|
||||
Pro).
|
||||
|
||||
18
TODO
18
TODO
@@ -12,14 +12,14 @@ may have evolved an idea since it was added here.
|
||||
|
||||
Feel free to send patches to add or clarify items on this list, too.
|
||||
|
||||
@section thelisttcl TCL
|
||||
@section thelisttcl Tcl
|
||||
|
||||
This section provides possible things to improve with OpenOCD's TCL support.
|
||||
This section provides possible things to improve with OpenOCD's Tcl support.
|
||||
|
||||
- Fix problem with incorrect line numbers reported for a syntax
|
||||
error in a reset init event.
|
||||
|
||||
- organize the TCL configurations:
|
||||
- organize the Tcl configurations:
|
||||
- provide more directory structure for boards/targets?
|
||||
- factor configurations into layers (encapsulation and re-use)
|
||||
|
||||
@@ -27,15 +27,15 @@ This section provides possible things to improve with OpenOCD's TCL support.
|
||||
parameters. Currently variables assigned through one such parameter
|
||||
command/script are unset before the next one is invoked.
|
||||
|
||||
- Isolate all TCL command support:
|
||||
- Isolate all Tcl command support:
|
||||
- Pure C CLI implementations using --disable-builtin-tcl.
|
||||
- Allow developers to build new dongles using OpenOCD's JTAG core.
|
||||
- At first, provide only low-level JTAG support; target layer and
|
||||
above rely heavily on scripting event mechanisms.
|
||||
- Allow full TCL support? add --with-tcl=/path/to/installed/tcl
|
||||
- Move TCL support out of foo.[ch] and into foo_tcl.[ch] (other ideas?)
|
||||
- Allow full Tcl support? add --with-tcl=/path/to/installed/tcl
|
||||
- Move Tcl support out of foo.[ch] and into foo_tcl.[ch] (other ideas?)
|
||||
- See src/jtag/core.c and src/jtag/tcl.c for an example.
|
||||
- allow some of these TCL command modules to be dynamically loadable?
|
||||
- allow some of these Tcl command modules to be dynamically loadable?
|
||||
|
||||
@section thelistadapter Adapter
|
||||
|
||||
@@ -75,7 +75,7 @@ directly in minidriver API for better embedded host performance.
|
||||
|
||||
The following tasks have been suggested for adding new core JTAG support:
|
||||
|
||||
- Improve autodetection of TAPs by supporting tcl escape procedures that
|
||||
- Improve autodetection of TAPs by supporting Tcl escape procedures that
|
||||
can configure discovered TAPs based on IDCODE value ... they could:
|
||||
- Remove guessing for irlen
|
||||
- Allow non-default irmask/ircapture values
|
||||
@@ -133,7 +133,7 @@ TCP/IP packets handled by the server.
|
||||
- add BSDL support?
|
||||
|
||||
A few possible options for the above:
|
||||
-# Fake a TCL equivalent?
|
||||
-# Fake a Tcl equivalent?
|
||||
-# Integrate an existing library?
|
||||
-# Write a new C implementation a la Jim?
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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!
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user