X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=4d13f073cfa280cd5ddf40a38c58f8de452fecd4;hp=e94c9d02bfef6afe80f226273deb1f967bf98529;hb=ed59dfc80aa6fc48a0894c8e46cee675f38ac949;hpb=0583cb0a0d222787c4048f9362292c5db9d969b0

diff --git a/doc/openocd.texi b/doc/openocd.texi
index e94c9d02bf..4d13f073cf 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -1411,6 +1411,20 @@ chip can be tweaked by the board.
 Some chips have specific ways the TRST and SRST signals are
 managed. In the unusual case that these are @emph{chip specific}
 and can never be changed by board wiring, they could go here.
+For example, some chips can't support JTAG debugging without
+both signals.
+
+Provide a @code{reset-assert} event handler if you can.
+Such a handler uses JTAG operations to reset the target,
+letting this target config be used in systems which don't
+provide the optional SRST signal, or on systems where you
+don't want to reset all targets at once.
+Such a handler might write to chip registers to force a reset,
+use a JRC to do that (preferable -- the target may be wedged!),
+or force a watchdog timer to trigger.
+(For Cortex-M3 targets, this is not necessary.  The target
+driver knows how to use trigger an NVIC reset when SRST is
+not available.)
 
 Some chips need special attention during reset handling if
 they're going to be used with JTAG.
@@ -1418,6 +1432,8 @@ An example might be needing to send some commands right
 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.
+Another would be reconfiguring the watchdog so that it stops
+counting while the core is halted in the debugger.
 
 JTAG clocking constraints often change during reset, and in
 some cases target config files (rather than board config files)
@@ -1508,7 +1524,7 @@ proc setc15 @{regs value@} @{
 
     echo [format "set p15 0x%04x, 0x%08x" $regs $value]
 
-    mcr 15 [expr ($regs>>12)&0x7] \
+    arm mcr 15 [expr ($regs>>12)&0x7] \
         [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] \
         [expr ($regs>>8)&0x7] $value
 @}
@@ -2401,6 +2417,12 @@ 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.
 
+@emph{When SRST is not an option} you must set
+up a @code{reset-assert} event handler for your target.
+For example, some JTAG adapters don't include the SRST signal;
+and some boards have multiple targets, and you won't always
+want to reset everything at once.
+
 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
@@ -3095,6 +3117,7 @@ There are several variants defined:
 @code{pxa27x} ... instruction register length is 7 bits
 @item @code{pxa250}, @code{pxa255},
 @code{pxa26x} ... instruction register length is 5 bits
+@item @code{pxa3xx} ... instruction register length is 11 bits
 @end itemize
 @end itemize
 @end deffn
@@ -3390,9 +3413,14 @@ For example:
 @itemize @bullet
 @item What should happen when GDB connects? Should your target reset?
 @item When GDB tries to flash the target, do you need to enable the flash via a special command?
+@item Is using SRST appropriate (and possible) on your system?
+Or instead of that, do you need to issue JTAG commands to trigger reset?
+SRST usually resets everything on the scan chain, which can be inappropriate.
 @item During reset, do you need to write to certain memory locations
 to set up system clocks or
 to reconfigure the SDRAM?
+How about configuring the watchdog timer, or other peripherals,
+to stop running while you hold the core stopped for debugging?
 @end itemize
 
 All of the above items can be addressed by target event handlers.
@@ -3457,16 +3485,28 @@ The following target events are defined:
 @item @b{reset-assert-pre}
 @* Issued as part of @command{reset} processing
 after @command{reset_init} was triggered
-but before SRST alone is re-asserted on the tap.
+but before either SRST alone is re-asserted on the scan chain,
+or @code{reset-assert} is triggered.
+@item @b{reset-assert}
+@* Issued as part of @command{reset} processing
+after @command{reset-assert-pre} was triggered.
+When such a handler is present, cores which support this event will use
+it instead of asserting SRST.
+This support is essential for debugging with JTAG interfaces which
+don't include an SRST line (JTAG doesn't require SRST), and for
+selective reset on scan chains that have multiple targets.
 @item @b{reset-assert-post}
 @* Issued as part of @command{reset} processing
-when SRST is asserted on the tap.
+after @code{reset-assert} has been triggered.
+or the target asserted SRST on the entire scan chain.
 @item @b{reset-deassert-pre}
 @* Issued as part of @command{reset} processing
-when SRST is about to be released on the tap.
+after @code{reset-assert-post} has been triggered.
 @item @b{reset-deassert-post}
 @* Issued as part of @command{reset} processing
-when SRST has been released on the tap.
+after @code{reset-deassert-pre} has been triggered
+and (if the target is using it) after SRST has been
+released on the scan chain.
 @item @b{reset-end}
 @* Issued as the final step in @command{reset} processing.
 @ignore
@@ -5569,6 +5609,24 @@ with a handful of exceptions.
 ThumbEE disassembly currently has no explicit support.
 @end deffn
 
+@deffn Command {arm mcr} pX op1 CRn CRm op2 value
+Write @var{value} to a coprocessor @var{pX} register
+passing parameters @var{CRn},
+@var{CRm}, opcodes @var{opc1} and @var{opc2},
+and using the MCR instruction.
+(Parameter sequence matches the ARM instruction, but omits
+an ARM register.)
+@end deffn
+
+@deffn Command {arm mrc} pX coproc op1 CRn CRm op2 
+Read a coprocessor @var{pX} register passing parameters @var{CRn},
+@var{CRm}, opcodes @var{opc1} and @var{opc2},
+and the MRC instruction.
+Returns the result so it can be manipulated by Jim scripts.
+(Parameter sequence matches the ARM instruction, but omits
+an ARM register.)
+@end deffn
+
 @deffn Command {arm reg}
 Display a table of all banked core registers, fetching the current value from every
 core mode if necessary.
@@ -5616,6 +5674,17 @@ cables (FT2232), but might be unsafe if used with targets running at very low
 speeds, like the 32kHz startup clock of an AT91RM9200.
 @end deffn
 
+@deffn Command {arm7_9 semihosting} [@option{enable}|@option{disable}]
+Display status of semihosting, after optionally changing that status.
+
+Semihosting allows for code executing on an ARM target to use the
+I/O facilities on the host computer i.e. the system where OpenOCD
+is running. The target application must be linked against a library
+implementing the ARM semihosting convention that forwards operation
+requests by using a special SVC instruction that is trapped at the
+Supervisor Call vector by OpenOCD.
+@end deffn
+
 @subsection ARM720T specific commands
 @cindex ARM720T