interesting
/
riscv-openocd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

Update the "General Commands" (a.k.a. "random stuff") chapter,
and associated chunks of other text:

 - Switch to @deffn and review everything that's documented

 - Improve descriptions of reset events, with reference to
   the setup.tcl code which issues them.

 - Move one zy1000-specific command to that driver's doc.

 - There is no "script" command; remove its doc.

NOTE:  Some things missing from this bit of work are:

 1- Reviewing the code to catch various *missing* functions,
    mostly from "target.c"

 2- Alphabetizing and organizing.  This chapter is a real
    grab-bag with no evident focus or structural principle.

 3- Hole-filling and bugfixing with respect to messaging/logging.
    Example, what principle could possibly justify the tcl command
    output going into the server output/log instead of just the
    telnet session?

 4- Not just for this chapter ... but there should be a section
    with descriptions of all the supported image file formats,
    so every image command can just reference that section.


git-svn-id: svn://svn.berlios.de/openocd/trunk@2039 b42882b7-edfa-0310-969c-e2dbd0fdcd60
This commit is contained in:
zwelch 2009-06-04 01:22:23 +00:00
parent e7d6306b23
commit de7cb1c76b
1 changed files with 253 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

410
doc/openocd.texi
View File

@ -1565,6 +1565,12 @@ This is the Zylin ZY1000 JTAG debugger.
This defines some driver-specific commands, This defines some driver-specific commands,
which are not currently documented here. which are not currently documented here.
@end quotation @end quotation
@deffn Command power [@option{on}|@option{off}]
Turn power switch to target on/off.
No arguments: print status.
@end deffn
@end deffn @end deffn
@anchor{JTAG Speed} @anchor{JTAG Speed}
@ -2308,26 +2314,33 @@ The following events are available:
@item @b{old-pre_resume} @item @b{old-pre_resume}
@* DO NOT USE THIS: Used internally @* DO NOT USE THIS: Used internally
@item @b{reset-assert-pre} @item @b{reset-assert-pre}
@* Before reset is asserted on the tap. @* Issued as part of @command{reset} processing
after SRST and/or TRST were activated and deactivated,
but before reset is asserted on the tap.
@item @b{reset-assert-post} @item @b{reset-assert-post}
@* Reset is now asserted on the tap. @* Issued as part of @command{reset} processing
when reset is asserted on the tap.
@item @b{reset-deassert-pre} @item @b{reset-deassert-pre}
@* Reset is about to be released on the tap @* Issued as part of @command{reset} processing
when reset is about to be released on the tap.
@item @b{reset-deassert-post} @item @b{reset-deassert-post}
@* Reset has been released on the tap @* Issued as part of @command{reset} processing
when reset has been released on the tap.
@item @b{reset-end} @item @b{reset-end}
@* Currently not used. @* Issued as the final step in @command{reset} processing.
@item @b{reset-halt-post} @item @b{reset-halt-post}
@* Currently not usd @* Currently not usd
@item @b{reset-halt-pre} @item @b{reset-halt-pre}
@* Currently not used @* Currently not used
@item @b{reset-init} @item @b{reset-init}
@* Used by @b{reset init} command for board-specific initialization. @* Used by @b{reset init} command for board-specific initialization.
This event fires after @emph{reset-deassert-post}.
This is where you would configure PLLs and clocking, set up DRAM so This is where you would configure PLLs and clocking, set up DRAM so
you can download programs that don't fit in on-chip SRAM, set up pin you can download programs that don't fit in on-chip SRAM, set up pin
multiplexing, and so on. multiplexing, and so on.
@item @b{reset-start} @item @b{reset-start}
@* Currently not used @* Issued as part of @command{reset} processing
before either SRST or TRST are activated.
@item @b{reset-wait-pos} @item @b{reset-wait-pos}
@* Currently not used @* Currently not used
@item @b{reset-wait-pre} @item @b{reset-wait-pre}
@ -3472,27 +3485,37 @@ port is 5555.
@section Daemon Commands @section Daemon Commands
@subsection sleep [@var{msec}] @deffn Command sleep msec [@option{busy}]
@cindex sleep Wait for at least @var{msec} milliseconds before resuming.
@*Wait for n milliseconds before resuming. Useful in connection with script files If @option{busy} is passed, busy-wait instead of sleeping.
(@var{script} command and @var{target_script} configuration). (This option is strongly discouraged.)
Useful in connection with script files
(@command{script} command and @command{target_name} configuration).
@end deffn
@subsection shutdown @deffn Command shutdown
@cindex shutdown Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
@*Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other). @end deffn
@anchor{debug_level} @anchor{debug_level}
@subsection debug_level [@var{n}] @deffn Command debug_level [n]
@cindex debug_level @cindex message level
@*Display or adjust debug level to n<0-3> Display debug level.
If @var{n} (from 0..3) is provided, then set it to that level.
This affects the kind of messages sent to the server log.
Level 0 is error messages only;
level 1 adds warnings;
level 2 (the default) adds informational messages;
and level 3 adds debugging messages.
@end deffn
@subsection fast [@var{enable|disable}] @deffn Command fast [enable|disable]
@cindex fast Default disabled.
@*Default disabled. Set default behaviour of OpenOCD to be "fast and dangerous". For instance ARM7/9 DCC memory Set default behaviour of OpenOCD to be "fast and dangerous".
downloads and fast memory access will work if the JTAG interface isn't too fast and
the core doesn't run at a too low frequency. Note that this option only changes the default At this writing, this only affects the defaults for two ARM7/ARM9 parameters:
and that the indvidual options, like DCC memory downloads, can be enabled and disabled fast memory access, and DCC downloads. Those parameters may still be
individually. individually overridden.
The target specific "dangerous" optimisation tweaking options may come and go The target specific "dangerous" optimisation tweaking options may come and go
as more robust and user friendly ways are found to ensure maximum throughput as more robust and user friendly ways are found to ensure maximum throughput
@ -3503,191 +3526,264 @@ Typically the "fast enable" is specified first on the command line:
@example @example
openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg
@end example @end example
@end deffn
@subsection echo <@var{message}> @deffn Command echo message
@cindex echo Logs a message at "user" priority.
@*Output message to stdio. e.g. echo "Programming - please wait" Output @var{message} to stdout.
@example
echo "Downloading kernel -- please wait"
@end example
@end deffn
@subsection log_output <@var{file}> @deffn Command log_output [filename]
@cindex log_output Redirect logging to @var{filename};
@*Redirect logging to <file> (default: stderr) the initial log output channel is stderr.
@end deffn
@subsection script <@var{file}> @section Target State handling
@cindex script @cindex reset
@*Execute commands from <file> @cindex halt
See also: ``source [find FILENAME]'' @cindex target initialization
@section Target state handling In this section ``target'' refers to a CPU configured as
@subsection power <@var{on}|@var{off}> shown earlier (@pxref{CPU Configuration}).
@cindex reg These commands, like many, implicitly refer to
@*Turn power switch to target on/off. a @dfn{current target} which is used to perform the
No arguments: print status. various operations. The current target may be changed
Not all interfaces support this. by using @command{targets} command with the name of the
target which should become current.
@subsection reg [@option{#}|@option{name}] [value] @deffn Command reg [(number|name) [value]]
@cindex reg Access a single register by @var{number} or by its @var{name}.
@*Access a single register by its number[@option{#}] or by its [@option{name}].
No arguments: list all available registers for the current target.
Number or name argument: display a register.
Number or name and value arguments: set register value.
@subsection poll [@option{on}|@option{off}] @emph{With no arguments}:
@cindex poll list all available registers for the current target,
@*Poll the target for its current state. If the target is in debug mode, architecture showing number, name, size, value, and cache status.
@emph{With number/name}: display that register's value.
@emph{With both number/name and value}: set register's value.
Cores may have surprisingly many registers in their
Debug and trace infrastructure:
@example
> reg
(0) r0 (/32): 0x0000D3C2 (dirty: 1, valid: 1)
(1) r1 (/32): 0xFD61F31C (dirty: 0, valid: 1)
(2) r2 (/32): 0x00022551 (dirty: 0, valid: 1)
...
(164) ETM_CONTEXTID_COMPARATOR_MASK (/32): \
0x00000000 (dirty: 0, valid: 0)
>
@end example
@end deffn
@deffn Command poll [@option{on}|@option{off}]
Poll the current target for its current state.
If that target is in debug mode, architecture
specific information about the current state is printed. An optional parameter specific information about the current state is printed. An optional parameter
allows continuous polling to be enabled and disabled. allows continuous polling to be enabled and disabled.
@subsection halt [@option{ms}] @example
@cindex halt > poll
@*Send a halt request to the target and wait for it to halt for up to [@option{ms}] milliseconds. target state: halted
Default [@option{ms}] is 5 seconds if no arg given. target halted in ARM state due to debug-request, \
Optional arg @option{ms} is a timeout in milliseconds. Using 0 as the [@option{ms}] current mode: Supervisor
will stop OpenOCD from waiting. cpsr: 0x800000d3 pc: 0x11081bfc
MMU: disabled, D-Cache: disabled, I-Cache: enabled
>
@end example
@end deffn
@subsection wait_halt [@option{ms}] @deffn Command halt [ms]
@cindex wait_halt @deffnx Command wait_halt [ms]
@*Wait for the target to enter debug mode. Optional [@option{ms}] is The @command{halt} command first sends a halt request to the target,
a timeout in milliseconds. Default [@option{ms}] is 5 seconds if no which @command{wait_halt} doesn't.
arg is given. Otherwise these behave the same: wait up to @var{ms} milliseconds,
or 5 seconds if there is no parameter, for the target to halt
(and enter debug mode).
Using 0 as the @var{ms} parameter prevents OpenOCD from waiting.
@end deffn
@subsection resume [@var{address}] @deffn Command resume [address]
@cindex resume Resume the target at its current code position,
@*Resume the target at its current code position, or at an optional address. or the optional @var{address} if it is provided.
OpenOCD will wait 5 seconds for the target to resume. OpenOCD will wait 5 seconds for the target to resume.
@end deffn
@subsection step [@var{address}] @deffn Command step [address]
@cindex step Single-step the target at its current code position,
@*Single-step the target at its current code position, or at an optional address. or the optional @var{address} if it is provided.
@end deffn
@anchor{Reset Command} @anchor{Reset Command}
@subsection reset [@option{run}|@option{halt}|@option{init}] @deffn Command reset
@cindex reset @deffnx Command {reset run}
@*Perform a hard-reset. The optional parameter specifies what should @deffnx Command {reset halt}
@deffnx Command {reset init}
Perform as hard a reset as possible, using SRST if possible.
@emph{All defined targets will be reset, and target
events will fire during the reset sequence.}
The optional parameter specifies what should
happen after the reset. happen after the reset.
If there is no parameter, a @command{reset run} is executed. If there is no parameter, a @command{reset run} is executed.
The other options will not work on all systems. The other options will not work on all systems.
@xref{Reset Configuration}. @xref{Reset Configuration}.
@itemize @minus
@item @b{run}
@cindex reset run
@*Let the target run.
@item @b{halt}
@cindex reset halt
@*Immediately halt the target (works only with certain configurations).
@item @b{init}
@cindex reset init
@*Immediately halt the target, and execute the reset script (works only with certain
configurations)
@end itemize
@subsection soft_reset_halt @itemize @minus
@cindex reset @item @b{run} Let the target run
@*Requesting target halt and executing a soft reset. This is often used @item @b{halt} Immediately halt the target
@item @b{init} Immediately halt the target, and execute the reset-init script
@end itemize
@end deffn
@deffn Command soft_reset_halt
Requesting target halt and executing a soft reset. This is often used
when a target cannot be reset and halted. The target, after reset is when a target cannot be reset and halted. The target, after reset is
released begins to execute code. OpenOCD attempts to stop the CPU and released begins to execute code. OpenOCD attempts to stop the CPU and
then sets the program counter back to the reset vector. Unfortunately then sets the program counter back to the reset vector. Unfortunately
the code that was executed may have left the hardware in an unknown the code that was executed may have left the hardware in an unknown
state. state.
@end deffn
@section I/O Utilities
These commands are available when
OpenOCD is built with @option{--enable-ioutil}.
They are mainly useful on embedded targets;
PC type hosts have complimentary tools.
@emph{Note:} there are several more such commands.
@deffn Command meminfo
Display available RAM memory on OpenOCD host.
Used in OpenOCD regression testing scripts.
@end deffn
@anchor{Memory access} @anchor{Memory access}
@section Memory access commands @section Memory access commands
@subsection meminfo @cindex memory access
display available RAM memory on OpenOCD host. Used in OpenOCD regression testing scripts. Mainly
useful on embedded targets, PC type hosts have complimentary tools like Valgrind to address
resource tracking problems.
@subsection Memory peek/poke type commands
These commands allow accesses of a specific size to the memory These commands allow accesses of a specific size to the memory
system. Often these are used to configure the current target in some system. Often these are used to configure the current target in some
special way. For example - one may need to write certian values to the special way. For example - one may need to write certain values to the
SDRAM controller to enable SDRAM. SDRAM controller to enable SDRAM.
@enumerate @enumerate
@item To change the current target see the ``targets'' (plural) command @item Use the @command{targets} (plural) command
@item In system level scripts these commands are deprecated, please use the TARGET object versions. to change the current target.
@item In system level scripts these commands are deprecated.
Please use their TARGET object siblings to avoid making assumptions
about what TAP is the current target, or about MMU configuration.
@end enumerate @end enumerate
@itemize @bullet @deffn Command mdw addr [count]
@item @b{mdw} <@var{addr}> [@var{count}] @deffnx Command mdh addr [count]
@cindex mdw @deffnx Command mdb addr [count]
@*display memory words (32bit) Display contents of address @var{addr}, as
@item @b{mdh} <@var{addr}> [@var{count}] 32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}),
@cindex mdh or 8-bit bytes (@command{mdb}).
@*display memory half-words (16bit) If @var{count} is specified, displays that many units.
@item @b{mdb} <@var{addr}> [@var{count}] @end deffn
@cindex mdb
@*display memory bytes (8bit) @deffn Command mww addr word
@item @b{mww} <@var{addr}> <@var{value}> @deffnx Command mwh addr halfword
@cindex mww @deffnx Command mwb addr byte
@*write memory word (32bit) Writes the specified @var{word} (32 bits),
@item @b{mwh} <@var{addr}> <@var{value}> @var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
@cindex mwh at the specified address @var{addr}.
@*write memory half-word (16bit) @end deffn
@item @b{mwb} <@var{addr}> <@var{value}>
@cindex mwb
@*write memory byte (8bit)
@end itemize
@anchor{Image access} @anchor{Image access}
@section Image loading commands @section Image loading commands
@anchor{load_image} @cindex image loading
@subsection load_image @cindex image dumping
@b{load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
@cindex load_image @anchor{dump_image}
@*Load image <@var{file}> to target memory at <@var{address}> @deffn Command {dump_image} filename address size
@subsection fast_load_image Dump @var{size} bytes of target memory starting at @var{address} to the
@b{fast_load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}] binary file named @var{filename}.
@cindex fast_load_image @end deffn
@*Normally you should be using @b{load_image} or GDB load. However, for
@deffn Command {fast_load}
Loads an image stored in memory by @command{fast_load_image} to the
current target. Must be preceeded by fast_load_image.
@end deffn
@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
Normally you should be using @command{load_image} or GDB load. However, for
testing purposes or when I/O overhead is significant(OpenOCD running on an embedded testing purposes or when I/O overhead is significant(OpenOCD running on an embedded
host), storing the image in memory and uploading the image to the target host), storing the image in memory and uploading the image to the target
can be a way to upload e.g. multiple debug sessions when the binary does not change. can be a way to upload e.g. multiple debug sessions when the binary does not change.
Arguments are the same as @b{load_image}, but the image is stored in OpenOCD host Arguments are the same as @command{load_image}, but the image is stored in OpenOCD host
memory, i.e. does not affect target. This approach is also useful when profiling memory, i.e. does not affect target. This approach is also useful when profiling
target programming performance as I/O and target programming can easily be profiled target programming performance as I/O and target programming can easily be profiled
separately. separately.
@subsection fast_load @end deffn
@b{fast_load}
@cindex fast_image @anchor{load_image}
@*Loads an image stored in memory by @b{fast_load_image} to the current target. Must be preceeded by fast_load_image. @deffn Command {load_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
@anchor{dump_image} Load image from file @var{filename} to target memory at @var{address}.
@subsection dump_image The file format may optionally be specified
@b{dump_image} <@var{file}> <@var{address}> <@var{size}> (@option{bin}, @option{ihex}, or @option{elf})
@cindex dump_image @end deffn
@*Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
(binary) <@var{file}>. @deffn Command {verify_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
@subsection verify_image Verify @var{filename} against target memory starting at @var{address}.
@b{verify_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}] The file format may optionally be specified
@cindex verify_image (@option{bin}, @option{ihex}, or @option{elf})
@*Verify <@var{file}> against target memory starting at <@var{address}>.
This will first attempt a comparison using a CRC checksum, if this fails it will try a binary compare. This will first attempt a comparison using a CRC checksum, if this fails it will try a binary compare.
@end deffn
@section Breakpoint commands @section Breakpoint and Watchpoint commands
@cindex Breakpoint commands @cindex breakpoint
@itemize @bullet @cindex watchpoint
@item @b{bp} <@var{addr}> <@var{len}> [@var{hw}]
@cindex bp CPUs often make debug modules accessible through JTAG, with
@*set breakpoint <address> <length> [hw] hardware support for a handful of code breakpoints and data
@item @b{rbp} <@var{addr}> watchpoints.
@cindex rbp In addition, CPUs almost always support software breakpoints.
@*remove breakpoint <adress>
@item @b{wp} <@var{addr}> <@var{len}> <@var{r}|@var{w}|@var{a}> [@var{value}] [@var{mask}] @deffn Command {bp} [address len [@option{hw}]]
@cindex wp With no parameters, lists all active breakpoints.
@*set watchpoint <address> <length> <r/w/a> [value] [mask] Else sets a breakpoint on code execution starting
@item @b{rwp} <@var{addr}> at @var{address} for @var{length} bytes.
@cindex rwp This is a software breakpoint, unless @option{hw} is specified
@*remove watchpoint <adress> in which case it will be a hardware breakpoint.
@end itemize @end deffn
@deffn Command {rbp} address
Remove the breakpoint at @var{address}.
@end deffn
@deffn Command {rwp} address
Remove data watchpoint on @var{address}
@end deffn
@deffn Command {wp} [address len [(@option{r}|@option{w}|@option{a}) [value [mask]]]
With no parameters, lists all active watchpoints.
Else sets a data watchpoint on data from @var{address} for @var{length} bytes.
The watch point is an "access" watchpoint unless
the @option{r} or @option{w} parameter is provided,
defining it as respectively a read or write watchpoint.
If a @var{value} is provided, that value is used when determining if
the watchpoint should trigger. The value may be first be masked
using @var{mask} to mark ``don't care'' fields.
@end deffn
@section Misc Commands @section Misc Commands
@cindex Other Target Commands @cindex profiling
@itemize
@item @b{profile} <@var{seconds}> <@var{gmon.out}>
Profiling samples the CPU's program counter as quickly as possible, which is useful for non-intrusive stochastic profiling. @deffn Command {profile} seconds filename
Profiling samples the CPU's program counter as quickly as possible,
@end itemize which is useful for non-intrusive stochastic profiling.
Saves up to 10000 sampines in @file{filename} using ``gmon.out'' format.
@end deffn
@node Architecture and Core Commands @node Architecture and Core Commands
@chapter Architecture and Core Commands @chapter Architecture and Core Commands