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
-\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename openocd.info
@c %**start of header
@setfilename openocd.info
-@settitle Open On-Chip Debugger (OpenOCD)
+@settitle OpenOCD User's Guide
@dircategory Development
@direntry
@dircategory Development
@direntry
-@paragraphindent 0
-* OpenOCD: (openocd). Open On-Chip Debugger.
+* OpenOCD: (openocd). OpenOCD User's Guide
@c %**end of header
@include version.texi
@copying
@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}
@itemize @bullet
@item Copyright @copyright{} 2008 The OpenOCD Project
@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
-@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}
@subtitle @value{UPDATED}
@page
@vskip 0pt plus 1filll
@insertcopying
@page
@vskip 0pt plus 1filll
@insertcopying
@summarycontents
@contents
@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
@menu
* About:: About OpenOCD
@menu
* About:: About OpenOCD
* FAQ:: Frequently Asked Questions
* Tcl Crash Course:: Tcl Crash Course
* License:: GNU Free Documentation License
* 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
@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
@uref{http://openocd.berlios.de/web/}
@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
@node Developers
@chapter OpenOCD Developer Resources
The OpenOCD Developer Mailing List provides the primary means of
communication between developers:
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:
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
@node Building OpenOCD
@chapter Building OpenOCD
svn checkout svn://svn.berlios.de/openocd/trunk openocd
@end example
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
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
# variable: _TARGETNAME = network.cpu
# other commands can refer to the "network.cpu" tap.
$_TARGETNAME configure .... params for this CPU..
# 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..
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]
unset ENDIAN
set CHIPNAME xilinx
source [find target/spartan3.cfg]
@example
# SIMPLE example
@example
# SIMPLE example
-if @{ [info exists CHIPNAME] @} @{
- set _CHIPNAME $CHIPNAME
-@} else @{
+if @{ [info exists CHIPNAME] @} @{
+ set _CHIPNAME $CHIPNAME
+@} else @{
set _CHIPNAME sam7x256
@}
set _CHIPNAME sam7x256
@}
-if @{ [info exists ENDIAN] @} @{
- set _ENDIAN $ENDIAN
-@} else @{
+if @{ [info exists ENDIAN] @} @{
+ set _ENDIAN $ENDIAN
+@} else @{
@subsection Work Areas
Work areas are small RAM areas used by OpenOCD to speed up downloads,
@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.
If the chip includes a form of ``on-chip-ram'' - and many do - define
a reasonable work area and use the ``backup'' option.
@* JIM-Tcl was introduced to OpenOCD in spring 2008.
@item @b{Need a crash course in Tcl?}
@* 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
@end itemize
@node Daemon Configuration
the port @var{number} defaults to 4444.
@end deffn
the port @var{number} defaults to 4444.
@end deffn
-@section GDB Configuration
@anchor{GDB Configuration}
@anchor{GDB Configuration}
+@section GDB Configuration
@cindex GDB
@cindex GDB configuration
You can reconfigure some GDB behaviors if needed.
@cindex GDB
@cindex GDB configuration
You can reconfigure some GDB behaviors if needed.
@xref{Target Create}, about declaring individual targets.
@xref{Target Events}, about configuring target-specific event handling.
@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}
@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
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
Default behaviour is @var{resume}.
@end deffn
Default behaviour is @var{resume}.
@end deffn
-@deffn {Config command} gdb_flash_program <enable|disable>
@anchor{gdb_flash_program}
@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}.
Set to @var{enable} to cause OpenOCD to program the flash memory when a
vFlash packet is received.
The default behaviour is @var{enable}.
@cindex ep93xx options
Currently, there are no options available for the ep93xx interface.
@cindex ep93xx options
Currently, there are no options available for the ep93xx interface.
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.
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.
creating a ``target'' a JTAG tap DOTTED.NAME must exist first.
@section targets [NAME]
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.
With NO parameter, this plural @b{targets} command lists all known
targets in a human friendly form.
Example:
@verbatim
(gdb) mon targets
Example:
@verbatim
(gdb) mon targets
- CmdName Type Endian ChainPos State
+ CmdName Type Endian ChainPos State
-- ---------- ---------- ---------- -------- ----------
0: target0 arm7tdmi little 0 halted
@end verbatim
-- ---------- ---------- ---------- -------- ----------
0: target0 arm7tdmi little 0 halted
@end verbatim
@* 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:
@* 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:
foreach t [target names] {
puts [format "Target: %s\n" $t]
}
foreach t [target names] {
puts [format "Target: %s\n" $t]
}
# Report
puts [format "The button is %s" $x]
@end example
# 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:
In OpenOCD's terms, the ``target'' is an object just like a Tcl/Tk
button. Commands available as a ``target object'' are:
@* Invokes the specific event manually for the target
@end itemize
@* Invokes the specific event manually for the target
@end itemize
@section Target Events
@cindex events
@section Target Events
@cindex events
At various times, certain things can happen, or you want them to happen.
Examples:
At various times, certain things can happen, or you want them to happen.
Examples:
@}
mychip.cpu configure -event gdb-attach my_attach_proc
mychip.cpu configure -event gdb-attach @{
@}
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
@end itemize
@end example
@end itemize
@cindex target
@cindex target creation
@cindex target
@cindex target creation
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.
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
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
@comment @option{flash erase_sector} using the same syntax.
@end deffn
@comment @option{flash erase_sector} using the same syntax.
@end deffn
-@section Flash Drivers, Options, and Commands
@anchor{Flash Driver List}
@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.
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.
with the wrong ECC data can cause them to be marked as bad.
@end deffn
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}
@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.
As noted above, the @command{nand device} command allows
driver-specific options and behaviors.
Some controllers also activate controller-specific commands.
@cindex shutdown
@*Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
@cindex shutdown
@*Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
@subsection debug_level [@var{n}]
@cindex debug_level
@subsection debug_level [@var{n}]
@cindex debug_level
@*Display or adjust debug level to n<0-3>
@subsection fast [@var{enable|disable}]
@*Display or adjust debug level to n<0-3>
@subsection fast [@var{enable|disable}]
-@section Memory access commands
+@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
@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
@*write memory byte (8bit)
@end itemize
@*write memory byte (8bit)
@end itemize
-@section Image loading commands
+@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
@subsection load_image
@b{load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
@cindex 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
@*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
@*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
@subsection fast_load
@b{fast_load}
@cindex fast_image
@subsection fast_load
@b{fast_load}
@cindex fast_image
@*Loads an image stored in memory by @b{fast_load_image} to the current target. Must be preceeded by fast_load_image.
@*Loads an image stored in memory by @b{fast_load_image} to the current target. Must be preceeded by fast_load_image.
@subsection dump_image
@b{dump_image} <@var{file}> <@var{address}> <@var{size}>
@cindex dump_image
@subsection dump_image
@b{dump_image} <@var{file}> <@var{address}> <@var{size}>
@cindex dump_image
@*Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
(binary) <@var{file}>.
@subsection verify_image
@*Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
(binary) <@var{file}>.
@subsection verify_image
OpenOCD complies with the remote gdbserver protocol, and as such can be used
to debug remote targets.
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
@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
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
@chapter FAQ
@cindex faq
@enumerate
@chapter FAQ
@cindex faq
@enumerate
-@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
+@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
@cindex RTCK
@cindex adaptive clocking
@*
@cindex RTCK
@cindex adaptive clocking
@*
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,
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.
@item @b{LPC2000 Flash} When erasing or writing LPC2000 on-chip flash, the operation fails at random.
arm7_9_execute_sys_speed(): timeout waiting for SYSCOMP
TODO.
arm7_9_execute_sys_speed(): timeout waiting for SYSCOMP
TODO.
@end enumerate
@node Tcl Crash Course
@end enumerate
@node Tcl Crash Course
SetResult( interp, "WRONG number of parameters");
return ERROR;
@}
SetResult( interp, "WRONG number of parameters");
return ERROR;
@}
// argv[0] = the ascii string just like C
// Execute the start statement.
// argv[0] = the ascii string just like C
// Execute the start statement.
SetResult( interp, "" );
return SUCCESS;
@}
SetResult( interp, "" );
return SUCCESS;
@}
Every other command IF, WHILE, FORMAT, PUTS, EXPR, everything works
in the same basic way.
Every other command IF, WHILE, FORMAT, PUTS, EXPR, everything works
in the same basic way.
@* SOURCE reads a file and executes as a script.
@end enumerate
@subsection format command
@* 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}
@* Tcl has no command like @b{printf()}, instead it has @b{format}, which is really more like
@b{sprintf()}.
@b{Example}