X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=19736ace3042fef4b6a80eb4c6a1f6a6f49cdc7a;hp=0f5bd9167673b5ab074416e47fd437a0dbdd77f0;hb=651ba91465d05f64b7650334499e320f6851936c;hpb=8c634335b41a805998e5bae05328bb47057cce0b diff --git a/doc/openocd.texi b/doc/openocd.texi index 0f5bd91676..19736ace30 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -4,8 +4,12 @@ @settitle Open On-Chip Debugger (openocd) @c %**end of header +@include version.texi + @titlepage @title Open On-Chip Debugger (openocd) +@subtitle Edition @value{EDITION} for openocd version @value{VERSION} +@subtitle @value{UPDATED} @page @vskip 0pt plus 1filll @end titlepage @@ -15,7 +19,8 @@ @node Top, About, , (dir) @top OpenOCD -The Manual always document the latest version of OpenOCD available from SVN. +This is edition @value{EDITION} of the openocd manual for version +@value{VERSION}, @value{UPDATED} @menu * About:: About Openocd. @@ -25,6 +30,7 @@ The Manual always document the latest version of OpenOCD available from SVN. * Configuration:: Openocd Configuration. * Commands:: Openocd Commands * Sample Scripts:: Sample Target Scripts +* GDB and Openocd:: Using GDB and Openocd * FAQ:: Frequently Asked Questions * License:: GNU Free Documentation License * Index:: Main index. @@ -67,11 +73,11 @@ as numerous bugfixes and enhancements. See the AUTHORS file for regular contribu You can download the current SVN version with SVN client of your choice from the following repositories: - (@uref{svn://svn.berlios.de/openocd/trunk} + (@uref{svn://svn.berlios.de/openocd/trunk}) or - (@uref{http://svn.berlios.de/svnroot/repos/openocd/trunk} + (@uref{http://svn.berlios.de/svnroot/repos/openocd/trunk}) Using the SVN command line client, you could use the following command to fetch the latest version (make sure there is no (non-svn) directory called "openocd" in the @@ -91,8 +97,8 @@ from the logs of one user - correct me if I'm wrong). You further need the appropriate driver files, if you want to build support for a FTDI FT2232 based interface: @itemize @bullet -@item @b{ftdi2232} libftdi ((@uref{http://www.intra2net.com/opensource/ftdi/}) -@item @b{ftd2xx} libftd2xx ((@uref{http://www.ftdichip.com/Drivers/D2XX.htm}) +@item @b{ftdi2232} libftdi (@uref{http://www.intra2net.com/opensource/ftdi/}) +@item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm}) @item When using the Amontec JTAGkey, you have to get the drivers from the Amontec homepage (@uref{www.amontec.com}), as the JTAGkey uses a non-standard VID/PID. @end itemize @@ -142,7 +148,7 @@ build properly} If you want to access the parallel port using the PPDEV interface you have to specify both the @option{--enable-parport} AND the @option{--enable-parport_ppdev} option since the @option{--enable-parport_ppdev} option actually is an option to the parport driver -(see (@uref{http://forum.sparkfun.com/viewtopic.php?t=3795} for more info). +(see @uref{http://forum.sparkfun.com/viewtopic.php?t=3795} for more info). Cygwin users have to specify the location of the FTDI D2XX package. This should be an absolute path containing no spaces. @@ -189,6 +195,22 @@ Port on which to listen for incoming telnet connections @cindex gdb_port First port on which to listen for incoming GDB connections. The GDB port for the first target will be gdb_port, the second target will listen on gdb_port + 1, and so on. +@item @b{gdb_detach} <@var{resume|reset|halt|nothing}> +@cindex gdb_detach +Configures what openocd will do when gdb detaches from the daeman. +Default behaviour is <@var{resume}> +@item @b{gdb_memory_map} <@var{enable|disable}> +@cindex gdb_memory_map +Set to <@var{enable}> so that openocd will send the memory configuration to gdb when +requested. gdb will then know when to set hardware breakpoints, and program flash +using the gdb load command. @option{gdb_flash_program enable} will also need enabling +for flash programming to work. +Default behaviour is <@var{disable}> +@item @b{gdb_flash_program} <@var{enable|disable}> +@cindex gdb_flash_program +Set to <@var{enable}> so that openocd will program the flash memory when a +vFlash packet is received. +Default behaviour is <@var{disable}> @item @b{daemon_startup} <@var{mode}> either @samp{attach} or @samp{reset} @cindex daemon_startup Tells the OpenOCD whether it should reset the target when the daemon is launched, or @@ -228,7 +250,16 @@ Cirrus Logic EP93xx based single-board computer bit-banging (in development) @item @b{jtag_speed} <@var{number}> @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. + +@itemize @minus +@item wiggler: maximum speed / @var{number} +@item ft2232: 6MHz / (@var{number}+1) +@item amt jtagaccel: 8 / 2**@var{number} +@end itemize + +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{reset_config} <@var{signals}> [@var{combination}] [@var{trst_type}] [@var{srst_type}] @cindex reset_config @@ -320,6 +351,10 @@ This is also the layout used by the HollyGates design @cindex flashlink ST Parallel cable. @end itemize +@item @b{parport_write_on_exit} <@var{on|off}> +@cindex parport_write_on_exit +This will configure the parallel driver to write a known value to the parallel +interface on exiting openocd @end itemize @section amt_jtagaccel options @@ -356,6 +391,14 @@ Luminary Micro EVB_LM3S811 as a JTAG interface (not onboard processor), no TRST SRST signals on external connector @item comstick Hitex STR9 comstick +@item stm32stick +Hitex STM32 Performance Stick +@item flyswatter +Tin Can Tools Flyswatter +@item turtelizer2 +egnite Software turtelizer2 +@item oocdlink +OOCDLink @end itemize @item @b{ft2232_vid_pid} <@var{vid}> <@var{pid}> @@ -430,8 +473,9 @@ unavailable for some time during startup (like the STR7 series), you can't use @item @b{target_script} <@var{target#}> <@var{event}> <@var{script_file}> @cindex target_script -Event is either @var{reset} or @var{post_halt} or @var{pre_resume}. -TODO: describe exact semantic of events +Event is either @option{reset}, @option{post_halt}, @option{pre_resume} or @option{gdb_program_config} + +TODO: describe exact semantic of events @item @b{run_and_halt_time} <@var{target#}> <@var{time_in_ms}> @cindex run_and_halt_time The amount of time the debugger should wait after releasing reset before it asserts @@ -516,11 +560,13 @@ CFI flashes require the number of the target they're connected to as an addition argument. The CFI driver makes use of a working area (specified for the target) to significantly speed up operation. +@var{chip_width} and @var{bus_width} are specified in bytes. + @subsection at91sam7 options @cindex at91sam7 options -@b{flash bank at91sam7} 0 0 0 0 <@var{target#>}> -AT91SAM7 flashes only require the target#, all other values are looked up after +@b{flash bank at91sam7} 0 0 0 0 <@var{target#}> +AT91SAM7 flashes only require the @var{target#}, all other values are looked up after reading the chip-id and type. @subsection str7 options @@ -552,13 +598,13 @@ Use the standard str9 driver for programming. @cindex stellaris (LM3Sxxx) options @b{flash bank stellaris} <@var{base}> <@var{size}> 0 0 <@var{target#}> -stellaris flash plugin only require the target#. +stellaris flash plugin only require the @var{target#}. @subsection stm32x options @cindex stm32x options @b{flash bank stm32x} <@var{base}> <@var{size}> 0 0 <@var{target#}> -stm32x flash plugin only require the target#. +stm32x flash plugin only require the @var{target#}. @node Commands @chapter Commands @@ -677,6 +723,7 @@ Dump <@var{size}> bytes of target memory starting at <@var{address}> to a @item @b{verify_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}] @cindex verify_image Verify <@var{file}> to target memory starting at <@var{address}>. +This will first attempt using a crc checksum, if this fails it will try a binary compare. @item @b{load_binary} <@var{file}> <@var{address}> [DEPRECATED] @cindex load_binary Load binary <@var{file}> to target memory at <@var{address}> @@ -708,12 +755,23 @@ updated information. @item @b{flash protect_check} <@var{num}> @cindex flash protect_check Check protection state of sectors in flash bank . -@item @b{flash erase} <@var{num}> <@var{first}> <@var{last}> + +@item @b{flash erase} <@var{num}> <@var{first}> <@var{last}> [DEPRECATED] @cindex flash erase Erase sectors at bank <@var{num}>, starting at sector <@var{first}> up to and including <@var{last}>. Sector numbering starts at 0. Depending on the flash type, erasing might require the protection to be disabled first (e.g. Intel Advanced Bootblock flash using -the CFI driver). +the CFI driver). This command was replaced by the new command +@option{flash erase_sector} using the same syntax. +@item @b{flash erase_sector} <@var{num}> <@var{first}> <@var{last}> +@cindex flash erase_sector +Erase sectors at bank <@var{num}>, starting at sector <@var{first}> up to and including +<@var{last}>. Sector numbering starts at 0. Depending on the flash type, erasing might +require the protection to be disabled first (e.g. Intel Advanced Bootblock flash using +the CFI driver). +@item @b{flash erase_address} <@var{address}> <@var{length}> +@cindex flash erase_address +Erase sectors starting at <@var{address}> for <@var{length}> number of bytes @item @b{flash write} <@var{num}> <@var{file}> <@var{offset}> [DEPRECATED] @cindex flash write Write the binary <@var{file}> to flash bank <@var{num}>, starting at <@var{offset}> @@ -843,8 +901,8 @@ mass erase flash memory. @end itemize @page -@section Arcitecture Specific Commands -@cindex Arcitecture Specific Commands +@section Architecture Specific Commands +@cindex Architecture Specific Commands @subsection ARMV4/5 specific commands @cindex ARMV4/5 specific commands @@ -991,7 +1049,7 @@ This page will collect some script examples for different CPUs. The configuration script can be divided in the following section: @itemize @bullet -@item deamon configuration +@item daemon configuration @item interface @item jtag scan chain @item target configuration @@ -1002,9 +1060,9 @@ Detailed information about each section can be found at OpenOCD configuration @section OMAP5912 Flash Debug @cindex OMAP5912 Flash Debug -The following two scripts was used with an wiggler PP and and a TI OMAP5912 -dual core processor (@uref{http://www.ti.com}) on a OMAP5912 OSK board -@uref{(http://www.spectrumdigital.com}). +The following two scripts were used with a wiggler PP and and a TI OMAP5912 +dual core processor - (@uref{http://www.ti.com}), on a OMAP5912 OSK board +- (@uref{http://www.spectrumdigital.com}). @subsection Openocd config @smallexample #daemon configuration @@ -1181,6 +1239,46 @@ working_area 0 0x50000000 16384 nobackup flash bank str9x 0x00000000 0x00080000 0 0 0 @end smallexample +@section STR912 comstick +@cindex STR912 comstick Script +The following script was used with a Hitex STR9 Comstick: +@smallexample +#daemon configuration +telnet_port 4444 +gdb_port 3333 + +#interface +interface ft2232 +ft2232_device_desc "STR9-comStick A" +ft2232_layout comstick +jtag_speed 1 + +jtag_nsrst_delay 100 +jtag_ntrst_delay 100 + +#use combined on interfaces or targets that can't set TRST/SRST separately +reset_config trst_and_srst + +#jtag scan chain +#format L IRC IRCM IDCODE (Length, IR Capture, IR Capture Mask, IDCODE) +jtag_device 8 0x1 0x1 0xfe +jtag_device 4 0x1 0xf 0xe +jtag_device 5 0x1 0x1 0x1e + +#target configuration +daemon_startup reset + +#target +#target arm966e +target arm966e little reset_halt 1 arm966e +run_and_halt_time 0 30 + +working_area 0 0x50000000 16384 nobackup + +#flash bank +flash bank str9x 0x00000000 0x00080000 0 0 0 +@end smallexample + @section STM32x Script @cindex STM32x Script The following script was used with an Amontec JTAGkey and a STM32x cpu: @@ -1194,7 +1292,10 @@ interface ft2232 ft2232_device_desc "Amontec JTAGkey A" ft2232_layout jtagkey jtag_speed 10 - + +jtag_nsrst_delay 100 +jtag_ntrst_delay 100 + #use combined on interfaces or targets that can't set TRST/SRST separately reset_config trst_and_srst @@ -1214,12 +1315,12 @@ run_and_halt_time 0 30 working_area 0 0x20000000 16384 nobackup #flash bank -flash bank stm32x 0x08000000 0x00010000 0 0 0 +flash bank stm32x 0x08000000 0x00020000 0 0 0 @end smallexample -@section LPC2294 Script -@cindex LPC2294 Script -The following script was used with an Amontec JTAGkey and a LPC2294 cpu: +@section STM32x Performance Stick +@cindex STM32x Performance Stick Script +The following script was used with the Hitex STM32 Performance Stick @smallexample #daemon configuration telnet_port 4444 @@ -1227,10 +1328,49 @@ gdb_port 3333 #interface interface ft2232 -ft2232_device_desc "Amontec JTAGkey A" -ft2232_layout jtagkey -ft2232_vid_pid 0x0403 0xcff8 -jtag_speed 2 +ft2232_device_desc "STM32-PerformanceStick A" +ft2232_layout stm32stick +jtag_speed 10 + +jtag_nsrst_delay 100 +jtag_ntrst_delay 100 + +#use combined on interfaces or targets that can't set TRST/SRST separately +reset_config trst_and_srst + +#jtag scan chain +#format L IRC IRCM IDCODE (Length, IR Capture, IR Capture Mask, IDCODE) +jtag_device 4 0x1 0xf 0xe +jtag_device 5 0x1 0x1 0x1e +jtag_device 4 0x1 0xf 0xe + +#target configuration +daemon_startup reset + +#target +#target cortex_m3 +target cortex_m3 little run_and_halt 0 +run_and_halt_time 0 30 + +working_area 0 0x20000000 16384 nobackup + +#flash bank +flash bank stm32x 0x08000000 0x00020000 0 0 0 +@end smallexample + +@section LPC2129 Script +@cindex LPC2129 Script +The following script was used with an wiggler PP and a LPC-2129 cpu: +@smallexample +#daemon configuration +telnet_port 4444 +gdb_port 3333 + +#interface +interface parport +parport_port 0x378 +parport_cable wiggler +jtag_speed 0 #use combined on interfaces or targets that can't set TRST/SRST separately reset_config trst_and_srst srst_pulls_trst @@ -1247,15 +1387,15 @@ daemon_startup reset target arm7tdmi little run_and_halt 0 arm7tdmi-s_r4 run_and_halt_time 0 30 -working_area 0 0x40000000 0x40000 nobackup +working_area 0 0x40000000 0x4000 nobackup -#flash configuration +#flash bank flash bank lpc2000 0x0 0x40000 0 0 0 lpc2000_v1 14765 calc_checksum @end smallexample -@section AT91R40008 Script -@cindex AT91R40008 Script -The following script was used with an Amontec JTAGkey and a AT91R40008 cpu: +@section LPC2148 Script +@cindex LPC2148 Script +The following script was used with an Amontec JTAGkey and a LPC2148 cpu: @smallexample #daemon configuration telnet_port 4444 @@ -1266,12 +1406,10 @@ interface ft2232 ft2232_device_desc "Amontec JTAGkey A" ft2232_layout jtagkey ft2232_vid_pid 0x0403 0xcff8 -jtag_speed 0 -jtag_nsrst_delay 200 -jtag_ntrst_delay 200 +jtag_speed 3 #use combined on interfaces or targets that can't set TRST/SRST separately -reset_config srst_only srst_pulls_trst +reset_config trst_and_srst srst_pulls_trst #jtag scan chain #format L IRC IRCM IDCODE (Length, IR Capture, IR Capture Mask, IDCODE) @@ -1282,23 +1420,29 @@ daemon_startup reset #target #target arm7tdmi -target arm7tdmi little run_and_halt 0 arm7tdmi +target arm7tdmi little run_and_halt 0 arm7tdmi-s_r4 run_and_halt_time 0 30 + +working_area 0 0x40000000 0x8000 nobackup + +#flash configuration +flash bank lpc2000 0x0 0x7d000 0 0 0 lpc2000_v1 14765 calc_checksum @end smallexample -@section LPC2129 Script -@cindex LPC2129 Script -The following script was used with an wiggler PP and a LPC-2129 cpu: +@section LPC2294 Script +@cindex LPC2294 Script +The following script was used with an Amontec JTAGkey and a LPC2294 cpu: @smallexample #daemon configuration telnet_port 4444 gdb_port 3333 #interface -interface parport -parport_port 0x378 -parport_cable wiggler -jtag_speed 0 +interface ft2232 +ft2232_device_desc "Amontec JTAGkey A" +ft2232_layout jtagkey +ft2232_vid_pid 0x0403 0xcff8 +jtag_speed 3 #use combined on interfaces or targets that can't set TRST/SRST separately reset_config trst_and_srst srst_pulls_trst @@ -1315,12 +1459,45 @@ daemon_startup reset target arm7tdmi little run_and_halt 0 arm7tdmi-s_r4 run_and_halt_time 0 30 -working_area 0 0x00000000 0x400000 nobackup +working_area 0 0x40000000 0x4000 nobackup -#flash bank +#flash configuration flash bank lpc2000 0x0 0x40000 0 0 0 lpc2000_v1 14765 calc_checksum @end smallexample +@section AT91R40008 Script +@cindex AT91R40008 Script +The following script was used with an Amontec JTAGkey and a AT91R40008 cpu: +@smallexample +#daemon configuration +telnet_port 4444 +gdb_port 3333 + +#interface +interface ft2232 +ft2232_device_desc "Amontec JTAGkey A" +ft2232_layout jtagkey +ft2232_vid_pid 0x0403 0xcff8 +jtag_speed 0 +jtag_nsrst_delay 200 +jtag_ntrst_delay 200 + +#use combined on interfaces or targets that can't set TRST/SRST separately +reset_config srst_only srst_pulls_trst + +#jtag scan chain +#format L IRC IRCM IDCODE (Length, IR Capture, IR Capture Mask, IDCODE) +jtag_device 4 0x1 0xf 0xe + +#target configuration +daemon_startup reset + +#target +#target arm7tdmi +target arm7tdmi little run_and_halt 0 arm7tdmi +run_and_halt_time 0 30 +@end smallexample + @section AT91SAM7s Script @cindex AT91SAM7s Script The following script was used with an Olimex ARM-JTAG-OCD and a AT91SAM7S64 cpu: @@ -1531,6 +1708,71 @@ run_and_halt_time 0 30 flash bank cfi 0x00000000 0x1000000 2 4 0 @end smallexample +@node GDB and Openocd +@chapter GDB and Openocd +@cindex GDB and Openocd +Openocd complies with the remote gdbserver protocol, and as such can be used +to debug remote targets. + +@section Connecting to gdb +@cindex Connecting to gdb +A connection is typically started as follows: +@smallexample +target remote localhost:3333 +@end smallexample +This would cause gdb to connect to the gdbserver on the local pc using port 3333. + +To see a list of available openocd commands type @option{monitor help} on the +gdb commandline. + +Openocd supports the gdb @option{qSupported} packet, this enables information +to be sent by the gdb server (openocd) to gdb. Typical information includes +packet size and device memory map. + +Previous versions of openocd required the following gdb options to increase +the packet size and speed up gdb communication. +@smallexample +set remote memory-write-packet-size 1024 +set remote memory-write-packet-size fixed +set remote memory-read-packet-size 1024 +set remote memory-read-packet-size fixed +@end smallexample +This is now handled in the @option{qSupported} PacketSize. + +@section Programming using gdb +@cindex Programming using gdb + +By default the target memory map is not sent to gdb, this can be enabled by +the following openocd config option: +@smallexample +gdb_memory_map enable +@end smallexample +For this to function correctly a valid flash config must also be configured +in openocd. For speed also configure a valid working area. + +Informing gdb of the memory map of the target will enable gdb to protect any +flash area of the target and use hardware breakpoints by default. This means +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. + +If @option{gdb_flash_program enable} is also used, gdb will be able to +program any flash memory using the vFlash interface. + +gdb will look at the target memory map when a load command is given, if any +areas to be programmed lie within the target flash area the vFlash packets +will be used. + +Incase the target needs configuring before gdb programming, a script can be executed. +@smallexample +target_script 0 gdb_program_config config.script +@end smallexample + +To verify any flash programming the gdb command @option{compare-sections} +can be used. + @node FAQ @chapter FAQ @cindex faq