-\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename openocd.info
-@settitle Open On-Chip Debugger (OpenOCD)
+@settitle OpenOCD User's Guide
@dircategory Development
@direntry
-@paragraphindent 0
-* OpenOCD: (openocd). Open On-Chip Debugger.
+* OpenOCD: (openocd). OpenOCD User's Guide
@end direntry
+@paragraphindent 0
@c %**end of header
@include version.texi
@copying
+This User's Guide documents
+release @value{VERSION},
+dated @value{UPDATED},
+of the Open On-Chip Debugger (OpenOCD).
+
@itemize @bullet
@item Copyright @copyright{} 2008 The OpenOCD Project
@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
@end copying
@titlepage
-@title Open On-Chip Debugger (OpenOCD)
-@subtitle Edition @value{EDITION} for OpenOCD version @value{VERSION}
+@titlefont{@emph{Open On-Chip Debugger:}}
+@sp 1
+@title OpenOCD User's Guide
+@subtitle for release @value{VERSION}
@subtitle @value{UPDATED}
+
@page
@vskip 0pt plus 1filll
@insertcopying
@summarycontents
@contents
-@node Top, About, , (dir)
-@top OpenOCD
-
-This manual documents edition @value{EDITION} of the Open On-Chip Debugger
-(OpenOCD) version @value{VERSION}, @value{UPDATED}.
+@ifnottex
+@node Top
+@top OpenOCD User's Guide
@insertcopying
+@end ifnottex
@menu
* About:: About OpenOCD
* FAQ:: Frequently Asked Questions
* Tcl Crash Course:: Tcl Crash Course
* License:: GNU Free Documentation License
+
@comment DO NOT use the plain word ``Index'', reason: CYGWIN filename
@comment case issue with ``Index.html'' and ``index.html''
@comment Occurs when creating ``--html --no-split'' output
@uref{http://openocd.berlios.de/web/}
+@section Latest User's Guide:
+
+The user's guide you are now reading may not be the latest one
+available. A version for more recent code may be available.
+Its HTML form is published irregularly at:
+
+@uref{http://openocd.berlios.de/doc/}
+
+PDF form is likewise published at:
+
+@uref{http://openocd.berlios.de/doc/pdf/}
+
+@section OpenOCD User's Forum
+
+There is an OpenOCD forum (phpBB) hosted by SparkFun:
+
+@uref{http://forum.sparkfun.com/viewforum.php?f=18}
+
@node Developers
@chapter OpenOCD Developer Resources
The OpenOCD Developer Mailing List provides the primary means of
communication between developers:
- @uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
+@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
All drivers developers are enouraged to also subscribe to the list of
SVN commits to keep pace with the ongoing changes:
- @uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
+@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
+
@node Building OpenOCD
@chapter Building OpenOCD
svn checkout svn://svn.berlios.de/openocd/trunk openocd
@end example
-Building OpenOCD requires a recent version of the GNU autotools (autoconf >= 2.59 and automake >= 1.9).
+If you prefer GIT based tools, the @command{git-svn} package works too:
+
+@example
+ git svn clone -s svn://svn.berlios.de/openocd
+@end example
+
+Building OpenOCD from a repository requires a recent version of the
+GNU autotools (autoconf >= 2.59 and automake >= 1.9).
For building on Windows,
you have to use Cygwin. Make sure that your @env{PATH} environment variable contains no
other locations with Unix utils (like UnxUtils) - these can't handle the Cygwin
# variable: _TARGETNAME = network.cpu
# other commands can refer to the "network.cpu" tap.
$_TARGETNAME configure .... params for this CPU..
-
+
set ENDIAN little
set CHIPNAME video
source [find target/pxa270.cfg]
# variable: _TARGETNAME = video.cpu
# other commands can refer to the "video.cpu" tap.
$_TARGETNAME configure .... params for this CPU..
-
+
unset ENDIAN
set CHIPNAME xilinx
source [find target/spartan3.cfg]
@example
# SIMPLE example
-if @{ [info exists CHIPNAME] @} @{
- set _CHIPNAME $CHIPNAME
-@} else @{
+if @{ [info exists CHIPNAME] @} @{
+ set _CHIPNAME $CHIPNAME
+@} else @{
set _CHIPNAME sam7x256
@}
-if @{ [info exists ENDIAN] @} @{
- set _ENDIAN $ENDIAN
-@} else @{
+if @{ [info exists ENDIAN] @} @{
+ set _ENDIAN $ENDIAN
+@} else @{
set _ENDIAN little
@}
@subsection Work Areas
Work areas are small RAM areas used by OpenOCD to speed up downloads,
-and to download small snippets of code to program flash chips.
+and to download small snippets of code to program flash chips.
If the chip includes a form of ``on-chip-ram'' - and many do - define
a reasonable work area and use the ``backup'' option.
examination of the instruction and data bus activity. Trace
activity is controlled through an ``Embedded Trace Module'' (ETM)
on one of the core's scan chains. The ETM emits voluminous data
-through a ``trace port''. The trace port is accessed in one
-of two ways. When its signals are pinned out from the chip,
-boards may provide a special high speed debugging connector;
-software support for this is not configured by default, use
-the ``--enable-oocd_trace'' option. Alternatively, trace data
-may be stored an on-chip SRAM which is packaged as an ``Embedded
-Trace Buffer'' (ETB). An ETB has its own TAP, usually right after
-its associated ARM core. OpenOCD supports the ETM, and your
-target configuration should set it up with the relevant trace
-port: ``etb'' for chips which use that, else the board-specific
-option will be either ``oocd_trace'' or ``dummy''.
+through a ``trace port''. (@xref{ARM Tracing}.)
+If you are using an external trace port,
+configure it in your board config file.
+If you are using an on-chip ``Embedded Trace Buffer'' (ETB),
+configure it in your target config file.
@example
etm config $_TARGETNAME 16 normal full etb
@* JIM-Tcl was introduced to OpenOCD in spring 2008.
@item @b{Need a crash course in Tcl?}
-@* See: @xref{Tcl Crash Course}.
+@*@xref{Tcl Crash Course}.
@end itemize
@node Daemon Configuration
the port @var{number} defaults to 4444.
@end deffn
-@section GDB Configuration
@anchor{GDB Configuration}
+@section GDB Configuration
@cindex GDB
@cindex GDB configuration
You can reconfigure some GDB behaviors if needed.
@xref{Target Create}, about declaring individual targets.
@xref{Target Events}, about configuring target-specific event handling.
-@deffn {Command} gdb_breakpoint_override <hard|soft|disable>
@anchor{gdb_breakpoint_override}
+@deffn {Command} gdb_breakpoint_override <hard|soft|disable>
Force breakpoint type for gdb @command{break} commands.
The raison d'etre for this option is to support GDB GUI's which don't
distinguish hard versus soft breakpoints, if the default OpenOCD and
Default behaviour is @var{resume}.
@end deffn
-@deffn {Config command} gdb_flash_program <enable|disable>
@anchor{gdb_flash_program}
+@deffn {Config command} gdb_flash_program <enable|disable>
Set to @var{enable} to cause OpenOCD to program the flash memory when a
vFlash packet is received.
The default behaviour is @var{enable}.
@cindex ep93xx options
Currently, there are no options available for the ep93xx interface.
-@section JTAG Speed
@anchor{JTAG Speed}
+@section JTAG Speed
JTAG clock setup is part of system setup.
It @emph{does not belong with interface setup} since any interface
only knows a few of the constraints for the JTAG clock speed.
@deffn {Command} reset_config mode_flag ...
This command tells OpenOCD the reset configuration
-of your combination of JTAG interface, board, and target.
+of your combination of JTAG board and target in target
+configuration scripts.
+
+If you have an interface that does not support SRST and
+TRST(unlikely), then you may be able to work around that
+problem by using a reset_config command to override any
+settings in the target configuration script.
+
+SRST and TRST has a fairly well understood definition and
+behaviour in the JTAG specification, but vendors take
+liberties to achieve various more or less clearly understood
+goals. Sometimes documentation is available, other times it
+is not. OpenOCD has the reset_config command to allow OpenOCD
+to deal with the various common cases.
The @var{mode_flag} options can be specified in any order, but only one
of each type -- @var{signals}, @var{combination}, @var{trst_type},
creating a ``target'' a JTAG tap DOTTED.NAME must exist first.
@section targets [NAME]
-@b{Note:} This command name is PLURAL - not singular.
+@b{Note:} This command name is PLURAL - not singular.
With NO parameter, this plural @b{targets} command lists all known
targets in a human friendly form.
Example:
@verbatim
(gdb) mon targets
- CmdName Type Endian ChainPos State
+ CmdName Type Endian ChainPos State
-- ---------- ---------- ---------- -------- ----------
0: target0 arm7tdmi little 0 halted
@end verbatim
@* Lists all supported target types (perhaps some are not yet in this document).
@item @b{names}
@* Lists all current debug target names, for example: 'str912.cpu' or 'pxa27.cpu' example usage:
-@verbatim
+@verbatim
foreach t [target names] {
puts [format "Target: %s\n" $t]
}
# Report
puts [format "The button is %s" $x]
@end example
-
+
In OpenOCD's terms, the ``target'' is an object just like a Tcl/Tk
button. Commands available as a ``target object'' are:
@* Invokes the specific event manually for the target
@end itemize
+@anchor{Target Events}
@section Target Events
@cindex events
-@anchor{Target Events}
At various times, certain things can happen, or you want them to happen.
Examples:
@}
mychip.cpu configure -event gdb-attach my_attach_proc
mychip.cpu configure -event gdb-attach @{
- puts "Reset..."
- reset halt
+ puts "Reset..."
+ reset halt
@}
@end example
@end example
@end itemize
-@section Target Create
@anchor{Target Create}
+@section Target Create
@cindex target
@cindex target creation
is that for read access, it acts exactly like any other addressible memory.
This means you can use normal memory read commands like @command{mdw} or
@command{dump_image} with it, with no special @command{flash} subcommands.
-@xref{Memory access}.
-@xref{Image access}.
+@xref{Memory access}, and @ref{Image access}.
Write access works differently. Flash memory normally needs to be erased
before it's written. Erasing a sector turns all of its bits to ones, and
@comment @option{flash erase_sector} using the same syntax.
@end deffn
-@section Flash Drivers, Options, and Commands
@anchor{Flash Driver List}
+@section Flash Drivers, Options, and Commands
As noted above, the @command{flash bank} command requires a driver name,
and allows driver-specific options and behaviors.
Some drivers also activate driver-specific commands.
with the wrong ECC data can cause them to be marked as bad.
@end deffn
-@section NAND Drivers, Options, and Commands
@anchor{NAND Driver List}
+@section NAND Drivers, Options, and Commands
As noted above, the @command{nand device} command allows
driver-specific options and behaviors.
Some controllers also activate controller-specific commands.
@cindex shutdown
@*Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
+@anchor{debug_level}
@subsection debug_level [@var{n}]
@cindex debug_level
-@anchor{debug_level}
@*Display or adjust debug level to n<0-3>
@subsection fast [@var{enable|disable}]
state.
-@section Memory access commands
@anchor{Memory access}
+@section Memory access commands
@subsection meminfo
-display available RAM memory.
+display available RAM memory on OpenOCD host. Used in OpenOCD regression testing scripts. Mainly
+useful on embedded targets, PC type hosts have complimentary tools like Valgrind to address
+resource tracking problems.
@subsection Memory peek/poke type commands
These commands allow accesses of a specific size to the memory
system. Often these are used to configure the current target in some
@*write memory byte (8bit)
@end itemize
-@section Image loading commands
@anchor{Image access}
+@section Image loading commands
+@anchor{load_image}
@subsection load_image
@b{load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
@cindex load_image
-@anchor{load_image}
@*Load image <@var{file}> to target memory at <@var{address}>
@subsection fast_load_image
@b{fast_load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
@cindex fast_load_image
-@anchor{fast_load_image}
@*Normally you should be using @b{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
@subsection fast_load
@b{fast_load}
@cindex fast_image
-@anchor{fast_image}
@*Loads an image stored in memory by @b{fast_load_image} to the current target. Must be preceeded by fast_load_image.
+@anchor{dump_image}
@subsection dump_image
@b{dump_image} <@var{file}> <@var{address}> <@var{size}>
@cindex dump_image
-@anchor{dump_image}
@*Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
(binary) <@var{file}>.
@subsection verify_image
Some of those operations don't fit well in that framework, so they are
exposed here using architecture or implementation specific commands.
+@anchor{ARM Tracing}
+@subsection ARM Tracing
+@cindex ETM
+@cindex ETB
+
+CPUs based on ARM cores may include standard tracing interfaces,
+based on an ``Embedded Trace Module'' (ETM) which sends voluminous
+address and data bus trace records to a ``Trace Port''.
+
+@itemize
+@item
+Development-oriented boards will sometimes provide a high speed
+trace connector for collecting that data, when the particular CPU
+supports such an interface.
+(The standard connector is a 38-pin Mictor, with both JTAG
+and trace port support.)
+Those trace connectors are supported by higher end JTAG adapters
+and some logic analyzer modules; frequently those modules can
+buffer several megabytes of trace data.
+Configuring an ETM coupled to such an external trace port belongs
+in the board-specific configuration file.
+@item
+If the CPU doesn't provide an external interface, it probably
+has an ``Embedded Trace Buffer'' (ETB) on the chip, which is a
+dedicated SRAM. 4KBytes is one common ETB size.
+Configuring an ETM coupled only to an ETB belongs in the CPU-specific
+(target) configuration file, since it works the same on all boards.
+@end itemize
+
+ETM support in OpenOCD doesn't seem to be widely used yet.
+
+@quotation Issues
+ETM support may be buggy, and at least some @command{etm config}
+parameters should be detected by asking the ETM for them.
+It seems like a GDB hookup should be possible,
+as well as triggering trace on specific events
+(perhaps @emph{handling IRQ 23} or @emph{calls foo()}).
+There should be GUI tools to manipulate saved trace data and help
+analyse it in conjunction with the source code.
+It's unclear how much of a common interface is shared
+with the current XScale trace support, or should be
+shared with eventual Nexus-style trace module support.
+@end quotation
+
+@subsubsection ETM Configuration
+ETM setup is coupled with the trace port driver configuration.
+
+@deffn {Config Command} {etm config} target width mode clocking driver
+Declares the ETM associated with @var{target}, and associates it
+with a given trace port @var{driver}. @xref{Trace Port Drivers}.
+
+Several of the parameters must reflect the trace port configuration.
+The @var{width} must be either 4, 8, or 16.
+The @var{mode} must be @option{normal}, @option{multiplexted},
+or @option{demultiplexted}.
+The @var{clocking} must be @option{half} or @option{full}.
+
+@quotation Note
+You can see the ETM registers using the @command{reg} command, although
+not all of those possible registers are present in every ETM.
+@end quotation
+@end deffn
+
+@deffn Command {etm info}
+Displays information about the current target's ETM.
+@end deffn
+
+@deffn Command {etm status}
+Displays status of the current target's ETM:
+is the ETM idle, or is it collecting data?
+Did trace data overflow?
+Was it triggered?
+@end deffn
+
+@deffn Command {etm tracemode} [type context_id_bits cycle_accurate branch_output]
+Displays what data that ETM will collect.
+If arguments are provided, first configures that data.
+When the configuration changes, tracing is stopped
+and any buffered trace data is invalidated.
+
+@itemize
+@item @var{type} ... one of
+@option{none} (save nothing),
+@option{data} (save data),
+@option{address} (save addresses),
+@option{all} (save data and addresses)
+@item @var{context_id_bits} ... 0, 8, 16, or 32
+@item @var{cycle_accurate} ... @option{enable} or @option{disable}
+@item @var{branch_output} ... @option{enable} or @option{disable}
+@end itemize
+@end deffn
+
+@deffn Command {etm trigger_percent} percent
+@emph{Buggy and effectively a NOP ... @var{percent} from 2..100}
+@end deffn
+
+@subsubsection ETM Trace Operation
+
+After setting up the ETM, you can use it to collect data.
+That data can be exported to files for later analysis.
+It can also be parsed with OpenOCD, for basic sanity checking.
+
+@deffn Command {etm analyze}
+Reads trace data into memory, if it wasn't already present.
+Decodes and prints the data that was collected.
+@end deffn
+
+@deffn Command {etm dump} filename
+Stores the captured trace data in @file{filename}.
+@end deffn
+
+@deffn Command {etm image} filename [base_address] [type]
+Opens an image file.
+@end deffn
+
+@deffn Command {etm load} filename
+Loads captured trace data from @file{filename}.
+@end deffn
+
+@deffn Command {etm start}
+Starts trace data collection.
+@end deffn
+
+@deffn Command {etm stop}
+Stops trace data collection.
+@end deffn
+
+@anchor{Trace Port Drivers}
+@subsubsection Trace Port Drivers
+
+To use an ETM trace port it must be associated with a driver.
+
+@deffn {Trace Port Driver} dummy
+Use the @option{dummy} driver if you are configuring an ETM that's
+not connected to anything (on-chip ETB or off-chip trace connector).
+@emph{This driver lets OpenOCD talk to the ETM, but it does not expose
+any trace data collection.}
+@deffn {Config Command} {etm_dummy config} target
+Associates the ETM for @var{target} with a dummy driver.
+@end deffn
+@end deffn
+
+@deffn {Trace Port Driver} etb
+Use the @option{etb} driver if you are configuring an ETM
+to use on-chip ETB memory.
+@deffn {Config Command} {etb config} target etb_tap
+Associates the ETM for @var{target} with the ETB at @var{etb_tap}.
+You can see the ETB registers using the @command{reg} command.
+@end deffn
+@end deffn
+
+@deffn {Trace Port Driver} oocd_trace
+This driver isn't available unless OpenOCD was explicitly configured
+with the @option{--enable-oocd_trace} option. You probably don't want
+to configure it unless you've built the appropriate prototype hardware;
+it's @emph{proof-of-concept} software.
+
+Use the @option{oocd_trace} driver if you are configuring an ETM that's
+connected to an off-chip trace connector.
+
+@deffn {Config Command} {oocd_trace config} target tty
+Associates the ETM for @var{target} with a trace driver which
+collects data through the serial port @var{tty}.
+@end deffn
+
+@deffn Command {oocd_trace resync}
+Re-synchronizes with the capture clock.
+@end deffn
+
+@deffn Command {oocd_trace status}
+Reports whether the capture clock is locked or not.
+@end deffn
+@end deffn
+
+
@subsection ARMv4 and ARMv5 Architecture
@cindex ARMv4 specific commands
@cindex ARMv5 specific commands
@deffn Command {target_request debugmsgs} [enable|disable|charmsg]
Displays current handling of target DCC message requests.
These messages may be sent to the debugger while the target is running.
-The optional @option{enable} and @option{charmsg} parameters are
-equivalent; both enable the messages, @option{disable} disables them.
+The optional @option{enable} and @option{charmsg} parameters
+both enable the messages, while @option{disable} disables them.
+With @option{charmsg} the DCC words each contain one character,
+as used by Linux with CONFIG_DEBUG_ICEDCC;
+otherwise the libdcc format is used.
@end deffn
@node JTAG Commands
OpenOCD complies with the remote gdbserver protocol, and as such can be used
to debug remote targets.
+@anchor{Connecting to GDB}
@section Connecting to GDB
@cindex Connecting to GDB
-@anchor{Connecting to GDB}
Use GDB 6.7 or newer with OpenOCD if you run into trouble. For
instance GDB 6.3 has a known bug that produces bogus memory access
errors, which has since been fixed: look up 1836 in
@chapter FAQ
@cindex faq
@enumerate
-@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
@anchor{FAQ RTCK}
+@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
@cindex RTCK
@cindex adaptive clocking
@*
GDB issues software breakpoints when a normal breakpoint is requested, or to implement
source-line single-stepping. On ARMv4T systems, like ARM7TDMI, ARM720T or ARM920T,
-software breakpoints consume one of the two available hardware breakpoints.
+software breakpoints consume one of the two available hardware breakpoints.
@item @b{LPC2000 Flash} When erasing or writing LPC2000 on-chip flash, the operation fails at random.
arm7_9_execute_sys_speed(): timeout waiting for SYSCOMP
TODO.
-
+
@end enumerate
@node Tcl Crash Course
SetResult( interp, "WRONG number of parameters");
return ERROR;
@}
-
+
// argv[0] = the ascii string just like C
// Execute the start statement.
SetResult( interp, "" );
return SUCCESS;
@}
-@end example
+@end example
Every other command IF, WHILE, FORMAT, PUTS, EXPR, everything works
in the same basic way.
@* SOURCE reads a file and executes as a script.
@end enumerate
@subsection format command
-@b{Where:} Generally occurs in numerous places.
+@b{Where:} Generally occurs in numerous places.
@* Tcl has no command like @b{printf()}, instead it has @b{format}, which is really more like
@b{sprintf()}.
@b{Example}