diff options
| -rw-r--r-- | doc/openocd.texi | 103 |
1 files changed, 87 insertions, 16 deletions
diff --git a/doc/openocd.texi b/doc/openocd.texi index b944912c..ab15bedb 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -486,16 +486,28 @@ bash$ openocd --help --pipe | -p use pipes when talking to gdb @end verbatim -By default OpenOCD reads the file configuration file ``openocd.cfg'' +By default OpenOCD reads the file configuration file @file{openocd.cfg} in the current directory. To specify a different (or multiple) configuration file, you can use the ``-f'' option. For example: @example - openocd -f config1.cfg -f config2.cfg -f config3.cfg +openocd -f config1.cfg -f config2.cfg -f config3.cfg @end example -Once started, OpenOCD runs as a daemon, waiting for connections from -clients (Telnet, GDB, Other). +OpenOCD starts by processing the configuration commands provided +on the command line or in @file{openocd.cfg}. +@xref{Configuration Stage}. +At the end of the configuration stage it verifies the JTAG scan +chain defined using those commands; your configuration should +ensure that this always succeeds. +Normally, OpenOCD then starts running as a daemon. +Alternatively, commands may be used to terminate the configuration +stage early, perform work (such as updating some flash memory), +and then shut down without acting as a daemon. + +Once OpenOCD starts running as a daemon, it waits for connections from +clients (Telnet, GDB, Other) and processes the commands issued through +those channels. If you are having problems, you can enable internal debug messages via the ``-d'' option. @@ -1061,8 +1073,16 @@ access uses the CPU or to prevent conflicting CPU access. @subsection JTAG Clock Rate 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 PLLs and clocking, you may need to run with +a low JTAG clock rate. +@xref{JTAG Speed}. +Then you'd increase that rate after your handler has +made it possible to use the faster JTAG clock. +When the initial low speed is board-specific, for example +because it depends on a board-specific oscillator speed, then +you should probably set it up in the board config file; +if it's target-specific, it belongs in the target config file. + 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. @@ -1252,6 +1272,24 @@ after the target's TAP has been reset, providing a @code{reset-deassert-post} event handler that writes a chip register to report that JTAG debugging is being done. +JTAG clocking constraints often change during reset, and in +some cases target config files (rather than board config files) +are the right places to handle some of those issues. +For example, immediately after reset most chips run using a +slower clock than they will use later. +That means that after reset (and potentially, as OpenOCD +first starts up) they must use a slower JTAG clock rate +than they will use later. +@xref{JTAG Speed}. + +@quotation Important +When you are debugging code that runs right after chip +reset, getting these issues right is critical. +In particular, if you see intermittent failures when +OpenOCD verifies the scan chain after reset, +look at how you are setting up JTAG clocking. +@end quotation + @subsection ARM Core Specific Hacks If the chip has a DCC, enable it. If the chip is an ARM9 with some @@ -1298,6 +1336,7 @@ The commands here are commonly found in the openocd.cfg file and are used to specify what TCP/IP ports are used, and how GDB should be supported. +@anchor{Configuration Stage} @section Configuration Stage @cindex configuration stage @cindex config command @@ -1318,6 +1357,18 @@ may access or activate TAPs. After it leaves this stage, configuration commands may no longer be issued. +The first thing OpenOCD does after leaving the configuration +stage is to verify that it can talk to the scan chain +(list of TAPs) which has been configured. +It will warn if it doesn't find TAPs it expects to find, +or finds TAPs that aren't supposed to be there. +You should see no errors at this point. +If you see errors, resolve them by correcting the +commands you used to configure the server. +Common errors include using an initial JTAG speed that's too +fast, and not providing the right IDCODE values for the TAPs +on the scan chain. + @deffn {Config Command} init This command terminates the configuration stage and enters the normal command mode. This can be useful to add commands to @@ -1787,9 +1838,28 @@ Both the "slow" and "fast" clock rates are functions of the oscillators used, the chip, the board design, and sometimes power management software that may be active. -The speed used during reset can be adjusted using pre_reset -and post_reset event handlers. +The speed used during reset, and the scan chain verification which +follows reset, can be adjusted using a @code{reset-start} +target event handler. +It can then be reconfigured to a faster speed by a +@code{reset-init} target event handler after it reprograms those +CPU clocks, or manually (if something else, such as a boot loader, +sets up those clocks). @xref{Target Events}. +When the initial low JTAG speed is a chip characteristic, perhaps +because of a required oscillator speed, provide such a handler +in the target config file. +When that speed is a function of a board-specific characteristic +such as which speed oscillator is used, it belongs in the board +config file instead. +In both cases it's safest to also set the initial JTAG clock rate +to that same slow speed, so that OpenOCD never starts up using a +clock speed that's faster than the scan chain can support. + +@example +jtag_rclk 3000 +$_TARGET.cpu configure -event reset-start @{ jtag_rclk 3000 @} +@end example If your system supports adaptive clocking (RTCK), configuring JTAG to use that is probably the most robust approach. @@ -2892,20 +2962,16 @@ The following target events are defined: @item @b{reset-assert-pre} @* Issued as part of @command{reset} processing after SRST and/or TRST were activated and deactivated, -but before reset is asserted on the tap. +but before SRST alone is re-asserted on the tap. @item @b{reset-assert-post} @* Issued as part of @command{reset} processing -when reset is asserted on the tap. +when SRST is asserted on the tap. @item @b{reset-deassert-pre} @* Issued as part of @command{reset} processing -when reset is about to be released on the tap. - -For some chips, this may be a good place to make sure -the JTAG clock is slow enough to work before the PLL -has been set up to allow faster JTAG speeds. +when SRST is about to be released on the tap. @item @b{reset-deassert-post} @* Issued as part of @command{reset} processing -when reset has been released on the tap. +when SRST has been released on the tap. @item @b{reset-end} @* Issued as the final step in @command{reset} processing. @ignore @@ -2921,9 +2987,14 @@ This event fires after @emph{reset-deassert-post}. This is where you would configure PLLs and clocking, set up DRAM so you can download programs that don't fit in on-chip SRAM, set up pin multiplexing, and so on. +(You may be able to switch to a fast JTAG clock rate here, after +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. + +This is the most robust place to switch to a low JTAG clock rate, if +SRST disables PLLs needed to use a fast clock. @ignore @item @b{reset-wait-pos} @* Currently not used |