[Openocd-development] [patch] doc updates to match help better
This makes the documentation a closer match to help output:
- pathmove somehow was not documented in the User's Guide
- jtag_nsrst_assert_width and jtag_ntrst_assert_width
are new; both needed descriptions.
- Removed two undocumented and fairly useless script mechanisms:
* production/production_info/production_test ... using it,
requires replacing everything; so having it adds no value.
* cpu ... way out of date; hopeless to keep that current
Note that anyone using that production stuff already defines
their own procedures, and can keep using them with no change.
---
committed ...
doc/openocd.texi | 42 --
src/helper/startup.tcl | 57 ---
2 files changed, 40 insertions(+), 59 deletions(-)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -2229,6 +2229,12 @@ needing to cope with both architecture a
@section Commands for Handling Resets
+...@deffn {Command} jtag_nsrst_assert_width milliseconds
+Minimum amount of time (in milliseconds) OpenOCD should wait
+after asserting nSRST (active-low system reset) before
+allowing it to be deasserted.
+...@end deffn
+
@deffn {Command} jtag_nsrst_delay milliseconds
How long (in milliseconds) OpenOCD should wait after deasserting
nSRST (active-low system reset) before starting new JTAG operations.
@@ -2236,6 +2242,12 @@ When a board has a reset button connecte
probably have hardware debouncing, implying you should use this.
@end deffn
+...@deffn {Command} jtag_ntrst_assert_width milliseconds
+Minimum amount of time (in milliseconds) OpenOCD should wait
+after asserting nTRST (active-low JTAG TAP reset) before
+allowing it to be deasserted.
+...@end deffn
+
@deffn {Command} jtag_ntrst_delay milliseconds
How long (in milliseconds) OpenOCD should wait after deasserting
nTRST (active-low JTAG TAP reset) before starting new JTAG operations.
@@ -6083,6 +6095,15 @@ TAP @code{post-reset} events are deliver
with handlers for that event.
@end deffn
+...@deffn Command {pathmove} start_state [next_state ...]
+Start by moving to @var{start_state}, which
+must be one of the @emph{stable} states.
+Then, in a series of single state transitions
+(conforming to the JTAG state machine) shift to
+each @var{next_state} in sequence, one per TCK cycle.
+The final state must also be stable.
+...@end deffn
+
@deffn Command {runtest} @var{num_cycles}
Move to the @sc{run/idle} state, and execute at least
@var{num_cycles} of the JTAG clock (TCK).
@@ -6110,23 +6131,30 @@ Default is enabled.
@cindex TAP state names
The @var{tap_state} names used by OpenOCD in the @command{drscan},
-and @command{irscan} commands are:
+...@command{irscan}, and @command{pathmove} commands are the same
+as those used in SVF boundary scan documents, except that some
+versions of SVF use @sc{idle} instead of @sc{run/idle}.
@itemize @bullet
-...@item @b{RESET} ... acts as if TRST were pulsed
-...@item @b{RUN/IDLE} ... don't assume this always means IDLE
+...@item @b{RESET} ... @emph{stable} (with TMS high);
+acts as if TRST were pulsed
+...@item @b{RUN/IDLE} ... @emph{stable}; don't assume this always means IDLE
@item @b{DRSELECT}
@item @b{DRCAPTURE}
-...@item @b{DRSHIFT} ... TDI/TDO shifting through the data register
+...@item @b{DRSHIFT} ... @emph{stable}; TDI/TDO shifting
+through the data register
@item @b{DREXIT1}
-...@item @b{DRPAUSE} ... data register ready for update or more shifting
+...@item @b{DRPAUSE} ... @emph{stable}; data register ready
+for update or more shifting
@item @b{DREXIT2}
@item @b{DRUPDATE}
@item @b{IRSELECT}
@item @b{IRCAPTURE}
-...@item @b{IRSHIFT} ... TDI/TDO shifting through the instruction register
+...@item @b{IRSHIFT} ... @emph{stable}; TDI/TDO shifting
+through the instruction register
@item @b{IREXIT1}
-...@item @b{IRPAUSE} ... instruction register ready for update or more shifting
+...@item @b{IRPAUSE} ... @emph{stable}; instruction register ready
+for update or more shifting
@item @b{IREXIT2}
@item @b{IRUPDATE}
@end itemize
--- a/src/helper/startup.tcl
+++ b/src/helper/startup.tcl
@@ -291,59 +291,10 @@ proc ocd_process_reset_inner { MODE } {
}
}
-# stubs for targets scripts that do not have production procedure
-proc production_info {} {
- return Imagine an explanation here...
-}
-add_help_text production_info Displays information on production procedure
for target script. Implement this procedure in target script.
-
-proc production {firmwarefile serialnumber} {
- puts Imagine production procedure running successfully. Programmed
$firmwarefile with serial number $serialnumber
-}
-
-add_help_text production serialnumber - Runs production procedure. Throws
exception if procedure failed. Prints progress messages. Implement this
procedure in the target script.
-
-proc production_test {} {
- puts Imagine nifty test procedure having run to completion here.
-}
-add_help_text production_test Runs test procedure.
[Openocd-development] [patch] doc updates
commit 07c86fdf5eaa3439d48e03fc0a4850bc0b7d0a7e
Author: dbrownell dbrown...@b42882b7-edfa-0310-969c-e2dbd0fdcd60
Date: Tue Sep 29 18:20:30 2009 +
Doc updates: add section on target software changes, minor fixes
git-svn-id: svn://svn.berlios.de/openocd/tr...@2774
b42882b7-edfa-0310-969c-e2dbd0fdcd60
diff --git a/doc/openocd.texi b/doc/openocd.texi
index e4609e4..716c452 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -845,6 +845,54 @@ the main bootloader code (which won't fit into that SRAM).
Other helper scripts might be used to write production system images,
involving considerably more than just a three stage bootloader.
+...@section Target Software Changes
+
+Sometimes you may want to make some small changes to the software
+you're developing, to help make JTAG debugging work better.
+For example, in C or assembly language code you might
+use @code{#ifdef JTAG_DEBUG} (or its converse) around code
+handling issues like:
+
+...@itemize @bullet
+
+...@item @b{ARM Wait-For-Interrupt}...
+Many ARM chips synchronize the JTAG clock using the core clock.
+Low power states which stop that core clock thus prevent JTAG access.
+Idle loops in tasking environments often enter those low power states
+via the @code{WFI} instruction (or its coprocessor equivalent, before ARMv7).
+
+You may want to @emph{disable that instruction} in source code,
+or otherwise prevent using that state,
+to ensure you can get JTAG access at any time.
+For example, the OpenOCD @command{halt} command may not
+work for an idle processor otherwise.
+
+...@item @b{Delay after reset}...
+Not all chips have good support for debugger access
+right after reset; many LPC2xxx chips have issues here.
+Similarly, applications that reconfigure pins used for
+JTAG access as they start will also block debugger access.
+
+To work with boards like this, @emph{enable a short delay loop}
+the first thing after reset, before real startup activities.
+For example, one second's delay is usually more than enough
+time for a JTAG debugger to attach, so that
+early code execution can be debugged
+or firmware can be replaced.
+
+...@item @b{Debug Communications Channel (DCC)}...
+Some processors include mechanisms to send messages over JTAG.
+Many ARM cores support these, as do some cores from other vendors.
+(OpenOCD may be able to use this DCC internally, speeding up some
+operations like writing to memory.)
+
+Your application may want to deliver various debugging messages
+over JTAG, by @emph{linking with a small library of code}
+provided with OpenOCD and using the utilities there to send
+various kinds of message.
+...@xref{software Debug Messages and Tracing}.
+
+...@end itemize
@node Config File Guidelines
@chapter Config File Guidelines
@@ -2462,7 +2510,7 @@ If necessary, disables the tap
by sending it a @option{tap-disable} event.
Returns the string 1 if the tap
specified by @var{dotted.name} is enabled,
-and 0 if it is disbabled.
+and 0 if it is disabled.
@end deffn
@deffn Command {jtag tapenable} dotted.name
@@ -2470,13 +2518,13 @@ If necessary, enables the tap
by sending it a @option{tap-enable} event.
Returns the string 1 if the tap
specified by @var{dotted.name} is enabled,
-and 0 if it is disbabled.
+and 0 if it is disabled.
@end deffn
@deffn Command {jtag tapisenabled} dotted.name
Returns the string 1 if the tap
specified by @var{dotted.name} is enabled,
-and 0 if it is disbabled.
+and 0 if it is disabled.
@quotation Note
Humans will find the @command{scan_chain} command more helpful
@@ -5600,7 +5648,7 @@ as used by Linux with CONFIG_DEBUG_ICEDCC;
otherwise the libdcc format is used.
@end deffn
-...@deffn Command {trace history} (@option{clear}|count)
+...@deffn Command {trace history} [...@option{clear}|count]
With no parameter, displays all the trace points that have triggered
in the order they triggered.
With the parameter @option{clear}, erases all current trace history records.
@@ -5608,7 +5656,7 @@ With a @var{count} parameter, allocates space for that
many
history records.
@end deffn
-...@deffn Command {trace point} (@option{clear}|identifier)
+...@deffn Command {trace point} [...@option{clear}|identifier]
With no parameter, displays all trace point identifiers and how many times
they have been triggered.
With the parameter @option{clear}, erases all current trace point counters.
___
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
