@* 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}
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
Before your @code{reset-init} handler has set up
the PLLs and clocking, you may need to use
a low JTAG clock rate; then you'd increase it later.
-(The rule of thumb for ARM-based processors is 1/8 the CPU clock.)
+For most ARM-based processors the fastest JTAG clock@footnote{A FAQ
+@uref{http://www.arm.com/support/faqdev/4170.html} gives details.}
+is one sixth of the CPU clock; or one eighth for ARM11 cores.
+Consult chip documentation to determine the peak JTAG clock rate,
+which might be less than that.
+
+@quotation Warning
+On most ARMs, JTAG clock detection is coupled to the core clock, so
+software using a @option{wait for interrupt} operation blocks JTAG access.
+Adaptive clocking provides a partial workaround, but a more complete
+solution just avoids using that instruction with JTAG debuggers.
+@end quotation
+
If the board supports adaptive clocking, use the @command{jtag_rclk}
command, in case your board is used with JTAG adapter which
also supports it. Otherwise use @command{jtag_khz}.
@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
speeds. The speed actually used won't be faster
than the speed specified.
-As a rule of thumb, if you specify a clock rate make
-sure the JTAG clock is no more than @math{1/6th CPU-Clock}.
-This is especially true for synthesized cores (ARMxxx-S).
+Chip data sheets generally include a top JTAG clock rate.
+The actual rate is often a function of a CPU core clock,
+and is normally less than that peak rate.
+For example, most ARM cores accept at most one sixth of the CPU clock.
Speed 0 (khz) selects RTCK method.
@xref{FAQ RTCK}.
@end deffn
@defun jtag_rclk fallback_speed_kHz
+@cindex adaptive clocking
@cindex RTCK
This Tcl proc (defined in @file{startup.tcl}) attempts to enable RTCK/RCLK.
If that fails (maybe the interface, board, or target doesn't
@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" \
@deffn {Flash Driver} lpc2000
Most members of the LPC1700 and LPC2000 microcontroller families from NXP
-include internal flash and use Cortex-M3 (LPC1700) or ARM7TDMI (LPC2000) cores.
+include internal flash and use Cortex-M3 (LPC1700) or ARM7TDMI (LPC2000) cores.
+
+@quotation Note
+There are LPC2000 devices which are not supported by the @var{lpc2000}
+driver:
+The LPC2888 is supported by the @var{lpc288x} driver.
+The LPC29xx family is supported by the @var{lpc2900} driver.
+@end quotation
+
The @var{lpc2000} driver defines two mandatory and one optional parameters,
which must appear in the following order:
@end example
@end deffn
+@deffn {Flash Driver} lpc2900
+This driver supports the LPC29xx ARM968E based microcontroller family
+from NXP.
+
+The predefined parameters @var{base}, @var{size}, @var{chip_width} and
+@var{bus_width} of the @code{flash bank} command are ignored. Flash size and
+sector layout are auto-configured by the driver.
+The driver has one additional mandatory parameter: The CPU clock rate
+(in kHz) at the time the flash operations will take place. Most of the time this
+will not be the crystal frequency, but a higher PLL frequency. The
+@code{reset-init} event handler in the board script is usually the place where
+you start the PLL.
+
+The driver rejects flashless devices (currently the LPC2930).
+
+The EEPROM in LPC2900 devices is not mapped directly into the address space.
+It must be handled much more like NAND flash memory, and will therefore be
+handled by a separate @code{lpc2900_eeprom} driver (not yet available).
+
+Sector protection in terms of the LPC2900 is handled transparently. Every time a
+sector needs to be erased or programmed, it is automatically unprotected.
+What is shown as protection status in the @code{flash info} command, is
+actually the LPC2900 @emph{sector security}. This is a mechanism to prevent a
+sector from ever being erased or programmed again. As this is an irreversible
+mechanism, it is handled by a special command (@code{lpc2900 secure_sector}),
+and not by the standard @code{flash protect} command.
+
+Example for a 125 MHz clock frequency:
+@example
+flash bank lpc2900 0 0 0 0 $_TARGETNAME 125000
+@end example
+
+Some @code{lpc2900}-specific commands are defined. In the following command list,
+the @var{bank} parameter is the bank number as obtained by the
+@code{flash banks} command.
+
+@deffn Command {lpc2900 signature} bank
+Calculates a 128-bit hash value, the @emph{signature}, from the whole flash
+content. This is a hardware feature of the flash block, hence the calculation is
+very fast. You may use this to verify the content of a programmed device against
+a known signature.
+Example:
+@example
+lpc2900 signature 0
+ signature: 0x5f40cdc8:0xc64e592e:0x10490f89:0x32a0f317
+@end example
+@end deffn
+
+@deffn Command {lpc2900 read_custom} bank filename
+Reads the 912 bytes of customer information from the flash index sector, and
+saves it to a file in binary format.
+Example:
+@example
+lpc2900 read_custom 0 /path_to/customer_info.bin
+@end example
+@end deffn
+
+The index sector of the flash is a @emph{write-only} sector. It cannot be
+erased! In order to guard against unintentional write access, all following
+commands need to be preceeded by a successful call to the @code{password}
+command:
+
+@deffn Command {lpc2900 password} bank password
+You need to use this command right before each of the following commands:
+@code{lpc2900 write_custom}, @code{lpc2900 secure_sector},
+@code{lpc2900 secure_jtag}.
+
+The password string is fixed to "I_know_what_I_am_doing".
+Example:
+@example
+lpc2900 password 0 I_know_what_I_am_doing
+ Potentially dangerous operation allowed in next command!
+@end example
+@end deffn
+
+@deffn Command {lpc2900 write_custom} bank filename type
+Writes the content of the file into the customer info space of the flash index
+sector. The filetype can be specified with the @var{type} field. Possible values
+for @var{type} are: @var{bin} (binary), @var{ihex} (Intel hex format),
+@var{elf} (ELF binary) or @var{s19} (Motorola S-records). The file must
+contain a single section, and the contained data length must be exactly
+912 bytes.
+@quotation Attention
+This cannot be reverted! Be careful!
+@end quotation
+Example:
+@example
+lpc2900 write_custom 0 /path_to/customer_info.bin bin
+@end example
+@end deffn
+
+@deffn Command {lpc2900 secure_sector} bank first last
+Secures the sector range from @var{first} to @var{last} (including) against
+further program and erase operations. The sector security will be effective
+after the next power cycle.
+@quotation Attention
+This cannot be reverted! Be careful!
+@end quotation
+Secured sectors appear as @emph{protected} in the @code{flash info} command.
+Example:
+@example
+lpc2900 secure_sector 0 1 1
+flash info 0
+ #0 : lpc2900 at 0x20000000, size 0x000c0000, (...)
+ # 0: 0x00000000 (0x2000 8kB) not protected
+ # 1: 0x00002000 (0x2000 8kB) protected
+ # 2: 0x00004000 (0x2000 8kB) not protected
+@end example
+@end deffn
+
+@deffn Command {lpc2900 secure_jtag} bank
+Irreversibly disable the JTAG port. The new JTAG security setting will be
+effective after the next power cycle.
+@quotation Attention
+This cannot be reverted! Be careful!
+@end quotation
+Examples:
+@example
+lpc2900 secure_jtag 0
+@end example
+@end deffn
+@end deffn
+
@deffn {Flash Driver} ocl
@emph{No idea what this is, other than using some arm7/arm9 core.}
or 5 seconds if there is no parameter, for the target to halt
(and enter debug mode).
Using 0 as the @var{ms} parameter prevents OpenOCD from waiting.
+
+@quotation Warning
+On ARM cores, software using the @emph{wait for interrupt} operation
+often blocks the JTAG access needed by a @command{halt} command.
+This is because that operation also puts the core into a low
+power mode by gating the core clock;
+but the core clock is needed to detect JTAG clock transitions.
+
+One partial workaround uses adaptive clocking: when the core is
+interrupted the operation completes, then JTAG clocks are accepted
+at least until the interrupt handler completes.
+However, this workaround is often unusable since the processor, board,
+and JTAG adapter must all support adaptive JTAG clocking.
+Also, it can't work until an interrupt is issued.
+
+A more complete workaround is to not use that operation while you
+work with a JTAG debugger.
+Tasking environments generaly have idle loops where the body is the
+@emph{wait for interrupt} operation.
+(On older cores, it is a coprocessor action;
+newer cores have a @option{wfi} instruction.)
+Such loops can just remove that operation, at the cost of higher
+power consumption (because the CPU is needlessly clocked).
+@end quotation
+
@end deffn
@deffn Command resume [address]
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.)
@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 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
-@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
In most simple terms: Often the JTAG clock must be 1/10 to 1/12 of
the target clock speed. But what that ``magic division'' is varies
-depending on the chips on your board. @b{ARM rule of thumb} Most ARM
-based systems require an 8:1 division. @b{Xilinx rule of thumb} is
-1/12 the clock speed.
+depending on the chips on your board.
+@b{ARM rule of thumb} Most ARM based systems require an 6:1 division;
+ARM11 cores use an 8:1 division.
+@b{Xilinx rule of thumb} is 1/12 the clock speed.
Note: Many FTDI2232C based JTAG dongles are limited to 6MHz.
sleep''. If you are careful - 98% of your problems can be debugged
this way.
+Note that on ARM you may need to avoid using the @emph{wait for interrupt}
+operation in your idle loops even if you don't otherwise change the CPU
+clock rate.
+That operation gates the CPU clock, and thus the JTAG clock; which
+prevents JTAG access. One consequence is not being able to @command{halt}
+cores which are executing that @emph{wait for interrupt} operation.
+
To set the JTAG frequency use the command:
@example
- # Example: 1.234MHz
- jtag_khz 1234
+# Example: 1.234MHz
+jtag_khz 1234
@end example
Code Review / openocd.git / blobdiff