When you write config files, separate the reusable parts
(things every user of that interface, chip, or board needs)
from ones specific to your environment and debugging approach.
+@itemize
+@item
For example, a @code{gdb-attach} event handler that invokes
the @command{reset init} command will interfere with debugging
early boot code, which performs some of the same actions
that the @code{reset-init} event handler does.
+
+@item
Likewise, the @command{arm9tdmi vector_catch} command (or
@cindex vector_catch
its siblings @command{xscale vector_catch}
along with messaging and tracing setup.
(@xref{Software Debug Messages and Tracing}.)
+@item
+You might need to override some defaults.
+For example, you might need to move, shrink, or back up the target's
+work area if your application needs much SRAM.
+
+@item
TCP/IP port configuration is another example of something which
is environment-specific, and should only appear in
a user config file. @xref{TCP/IP Ports}.
+@end itemize
@section Project-Specific Utilities
@deffn Command {jtag cget} dotted.name @option{-event} name
@deffnx Command {jtag configure} dotted.name @option{-event} name string
-At this writing this mechanism is used only for event handling,
-and the only two events relate to TAP enabling and disabling.
+At this writing this mechanism is used only for event handling.
+Three events are available. Two events relate to TAP enabling
+and disabling, one to post reset handling.
The @code{configure} subcommand assigns an event handler,
a TCL string which is evaluated when the event is triggered.
The @code{cget} subcommand returns that handler.
-The two possible values for an event @var{name}
-are @option{tap-disable} and @option{tap-enable}.
+The three possible values for an event @var{name} are @option{tap-disable}, @option{tap-enable} and @option{post-reset}.
So for example, when defining a TAP for a CPU connected to
a JTAG router, you should define TAP event handlers using
... jtag operations using CHIP.jrc
@}
@end example
+
+If you need some post reset action, you can do:
+
+@example
+jtag configure CHIP.cpu -event post-reset @{
+ echo "Reset done"
+ ... jtag operations to be done after reset
+@}
+@end example
@end deffn
@deffn Command {jtag tapdisable} dotted.name
Several commands let you examine the list of targets:
@deffn Command {target count}
+@emph{Note: target numbers are deprecated; don't use them.
+They will be removed shortly after August 2010, including this command.
+Iterate target using @command{target names}, not by counting.}
+
Returns the number of targets, @math{N}.
The highest numbered target is @math{N - 1}.
@example
@end deffn
@deffn Command {target number} number
+@emph{Note: target numbers are deprecated; don't use them.
+They will be removed shortly after August 2010, including this command.}
+
The list of targets is numbered starting at zero.
This command returns the name of the target at index @var{number}.
@example
which OpenOCD needs to know about.
@item @code{-work-area-backup} (@option{0}|@option{1}) -- says
-whether the work area gets backed up; by default, it doesn't.
+whether the work area gets backed up; by default,
+@emph{it is not backed up.}
When possible, use a working_area that doesn't need to be backed up,
since performing a backup slows down operations.
+For example, the beginning of an SRAM block is likely to
+be used by most build systems, but the end is often unused.
@item @code{-work-area-size} @var{size} -- specify/set the work area
all the targets you might use something like this:
@example
-for @{ set x 0 @} @{ $x < [target count] @} @{ incr x @} @{
- set name [target number $x]
+foreach name [target names] @{
set y [$name cget -endian]
set z [$name cget -type]
puts [format "Chip %d is %s, Endian: %s, type: %s" \
@subsection ARM11 specific commands
@cindex ARM11
-@deffn Command {arm11 mcr} p1 p2 p3 p4 p5
-Read coprocessor register
+@deffn Command {arm11 mcr} pX opc1 CRn CRm opc2 value
+Write @var{value} to a coprocessor @var{pX} register
+passing parameters @var{CRn},
+@var{CRm}, opcodes @var{opc1} and @var{opc2},
+and the MCR instruction.
+(The difference beween this and the MCR2 instruction is
+one bit in the encoding, effecively a fifth parameter.)
@end deffn
@deffn Command {arm11 memwrite burst} [value]
If @var{value} is defined, first assigns that.
@end deffn
-@deffn Command {arm11 mrc} p1 p2 p3 p4 p5 value
-Write coprocessor register
+@deffn Command {arm11 mrc} pX opc1 CRn CRm opc2
+Read a coprocessor @var{pX} register passing parameters @var{CRn},
+@var{CRm}, opcodes @var{opc1} and @var{opc2},
+and the MRC instruction.
+(The difference beween this and the MRC2 instruction is
+one bit in the encoding, effecively a fifth parameter.)
+Displays the result.
@end deffn
@deffn Command {arm11 no_increment} [value]
If @var{value} is defined, first assigns that.
@end deffn
+@subsection ARMv7-A specific commands
+@cindex ARMv7-A
+
+@deffn Command {armv7a disassemble} address [count [@option{thumb}]]
+@cindex disassemble
+Disassembles @var{count} instructions starting at @var{address}.
+If @var{count} is not specified, a single instruction is disassembled.
+If @option{thumb} is specified, or the low bit of the address is set,
+Thumb2 (mixed 16/32-bit) instructions are used;
+else ARM (32-bit) instructions are used.
+With a handful of exceptions, ThumbEE instructions are the same as Thumb2;
+ThumbEE disassembly currently has no explicit support.
+(Processors may also support the Jazelle state, but
+those instructions are not currently understood by OpenOCD.)
+@end deffn
+
+
@subsection Cortex-M3 specific commands
@cindex Cortex-M3