@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
+
@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
@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.
* 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.
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
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
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.
@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
@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
@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
@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
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}>
@item arm926ejs
@item arm966e
@item cortex_m3
+@item feroceon
@item xscale
@end itemize
@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
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
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
@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
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
@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}>
@item @b{flash protect_check} <@var{num}>
@cindex flash protect_check
Check protection state of sectors in flash bank <num>.
-@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}>
@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
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
@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
working_area 0 0x20000000 16384 nobackup
#flash bank <driver> <base> <size> <chip_width> <bus_width>
-flash bank stm32x 0x08000000 0x00010000 0 0 0
+flash bank stm32x 0x08000000 0x00020000 0 0 0
@end smallexample
@section STM32x Performance Stick
working_area 0 0x20000000 16384 nobackup
#flash bank <driver> <base> <size> <chip_width> <bus_width>
-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 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 ft2232
-ft2232_device_desc "Amontec JTAGkey A"
-ft2232_layout jtagkey
-ft2232_vid_pid 0x0403 0xcff8
-jtag_speed 2
+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
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 <driver> <base> <size> <chip_width> <bus_width>
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
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)
#target <type> <startup mode>
#target arm7tdmi <endianness> <reset mode> <chainpos> <variant>
-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
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 <driver> <base> <size> <chip_width> <bus_width>
+#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 <type> <startup mode>
+#target arm7tdmi <endianness> <reset mode> <chainpos> <variant>
+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:
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
Code Review / openocd.git / blobdiff