X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=0eb40b13cece40b7192c2d081fbdb5c4201e275e;hp=3f5882ceebbc66b6b142be0b46d0cdca685fc1cc;hb=c8267930c7cff5685b33cd0174deb75a46dbb09b;hpb=b3bf1d12b2fdfba1c1cbee3e1afbfbb27cbd1a26

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 3f5882ceeb..0eb40b13ce 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -223,7 +223,7 @@ communication between developers:
 @uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
 
 Discuss and submit patches to this list.
-The @file{PATCHES} file contains basic information about how
+The @file{PATCHES.txt} file contains basic information about how
 to prepare patches.
 
 
@@ -1721,17 +1721,17 @@ In such cases, just specify the relevant port number as zero.
 If you disable all access through TCP/IP, you will need to
 use the command line @option{-pipe} option.
 
-@deffn {Command} gdb_port (number)
+@deffn {Command} gdb_port [number]
 @cindex GDB server
 Specify or query the first port used for incoming GDB connections.
 The GDB port for the
 first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
 When not specified during the configuration stage,
 the port @var{number} defaults to 3333.
-When specified as zero, this port is not activated.
+When specified as zero, GDB remote access ports are not activated.
 @end deffn
 
-@deffn {Command} tcl_port (number)
+@deffn {Command} tcl_port [number]
 Specify or query the port used for a simplified RPC
 connection that can be used by clients to issue TCL commands and get the
 output from the Tcl engine.
@@ -1741,7 +1741,7 @@ the port @var{number} defaults to 6666.
 When specified as zero, this port is not activated.
 @end deffn
 
-@deffn {Command} telnet_port (number)
+@deffn {Command} telnet_port [number]
 Specify or query the
 port on which to listen for incoming telnet connections.
 This port is intended for interaction with one human through TCL commands.
@@ -2073,9 +2073,11 @@ $_TARGETNAME configure -event reset-assert \
 Gateworks GW16012 JTAG programmer.
 This has one driver-specific command:
 
