* 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.
$_TARGETNAME configure -work-area-phys 0x00200000 \
-work-area-size 0x4000 -work-area-backup 0
@end example
+@pxref{Define CPU targets working in SMP}
+@anchor{Define CPU targets working in SMP}
+@subsection Define CPU targets working in SMP
+@cindex SMP
+After setting targets, you can define a list of targets working in SMP.
+
+@example
+set _TARGETNAME_1 $_CHIPNAME.cpu1
+set _TARGETNAME_2 $_CHIPNAME.cpu2
+target create $_TARGETNAME_1 cortex_a8 -chain-position $_CHIPNAME.dap \
+-coreid 0 -dbgbase $_DAP_DBG1
+target create $_TARGETNAME_2 cortex_a8 -chain-position $_CHIPNAME.dap \
+-coreid 1 -dbgbase $_DAP_DBG2
+#define 2 targets working in smp.
+target smp $_CHIPNAME.cpu2 $_CHIPNAME.cpu1
+@end example
+In the above example on cortex_a8, 2 cpus are working in SMP.
+In SMP only one GDB instance is created and :
+@itemize @bullet
+@item a set of hardware breakpoint sets the same breakpoint on all targets in the list.
+@item halt command triggers the halt of all targets in the list.
+@item resume command triggers the write context and the restart of all targets in the list.
+@item following a breakpoint: the target stopped by the breakpoint is displayed to the GDB session.
+@item dedicated GDB serial protocol packets are implemented for switching/retrieving the target
+displayed by the GDB session @pxref{Using openocd SMP with GDB}.
+@end itemize
+
+The SMP behaviour can be disabled/enabled dynamically. On cortex_a8 following
+command have been implemented.
+@itemize @bullet
+@item cortex_a8 smp_on : enable SMP mode, behaviour is as described above.
+@item cortex_a8 smp_off : disable SMP mode, the current target is the one
+displayed in the GDB session, only this target is now controlled by GDB
+session. This behaviour is useful during system boot up.
+@item cortex_a8 smp_gdb : display/fix the core id displayed in GDB session see
+following example.
+@end itemize
+
+@example
+>cortex_a8 smp_gdb
+gdb coreid 0 -> -1
+#0 : coreid 0 is displayed to GDB ,
+#-> -1 : next resume triggers a real resume
+> cortex_a8 smp_gdb 1
+gdb coreid 0 -> 1
+#0 :coreid 0 is displayed to GDB ,
+#->1 : next resume displays coreid 1 to GDB
+> resume
+> cortex_a8 smp_gdb
+gdb coreid 1 -> 1
+#1 :coreid 1 is displayed to GDB ,
+#->1 : next resume displays coreid 1 to GDB
+> cortex_a8 smp_gdb -1
+gdb coreid 1 -> -1
+#1 :coreid 1 is displayed to GDB,
+#->-1 : next resume triggers a real resume
+@end example
+
@subsection Chip Reset Setup
@deffn {Interface Driver} {jlink}
Segger jlink USB adapter
-@c command: jlink_info
+@c command: jlink caps
+@c dumps jlink capabilities
+@c command: jlink config
+@c access J-Link configurationif no argument this will dump the config
+@c command: jlink config kickstart [val]
+@c set Kickstart power on JTAG-pin 19.
+@c command: jlink config mac_address [ff:ff:ff:ff:ff:ff]
+@c set the MAC Address
+@c command: jlink config ip [A.B.C.D[/E] [F.G.H.I]]
+@c set the ip address of the J-Link Pro, "
+@c where A.B.C.D is the ip,
+@c E the bit of the subnet mask
+@c F.G.H.I the subnet mask
+@c command: jlink config reset
+@c reset the current config
+@c command: jlink config save
+@c save the current config
+@c command: jlink config usb_address [0x00 to 0x03 or 0xff]
+@c set the USB-Address,
+@c This will change the product id
+@c command: jlink info
@c dumps status
-@c command: jlink_hw_jtag (2|3)
+@c command: jlink hw_jtag (2|3)
@c sets version 2 or 3
+@c command: jlink pid
+@c set the pid of the interface we want to use
@end deffn
@deffn {Interface Driver} {parport}
@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.
@emph{JTAG TAP Reset} ... the @emph{TRST} hardware signal resets
just the TAP controllers connected to the JTAG adapter.
Such resets should not be visible to the rest of the system; resetting a
-device's the TAP controller just puts that controller into a known state.
+device's TAP controller just puts that controller into a known state.
@item
@emph{Emulation Reset} ... many devices can be reset through JTAG
commands. These resets are often distinguishable from system
when either of those signals is not connected.
When SRST is not available, your code might not be able to rely
on controllers having been fully reset during code startup.
-Missing TRST is not a problem, since JTAG level resets can
+Missing TRST is not a problem, since JTAG-level resets can
be triggered using with TMS signaling.
@item @emph{Signals shorted} ... Sometimes a chip, board, or
@c "cfi part_id" disabled
@end deffn
-@deffn {Flash Driver} spearsmi
-@cindex SPEAr Serial Memory Interface
+@deffn {Flash Driver} stmsmi
+@cindex STMicroelectronics Serial Memory Interface
@cindex SMI
-@cindex spearsmi
-All members of SPEAr MPU family from STMicroelectronics include a
+@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 MPU and board configuration, up to 4 external
+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
flash size, are detected automatically.
@example
-flash bank $_FLASHNAME spearsmi 0xf8000000 0 0 0 $_TARGETNAME
+flash bank $_FLASHNAME stmsmi 0xf8000000 0 0 0 $_TARGETNAME
@end example
@end deffn
current target. Must be preceeded by fast_load_image.
@end deffn
-@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
+@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}|@option{s19}]
Normally you should be using @command{load_image} or GDB load. However, for
testing purposes or when I/O overhead is significant(OpenOCD running on an embedded
host), storing the image in memory and uploading the image to the target
@end deffn
@anchor{load_image}
-@deffn Command {load_image} filename address [[@option{bin}|@option{ihex}|@option{elf}] @option{min_addr} @option{max_length}]
+@deffn Command {load_image} filename address [[@option{bin}|@option{ihex}|@option{elf}|@option{s19}] @option{min_addr} @option{max_length}]
Load image from file @var{filename} to target memory offset by @var{address} from its load address.
The file format may optionally be specified
-(@option{bin}, @option{ihex}, or @option{elf}).
+(@option{bin}, @option{ihex}, @option{elf}, or @option{s19}).
In addition the following arguments may be specifed:
@var{min_addr} - ignore data below @var{min_addr} (this is w.r.t. to the target's load address + @var{address})
@var{max_length} - maximum number of bytes to load.
To verify any flash programming the GDB command @option{compare-sections}
can be used.
+@anchor{Using openocd SMP with GDB}
+@section Using openocd SMP with GDB
+@cindex SMP
+For SMP support following GDB serial protocol packet have been defined :
+@itemize @bullet
+@item j - smp status request
+@item J - smp set request
+@end itemize
+
+OpenOCD implements :
+@itemize @bullet
+@item @option{jc} packet for reading core id displayed by
+GDB connection. Reply is @option{XXXXXXXX} (8 hex digits giving core id) or
+ @option{E01} for target not smp.
+@item @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue
+(core id -1 is reserved for returning to normal resume mode). Reply @option{E01}
+for target not smp or @option{OK} on success.
+@end itemize
+
+Handling of this packet within GDB can be done :
+@itemize @bullet
+@item by the creation of an internal variable (i.e @option{_core}) by mean
+of function allocate_computed_value allowing following GDB command.
+@example
+set $_core 1
+#Jc01 packet is sent
+print $_core
+#jc packet is sent and result is affected in $
+@end example
+
+@item by the usage of GDB maintenance command as described in following example (2
+cpus in SMP with core id 0 and 1 @pxref{Define CPU targets working in SMP}).
+
+@example
+# toggle0 : force display of coreid 0
+define toggle0
+maint packet Jc0
+continue
+main packet Jc-1
+end
+# toggle1 : force display of coreid 1
+define toggle1
+maint packet Jc1
+continue
+main packet Jc-1
+end
+@end example
+@end itemize
+
@node Tcl Scripting API
@chapter Tcl Scripting API
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.
Code Review / openocd.git / blobdiff