David Brownell <david-b@pacbell.net>:

Start converting the architecture-specific commands to @deffn format,
reviewing against the code.

  * armv4_5 disassemble ... now documented; although Jazelle code
    is not handled

  * It's "armv4_5 core_state" not "core_mode"; although Jazelle state
    is not handled

  * arm7/9 "debug" commands ... now with other arm7_9 commands, no
    longer in a separate section

  * arm926ejs cp15 ... previous description was broken, it matched
    the code for arm920t instead

  * Have separate subsections for ARMv4/ARMv5, ARMv6, and ARMv7; the
    latter are new
    
  * Move core-specific descriptions into sub-subsections under those
    architectures; XScale and ARM11 descriptions are new

The new XScale and ARM11 command descriptions surely need elaboration
and review.  ARM CP15 operation descriptions in general seem to be
confused and incomplete.


git-svn-id: svn://svn.berlios.de/openocd/trunk@1939 b42882b7-edfa-0310-969c-e2dbd0fdcd60
This commit is contained in:
zwelch 2009-05-28 23:13:32 +00:00
parent 6149c509ca
commit ea62c7964a
1 changed files with 369 additions and 153 deletions

View File

@ -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
@subsection ARMV4/5 specific commands
@cindex ARMV4/5 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.
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
@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
@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
@subsection ARM720T specific commands
@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.}
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.
@subsection ARM9TDMI specific 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
@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
@subsection ARM966E specific commands
@cindex ARM966E specific commands
@itemize @bullet
@item @b{arm966e cp15} <@var{num}> [@var{value}]
@cindex arm966e cp15
@*display/modify cp15 register <@option{num}> [@option{value}].
@end itemize
@subsection ARM920T specific commands
@subsubsection ARM920T specific commands
@cindex ARM920T specific commands
@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
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.
@subsection ARM926EJ-S specific commands
@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
@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
@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
@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