diff options
| -rw-r--r-- | doc/openocd.texi | 516 |
1 files changed, 366 insertions, 150 deletions
diff --git a/doc/openocd.texi b/doc/openocd.texi index ef190e8d..faf252be 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 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. -@section Architecture Specific Commands -@cindex Architecture Specific Commands +@subsection ARMv4 and ARMv5 Architecture +@cindex ARMv4 specific commands +@cindex ARMv5 specific commands -@subsection ARMV4/5 specific commands -@cindex ARMV4/5 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. -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 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 + +@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 + +@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.} -@subsection ARM720T specific commands +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.} + +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 -@subsection ARM9TDMI specific commands +@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 + +@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 -@subsection ARM926EJ-S specific commands +@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 + +@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 |