David Brownell <david-b@pacbell.net>:
Various updates, mostly small/formatting changes:
* Small content tweaks:
- Re-title: "OpenOCD User's Guide".
- For users, URLS for latest doc and SparkFun forum
- Mention GIT-SVN
* Fix some front-matter goofage, matching texinfo docs:
- "paragraphintent" location matters
- put release version/date description with the copyright
* Fix some other stuff matching texinfo docs:
- no tabs
- tweak some refs and anchors
* whitespace-at-end-o-line fixes
git-svn-id: svn://svn.berlios.de/openocd/trunk@1975 b42882b7-edfa-0310-969c-e2dbd0fdcd60
This commit is contained in:
zwelch
parent
878d0cb043
commit
a066529fa5
139
doc/openocd.texi
139
doc/openocd.texi
|
|
@ -1,18 +1,23 @@
|
|||
\input texinfo @c -*-texinfo-*-
|
||||
\input texinfo @c -*-texinfo-*-
|
||||
@c %**start of header
|
||||
@setfilename openocd.info
|
||||
@settitle Open On-Chip Debugger (OpenOCD)
|
||||
@settitle OpenOCD User's Guide
|
||||
@dircategory Development
|
||||
@direntry
|
||||
@paragraphindent 0
|
||||
* OpenOCD: (openocd). Open On-Chip Debugger.
|
||||
* OpenOCD: (openocd). OpenOCD User's Guide
|
||||
@end direntry
|
||||
@paragraphindent 0
|
||||
@c %**end of header
|
||||
|
||||
@include version.texi
|
||||
|
||||
@copying
|
||||
|
||||
This User's Guide documents
|
||||
release @value{VERSION},
|
||||
dated @value{UPDATED},
|
||||
of the Open On-Chip Debugger (OpenOCD).
|
||||
|
||||
@itemize @bullet
|
||||
@item Copyright @copyright{} 2008 The OpenOCD Project
|
||||
@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
|
||||
|
|
@ -31,9 +36,12 @@ Free Documentation License''.
|
|||
@end copying
|
||||
|
||||
@titlepage
|
||||
@title Open On-Chip Debugger (OpenOCD)
|
||||
@subtitle Edition @value{EDITION} for OpenOCD version @value{VERSION}
|
||||
@titlefont{@emph{Open On-Chip Debugger:}}
|
||||
@sp 1
|
||||
@title OpenOCD User's Guide
|
||||
@subtitle for release @value{VERSION}
|
||||
@subtitle @value{UPDATED}
|
||||
|
||||
@page
|
||||
@vskip 0pt plus 1filll
|
||||
@insertcopying
|
||||
|
|
@ -42,13 +50,12 @@ Free Documentation License''.
|
|||
@summarycontents
|
||||
@contents
|
||||
|
||||
@node Top, About, , (dir)
|
||||
@top OpenOCD
|
||||
|
||||
This manual documents edition @value{EDITION} of the Open On-Chip Debugger
|
||||
(OpenOCD) version @value{VERSION}, @value{UPDATED}.
|
||||
@ifnottex
|
||||
@node Top
|
||||
@top OpenOCD User's Guide
|
||||
|
||||
@insertcopying
|
||||
@end ifnottex
|
||||
|
||||
@menu
|
||||
* About:: About OpenOCD
|
||||
|
|
@ -77,6 +84,7 @@ This manual documents edition @value{EDITION} of the Open On-Chip Debugger
|
|||
* FAQ:: Frequently Asked Questions
|
||||
* Tcl Crash Course:: Tcl Crash Course
|
||||
* License:: GNU Free Documentation License
|
||||
|
||||
@comment DO NOT use the plain word ``Index'', reason: CYGWIN filename
|
||||
@comment case issue with ``Index.html'' and ``index.html''
|
||||
@comment Occurs when creating ``--html --no-split'' output
|
||||
|
|
@ -125,6 +133,24 @@ The OpenOCD web site provides the latest public news from the community:
|
|||
|
||||
@uref{http://openocd.berlios.de/web/}
|
||||
|
||||
@section Latest User's Guide:
|
||||
|
||||
The user's guide you are now reading may not be the latest one
|
||||
available. A version for more recent code may be available.
|
||||
Its HTML form is published irregularly at:
|
||||
|
||||
@uref{http://openocd.berlios.de/doc/}
|
||||
|
||||
PDF form is likewise published at:
|
||||
|
||||
@uref{http://openocd.berlios.de/doc/pdf/}
|
||||
|
||||
@section OpenOCD User's Forum
|
||||
|
||||
There is an OpenOCD forum (phpBB) hosted by SparkFun:
|
||||
|
||||
@uref{http://forum.sparkfun.com/viewforum.php?f=18}
|
||||
|
||||
|
||||
@node Developers
|
||||
@chapter OpenOCD Developer Resources
|
||||
|
|
@ -167,12 +193,13 @@ listed in the Doxyfile configuration in the top of the repository trunk.
|
|||
The OpenOCD Developer Mailing List provides the primary means of
|
||||
communication between developers:
|
||||
|
||||
@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
|
||||
@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
|
||||
|
||||
All drivers developers are enouraged to also subscribe to the list of
|
||||
SVN commits to keep pace with the ongoing changes:
|
||||
|
||||
@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
|
||||
@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
|
||||
|
||||
|
||||
@node Building OpenOCD
|
||||
@chapter Building OpenOCD
|
||||
|
|
@ -247,7 +274,14 @@ current directory):
|
|||
svn checkout svn://svn.berlios.de/openocd/trunk openocd
|
||||
@end example
|
||||
|
||||
Building OpenOCD requires a recent version of the GNU autotools (autoconf >= 2.59 and automake >= 1.9).
|
||||
If you prefer GIT based tools, the @command{git-svn} package works too:
|
||||
|
||||
@example
|
||||
git svn clone -s svn://svn.berlios.de/openocd
|
||||
@end example
|
||||
|
||||
Building OpenOCD from a repository requires a recent version of the
|
||||
GNU autotools (autoconf >= 2.59 and automake >= 1.9).
|
||||
For building on Windows,
|
||||
you have to use Cygwin. Make sure that your @env{PATH} environment variable contains no
|
||||
other locations with Unix utils (like UnxUtils) - these can't handle the Cygwin
|
||||
|
|
@ -951,14 +985,14 @@ used at will within a ?TARGET? configuration file.
|
|||
# variable: _TARGETNAME = network.cpu
|
||||
# other commands can refer to the "network.cpu" tap.
|
||||
$_TARGETNAME configure .... params for this CPU..
|
||||
|
||||
|
||||
set ENDIAN little
|
||||
set CHIPNAME video
|
||||
source [find target/pxa270.cfg]
|
||||
# variable: _TARGETNAME = video.cpu
|
||||
# other commands can refer to the "video.cpu" tap.
|
||||
$_TARGETNAME configure .... params for this CPU..
|
||||
|
||||
|
||||
unset ENDIAN
|
||||
set CHIPNAME xilinx
|
||||
source [find target/spartan3.cfg]
|
||||
|
|
@ -976,15 +1010,15 @@ All target configuration files should start with this (or a modified form)
|
|||
|
||||
@example
|
||||
# SIMPLE example
|
||||
if @{ [info exists CHIPNAME] @} @{
|
||||
set _CHIPNAME $CHIPNAME
|
||||
@} else @{
|
||||
if @{ [info exists CHIPNAME] @} @{
|
||||
set _CHIPNAME $CHIPNAME
|
||||
@} else @{
|
||||
set _CHIPNAME sam7x256
|
||||
@}
|
||||
|
||||
if @{ [info exists ENDIAN] @} @{
|
||||
set _ENDIAN $ENDIAN
|
||||
@} else @{
|
||||
if @{ [info exists ENDIAN] @} @{
|
||||
set _ENDIAN $ENDIAN
|
||||
@} else @{
|
||||
set _ENDIAN little
|
||||
@}
|
||||
|
||||
|
|
@ -1069,7 +1103,7 @@ managed. If these are @b{CHIP SPECIFIC} they go here, if they are
|
|||
@subsection Work Areas
|
||||
|
||||
Work areas are small RAM areas used by OpenOCD to speed up downloads,
|
||||
and to download small snippets of code to program flash chips.
|
||||
and to download small snippets of code to program flash chips.
|
||||
|
||||
If the chip includes a form of ``on-chip-ram'' - and many do - define
|
||||
a reasonable work area and use the ``backup'' option.
|
||||
|
|
@ -1155,7 +1189,7 @@ can type a Tcl for() loop, set variables, etc.
|
|||
@* JIM-Tcl was introduced to OpenOCD in spring 2008.
|
||||
|
||||
@item @b{Need a crash course in Tcl?}
|
||||
@* See: @xref{Tcl Crash Course}.
|
||||
@*@xref{Tcl Crash Course}.
|
||||
@end itemize
|
||||
|
||||
@node Daemon Configuration
|
||||
|
|
@ -1232,8 +1266,8 @@ When not specified during the configuration stage,
|
|||
the port @var{number} defaults to 4444.
|
||||
@end deffn
|
||||
|
||||
@section GDB Configuration
|
||||
@anchor{GDB Configuration}
|
||||
@section GDB Configuration
|
||||
@cindex GDB
|
||||
@cindex GDB configuration
|
||||
You can reconfigure some GDB behaviors if needed.
|
||||
|
|
@ -1241,8 +1275,8 @@ The ones listed here are static and global.
|
|||
@xref{Target Create}, about declaring individual targets.
|
||||
@xref{Target Events}, about configuring target-specific event handling.
|
||||
|
||||
@deffn {Command} gdb_breakpoint_override <hard|soft|disable>
|
||||
@anchor{gdb_breakpoint_override}
|
||||
@deffn {Command} gdb_breakpoint_override <hard|soft|disable>
|
||||
Force breakpoint type for gdb @command{break} commands.
|
||||
The raison d'etre for this option is to support GDB GUI's which don't
|
||||
distinguish hard versus soft breakpoints, if the default OpenOCD and
|
||||
|
|
@ -1258,8 +1292,8 @@ Configures what OpenOCD will do when GDB detaches from the daemon.
|
|||
Default behaviour is @var{resume}.
|
||||
@end deffn
|
||||
|
||||
@deffn {Config command} gdb_flash_program <enable|disable>
|
||||
@anchor{gdb_flash_program}
|
||||
@deffn {Config command} gdb_flash_program <enable|disable>
|
||||
Set to @var{enable} to cause OpenOCD to program the flash memory when a
|
||||
vFlash packet is received.
|
||||
The default behaviour is @var{enable}.
|
||||
|
|
@ -1508,8 +1542,8 @@ The OpenOCD default value is 2 and for some systems a value of 10 has proved use
|
|||
@cindex ep93xx options
|
||||
Currently, there are no options available for the ep93xx interface.
|
||||
|
||||
@section JTAG Speed
|
||||
@anchor{JTAG Speed}
|
||||
@section JTAG Speed
|
||||
JTAG clock setup is part of system setup.
|
||||
It @emph{does not belong with interface setup} since any interface
|
||||
only knows a few of the constraints for the JTAG clock speed.
|
||||
|
|
@ -1987,7 +2021,7 @@ This chapter discusses how to create a GDB debug target. Before
|
|||
creating a ``target'' a JTAG tap DOTTED.NAME must exist first.
|
||||
|
||||
@section targets [NAME]
|
||||
@b{Note:} This command name is PLURAL - not singular.
|
||||
@b{Note:} This command name is PLURAL - not singular.
|
||||
|
||||
With NO parameter, this plural @b{targets} command lists all known
|
||||
targets in a human friendly form.
|
||||
|
|
@ -1998,7 +2032,7 @@ target to the given name. (i.e.: If there are multiple debug targets)
|
|||
Example:
|
||||
@verbatim
|
||||
(gdb) mon targets
|
||||
CmdName Type Endian ChainPos State
|
||||
CmdName Type Endian ChainPos State
|
||||
-- ---------- ---------- ---------- -------- ----------
|
||||
0: target0 arm7tdmi little 0 halted
|
||||
@end verbatim
|
||||
|
|
@ -2018,7 +2052,7 @@ The TARGET command accepts these sub-commands:
|
|||
@* Lists all supported target types (perhaps some are not yet in this document).
|
||||
@item @b{names}
|
||||
@* Lists all current debug target names, for example: 'str912.cpu' or 'pxa27.cpu' example usage:
|
||||
@verbatim
|
||||
@verbatim
|
||||
foreach t [target names] {
|
||||
puts [format "Target: %s\n" $t]
|
||||
}
|
||||
|
|
@ -2073,7 +2107,7 @@ configure it like this:
|
|||
# Report
|
||||
puts [format "The button is %s" $x]
|
||||
@end example
|
||||
|
||||
|
||||
In OpenOCD's terms, the ``target'' is an object just like a Tcl/Tk
|
||||
button. Commands available as a ``target object'' are:
|
||||
|
||||
|
|
@ -2120,9 +2154,9 @@ with odd reset situations and are not documented here.
|
|||
@* Invokes the specific event manually for the target
|
||||
@end itemize
|
||||
|
||||
@anchor{Target Events}
|
||||
@section Target Events
|
||||
@cindex events
|
||||
@anchor{Target Events}
|
||||
At various times, certain things can happen, or you want them to happen.
|
||||
|
||||
Examples:
|
||||
|
|
@ -2152,8 +2186,8 @@ creates and invokes small procedure. The second inlines the procedure.
|
|||
@}
|
||||
mychip.cpu configure -event gdb-attach my_attach_proc
|
||||
mychip.cpu configure -event gdb-attach @{
|
||||
puts "Reset..."
|
||||
reset halt
|
||||
puts "Reset..."
|
||||
reset halt
|
||||
@}
|
||||
@end example
|
||||
|
||||
|
|
@ -2243,8 +2277,8 @@ jtag configure DOTTED.NAME -event tap-disable @{
|
|||
@end example
|
||||
@end itemize
|
||||
|
||||
@section Target Create
|
||||
@anchor{Target Create}
|
||||
@section Target Create
|
||||
@cindex target
|
||||
@cindex target creation
|
||||
|
||||
|
|
@ -2455,8 +2489,7 @@ One feature distinguishing NOR flash from NAND or serial flash technologies
|
|||
is that for read access, it acts exactly like any other addressible memory.
|
||||
This means you can use normal memory read commands like @command{mdw} or
|
||||
@command{dump_image} with it, with no special @command{flash} subcommands.
|
||||
@xref{Memory access}.
|
||||
@xref{Image access}.
|
||||
@xref{Memory access}, and @ref{Image access}.
|
||||
|
||||
Write access works differently. Flash memory normally needs to be erased
|
||||
before it's written. Erasing a sector turns all of its bits to ones, and
|
||||
|
|
@ -2570,8 +2603,8 @@ The @var{num} parameter is a value shown by @command{flash banks}.
|
|||
@comment @option{flash erase_sector} using the same syntax.
|
||||
@end deffn
|
||||
|
||||
@section Flash Drivers, Options, and Commands
|
||||
@anchor{Flash Driver List}
|
||||
@section Flash Drivers, Options, and Commands
|
||||
As noted above, the @command{flash bank} command requires a driver name,
|
||||
and allows driver-specific options and behaviors.
|
||||
Some drivers also activate driver-specific commands.
|
||||
|
|
@ -3273,8 +3306,8 @@ bypassing hardware ECC logic.
|
|||
with the wrong ECC data can cause them to be marked as bad.
|
||||
@end deffn
|
||||
|
||||
@section NAND Drivers, Options, and Commands
|
||||
@anchor{NAND Driver List}
|
||||
@section NAND Drivers, Options, and Commands
|
||||
As noted above, the @command{nand device} command allows
|
||||
driver-specific options and behaviors.
|
||||
Some controllers also activate controller-specific commands.
|
||||
|
|
@ -3376,9 +3409,9 @@ port is 5555.
|
|||
@cindex shutdown
|
||||
@*Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
|
||||
|
||||
@anchor{debug_level}
|
||||
@subsection debug_level [@var{n}]
|
||||
@cindex debug_level
|
||||
@anchor{debug_level}
|
||||
@*Display or adjust debug level to n<0-3>
|
||||
|
||||
@subsection fast [@var{enable|disable}]
|
||||
|
|
@ -3485,8 +3518,8 @@ the code that was executed may have left the hardware in an unknown
|
|||
state.
|
||||
|
||||
|
||||
@section Memory access commands
|
||||
@anchor{Memory access}
|
||||
@section Memory access commands
|
||||
@subsection meminfo
|
||||
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
|
||||
|
|
@ -3523,17 +3556,16 @@ SDRAM controller to enable SDRAM.
|
|||
@*write memory byte (8bit)
|
||||
@end itemize
|
||||
|
||||
@section Image loading commands
|
||||
@anchor{Image access}
|
||||
@section Image loading commands
|
||||
@anchor{load_image}
|
||||
@subsection load_image
|
||||
@b{load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
|
||||
@cindex load_image
|
||||
@anchor{load_image}
|
||||
@*Load image <@var{file}> to target memory at <@var{address}>
|
||||
@subsection fast_load_image
|
||||
@b{fast_load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
|
||||
@cindex fast_load_image
|
||||
@anchor{fast_load_image}
|
||||
@*Normally you should be using @b{load_image} or GDB load. However, for
|
||||
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
|
||||
|
|
@ -3545,12 +3577,11 @@ separately.
|
|||
@subsection fast_load
|
||||
@b{fast_load}
|
||||
@cindex fast_image
|
||||
@anchor{fast_image}
|
||||
@*Loads an image stored in memory by @b{fast_load_image} to the current target. Must be preceeded by fast_load_image.
|
||||
@anchor{dump_image}
|
||||
@subsection dump_image
|
||||
@b{dump_image} <@var{file}> <@var{address}> <@var{size}>
|
||||
@cindex dump_image
|
||||
@anchor{dump_image}
|
||||
@*Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
|
||||
(binary) <@var{file}>.
|
||||
@subsection verify_image
|
||||
|
|
@ -4299,9 +4330,9 @@ openocd -f interface/parport.cfg -f target/at91r40008.cfg \
|
|||
OpenOCD complies with the remote gdbserver protocol, and as such can be used
|
||||
to debug remote targets.
|
||||
|
||||
@anchor{Connecting to GDB}
|
||||
@section Connecting to GDB
|
||||
@cindex Connecting to GDB
|
||||
@anchor{Connecting to GDB}
|
||||
Use GDB 6.7 or newer with OpenOCD if you run into trouble. For
|
||||
instance GDB 6.3 has a known bug that produces bogus memory access
|
||||
errors, which has since been fixed: look up 1836 in
|
||||
|
|
@ -4555,8 +4586,8 @@ halt
|
|||
@chapter FAQ
|
||||
@cindex faq
|
||||
@enumerate
|
||||
@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
|
||||
@anchor{FAQ RTCK}
|
||||
@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
|
||||
@cindex RTCK
|
||||
@cindex adaptive clocking
|
||||
@*
|
||||
|
|
@ -4660,7 +4691,7 @@ arm7_9_add_breakpoint(): sw breakpoint requested, but software breakpoints not e
|
|||
|
||||
GDB issues software breakpoints when a normal breakpoint is requested, or to implement
|
||||
source-line single-stepping. On ARMv4T systems, like ARM7TDMI, ARM720T or ARM920T,
|
||||
software breakpoints consume one of the two available hardware breakpoints.
|
||||
software breakpoints consume one of the two available hardware breakpoints.
|
||||
|
||||
@item @b{LPC2000 Flash} When erasing or writing LPC2000 on-chip flash, the operation fails at random.
|
||||
|
||||
|
|
@ -4811,7 +4842,7 @@ log file, I can see these error messages: Error: arm7_9_common.c:561
|
|||
arm7_9_execute_sys_speed(): timeout waiting for SYSCOMP
|
||||
|
||||
TODO.
|
||||
|
||||
|
||||
@end enumerate
|
||||
|
||||
@node Tcl Crash Course
|
||||
|
|
@ -5028,7 +5059,7 @@ MyForCommand( void *interp,
|
|||
SetResult( interp, "WRONG number of parameters");
|
||||
return ERROR;
|
||||
@}
|
||||
|
||||
|
||||
// argv[0] = the ascii string just like C
|
||||
|
||||
// Execute the start statement.
|
||||
|
|
@ -5051,7 +5082,7 @@ MyForCommand( void *interp,
|
|||
SetResult( interp, "" );
|
||||
return SUCCESS;
|
||||
@}
|
||||
@end example
|
||||
@end example
|
||||
|
||||
Every other command IF, WHILE, FORMAT, PUTS, EXPR, everything works
|
||||
in the same basic way.
|
||||
|
|
@ -5071,7 +5102,7 @@ substituted on the orginal command line.
|
|||
@* SOURCE reads a file and executes as a script.
|
||||
@end enumerate
|
||||
@subsection format command
|
||||
@b{Where:} Generally occurs in numerous places.
|
||||
@b{Where:} Generally occurs in numerous places.
|
||||
@* Tcl has no command like @b{printf()}, instead it has @b{format}, which is really more like
|
||||
@b{sprintf()}.
|
||||
@b{Example}
|
||||
|
|
|
|||
Loading…
Reference in New Issue