X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=faf252bed9064385ef959992ffa3c7e4303ad210;hp=ef190e8d9441fd42412dd2406d6bb2e7bf8eb4fb;hb=ea62c7964ab5c7a12f95cf6b7f7d782aae94f50e;hpb=6149c509ca3e734d8e48129a03fc6a399853e1db

diff --git a/doc/openocd.texi b/doc/openocd.texi
index ef190e8d94..faf252bed9 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -2482,8 +2482,9 @@ Write the image @file{filename} to the current target's flash bank(s).
 A relocation @var{offset} may be specified, in which case it is added
 to the base address for each section in the image.
 The file [@var{type}] can be specified
-explicitly as @option{bin} (binary), @option{ihex} (Intel hex), @option{elf}
-(ELF file) or @option{s19} (Motorola s19).
+explicitly as @option{bin} (binary), @option{ihex} (Intel hex),
+@option{elf} (ELF file), @option{s19} (Motorola s19).
+@option{mem}, or @option{builder}.
 The relevant flash sectors will be erased prior to programming
 if the @option{erase} parameter is given.
 The flash bank to use is inferred from the @var{address} of
@@ -3463,188 +3464,403 @@ Profiling samples the CPU's program counter as quickly as possible, which is use
 
 @end itemize
 
-@section Target Specific Commands
-@cindex Target Specific Commands
-
-
-@section Architecture Specific Commands
+@section Architecture and Core Specific Commands
 @cindex Architecture Specific Commands
+@cindex Core Specific Commands
+
+Most CPUs have specialized JTAG operations to support debugging.
+OpenOCD packages most such operations in its standard command framework.
+Some of those operations don't fit well in that framework, so they are
+exposed here using architecture or implementation specific commands.
+
+@subsection ARMv4 and ARMv5 Architecture
+@cindex ARMv4 specific commands
+@cindex ARMv5 specific commands
+
+These commands are specific to ARM architecture v4 and v5,
+including all ARM7 or ARM9 systems and Intel XScale.
+They are available in addition to other core-specific
+commands that may be available.
+
+@deffn Command {armv4_5 core_state} [arm|thumb]
+Displays the core_state, optionally changing it to process
+either @option{arm} or @option{thumb} instructions.
+The target may later be resumed in the currently set core_state.
+(Processors may also support the Jazelle state, but
+that is not currently supported in OpenOCD.)
+@end deffn
 
-@subsection ARMV4/5 specific commands
-@cindex ARMV4/5 specific commands
+@deffn Command {armv4_5 disassemble} address count [thumb]
+@cindex disassemble
+Disassembles @var{count} instructions starting at @var{address}.
+If @option{thumb} is specified, Thumb (16-bit) instructions are used;
+else ARM (32-bit) instructions are used.
+(Processors may also support the Jazelle state, but
+those instructions are not currently understood by OpenOCD.)
+@end deffn
 
