diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/openocd.texi | 154 |
1 files changed, 126 insertions, 28 deletions
diff --git a/doc/openocd.texi b/doc/openocd.texi index daa94609..d41f422b 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -66,7 +66,6 @@ Free Documentation License''. * Running:: Running OpenOCD * OpenOCD Project Setup:: OpenOCD Project Setup * Config File Guidelines:: Config File Guidelines -* Translating Configuration Files:: Translating Configuration Files * Daemon Configuration:: Daemon Configuration * Interface - Dongle Configuration:: Interface - Dongle Configuration * Reset Configuration:: Reset Configuration @@ -1186,7 +1185,9 @@ handlers too, if just for developer convenience. Because this is so very board-specific, and chip-specific, no examples are included here. Instead, look at the board config files distributed with OpenOCD. -If you have a boot loader, its source code may also be useful. +If you have a boot loader, its source code will help; so will +configuration files for other JTAG tools +(@pxref{Translating Configuration Files}). @end quotation Some of this code could probably be shared between different boards. @@ -1464,17 +1465,18 @@ Examples: @item pxa270 - again - CS0 flash - it goes in the board file. @end itemize -@node Translating Configuration Files -@chapter Translating Configuration Files +@anchor{Translating Configuration Files} +@section Translating Configuration Files @cindex translation -If you have a configuration file for another hardware debugger(Abatron, -BDI2000, BDI3000, Lauterbach, Segger, MacRaigor, etc.), translating +If you have a configuration file for another hardware debugger +or toolset (Abatron, BDI2000, BDI3000, CCS, +Lauterbach, Segger, Macraigor, etc.), translating it into OpenOCD syntax is often quite straightforward. The most tricky part of creating a configuration script is oftentimes the reset init sequence where e.g. PLLs, DRAM and the like is set up. One trick that you can use when translating is to write small -Tcl proc's to translate the syntax into OpenOCD syntax. This +Tcl procedures to translate the syntax into OpenOCD syntax. This can avoid manual translation errors and make it easier to convert other scripts later on. @@ -1482,23 +1484,22 @@ Example of transforming quirky arguments to a simple search and replace job: @example -# rewrite commands of the form below to arm11 mcr... -# # Lauterbach syntax(?) # -# Data.Set c15:0x042f %long 0x40000015 +# Data.Set c15:0x042f %long 0x40000015 # # OpenOCD syntax when using procedure below. # -# setc15 0x01 0x00050078 -# -# +# setc15 0x01 0x00050078 + proc setc15 @{regs value@} @{ - global TARGETNAME + global TARGETNAME - echo [format "set p15 0x%04x, 0x%08x" $regs $value] + echo [format "set p15 0x%04x, 0x%08x" $regs $value] - arm11 mcr $TARGETNAME 15 [expr ($regs>>12)&0x7] [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] [expr ($regs>>8)&0x7] $value + arm11 mcr $TARGETNAME 15 [expr ($regs>>12)&0x7] \ + [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] \ + [expr ($regs>>8)&0x7] $value @} @end example @@ -1563,6 +1564,17 @@ read/write memory on your target, @command{init} must occur before the memory read/write commands. This includes @command{nand probe}. @end deffn +@deffn {Overridable Procedure} jtag_init +This is invoked at server startup to verify that it can talk +to the scan chain (list of TAPs) which has been configured. + +The default implementation first tries @command{jtag arp_init}, +which uses only a lightweight JTAG reset before examining the +scan chain. +If that fails, it tries again, using a harder reset +from the overridable procedure @command{init_reset}. +@end deffn + @anchor{TCP/IP Ports} @section TCP/IP Ports @cindex TCP port @@ -2192,8 +2204,9 @@ issues (not limited to errata). For example, certain JTAG commands might need to be issued while the system as a whole is in a reset state (SRST active) but the JTAG scan chain is usable (TRST inactive). -(@xref{JTAG Commands}, where the @command{jtag_reset} -command is presented.) +Many systems treat combined assertion of SRST and TRST as a +trigger for a harder reset than SRST alone. +Such custom reset handling is discussed later in this chapter. @end itemize There can also be other issues. @@ -2260,7 +2273,7 @@ Possible values are @option{none} (the default), @option{trst_only}, @quotation Tip If your board provides SRST and/or TRST through the JTAG connector, -you must declare that or else those signals will not be used. +you must declare that so those signals can be used. @end quotation @item @@ -2309,6 +2322,82 @@ powerup and pressing a reset button. @end itemize @end deffn +@section Custom Reset Handling +@cindex events + +OpenOCD has several ways to help support the various reset +mechanisms provided by chip and board vendors. +The commands shown in the previous section give standard parameters. +There are also @emph{event handlers} associated with TAPs or Targets. +Those handlers are Tcl procedures you can provide, which are invoked +at particular points in the reset sequence. + +After configuring those mechanisms, you might still +find your board doesn't start up or reset correctly. +For example, maybe it needs a slightly different sequence +of SRST and/or TRST manipulations, because of quirks that +the @command{reset_config} mechanism doesn't address; +or asserting both might trigger a stronger reset, which +needs special attention. + +Experiment with lower level operations, such as @command{jtag_reset} +and the @command{jtag arp_*} operations shown here, +to find a sequence of operations that works. +@xref{JTAG Commands}. +When you find a working sequence, it can be used to override +@command{jtag_init}, which fires during OpenOCD startup +(@pxref{Configuration Stage}); +or @command{init_reset}, which fires during reset processing. + +You might also want to provide some project-specific reset +schemes. For example, on a multi-target board the standard +@command{reset} command would reset all targets, but you +may need the ability to reset only one target at time and +thus want to avoid using the board-wide SRST signal. + +@deffn {Overridable Procedure} init_reset mode +This is invoked near the beginning of the @command{reset} command, +usually to provide as much of a cold (power-up) reset as practical. +By default it is also invoked from @command{jtag_init} if +the scan chain does not respond to pure JTAG operations. +The @var{mode} parameter is the parameter given to the +low level reset command (@option{halt}, +@option{init}, or @option{run}), @option{setup}, +or potentially some other value. + +The default implementation just invokes @command{jtag arp_init-reset}. +Replacements will normally build on low level JTAG +operations such as @command{jtag_reset}. +Operations here must not address individual TAPs +(or their associated targets) +until the JTAG scan chain has first been verified to work. + +Implementations must have verified the JTAG scan chain before +they return. +This is done by calling @command{jtag arp_init} +(or @command{jtag arp_init-reset}). +@end deffn + +@deffn Command {jtag arp_init} +This validates the scan chain using just the four +standard JTAG signals (TMS, TCK, TDI, TDO). +It starts by issuing a JTAG-only reset. +Then it performs checks to verify that the scan chain configuration +matches the TAPs it can observe. +Those checks include checking IDCODE values for each active TAP, +and verifying the length of their instruction registers using +TAP @code{-ircapture} and @code{-irmask} values. +If these tests all pass, TAP @code{setup} events are +issued to all TAPs with handlers for that event. +@end deffn + +@deffn Command {jtag arp_init-reset} +This uses TRST and SRST to try resetting +everything on the JTAG scan chain +(and anything else connected to SRST). +It then invokes the logic of @command{jtag arp_init}. +@end deffn + @node TAP Declaration @chapter TAP Declaration @@ -2540,9 +2629,6 @@ there seems to be no problems with JTAG scan chain operations. @section Other TAP commands -@c @deffn Command {jtag arp_init-reset} -@c ... more or less "toggle TRST ... and SRST too, what the heck" - @deffn Command {jtag cget} dotted.name @option{-event} name @deffnx Command {jtag configure} dotted.name @option{-event} name string At this writing this TAP attribute @@ -3218,7 +3304,7 @@ The following target events are defined: @end ignore @item @b{reset-assert-pre} @* Issued as part of @command{reset} processing -after SRST and/or TRST were activated and deactivated, +after @command{reset_init} was triggered but before SRST alone is re-asserted on the tap. @item @b{reset-assert-post} @* Issued as part of @command{reset} processing @@ -3248,10 +3334,11 @@ multiplexing, and so on. the target clocks are fully set up.) @item @b{reset-start} @* Issued as part of @command{reset} processing -before either SRST or TRST are activated. +before @command{reset_init} is called. -This is the most robust place to switch to a low JTAG clock rate, if -SRST disables PLLs needed to use a fast clock. +This is the most robust place to use @command{jtag_rclk} +or @command{jtag_khz} to switch to a low JTAG clock rate, +when reset disables PLLs needed to use a fast clock. @ignore @item @b{reset-wait-pos} @* Currently not used @@ -5983,6 +6070,17 @@ The @command{reset_config} command should already have been used to configure how the board and JTAG adapter treat these two signals, and to say if either signal is even present. @xref{Reset Configuration}. + +Note that TRST is specially handled. +It actually signifies JTAG's @sc{reset} state. +So if the board doesn't support the optional TRST signal, +or it doesn't support it along with the specified SRST value, +JTAG reset is triggered with TMS and TCK signals +instead of the TRST signal. +And no matter how that JTAG reset is triggered, once +the scan chain enters @sc{reset} with TRST inactive, +TAP @code{post-reset} events are delivered to all TAPs +with handlers for that event. @end deffn @deffn Command {runtest} @var{num_cycles} @@ -6015,7 +6113,7 @@ The @var{tap_state} names used by OpenOCD in the @command{drscan}, and @command{irscan} commands are: @itemize @bullet -@item @b{RESET} ... should act as if TRST were active +@item @b{RESET} ... acts as if TRST were pulsed @item @b{RUN/IDLE} ... don't assume this always means IDLE @item @b{DRSELECT} @item @b{DRCAPTURE} @@ -6046,7 +6144,7 @@ may not be as expected. @item @sc{run/idle}, @sc{drpause}, and @sc{irpause} are reasonable choices after @command{drscan} or @command{irscan} commands, since they are free of JTAG side effects. -However, @sc{run/idle} may have side effects that appear at other +@item @sc{run/idle} may have side effects that appear at non-JTAG levels, such as advancing the ARM9E-S instruction pipeline. Consult the documentation for the TAP(s) you are working with. @end itemize |