* 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
are many types of debug adapter, and little uniformity in what
they are called. (There are also product naming differences.)
-These adapters are sometimes packaged as discrete dongles. which
+These adapters are sometimes packaged as discrete dongles, which
may generically be called @dfn{hardware interface dongles}.
Some development boards also integrate them directly, which may
let the development board can be directly connected to the debug
@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 includes 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, can write Tcl programs with them.
-You can learn more about JIM at its website, @url{http://jim.berlios.de}.
+You can learn more about Jim at its website, @url{http://jim.berlios.de}.
+There is an active and responsive community, get on the mailing list
+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 a single .C file and a single .H file and
+@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 a single .C file and a single .H file and
implements the basic Tcl command set. In contrast: Tcl 8.6 is a
-4.2 MB .zip file containing 1540 files.
+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.
+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 (older) the orginal command interpreter.
+Jim-Tcl commands, and (older) the orginal command interpreter.
@item @b{Commands}
@* At the OpenOCD telnet command line (or via the GDB monitor command) one
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.
+@* 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}.
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
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.
@deffn {Command} gdb_port [number]
@cindex GDB server
-Specify or query the first port used for incoming GDB connections.
-The GDB port for the
-first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
+Normally gdb listens to a TCP/IP port, but GDB can also
+communicate via pipes(stdin/out or named pipes). The name
+"gdb_port" stuck because it covers probably more than 90% of
+the normal use cases.
+
+No arguments reports GDB port. "pipe" means listen to stdin
+output to stdout, an integer is base port number, "disable"
+disables the gdb server.
+
+When using "pipe", also use log_output to redirect the log
+output to a file so as not to flood the stdin/out pipes.
+
+The -p/--pipe option is deprecated and a warning is printed
+as it is equivalent to passing in -c "gdb_port pipe; log_output openocd.log".
+
+Any other string is interpreted as named pipe to listen to.
+Output pipe is the same name as input pipe, but with 'o' appended,
+e.g. /var/gdb, /var/gdbo.
+
+The GDB port for the first target will be the base port, the
+second target will listen on gdb_port + 1, and so on.
When not specified during the configuration stage,
the port @var{number} defaults to 3333.
-When specified as zero, GDB remote access ports are not activated.
@end deffn
@deffn {Command} tcl_port [number]
Intended as a machine interface.
When not specified during the configuration stage,
the port @var{number} defaults to 6666.
-When specified as zero, this port is not activated.
+
@end deffn
@deffn {Command} telnet_port [number]
@end deffn
@section Transport Configuration
+@cindex Transport
As noted earlier, depending on the version of OpenOCD you use,
and the debug adapter you are using,
several transports may be available to
@end deffn
@subsection JTAG Transport
+@cindex JTAG
JTAG is the original transport supported by OpenOCD, and most
of the OpenOCD commands support it.
JTAG transports expose a chain of one or more Test Access Points (TAPs),
JTAG supports both debugging and boundary scan testing.
Flash programming support is built on top of debug support.
@subsection SWD Transport
+@cindex SWD
+@cindex Serial Wire Debug
SWD (Serial Wire Debug) is an ARM-specific transport which exposes one
Debug Access Point (DAP, which must be explicitly declared.
(SWD uses fewer signal wires than JTAG.)
SWD is debug-oriented, and does not support boundary scan testing.
Flash programming support is built on top of debug support.
(Some processors support both JTAG and SWD.)
+@deffn Command {swd newdap} ...
+Declares a single DAP which uses SWD transport.
+Parameters are currently the same as "jtag newtap" but this is
+expected to change.
+@end deffn
+@deffn Command {swd wcr trn prescale}
+Updates TRN (turnaraound delay) and prescaling.fields of the
+Wire Control Register (WCR).
+No parameters: displays current settings.
+@end deffn
+
@subsection SPI Transport
+@cindex SPI
+@cindex Serial Peripheral Interface
The Serial Peripheral Interface (SPI) is a general purpose transport
which uses four wire signaling. Some processors use it as part of a
solution for flash programming.
@c "cfi part_id" disabled
@end deffn
+@deffn {Flash Driver} stmsmi
+@cindex STMicroelectronics Serial Memory Interface
+@cindex SMI
+@cindex stmsmi
+Some devices form STMicroelectronics (e.g. STR75x MCU family,
+SPEAr MPU family) include a proprietary
+``Serial Memory Interface'' (SMI) controller able to drive external
+SPI flash devices.
+Depending on specific device and board configuration, up to 4 external
+flash devices can be connected.
+
+SMI makes the flash content directly accessible in the CPU address
+space; each external device is mapped in a memory bank.
+CPU can directly read data, execute code and boot from SMI banks.
+Normal OpenOCD commands like @command{mdw} can be used to display
+the flash content.
+
+The setup command only requires the @var{base} parameter in order
+to identify the memory bank.
+All other parameters are ignored. Additional information, like
+flash size, are detected automatically.
+
+@example
+flash bank $_FLASHNAME stmsmi 0xf8000000 0 0 0 $_TARGETNAME
+@end example
+
+@end deffn
+
@subsection Internal Flash (Microcontrollers)
@deffn {Flash Driver} aduc702x
@xref{Running}.
@end deffn
-@deffn Command echo message
+@deffn Command echo [-n] message
Logs a message at "user" priority.
Output @var{message} to stdout.
+Option "-n" suppresses trailing newline.
@example
echo "Downloading kernel -- please wait"
@end example
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.