User's Guide: mention ETM on ARM11 comes up too

[fw/openocd] / doc / openocd.texi

diff --git a/doc/openocd.texi b/doc/openocd.texi
index ea300925c002370f31a88f3b41ab75db9c615250..b0aa7c6325d801b3bb488c45d20e1163e5f39865 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -873,6 +873,20 @@ handling issues like:
 
 @itemize @bullet
 
+@item @b{ARM Semihosting}...
+@cindex ARM semihosting
+When linked with a special runtime library provided with many
+toolchains@footnote{See chapter 8 "Semihosting" in
+@uref{http://infocenter.arm.com/help/topic/com.arm.doc.dui0203i/DUI0203I_rvct_developer_guide.pdf,
+ARM DUI 0203I}, the "RealView Compilation Tools Developer Guide".
+The CodeSourcery EABI toolchain also includes a semihosting library.},
+your target code can use I/O facilities on the debug host.  That library
+provides a small set of system calls which are handled by OpenOCD.
+It can let the debugger provide your system console and a file system,
+helping with early debugging or providing a more capable environment
+for sometimes-complex tasks like installing system firmware onto
+NAND or SPI flash.
+
 @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.
@@ -1524,7 +1538,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
 @}
@@ -3624,12 +3638,18 @@ Use it in board specific configuration files, not interactively.
 @comment the REAL name for this command is "ocd_flash_banks"
 @comment less confusing would be:  "flash list" (like "nand list")
 @deffn Command {flash banks}
-Prints a one-line summary of each device declared
-using @command{flash bank}, numbered from zero.
+Prints a one-line summary of each device that was 
+declared using @command{flash bank}, numbered from zero.
 Note that this is the @emph{plural} form;
 the @emph{singular} form is a very different command.
 @end deffn
 
+@deffn Command {flash list}
+Retrieves a list of associative arrays for each device that was 
+declared using @command{flash bank}, numbered from zero.
+This returned list can be manipulated easily from within scripts.
+@end deffn
+
 @deffn Command {flash probe} num
 Identify the flash, or validate the parameters of the configured flash. Operation
 depends on the flash type.
@@ -5365,7 +5385,7 @@ It's unclear how much of a common interface is shared
 with the current XScale trace support, or should be
 shared with eventual Nexus-style trace module support.
 
-At this writing (September 2009) only ARM7 and ARM9 support
+At this writing (November 2009) only ARM7, ARM9, and ARM11 support
 for ETM modules is available.  The code should be able to
 work with some newer cores; but not all of them support
 this original style of JTAG access.
@@ -5609,6 +5629,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.
@@ -5656,6 +5694,18 @@ 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}]
+@cindex ARM semihosting
+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
 
@@ -6020,8 +6070,12 @@ This finishes by listing the current vector catch configuration.
 @cindex tracing
 @cindex libdcc
 @cindex DCC
-OpenOCD can process certain requests from target software.  Currently
-@command{target_request debugmsgs}
+OpenOCD can process certain requests from target software, when
+the target uses appropriate libraries.
+The most powerful mechanism is semihosting, but there is also
+a lighter weight mechanism using only the DCC channel.
+
+Currently @command{target_request debugmsgs}
 is supported only for @option{arm7_9} and @option{cortex_m3} cores.
 These messages are received as part of target polling, so
 you need to have @command{poll on} active to receive them.