@c %**start of header
@setfilename openocd.info
@settitle Open On-Chip Debugger (openocd)
+@dircategory Development
+@direntry
+* OpenOCD: (openocd). Open On-Chip Debugger.
+@end direntry
@c %**end of header
@include version.texi
+@copying
+Copyright @copyright{} 2007-2008 Spen @email{spen@@spen-soft.co.uk}
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end quotation
+@end copying
+
@titlepage
@title Open On-Chip Debugger (openocd)
@subtitle Edition @value{EDITION} for openocd version @value{VERSION}
@subtitle @value{UPDATED}
@page
@vskip 0pt plus 1filll
+@insertcopying
@end titlepage
@contents
@node Top, About, , (dir)
@top OpenOCD
-This is edition @value{EDITION} of the openocd manual for version
-@value{VERSION}, @value{UPDATED}
+This manual documents edition @value{EDITION} of the Open On-Chip Debugger
+(openocd) version @value{VERSION}, @value{UPDATED}.
+
+@insertcopying
@menu
* About:: About Openocd.
-* Developers::
+* Developers:: Openocd developers
* Building:: Building Openocd
* Running:: Running Openocd
* Configuration:: Openocd Configuration.
current directory):
@smallexample
- svn checkout svn://svn.berlios.de/openocd/trunk
+ svn checkout svn://svn.berlios.de/openocd/trunk openocd
@end smallexample
Building the OpenOCD requires a recent version of the GNU autotools.
@smallexample
./configure
@end smallexample
-Configure generates the Makefiles used to build OpenOCD
+Configure generates the Makefiles used to build OpenOCD.
@smallexample
make
@end smallexample
-Make builds the OpenOCD, and places the final executable in ./src/
+Make builds the OpenOCD, and places the final executable in ./src/.
The configure script takes several options, specifying which JTAG interfaces
should be included:
@itemize @bullet
@item
---enable-parport
+@option{--enable-parport}
@item
---enable-parport_ppdev
+@option{--enable-parport_ppdev}
@item
---enable-amtjtagaccel
+@option{--enable-amtjtagaccel}
@item
---enable-ft2232_ftd2xx
+@option{--enable-ft2232_ftd2xx}
@footnote{Using the latest D2XX drivers from FTDI and following their installation
instructions, I had to use @option{--enable-ft2232_libftd2xx} for the OpenOCD to
-build properly}
+build properly.}
@item
---enable-ft2232_libftdi
+@option{--enable-ft2232_libftdi}
@item
---with-ftd2xx=/path/to/d2xx/
+@option{--with-ftd2xx=/path/to/d2xx/}
@end itemize
If you want to access the parallel port using the PPDEV interface you have to specify
@node Running
@chapter Running
@cindex running openocd
+@cindex --configfile
+@cindex --debug_level
+@cindex --logfile
+@cindex --search
The OpenOCD runs as a daemon, waiting for connections from clients (Telnet or GDB).
Run with @option{--help} or @option{-h} to view the available command line arguments.
only informational messages, warnings and errors. You can also change this setting
from within a telnet or gdb session (@option{debug_level <n>}).
-You can redirect all output from the daemon to a file using the @option{-l <logfile>} switch.
+You can redirect all output from the daemon to a file using the @option{-l <logfile>} switch.
+
+Search paths for config/script files can be added to openocd by using
+the @option{-s <search>} switch.
@node Configuration
@chapter Configuration
@end itemize
@itemize @bullet
-@item @b{jtag_speed} <@var{number}>
+@item @b{jtag_speed} <@var{reset speed}> <@var{post reset speed}>
@cindex jtag_speed
Limit the maximum speed of the JTAG interface. Usually, a value of zero means maximum
-speed. The actual effect of this option depends on the JTAG interface used.
-
+speed. The actual effect of this option depends on the JTAG interface used. Reset
+speed is used during reset and post reset speed after reset. post reset speed
+is optional, in which case the reset speed is used.
@itemize @minus
+
+
+
+
+
@item wiggler: maximum speed / @var{number}
@item ft2232: 6MHz / (@var{number}+1)
@item amt jtagaccel: 8 / 2**@var{number}
Note: Make sure the jtag clock is no more than @math{1/6th × CPU-Clock}. This is
especially true for synthesized cores (-S).
+@item @b{jtag_khz} <@var{reset speed kHz}> <@var{post reset speed kHz}>
+@cindex jtag_khz
+Same as jtag_speed, except that the speed is specified in maximum kHz. If
+the device can not support the rate asked for, or can not translate from
+kHz to jtag_speed, then an error is returned. 0 means RTCK. If RTCK
+is not supported, then an error is reported.
+
@item @b{reset_config} <@var{signals}> [@var{combination}] [@var{trst_type}] [@var{srst_type}]
@cindex reset_config
The configuration of the reset signals available on the JTAG interface AND the target.
@item arm926ejs
@item arm966e
@item cortex_m3
+@item feroceon
@item xscale
@end itemize
Configures a flash bank at <@var{base}> of <@var{size}> bytes and <@var{chip_width}>
and <@var{bus_width}> bytes using the selected flash <driver>.
-@item @b{flash autoerase} <@option{on}|@option{off}>
-@cindex flash autoerase
+@item @b{flash auto_erase} <@option{on}|@option{off}>
+@cindex flash auto_erase
auto erase flash banks prior to writing. Currently only works when using
@option{flash write_image} command. Default is @option{off}.
@end itemize
specific information about the current state are printed. An optional parameter
allows continuous polling to be enabled and disabled.
-@item @b{halt}
+@item @b{halt} [@option{ms}]
@cindex halt
-Send a halt request to the target. The debugger signals the debug request,
-and waits for the target to enter debug mode.
+Send a halt request to the target and waits for it to halt for [@option{ms}].
+Default [@option{ms}] is 5 seconds if no arg given.
+Optional arg @option{ms} is a timeout in milliseconds. Using 0 as the [@option{ms}]
+will stop openocd from waiting.
+
+@item @b{wait_halt} [@option{ms}]
+@cindex wait_halt
+Wait for the target to enter debug mode. Optional [@option{ms}] is
+a timeout in milliseconds. Default [@option{ms}] is 5 seconds if no
+arg given.
@item @b{resume} [@var{address}]
@cindex resume
Resume the target at its current code position, or at an optional address.
+Openocd will wait 5 seconds for the target to resume.
@item @b{step} [@var{address}]
@cindex step
@section STR71x Script
@cindex STR71x Script
-The following script was used with an Amontec JTAGkey and a STR710 / STR711 cpu:
+The following script was used with an Amontec JTAGkey and a STR710 / STR711 CPU:
@smallexample
#daemon configuration
telnet_port 4444
@section STR750 Script
@cindex STR750 Script
-The following script was used with an Amontec JTAGkey and a STR750 cpu:
+The following script was used with an Amontec JTAGkey and a STR750 CPU:
@smallexample
#daemon configuration
telnet_port 4444
@section STR912 Script
@cindex STR912 Script
-The following script was used with an Amontec JTAGkey and a STR912 cpu:
+The following script was used with an Amontec JTAGkey and a STR912 CPU:
@smallexample
#daemon configuration
telnet_port 4444
@section STM32x Script
@cindex STM32x Script
-The following script was used with an Amontec JTAGkey and a STM32x cpu:
+The following script was used with an Amontec JTAGkey and a STM32x CPU:
@smallexample
#daemon configuration
telnet_port 4444
@section LPC2129 Script
@cindex LPC2129 Script
-The following script was used with an wiggler PP and a LPC-2129 cpu:
+The following script was used with an wiggler PP and a LPC-2129 CPU:
@smallexample
#daemon configuration
telnet_port 4444
@section LPC2148 Script
@cindex LPC2148 Script
-The following script was used with an Amontec JTAGkey and a LPC2148 cpu:
+The following script was used with an Amontec JTAGkey and a LPC2148 CPU:
@smallexample
#daemon configuration
telnet_port 4444
@section LPC2294 Script
@cindex LPC2294 Script
-The following script was used with an Amontec JTAGkey and a LPC2294 cpu:
+The following script was used with an Amontec JTAGkey and a LPC2294 CPU:
@smallexample
#daemon configuration
telnet_port 4444
@section AT91R40008 Script
@cindex AT91R40008 Script
-The following script was used with an Amontec JTAGkey and a AT91R40008 cpu:
+The following script was used with an Amontec JTAGkey and a AT91R40008 CPU:
@smallexample
#daemon configuration
telnet_port 4444
@section AT91SAM7s Script
@cindex AT91SAM7s Script
-The following script was used with an Olimex ARM-JTAG-OCD and a AT91SAM7S64 cpu:
+The following script was used with an Olimex ARM-JTAG-OCD and a AT91SAM7S64 CPU:
@smallexample
#daemon configuration
telnet_port 4444
@section XSCALE IXP42x Script
@cindex XSCALE IXP42x Script
-The following script was used with an Amontec JTAGkey-Tiny and a xscale ixp42x cpu:
+The following script was used with an Amontec JTAGkey-Tiny and a xscale ixp42x CPU:
@smallexample
#daemon configuration
telnet_port 4444
@section Hilscher netX 100 / 500 Script
@cindex Hilscher netX 100 / 500 Script
The following script was used with an Amontec JTAGkey and a Hilscher
-netX 500 cpu:
+netX 500 CPU:
@smallexample
#daemon configuration
telnet_port 4444
using a memory map.
To view the configured memory map in gdb, use the gdb command @option{info mem}
-All other unasigned addresses within gdb are treated as ram.
+All other unasigned addresses within gdb are treated as RAM.
If @option{gdb_flash_program enable} is also used, gdb will be able to
program any flash memory using the vFlash interface.
@chapter FAQ
@cindex faq
@enumerate
-@item OpenOCD complains about a missing cygwin1.dll
+@item OpenOCD complains about a missing cygwin1.dll.
Make sure you have Cygwin installed, or at least a version of OpenOCD that
claims to come with all the necessary dlls. When using Cygwin, try launching
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,
-and are therefor disabled by default. If your code is running from RAM, you
+and are therefore disabled by default. If your code is running from RAM, you
can enable software breakpoints with the @option{arm7_9 sw_bkpts enable} command. If
your code resides in Flash, you can't use software breakpoints, but you can force
OpenOCD to use hardware breakpoints instead: @option{arm7_9 force_hw_bkpts enable}.
out while waiting for end of scan, rtck was disabled".
Make sure your PC's parallel port operates in EPP mode. You might have to try several
-settings in your PC Bios (ECP, EPP, and different versions of those).
+settings in your PC BIOS (ECP, EPP, and different versions of those).
@item When debugging with the OpenOCD and GDB (plain GDB, Insight, or Eclipse),
I get lots of "Error: arm7_9_common.c:1771 arm7_9_read_memory():
unstable. When single-stepping over large blocks of code, GDB and OpenOCD
quit with an error message. Is there a stability issue with OpenOCD?
-No, this is not a stability issue concering OpenOCD. Most users have solved
-this issue by simply using a self-powered USB Hub, which they connect their
+No, this is not a stability issue concerning OpenOCD. Most users have solved
+this issue by simply using a self-powered USB hub, which they connect their
Amontec JTAGkey to. Apparently, some computers do not provide a USB power
supply stable enough for the Amontec JTAGkey to be operated.
First of all, the reason might be the USB power supply. Try using a self-powered
hub instead of a direct connection to your computer. Secondly, the error code 4
corresponds to an FT_IO_ERROR, which means that the driver for the FTDI USB
-Chip ran into some sort of error - this points us to a USB problem.
+chip ran into some sort of error - this points us to a USB problem.
@item When using the Amontec JTAGkey, sometimes OpenOCD crashes with the following
error message: "Error: gdb_server.c:101 gdb_get_char(): read: 10054".
@item In the configuration file in the section where flash device configurations
are described, there is a parameter for specifying the clock frequency for
LPC2000 internal flash devices (e.g.
-@option{flash bank lpc2000 0x0 0x40000 0 0 lpc2000_v1 0 14746 calc_checksum}),
-which must be sepcified in kilohertz. However, I do have a quartz crystal of a
+@option{flash bank lpc2000 0x0 0x40000 0 0 0 lpc2000_v1 14746 calc_checksum}),
+which must be specified in kilohertz. However, I do have a quartz crystal of a
frequency that contains fractions of kilohertz (e.g. 14,745,600 Hz, i.e. 14,745.600 kHz).
Is it possible to specify real numbers for the clock frequency?
@item Sometimes my debugging session terminates with an error. When I look into the
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
Code Review / openocd.git / blobdiff