-These commands are specific to ARM architecture v4 and v5, like all ARM7/9 systems
-or Intel XScale (XScale isn't supported yet).
-@itemize @bullet
-@item @b{armv4_5 reg}
-@cindex armv4_5 reg
-@*Display a list of all banked core registers, fetching the current value from every
+@deffn Command {armv4_5 reg}
+Display a list of all banked core registers, fetching the current value from every
 core mode if necessary. OpenOCD versions before rev. 60 didn't fetch the current
 register value. 
-@item @b{armv4_5 core_mode} [@var{arm}|@var{thumb}]
-@cindex armv4_5 core_mode
-@*Displays the core_mode, optionally changing it to either ARM or Thumb mode.
-The target is resumed in the currently set @option{core_mode}. 
-@end itemize
+@end deffn
 
-@subsection ARM7/9 specific commands
-@cindex ARM7/9 specific commands
+@subsubsection ARM7 and ARM9 specific commands
+@cindex ARM7 specific commands
+@cindex ARM9 specific commands
 
-These commands are specific to ARM7 and ARM9 targets, like ARM7TDMI, ARM720t,
-ARM920T or ARM926EJ-S.
-@itemize @bullet
-@item @b{arm7_9 dbgrq} <@var{enable}|@var{disable}>
-@cindex arm7_9 dbgrq
-@*Enable use of the DBGRQ bit to force entry into debug mode. This should be
+These commands are specific to ARM7 and ARM9 cores, like ARM7TDMI, ARM720T,
+ARM9TDMI, ARM920T or ARM926EJ-S.
+They are available in addition to the ARMv4/5 commands,
+and any other core-specific commands that may be available.
+
+@deffn Command {arm7_9 dbgrq} (enable|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). 
-@item @b{arm7_9 fast_memory_access} <@var{enable}|@var{disable}>
-@cindex arm7_9 fast_memory_access
+@end deffn
+
+@deffn Command {arm7_9 dcc_downloads} (enable|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
+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}
-@*Allow OpenOCD to read and write memory without checking completion of
+@deffn Command {arm7_9 fast_memory_access} (enable|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
 cables (FT2232), but might be unsafe if used with targets running at very low
 speeds, like the 32kHz startup clock of an AT91RM9200. 
-@item @b{arm7_9 dcc_downloads} <@var{enable}|@var{disable}>
-@cindex arm7_9 dcc_downloads
-@*Enable 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 potentially
-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 itemize
+@end deffn
+
+@deffn {Debug Command} {arm7_9 write_core_reg} num mode word
+@emph{This is intended for use while debugging OpenOCD; you probably
+shouldn't use it.}
+
+Writes a 32-bit @var{word} to register @var{num} (from 0 to 16)
+as used in the specified @var{mode}
+(where e.g. mode 16 is "user" and mode 19 is "supervisor";
+the M4..M0 bits of the PSR).
+Registers 0..15 are the normal CPU registers such as r0(0), r1(1) ... pc(15).
+Register 16 is the mode-specific SPSR,
+unless the specified mode is 0xffffffff (32-bit all-ones)
+in which case register 16 is the CPSR.
+The write goes directly to the CPU, bypassing the register cache.
+@end deffn
+
+@deffn {Debug Command} {arm7_9 write_xpsr} word (0|1)
+@emph{This is intended for use while debugging OpenOCD; you probably
+shouldn't use it.}
+
+If the second parameter is zero, writes @var{word} to the
+Current Program Status register (CPSR).
+Else writes @var{word} to the current mode's Saved PSR (SPSR).
+In both cases, this bypasses the register cache.
+@end deffn
+
+@deffn {Debug Command} {arm7_9 write_xpsr_im8} byte rotate (0|1)
+@emph{This is intended for use while debugging OpenOCD; you probably
+shouldn't use it.}
 
-@subsection ARM720T specific commands
+Writes eight bits to the CPSR or SPSR,
+first rotating them by @math{2*rotate} bits,
+and bypassing the register cache.
+This has lower JTAG overhead than writing the entire CPSR or SPSR
+with @command{arm7_9 write_xpsr}.
+@end deffn
+
+@subsubsection ARM720T specific commands
 @cindex ARM720T specific commands
 
-@itemize @bullet
-@item @b{arm720t cp15} <@var{num}> [@var{value}]
-@cindex arm720t cp15
-@*display/modify cp15 register <@option{num}> [@option{value}].
-@item @b{arm720t md<bhw>_phys} <@var{addr}> [@var{count}]
-@cindex arm720t md<bhw>_phys
-@*Display memory at physical address addr. 
-@item @b{arm720t mw<bhw>_phys} <@var{addr}> <@var{value}>
-@cindex arm720t mw<bhw>_phys
-@*Write memory at physical address addr.
-@item @b{arm720t virt2phys} <@var{va}>
-@cindex arm720t virt2phys
-@*Translate a virtual address to a physical address. 
-@end itemize
+These commands are available to ARM720T based CPUs,
+which are implementations of the ARMv4T architecture
+based on the ARM7TDMI-S integer core.
+They are available in addition to the ARMv4/5 and ARM7/ARM9 commands.
+
+@deffn Command {arm720t cp15} regnum [value]
+Display cp15 register @var{regnum};
+else if a @var{value} is provided, that value is written to that register.
+@end deffn
+
+@deffn Command {arm720t mdw_phys} addr [count]
+@deffnx Command {arm720t mdh_phys} addr [count]
+@deffnx Command {arm720t mdb_phys} addr [count]
+Display contents of physical address @var{addr}, as
+32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
+or 8-bit bytes (@command{mdb_phys}).
+If @var{count} is specified, displays that many units.
+@end deffn
 
-@subsection ARM9TDMI specific commands
+@deffn Command {arm720t mww_phys} addr word
+@deffnx Command {arm720t mwh_phys} addr halfword
+@deffnx Command {arm720t mwb_phys} addr byte
+Writes the specified @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+at the specified physical address @var{addr}.
+@end deffn
+
+@deffn Command {arm720t virt2phys} va
+Translate a virtual address @var{va} to a physical address
+and display the result.
+@end deffn
+
+@subsubsection ARM9TDMI specific commands
 @cindex ARM9TDMI specific commands
 
-@itemize @bullet
-@item @b{arm9tdmi vector_catch} <@var{all}|@var{none}>
-@cindex arm9tdmi vector_catch
-@*Catch arm9 interrupt vectors, can be @option{all} @option{none} or any of the following:
+Many ARM9-family CPUs are built around ARM9TDMI integer cores,
+or processors resembling ARM9TDMI, and can use these commands.
+Such cores include the ARM920T, ARM926EJ-S, and ARM966.
+
+@deffn Command {arm9tdmi vector_catch} (all|none|list)
+Catch arm9 interrupt vectors, can be @option{all}, @option{none},
+or a list with one or more of the following:
 @option{reset} @option{undef} @option{swi} @option{pabt} @option{dabt} @option{reserved}
 @option{irq} @option{fiq}.
+@end deffn
 
-Can also be used on other ARM9 based cores such as ARM966, ARM920T and ARM926EJ-S.
-@end itemize
+@subsubsection ARM920T specific commands
+@cindex ARM920T specific commands
 
-@subsection ARM966E specific commands
-@cindex ARM966E specific commands
+These commands are available to ARM920T based CPUs,
+which are implementations of the ARMv4T architecture
+built using the ARM9TDMI integer core.
+They are available in addition to the ARMv4/5, ARM7/ARM9,
+and ARM9TDMI commands.
 
-@itemize @bullet
-@item @b{arm966e cp15} <@var{num}> [@var{value}]
-@cindex arm966e cp15
-@*display/modify cp15 register <@option{num}> [@option{value}].
-@end itemize
+@deffn Command {arm920t cache_info}
+Print information about the caches found. This allows to see whether your target
+is an ARM920T (2x16kByte cache) or ARM922T (2x8kByte cache).
+@end deffn
 
-@subsection ARM920T specific commands
-@cindex ARM920T specific commands
+@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.
+@end deffn
 
-@itemize @bullet
-@item @b{arm920t cp15} <@var{num}> [@var{value}]
-@cindex arm920t cp15
-@*display/modify cp15 register <@option{num}> [@option{value}].
-@item @b{arm920t cp15i} <@var{num}> [@var{value}] [@var{address}]
-@cindex arm920t cp15i
-@*display/modify cp15 (interpreted access) <@option{opcode}> [@option{value}] [@option{address}]
-@item @b{arm920t cache_info}
-@cindex arm920t cache_info
-@*Print information about the caches found. This allows to see whether your target
-is an ARM920T (2x16kByte cache) or ARM922T (2x8kByte cache). 
-@item @b{arm920t md<bhw>_phys} <@var{addr}> [@var{count}]
-@cindex arm920t md<bhw>_phys
-@*Display memory at physical address addr. 
-@item @b{arm920t mw<bhw>_phys} <@var{addr}> <@var{value}>
-@cindex arm920t mw<bhw>_phys
-@*Write memory at physical address addr. 
-@item @b{arm920t read_cache} <@var{filename}>
-@cindex arm920t read_cache
-@*Dump the content of ICache and DCache to a file. 
-@item @b{arm920t read_mmu} <@var{filename}>
-@cindex arm920t read_mmu
-@*Dump the content of the ITLB and DTLB to a file. 
-@item @b{arm920t virt2phys} <@var{va}>
-@cindex arm920t virt2phys
-@*Translate a virtual address to a physical address. 
-@end itemize
+@deffn Command {arm920t cp15i} opcode [value [address]]
+Interpreted access using cp15 @var{opcode}.
+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.
+@end deffn
+
+@deffn Command {arm920t mdw_phys} addr [count]
+@deffnx Command {arm920t mdh_phys} addr [count]
+@deffnx Command {arm920t mdb_phys} addr [count]
+Display contents of physical address @var{addr}, as
+32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
+or 8-bit bytes (@command{mdb_phys}).
+If @var{count} is specified, displays that many units.
+@end deffn
+
+@deffn Command {arm920t mww_phys} addr word
+@deffnx Command {arm920t mwh_phys} addr halfword
+@deffnx Command {arm920t mwb_phys} addr byte
+Writes the specified @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+at the specified physical address @var{addr}.
+@end deffn
+
+@deffn Command {arm920t read_cache} filename
+Dump the content of ICache and DCache to a file named @file{filename}.
+@end deffn
+
+@deffn Command {arm920t read_mmu} filename
+Dump the content of the ITLB and DTLB to a file named @file{filename}.
+@end deffn
+
+@deffn Command {arm920t virt2phys} @var{va}
+Translate a virtual address @var{va} to a physical address
+and display the result.
+@end deffn
 
-@subsection ARM926EJ-S specific commands
+@subsubsection ARM926EJ-S specific commands
 @cindex ARM926EJ-S specific commands
 
-@itemize @bullet
-@item @b{arm926ejs cp15} <@var{num}> [@var{value}]
-@cindex arm926ejs cp15
-@*display/modify cp15 register <@option{num}> [@option{value}].
-@item @b{arm926ejs cache_info}
-@cindex arm926ejs cache_info
-@*Print information about the caches found.
-@item @b{arm926ejs md<bhw>_phys} <@var{addr}> [@var{count}]
-@cindex arm926ejs md<bhw>_phys
-@*Display memory at physical address addr. 
-@item @b{arm926ejs mw<bhw>_phys} <@var{addr}> <@var{value}>
-@cindex arm926ejs mw<bhw>_phys
-@*Write memory at physical address addr. 
-@item @b{arm926ejs virt2phys} <@var{va}>
-@cindex arm926ejs virt2phys
-@*Translate a virtual address to a physical address. 
-@end itemize
+These commands are available to ARM926EJ-S based CPUs,
+which are implementations of the ARMv5TEJ architecture
+based on the ARM9EJ-S integer core.
+They are available in addition to the ARMv4/5, ARM7/ARM9,
+and ARM9TDMI commands.
 
-@subsection CORTEX_M3 specific commands
-@cindex CORTEX_M3 specific commands
+@deffn Command {arm926ejs cache_info}
+Print information about the caches found.
+@end deffn
 
-@itemize @bullet
-@item @b{cortex_m3 maskisr} <@var{on}|@var{off}>
-@cindex cortex_m3 maskisr
-@*Enable masking (disabling) interrupts during target step/resume.
-@end itemize
+@deffn Command {arm926ejs cp15} opcode1 opcode2 CRn CRm regnum [value]
+Accesses cp15 register @var{regnum} using
+@var{opcode1}, @var{opcode2}, @var{CRn}, and @var{CRm}.
+If a @var{value} is provided, that value is written to that register.
+Else that register is read and displayed.
+@end deffn
 
-@page
-@section Debug commands
-@cindex Debug commands
-The following commands give direct access to the core, and are most likely
-only useful while debugging OpenOCD.
-@itemize @bullet
-@item @b{arm7_9 write_xpsr} <@var{32-bit value}> <@option{0=cpsr}, @option{1=spsr}>
-@cindex arm7_9 write_xpsr
-@*Immediately write either the current program status register (CPSR) or the saved
-program status register (SPSR), without changing the register cache (as displayed
-by the @option{reg} and @option{armv4_5 reg} commands). 
-@item @b{arm7_9 write_xpsr_im8} <@var{8-bit value}> <@var{rotate 4-bit}>
-<@var{0=cpsr},@var{1=spsr}>
-@cindex arm7_9 write_xpsr_im8
-@*Write the 8-bit value rotated right by 2*rotate bits, using an immediate write
-operation (similar to @option{write_xpsr}). 
-@item @b{arm7_9 write_core_reg} <@var{num}> <@var{mode}> <@var{value}>
-@cindex arm7_9 write_core_reg
-@*Write a core register, without changing the register cache (as displayed by the
-@option{reg} and @option{armv4_5 reg} commands). The <@var{mode}> argument takes the
-encoding of the [M4:M0] bits of the PSR. 
-@end itemize
+@deffn Command {arm926ejs mdw_phys} addr [count]
+@deffnx Command {arm926ejs mdh_phys} addr [count]
+@deffnx Command {arm926ejs mdb_phys} addr [count]
+Display contents of physical address @var{addr}, as
+32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
+or 8-bit bytes (@command{mdb_phys}).
+If @var{count} is specified, displays that many units.
+@end deffn
+
+@deffn Command {arm926ejs mww_phys} addr word
+@deffnx Command {arm926ejs mwh_phys} addr halfword
+@deffnx Command {arm926ejs mwb_phys} addr byte
+Writes the specified @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+at the specified physical address @var{addr}.
+@end deffn
+
+@deffn Command {arm926ejs virt2phys} @var{va}
+Translate a virtual address @var{va} to a physical address
+and display the result.
+@end deffn
+
+@subsubsection ARM966E specific commands
+@cindex ARM966E specific commands
+
+These commands are available to ARM966 based CPUs,
+which are implementations of the ARMv5TE architecture.
+They are available in addition to the ARMv4/5, ARM7/ARM9,
+and ARM9TDMI 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.
+@end deffn
+
+@subsubsection XScale specific commands
+@cindex XScale specific commands
+
+These commands are available to XScale based CPUs,
+which are implementations of the ARMv5TE architecture.
+
+@deffn Command {xscale analyze_trace}
+Displays the contents of the trace buffer.
+@end deffn
+
+@deffn Command {xscale cache_clean_address} address
+Changes the address used when cleaning the data cache.
+@end deffn
+
+@deffn Command {xscale cache_info}
+Displays information about the CPU caches.
+@end deffn
+
+@deffn Command {xscale cp15} regnum [value]
+Display cp15 register @var{regnum};
+else if a @var{value} is provided, that value is written to that register.
+@end deffn
+
+@deffn Command {xscale debug_handler} target address
+Changes the address used for the specified target's debug handler.
+@end deffn
+
+@deffn Command {xscale dcache} (enable|disable)
+Enables or disable the CPU's data cache.
+@end deffn
+
+@deffn Command {xscale dump_trace} filename
+Dumps the raw contents of the trace buffer to @file{filename}.
+@end deffn
+
+@deffn Command {xscale icache} (enable|disable)
+Enables or disable the CPU's instruction cache.
+@end deffn
+
+@deffn Command {xscale mmu} (enable|disable)
+Enables or disable the CPU's memory management unit.
+@end deffn
+
+@deffn Command {xscale trace_buffer} (enable|disable) [fill [n] | wrap]
+Enables or disables the trace buffer,
+and controls how it is emptied.
+@end deffn
+
+@deffn Command {xscale trace_image} filename [offset [type]]
+Opens a trace image from @file{filename}, optionally rebasing
+its segment addresses by @var{offset}.
+The image @var{type} may be one of
+@option{bin} (binary), @option{ihex} (Intel hex),
+@option{elf} (ELF file), @option{s19} (Motorola s19),
+@option{mem}, or @option{builder}.
+@end deffn
+
+@deffn Command {xscale vector_catch} mask
+Provide a bitmask showing the vectors to catch.
+@end deffn
+
+@subsection ARMv6 Architecture
+
+@subsubsection ARM11 specific commands
+@cindex ARM11 specific commands
+
+@deffn Command {arm11 mcr} p1 p2 p3 p4 p5
+Read coprocessor register
+@end deffn
+
+@deffn Command {arm11 memwrite burst} [value]
+Displays the value of the memwrite burst-enable flag,
+which is enabled by default.
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@deffn Command {arm11 memwrite error_fatal} [value]
+Displays the value of the memwrite error_fatal flag,
+which is enabled by default.
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@deffn Command {arm11 mrc} p1 p2 p3 p4 p5 value
+Write coprocessor register
+@end deffn
+
+@deffn Command {arm11 no_increment}  [value]
+Displays the value of the flag controlling whether
+some read or write operations increment the pointer
+(the default behavior) or not (acting like a FIFO).
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@deffn Command {arm11 step_irq_enable}  [value]
+Displays the value of the flag controlling whether
+IRQs are enabled during single stepping;
+they is disabled by default.
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@subsection ARMv7 Architecture
+
+@subsubsection Cortex-M3 specific commands
+@cindex Cortex-M3 specific commands
+
+@deffn Command {cortex_m3 maskisr} (on|off)
+Control masking (disabling) interrupts during target step/resume.
+@end deffn
+
+@section Target DCC Requests
+@cindex Linux-ARM DCC support
+@cindex libdcc
+@cindex DCC
+OpenOCD can handle certain target requests; currently debugmsgs
+@command{target_request debugmsgs}
+are only supported for arm7_9 and cortex_m3.
 
-@section Target Requests
-@cindex Target Requests
-OpenOCD can handle certain target requests, currently debugmsg are only supported for arm7_9 and cortex_m3.
 See libdcc in the contrib dir for more details.
-@itemize @bullet
-@item @b{target_request debugmsgs} <@var{enable}|@var{disable}|@var{charmsg}>
-@cindex target_request debugmsgs
-@*Enable/disable target debugmsgs requests. debugmsgs enable messages to be sent to the debugger while the target is running. @var{charmsg} receives messages if Linux kernel ``Kernel low-level debugging via EmbeddedICE DCC channel'' option is enabled.
-@end itemize
+Linux-ARM kernels have a ``Kernel low-level debugging
+via EmbeddedICE DCC channel'' option (CONFIG_DEBUG_ICEDCC,
+depends on CONFIG_DEBUG_LL) which uses this mechanism to
+deliver messages before a serial console can be activated.
+
+@deffn Command {target_request debugmsgs} [enable|disable|charmsg]
+Displays current handling of target DCC message requests.
+These messages may be sent to the debugger while the target is running.
+The optional @option{enable} and @option{charmsg} parameters are
+equivalent; both enable the messages, @option{disable} disables them.
+@end deffn
 
 @node JTAG Commands
 @chapter JTAG Commands