@b{Flash Programing:} Flash writing is supported for external CFI
compatible NOR flashes (Intel and AMD/Spansion command set) and several
-internal flashes (LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and
+internal flashes (LPC1700, LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and
STM32x). Preliminary support for various NAND flash controllers
(LPC3180, Orion, S3C24xx, more) controller is included.
@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
@item @b{jtagkey}
@* See: @url{http://www.amontec.com/jtagkey.shtml}
+@item @b{jtagkey2}
+@* See: @url{http://www.amontec.com/jtagkey2.shtml}
@item @b{oocdlink}
@* See: @url{http://www.oocdlink.com} By Joern Kaipf
@item @b{signalyzer}
early boot code, which performs some of the same actions
that the @code{reset-init} event handler does.
Likewise, the @command{arm9tdmi vector_catch} command (or
-its @command{xscale vector_catch} sibling) can be a timesaver
+@cindex vector_catch
+its siblings @command{xscale vector_catch}
+and @command{cortex_m3 vector_catch}) can be a timesaver
during some debug sessions, but don't make everyone use that either.
Keep those kinds of debugging aids in your user config file,
along with messaging and tracing setup.
@item @b{flyswatter} Tin Can Tools Flyswatter
@item @b{icebear} ICEbear JTAG adapter from Section 5
@item @b{jtagkey} Amontec JTAGkey and JTAGkey-Tiny (and compatibles)
+@item @b{jtagkey2} Amontec JTAGkey2 (and compatibles)
@item @b{m5960} American Microsystems M5960
@item @b{olimex-jtag} Olimex ARM-USB-OCD and ARM-USB-Tiny
@item @b{oocdlink} OOCDLink
@itemize @bullet
@item @code{-ircapture} @var{NUMBER}
-@*The IDCODE capture command, such as 0x01.
+@*The bit pattern loaded by the TAP into the JTAG shift register
+on entry to the @sc{ircapture} state, such as 0x01.
+JTAG requires the two LSBs of this value to be 01.
+The value is used to verify that instruction scans work correctly.
@item @code{-irlen} @var{NUMBER}
@*The length in bits of the
instruction register, such as 4 or 5 bits.
@subsection Internal Flash (Microcontrollers)
@deffn {Flash Driver} aduc702x
-The ADUC702x analog microcontrollers from ST Micro
+The ADUC702x analog microcontrollers from Analog Devices
include internal flash and use ARM7TDMI cores.
The aduc702x flash driver works with models ADUC7019 through ADUC7028.
The setup command only requires the @var{target} argument
@end deffn
@deffn {Flash Driver} lpc2000
-Most members of the LPC2000 microcontroller family from NXP
-include internal flash and use ARM7TDMI cores.
+Most members of the LPC1700 and LPC2000 microcontroller families from NXP
+include internal flash and use Cortex-M3 (LPC1700) or ARM7TDMI (LPC2000) cores.
The @var{lpc2000} driver defines two mandatory and one optional parameters,
which must appear in the following order:
@itemize
@item @var{variant} ... required, may be
@var{lpc2000_v1} (older LPC21xx and LPC22xx)
-or @var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx)
+@var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx)
+or @var{lpc1700} (LPC175x and LPC176x)
@item @var{clock_kHz} ... the frequency, in kiloHertz,
at which the core is running
@item @var{calc_checksum} ... optional (but you probably want to provide this!),
that is not currently supported in OpenOCD.)
@end deffn
-@deffn Command {armv4_5 disassemble} address count [thumb]
+@deffn Command {armv4_5 disassemble} address [count [@option{thumb}]]
@cindex disassemble
Disassembles @var{count} instructions starting at @var{address}.
-If @option{thumb} is specified, Thumb (16-bit) instructions are used;
+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,
+Thumb (16-bit) instructions are used;
else ARM (32-bit) instructions are used.
(Processors may also support the Jazelle state, but
those instructions are not currently understood by OpenOCD.)
Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode,
instead of breakpoints. This should be
safe for all but ARM7TDMI--S cores (like Philips LPC).
+This feature is enabled by default on most ARM9 cores,
+including ARM9TDMI, ARM920T, and ARM926EJ-S.
@end deffn
@deffn Command {arm7_9 dcc_downloads} (@option{enable}|@option{disable})
@anchor{arm9tdmi vector_catch}
@deffn Command {arm9tdmi vector_catch} [@option{all}|@option{none}|list]
+@cindex vector_catch
Vector Catch hardware provides a sort of dedicated breakpoint
for hardware events such as reset, interrupt, and abort.
You can use this to conserve normal breakpoint resources,
@subsection XScale specific commands
@cindex XScale
+Some notes about the debug implementation on the XScale CPUs:
+
+The XScale CPU provides a special debug-only mini-instruction cache
+(mini-IC) in which exception vectors and target-resident debug handler
+code are placed by OpenOCD. In order to get access to the CPU, OpenOCD
+must point vector 0 (the reset vector) to the entry of the debug
+handler. However, this means that the complete first cacheline in the
+mini-IC is marked valid, which makes the CPU fetch all exception
+handlers from the mini-IC, ignoring the code in RAM.
+
+OpenOCD currently does not sync the mini-IC entries with the RAM
+contents (which would fail anyway while the target is running), so
+the user must provide appropriate values using the @code{xscale
+vector_table} command.
+
+It is recommended to place a pc-relative indirect branch in the vector
+table, and put the branch destination somewhere in memory. Doing so
+makes sure the code in the vector table stays constant regardless of
+code layout in memory:
+@example
+_vectors:
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ .org 0x100
+ .long real_reset_vector
+ .long real_ui_handler
+ .long real_swi_handler
+ .long real_pf_abort
+ .long real_data_abort
+ .long 0 /* unused */
+ .long real_irq_handler
+ .long real_fiq_handler
+@end example
+
+The debug handler must be placed somewhere in the address space using
+the @code{xscale debug_handler} command. The allowed locations for the
+debug handler are either (0x800 - 0x1fef800) or (0xfe000800 -
+0xfffff800). The default value is 0xfe000800.
+
+
These commands are available to XScale based CPUs,
which are implementations of the ARMv5TE architecture.
@anchor{xscale vector_catch}
@deffn Command {xscale vector_catch} [mask]
+@cindex vector_catch
Display a bitmask showing the hardware vectors to catch.
If the optional parameter is provided, first set the bitmask to that value.
+
+The mask bits correspond with bit 16..23 in the DCSR:
+@example
+0x01 Trap Reset
+0x02 Trap Undefined Instructions
+0x04 Trap Software Interrupt
+0x08 Trap Prefetch Abort
+0x10 Trap Data Abort
+0x20 reserved
+0x40 Trap IRQ
+0x80 Trap FIQ
+@end example
+@end deffn
+
+@anchor{xscale vector_table}
+@deffn Command {xscale vector_table} [<low|high> <index> <value>]
+@cindex vector_table
+
+Set an entry in the mini-IC vector table. There are two tables: one for
+low vectors (at 0x00000000), and one for high vectors (0xFFFF0000), each
+holding the 8 exception vectors. @var{index} can be 1-7, because vector 0
+points to the debug handler entry and can not be overwritten.
+@var{value} holds the 32-bit opcode that is placed in the mini-IC.
+
+Without arguments, the current settings are displayed.
+
@end deffn
@section ARMv6 Architecture
@subsection Cortex-M3 specific commands
@cindex Cortex-M3
+@deffn Command {cortex_m3 disassemble} address [count]
+@cindex disassemble
+Disassembles @var{count} Thumb2 instructions starting at @var{address}.
+If @var{count} is not specified, a single instruction is disassembled.
+@end deffn
+
@deffn Command {cortex_m3 maskisr} (@option{on}|@option{off})
Control masking (disabling) interrupts during target step/resume.
@end deffn
+@deffn Command {cortex_m3 vector_catch} [@option{all}|@option{none}|list]
+@cindex vector_catch
+Vector Catch hardware provides dedicated breakpoints
+for certain hardware events.
+
+Parameters request interception of
+@option{all} of these hardware event vectors,
+@option{none} of them,
+or one or more of the following:
+@option{hard_err} for a HardFault exception;
+@option{mm_err} for a MemManage exception;
+@option{bus_err} for a BusFault exception;
+@option{irq_err},
+@option{state_err},
+@option{chk_err}, or
+@option{nocp_err} for various UsageFault exceptions; or
+@option{reset}.
+If NVIC setup code does not enable them,
+MemManage, BusFault, and UsageFault exceptions
+are mapped to HardFault.
+UsageFault checks for
+divide-by-zero and unaligned access
+must also be explicitly enabled.
+
+This finishes by listing the current vector catch configuration.
+@end deffn
+
@anchor{Software Debug Messages and Tracing}
@section Software Debug Messages and Tracing
@cindex Linux-ARM DCC support
time. One can set a break point or halt the system in the deep power
down code, slow step out until the system speeds up.
+Note that adaptive clocking may also need to work at the board level,
+when a board-level scan chain has multiple chips.
+Parallel clock voting schemes are good way to implement this,
+both within and between chips, and can easily be implemented
+with a CPLD.
+It's not difficult to have logic fan a module's input TCK signal out
+to each TAP in the scan chain, and then wait until each TAP's RTCK comes
+back with the right polarity before changing the output RTCK signal.
+Texas Instruments makes some clock voting logic available
+for free (with no support) in VHDL form; see
+@url{http://tiexpressdsp.com/index.php/Adaptive_Clocking}
+
@b{Solution #2 - Always works - but may be slower}
Often this is a perfectly acceptable solution.