X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=389b2a9d1b39371ba580ce9e3224eaeb68f6efdc;hb=a17eb667a348784e67ddbdb4fb50bcc91e5f575b;hp=7c3b70e85928a1d6e49d7250798e7f05405a993e;hpb=732df6fea0fed36b2f90e0b20f1031e230eccb6f;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 7c3b70e859..389b2a9d1b 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -130,7 +130,7 @@ debugged via the GDB protocol. @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. @@ -281,6 +281,8 @@ chips are starting to become available in JTAG adapters. @* 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} @@ -731,21 +733,34 @@ You may find a board configuration that's a good example to follow. 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 -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. (@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 @@ -1583,6 +1598,7 @@ or in a passthrough mode (neither SRST nor TRST) @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 @@ -2273,14 +2289,14 @@ does include a kind of JTAG router functionality. @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 @@ -2296,6 +2312,15 @@ jtag configure CHIP.cpu -event tap-disable @{ ... 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 @@ -2360,6 +2385,10 @@ are examples; and there are many more. 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 @@ -2385,6 +2414,9 @@ foreach t [target names] @{ @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 @@ -2602,9 +2634,12 @@ same event name assigns only one handler. 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 @@ -2706,8 +2741,7 @@ For example, if you wanted to summarize information about 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" \ @@ -3274,15 +3308,16 @@ and executed. @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!), @@ -4606,10 +4641,12 @@ The target may later be resumed in the currently set core_state. 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.) @@ -4737,6 +4774,7 @@ Such cores include the ARM920T, ARM926EJ-S, and ARM966. @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, @@ -4870,6 +4908,52 @@ else if a @var{value} is provided, that value is written to that register. @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. @@ -4926,8 +5010,35 @@ The image @var{type} may be one of @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} [ ] +@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 @@ -4936,8 +5047,13 @@ If the optional parameter is provided, first set the bitmask to that value. @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] @@ -4952,8 +5068,13 @@ which is enabled by default. 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] @@ -5003,18 +5124,63 @@ Displays the number of extra tck for mem-ap memory bus access [0-255]. 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 -@deffn Command {cortex_m3 disassemble} address count +@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