Update the User's Guide to cover the scan chain verification step

done on exit from the config stage, how JTAG clocking issues can
trigger errors there, and how to avoid such problems.


git-svn-id: svn://svn.berlios.de/openocd/trunk@2737 b42882b7-edfa-0310-969c-e2dbd0fdcd60
__archive__
dbrownell 2009-09-20 21:17:08 +00:00
parent 0c4b119d3f
commit 24df719b09
1 changed files with 87 additions and 16 deletions

View File

@ -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