-@deffn {Config Command} {parport_port} number
-Specifies either the address of the I/O port (default: 0x378 for LPT1) or
-the number of the @file{/dev/parport} device.
+@deffn {Config Command} {parport_port} [port_number]
+Display either the address of the I/O port
+(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
+If a parameter is provided, first switch to use that port.
+This is a write-once setting.
 @end deffn
 @end deffn
 
@@ -2094,7 +2096,8 @@ These interfaces have several commands, used to configure the driver
 before initializing the JTAG scan chain:
 
 @deffn {Config Command} {parport_cable} name
-The layout of the parallel port cable used to connect to the target.
+Set the layout of the parallel port cable used to connect to the target.
+This is a write-once setting.
 Currently valid cable @var{name} values include:
 
 @itemize @minus
@@ -2122,9 +2125,11 @@ several clones, such as the Olimex ARM-JTAG
 @end itemize
 @end deffn
 
-@deffn {Config Command} {parport_port} number
-Either the address of the I/O port (default: 0x378 for LPT1) or the number of
-the @file{/dev/parport} device
+@deffn {Config Command} {parport_port} [port_number]
+Display either the address of the I/O port
+(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
+If a parameter is provided, first switch to use that port.
+This is a write-once setting.
 
 When using PPDEV to access the parallel port, use the number of the parallel port:
 @option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
@@ -2167,25 +2172,26 @@ match for the jtag_khz rate you specified; be conservative.
 @end quotation
 @end deffn
 
-@deffn {Config Command} {parport_write_on_exit} (on|off)
+@deffn {Config Command} {parport_write_on_exit} (@option{on}|@option{off})
 This will configure the parallel driver to write a known
-cable-specific value to the parallel interface on exiting OpenOCD
+cable-specific value to the parallel interface on exiting OpenOCD.
 @end deffn
 
 For example, the interface configuration file for a
-classic ``Wiggler'' cable might look something like this:
+classic ``Wiggler'' cable on LPT2 might look something like this:
 
 @example
 interface parport
-parport_port 0xc8b8
+parport_port 0x278
 parport_cable wiggler
 @end example
 @end deffn
 
 @deffn {Interface Driver} {presto}
 ASIX PRESTO USB JTAG programmer.
-@c command:	presto_serial str
-@c     sets serial number
+@deffn {Config Command} {presto_serial} serial_string
+Configures the USB serial number of the Presto device to use.
+@end deffn
 @end deffn
 
 @deffn {Interface Driver} {rlink}
@@ -2501,7 +2507,7 @@ signal implementations.
 The default behaviour if no option given is @option{separate},
 indicating everything behaves normally.
 @option{srst_pulls_trst} states that the
-test logic is reset together with the reset of the system (e.g. Philips
+test logic is reset together with the reset of the system (e.g. NXP
 LPC2000, "broken" board layout), @option{trst_pulls_srst} says that
 the system is reset together with the test logic (only hypothetical, I
 haven't seen hardware with such a bug, and can be worked around).
@@ -3737,7 +3743,7 @@ see the driver-specific documentation.
 
 @itemize @bullet
 @item @var{name} ... may be used to reference the flash bank
-in other flash commands.
+in other flash commands.  A number is also available.
 @item @var{driver} ... identifies the controller driver
 associated with the flash bank being declared.
 This is usually @code{cfi} for external flash, or else
@@ -4103,7 +4109,7 @@ plane (of up to 256KB), and it will be used automatically when you issue
 @command{flash erase_sector} or @command{flash erase_address} commands.
 
 @deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
-Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
+Set or clear a ``General Purpose Non-Volatile Memory'' (GPNVM)
 bit for the processor.   Each processor has a number of such bits,
 used for controlling features such as brownout detection (so they
 are not truly general purpose).
@@ -4673,7 +4679,7 @@ NAND chips must be declared in configuration scripts,
 plus some additional configuration that's done after
 OpenOCD has initialized.
 
-@deffn {Config Command} {nand device} name controller target [configparams...]
+@deffn {Config Command} {nand device} name driver target [configparams...]
 Declares a NAND device, which can be read and written to
 after it has been configured through @command{nand probe}.
 In OpenOCD, devices are single chips; this is unlike some
@@ -4688,8 +4694,8 @@ configuration files, not interactively.
 
 @itemize @bullet
 @item @var{name} ... may be used to reference the NAND bank
-in other commands.
-@item @var{controller} ... identifies the controller driver
+in most other NAND commands.  A number is also available.
+@item @var{driver} ... identifies the NAND controller driver
 associated with the NAND device being declared.
 @xref{NAND Driver List}.
 @item @var{target} ... names the target used when issuing
@@ -5867,26 +5873,36 @@ ARM9TDMI, ARM920T or ARM926EJ-S.
 They are available in addition to the ARM commands,
 and any other core-specific commands that may be available.
 
-@deffn Command {arm7_9 dbgrq} (@option{enable}|@option{disable})
-Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode,
-instead of breakpoints.  This should be
-safe for all but ARM7TDMI--S cores (like Philips LPC).
+@deffn Command {arm7_9 dbgrq} [@option{enable}|@option{disable}]
+Displays the value of the flag controlling use of the
+the EmbeddedIce DBGRQ signal to force entry into debug mode,
+instead of breakpoints.
+If a boolean parameter is provided, first assigns that flag.
+
+This should be
+safe for all but ARM7TDMI-S cores (like NXP LPC).
 This feature is enabled by default on most ARM9 cores,
 including ARM9TDMI, ARM920T, and ARM926EJ-S.
 @end deffn
 
-@deffn Command {arm7_9 dcc_downloads} (@option{enable}|@option{disable})
+@deffn Command {arm7_9 dcc_downloads} [@option{enable}|@option{disable}]
 @cindex DCC
-Control the use of the debug communications channel (DCC) to write larger (>128 byte)
-amounts of memory. DCC downloads offer a huge speed increase, but might be
+Displays the value of the flag controlling use of the debug communications
+channel (DCC) to write larger (>128 byte) amounts of memory.
+If a boolean parameter is provided, first assigns that flag.
+
+DCC downloads offer a huge speed increase, but might be
 unsafe, especially with targets running at very low speeds. This command was introduced
 with OpenOCD rev. 60, and requires a few bytes of working area.
 @end deffn
 
 @anchor{arm7_9 fast_memory_access}
-@deffn Command {arm7_9 fast_memory_access} (@option{enable}|@option{disable})
-Enable or disable memory writes and reads that don't check completion of
-the operation. This provides a huge speed increase, especially with USB JTAG
+@deffn Command {arm7_9 fast_memory_access} [@option{enable}|@option{disable}]
+Displays the value of the flag controlling use of memory writes and reads
+that don't check completion of the operation.
+If a boolean parameter is provided, first assigns that flag.
+
+This provides a huge speed increase, especially with USB JTAG
 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
@@ -5911,9 +5927,13 @@ which are implementations of the ARMv4T architecture
 based on the ARM7TDMI-S integer core.
 They are available in addition to the ARM and ARM7/ARM9 commands.
 
-@deffn Command {arm720t cp15} regnum [value]
-Display cp15 register @var{regnum};
+@deffn Command {arm720t cp15} opcode [value]
+@emph{DEPRECATED -- avoid using this.
+Use the @command{arm mrc} or @command{arm mcr} commands instead.}
+
+Display cp15 register returned by the ARM instruction @var{opcode};
 else if a @var{value} is provided, that value is written to that register.
+The @var{opcode} should be the value of either an MRC or MCR instruction.
 @end deffn
 
 @subsection ARM9 specific commands
@@ -5964,13 +5984,21 @@ is an ARM920T (2x16kByte cache) or ARM922T (2x8kByte cache).
 @deffn Command {arm920t cp15} regnum [value]
 Display cp15 register @var{regnum};
 else if a @var{value} is provided, that value is written to that register.
+This uses "physical access" and the register number is as
+shown in bits 38..33 of table 9-9 in the ARM920T TRM.
+(Not all registers can be written.)
 @end deffn
 
 @deffn Command {arm920t cp15i} opcode [value [address]]
-Interpreted access using cp15 @var{opcode}.
+@emph{DEPRECATED -- avoid using this.
+Use the @command{arm mrc} or @command{arm mcr} commands instead.}
+
+Interpreted access using ARM instruction @var{opcode}, which should
+be the value of either an MRC or MCR instruction
+(as shown tables 9-11, 9-12, and 9-13 in the ARM920T TRM).
 If no @var{value} is provided, the result is displayed.
 Else if that value is written using the specified @var{address},
-or using zero if no other address is not provided.
+or using zero if no other address is provided.
 @end deffn
 
 @deffn Command {arm920t read_cache} filename
@@ -6008,6 +6036,10 @@ and ARM9 commands.
 @deffn Command {arm966e cp15} regnum [value]
 Display cp15 register @var{regnum};
 else if a @var{value} is provided, that value is written to that register.
+The six bit @var{regnum} values are bits 37..32 from table 7-2 of the
+ARM966E-S TRM.
+There is no current control over bits 31..30 from that table,
+as required for BIST support.
 @end deffn
 
 @subsection XScale specific commands
@@ -6083,7 +6115,7 @@ else if a @var{value} is provided, that value is written to that register.
 Changes the address used for the specified target's debug handler.
 @end deffn
 
-@deffn Command {xscale dcache} (@option{enable}|@option{disable})
+@deffn Command {xscale dcache} [@option{enable}|@option{disable}]
 Enables or disable the CPU's data cache.
 @end deffn
 
@@ -6091,17 +6123,18 @@ Enables or disable the CPU's data cache.
 Dumps the raw contents of the trace buffer to @file{filename}.
 @end deffn
 
-@deffn Command {xscale icache} (@option{enable}|@option{disable})
+@deffn Command {xscale icache} [@option{enable}|@option{disable}]
 Enables or disable the CPU's instruction cache.
 @end deffn
 
-@deffn Command {xscale mmu} (@option{enable}|@option{disable})
+@deffn Command {xscale mmu} [@option{enable}|@option{disable}]
 Enables or disable the CPU's memory management unit.
 @end deffn
 
-@deffn Command {xscale trace_buffer} (@option{enable}|@option{disable}) [@option{fill} [n] | @option{wrap}]
-Enables or disables the trace buffer,
-and controls how it is emptied.
+@deffn Command {xscale trace_buffer} [@option{enable}|@option{disable} [@option{fill} [n] | @option{wrap}]]
+Displays the trace buffer status, after optionally
+enabling or disabling the trace buffer
+and modifying how it is emptied.
 @end deffn
 
 @deffn Command {xscale trace_image} filename [offset [type]]
@@ -6133,7 +6166,7 @@ The mask bits correspond with bit 16..23 in the DCSR:
 @end deffn
 
 @anchor{xscale vector_table}
-@deffn Command {xscale vector_table} [<low|high> <index> <value>]
+@deffn Command {xscale vector_table} [(@option{low}|@option{high}) index value]
 @cindex vector_table
 
 Set an entry in the mini-IC vector table. There are two tables: one for
@@ -6152,27 +6185,29 @@ Without arguments, the current settings are displayed.
 @subsection ARM11 specific commands
 @cindex ARM11
 
-@deffn Command {arm11 memwrite burst} [value]
+@deffn Command {arm11 memwrite burst} [@option{enable}|@option{disable}]
 Displays the value of the memwrite burst-enable flag,
-which is enabled by default. Burst writes are only used
-for memory writes larger than 1 word. Single word writes
-are likely to be from reset init scripts and those writes
-are often to non-memory locations which could easily have
-many wait states, which could easily break burst writes.
-If @var{value} is defined, first assigns that.
+which is enabled by default.
+If a boolean parameter is provided, first assigns that flag.
+Burst writes are only used for memory writes larger than 1 word.
+They improve performance by assuming that the CPU has read each data
+word over JTAG and completed its write before the next word arrives,
+instead of polling for a status flag to verify that completion.
+This is usually safe, because JTAG runs much slower than the CPU.
 @end deffn
 
-@deffn Command {arm11 memwrite error_fatal} [value]
+@deffn Command {arm11 memwrite error_fatal} [@option{enable}|@option{disable}]
 Displays the value of the memwrite error_fatal flag,
 which is enabled by default.
-If @var{value} is defined, first assigns that.
+If a boolean parameter is provided, first assigns that flag.
+When set, certain memory write errors cause earlier transfer termination.
 @end deffn
 
-@deffn Command {arm11 step_irq_enable}  [value]
+@deffn Command {arm11 step_irq_enable} [@option{enable}|@option{disable}]
 Displays the value of the flag controlling whether
 IRQs are enabled during single stepping;
 they are disabled by default.
-If @var{value} is defined, first assigns that.
+If a boolean parameter is provided, first assigns that.
 @end deffn
 
 @deffn Command {arm11 vcr} [value]
@@ -6198,26 +6233,28 @@ These commands are specific to ARM architecture v7 Debug Access Port (DAP),
 included on Cortex-M3 and Cortex-A8 systems.
 They are available in addition to other core-specific commands that may be available.
 
-@deffn Command {dap info} [num]
-Displays dap info for ap @var{num}, defaulting to the currently selected AP.
+@deffn Command {dap apid} [num]
+Displays ID register from AP @var{num},
+defaulting to the currently selected AP.
 @end deffn
 
 @deffn Command {dap apsel} [num]
 Select AP @var{num}, defaulting to 0.
 @end deffn
 
-@deffn Command {dap apid} [num]
-Displays id register from AP @var{num},
+@deffn Command {dap baseaddr} [num]
+Displays debug base address from MEM-AP @var{num},
 defaulting to the currently selected AP.
 @end deffn
 
-@deffn Command {dap baseaddr} [num]
-Displays debug base address from AP @var{num},
+@deffn Command {dap info} [num]
+Displays the ROM table for MEM-AP @var{num},
 defaulting to the currently selected AP.
 @end deffn
 
 @deffn Command {dap memaccess} [value]
-Displays the number of extra tck for mem-ap memory bus access [0-255].
+Displays the number of extra tck cycles in the JTAG idle to use for MEM-AP
+memory bus access [0-255], giving additional time to respond to reads.
 If @var{value} is defined, first assigns that.
 @end deffn
 
@@ -6876,11 +6913,12 @@ variables. JimTCL, as implemented in OpenOCD creates $ocd_HOSTOS which
 holds one of the following values:
 
 @itemize @bullet
-@item @b{winxx}    Built using Microsoft Visual Studio
-@item @b{linux}    Linux is the underlying operating sytem
-@item @b{darwin}   Darwin (mac-os) is the underlying operating sytem.
 @item @b{cygwin}   Running under Cygwin
+@item @b{darwin}   Darwin (Mac-OS) is the underlying operating sytem.
+@item @b{freebsd}  Running under FreeBSD
+@item @b{linux}    Linux is the underlying operating sytem
 @item @b{mingw32}  Running under MingW32
+@item @b{winxx}    Built using Microsoft Visual Studio
 @item @b{other}    Unknown, none of the above.
 @end itemize