X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=15144d0265818d89ef0cc3435f6ada92066abcbf;hb=7e8892ca39d18315c703298d6332d52acbea1964;hp=9e310f3386d6ae49ea606913a5383251d0342baa;hpb=53bbd36c7d5adfe86aef071e2effbbfa804d0054;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 9e310f3386..15144d0265 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -2,16 +2,33 @@ @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 @@ -19,12 +36,14 @@ @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. @@ -84,7 +103,7 @@ latest version (make sure there is no (non-svn) directory called "openocd" in th 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. @@ -118,31 +137,31 @@ Bootstrap generates the configure script, and prepares building on your system. @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 @@ -159,6 +178,10 @@ locations, i.e. /usr/include, /usr/lib. @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. @@ -172,7 +195,10 @@ the most information, including debug messages. The default setting is "2", outp only informational messages, warnings and errors. You can also change this setting from within a telnet or gdb session (@option{debug_level }). -You can redirect all output from the daemon to a file using the @option{-l } switch. +You can redirect all output from the daemon to a file using the @option{-l } switch. + +Search paths for config/script files can be added to openocd by using +the @option{-s } switch. @node Configuration @chapter Configuration @@ -247,12 +273,18 @@ Cirrus Logic EP93xx based single-board computer bit-banging (in development) @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} @@ -261,6 +293,13 @@ speed. The actual effect of this option depends on the JTAG interface used. 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. @@ -434,6 +473,7 @@ Defines a target that should be debugged. Currently supported types are: @item arm926ejs @item arm966e @item cortex_m3 +@item feroceon @item xscale @end itemize @@ -1136,7 +1176,7 @@ flash probe 0 @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 @@ -1172,7 +1212,7 @@ flash bank str7x 0x40000000 0x00040000 0 0 0 STR71x @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 @@ -1213,7 +1253,7 @@ flash bank str7x 0x20000000 0x000040000 0 0 0 STR75x @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 @@ -1290,7 +1330,7 @@ flash bank str9x 0x00000000 0x00080000 0 0 0 @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 @@ -1369,7 +1409,7 @@ flash bank stm32x 0x08000000 0x00020000 0 0 0 @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 @@ -1404,7 +1444,7 @@ flash bank lpc2000 0x0 0x40000 0 0 0 lpc2000_v1 14765 calc_checksum @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 @@ -1440,7 +1480,7 @@ flash bank lpc2000 0x0 0x7d000 0 0 0 lpc2000_v1 14765 calc_checksum @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 @@ -1476,7 +1516,7 @@ flash bank lpc2000 0x0 0x40000 0 0 0 lpc2000_v1 14765 calc_checksum @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 @@ -1509,7 +1549,7 @@ run_and_halt_time 0 30 @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 @@ -1555,7 +1595,7 @@ flash bank at91sam7 0 0 0 0 0 @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 @@ -1641,7 +1681,7 @@ flash bank cfi 0x60000000 0x1000000 2 2 0 @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 @@ -1765,7 +1805,7 @@ that the openocd option @option{arm7_9 force_hw_bkpts} is not required when 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. @@ -1786,7 +1826,7 @@ can be used. @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 @@ -1799,7 +1839,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, -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}. @@ -1817,7 +1857,7 @@ I keep getting "Error: amt_jtagaccel.c:184 amt_wait_scan_busy(): amt_jtagaccel t 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(): @@ -1843,8 +1883,8 @@ Toolchain (Eclipse, arm-elf-gcc, arm-elf-gdb), the debugging seems to be 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. @@ -1856,7 +1896,7 @@ What does that mean and what might be the reason for this? 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". @@ -1868,8 +1908,8 @@ has closed the connection to OpenOCD. This might be a GDB issue. @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? @@ -1891,6 +1931,8 @@ banks - a target references a jtag_device and a flash bank references a target). @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