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>
- 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).
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)
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
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
- 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?
/** @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.
- 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
*/
-/** @page jtagtcl JTAG TCL API
+/** @page jtagtcl JTAG Tcl API
This section needs to be expanded.
- 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.
-/** @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
****************************************
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.
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.
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...
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
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:
#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.
----
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"
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:
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.
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
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.
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
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,
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;
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.
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.
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
@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
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
@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.
@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!
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
projects / users / borneoa / openocd-next.git / commitdiff