|
- \input texinfo @c -*-texinfo-*-
- @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}@*
- Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
- @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 manual documents edition @value{EDITION} of the Open On-Chip Debugger
- (OpenOCD) version @value{VERSION}, @value{UPDATED}.
-
- @insertcopying
-
- @menu
- * About:: About OpenOCD.
- * Developers:: OpenOCD developers
- * Building:: Building OpenOCD
- * Running:: Running OpenOCD
- * Configuration:: OpenOCD Configuration.
- * Target library:: Target library
- * Commands:: OpenOCD Commands
- * Sample Scripts:: Sample Target Scripts
- * TFTP:: TFTP
- * GDB and OpenOCD:: Using GDB and OpenOCD
- * TCL and OpenOCD:: Using TCL and OpenOCD
- * TCL scripting API:: Tcl scripting API
- * Upgrading:: Deprecated/Removed Commands
- * FAQ:: Frequently Asked Questions
- * License:: GNU Free Documentation License
- * Index:: Main index.
- @end menu
-
- @node About
- @unnumbered About
- @cindex about
-
- The Open On-Chip Debugger (OpenOCD) aims to provide debugging, in-system programming
- and boundary-scan testing for embedded target devices. The targets are interfaced
- using JTAG (IEEE 1149.1) compliant hardware, but this may be extended to other
- connection types in the future.
-
- OpenOCD currently supports Wiggler (clones), FTDI FT2232 based JTAG interfaces, the
- Amontec JTAG Accelerator, and the Gateworks GW1602. It allows ARM7 (ARM7TDMI and ARM720t),
- ARM9 (ARM920t, ARM922t, ARM926ej--s, ARM966e--s), XScale (PXA25x, IXP42x) and
- Cortex-M3 (Luminary Stellaris LM3 and ST STM32) based cores to be debugged.
-
- Flash writing is supported for external CFI compatible flashes (Intel and AMD/Spansion
- command set) and several internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3
- and STM32x). Preliminary support for using the LPC3180's NAND flash controller is included.
-
- @node Developers
- @chapter Developers
- @cindex developers
-
- OpenOCD was created by Dominic Rath as part of a diploma thesis written at the
- University of Applied Sciences Augsburg (@uref{http://www.fh-augsburg.de}).
- Others interested in improving the state of free and open debug and testing technology
- are welcome to participate.
-
- Other developers have contributed support for additional targets and flashes as well
- as numerous bugfixes and enhancements. See the AUTHORS file for regular contributors.
-
- The main OpenOCD web site is available at @uref{http://openocd.berlios.de/web/}
-
- @node Building
- @chapter Building
- @cindex building OpenOCD
-
- If you are interested in getting actual work done rather than building
- OpenOCD, then check if your interface supplier provides binaries for
- you. Chances are that that binary is from some SVN version that is more
- stable than SVN trunk where bleeding edge development takes place.
-
-
- You can download the current SVN version with SVN client of your choice from the
- following repositories:
-
- (@uref{svn://svn.berlios.de/openocd/trunk})
-
- or
-
- (@uref{http://svn.berlios.de/svnroot/repos/openocd/trunk})
-
- Using the SVN command line client, you can use the following command to fetch the
- latest version (make sure there is no (non-svn) directory called "openocd" in the
- current directory):
-
- @smallexample
- svn checkout svn://svn.berlios.de/openocd/trunk openocd
- @end smallexample
-
- Building OpenOCD requires a recent version of the GNU autotools.
- On my build system, I'm using autoconf 2.13 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
- paths, resulting in obscure dependency errors (This is an observation I've gathered
- 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 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
-
- libftdi is supported under windows. Versions earlier than 0.13 will require patching.
- see contrib/libftdi for more details.
-
- In general, the D2XX driver provides superior performance (several times as fast),
- but has the draw-back of being binary-only - though that isn't that bad, as it isn't
- a kernel module, only a user space library.
-
- To build OpenOCD (on both Linux and Cygwin), use the following commands:
- @smallexample
- ./bootstrap
- @end smallexample
- Bootstrap generates the configure script, and prepares building on your system.
- @smallexample
- ./configure
- @end smallexample
- Configure generates the Makefiles used to build OpenOCD.
- @smallexample
- make
- @end smallexample
- Make builds OpenOCD, and places the final executable in ./src/.
-
- The configure script takes several options, specifying which JTAG interfaces
- should be included:
-
- @itemize @bullet
- @item
- @option{--enable-parport}
- @item
- @option{--enable-parport_ppdev}
- @item
- @option{--enable-parport_giveio}
- @item
- @option{--enable-amtjtagaccel}
- @item
- @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 OpenOCD to
- build properly.}
- @item
- @option{--enable-ft2232_libftdi}
- @item
- @option{--with-ftd2xx=/path/to/d2xx/}
- @item
- @option{--enable-gw16012}
- @item
- @option{--enable-usbprog}
- @item
- @option{--enable-presto_libftdi}
- @item
- @option{--enable-presto_ftd2xx}
- @item
- @option{--enable-jlink}
- @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).
-
- Cygwin users have to specify the location of the FTDI D2XX package. This should be an
- absolute path containing no spaces.
-
- Linux users should copy the various parts of the D2XX package to the appropriate
- locations, i.e. /usr/include, /usr/lib.
-
- Miscellaneous configure options
-
- @itemize @bullet
- @item
- @option{--enable-gccwarnings} - enable extra gcc warnings during build
- @end itemize
-
- @node Running
- @chapter Running
- @cindex running OpenOCD
- @cindex --configfile
- @cindex --debug_level
- @cindex --logfile
- @cindex --search
- OpenOCD runs as a daemon, waiting for connections from clients (Telnet, GDB, Other).
- Run with @option{--help} or @option{-h} to view the available command line switches.
-
- It reads its configuration by default from the file openocd.cfg located in the current
- working directory. This may be overwritten with the @option{-f <configfile>} command line
- switch. The @option{-f} command line switch can be specified multiple times, in which case the config files
- are executed in order.
-
- Also it is possible to interleave commands w/config scripts using the @option{-c} command line switch.
-
- To enable debug output (when reporting problems or working on OpenOCD itself), use
- the @option{-d} command line switch. This sets the @option{debug_level} to "3", outputting
- the most information, including debug messages. The default setting is "2", outputting
- only informational messages, warnings and errors. You can also change this setting
- from within a telnet or gdb session using @option{debug_level <n>} @xref{debug_level}.
-
- 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. The current directory and the OpenOCD target library
- is in the search path by default.
-
- Note! OpenOCD will launch the GDB & telnet server even if it can not establish a connection
- with the target. In general, it is possible for the JTAG controller to be unresponsive until
- the target is set up correctly via e.g. GDB monitor commands in a GDB init script.
-
- @node Configuration
- @chapter Configuration
- @cindex configuration
- OpenOCD runs as a daemon, and reads it current configuration
- by default from the file openocd.cfg in the current directory. A different configuration
- file can be specified with the @option{-f <conf.file>} command line switch specified when starting OpenOCD.
-
- The configuration file is used to specify on which ports the daemon listens for new
- connections, the JTAG interface used to connect to the target, the layout of the JTAG
- chain, the targets that should be debugged, and connected flashes.
-
- @section Daemon configuration
-
- @itemize @bullet
- @item @b{init}
- @*This command terminates the configuration stage and enters the normal
- command mode. This can be useful to add commands to the startup scripts and commands
- such as resetting the target, programming flash, etc. To reset the CPU upon startup,
- add "init" and "reset" at the end of the config script or at the end of the
- OpenOCD command line using the @option{-c} command line switch.
- @cindex init
- @item @b{telnet_port} <@var{number}>
- @cindex telnet_port
- @*Port on which to listen for incoming telnet connections
- @item @b{telnet_async} <@var{enable/disable}>
- @cindex telnet_async
- @*Enable/disable asynchronous messages. Default off. Slows down debugging
- if enabled and telnet session is open while stepping.
- @item @b{tcl_port} <@var{number}>
- @cindex tcl_port
- @*Port on which to listen for incoming TCL syntax. This port is intended as
- a simplified RPC connection that can be used by clients to issue commands
- and get the output from the TCL engine.
- @item @b{gdb_port} <@var{number}>
- @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_breakpoint_override} <@var{hard|soft|disabled}>
- @cindex gdb_breakpoint_override
- @anchor{gdb_breakpoint_override}
- @*Force breakpoint type for gdb 'break' commands.
- The raison d'etre for this option is to support GDB GUI's without
- a hard/soft breakpoint concept where the default OpenOCD and
- GDB behaviour is not sufficient. Note that GDB will use hardware
- breakpoints if the memory map has been set up for flash regions.
-
- This option replaces older arm7_9 target commands that addressed
- the same issue.
- @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}> to cause OpenOCD to 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{enable}>
- @xref{gdb_flash_program}.
- @item @b{gdb_flash_program} <@var{enable|disable}>
- @cindex gdb_flash_program
- @anchor{gdb_flash_program}
- @*Set to <@var{enable}> to cause OpenOCD to program the flash memory when a
- vFlash packet is received.
- Default behaviour is <@var{enable}>
- @end itemize
-
- @section JTAG interface configuration
-
- @itemize @bullet
- @item @b{interface} <@var{name}>
- @cindex interface
- @*Use the interface driver <@var{name}> to connect to the target. Currently supported
- interfaces are
- @itemize @minus
- @item @b{parport}
- PC parallel port bit-banging (Wigglers, PLD download cable, ...)
- @end itemize
- @itemize @minus
- @item @b{amt_jtagaccel}
- Amontec Chameleon in its JTAG Accelerator configuration connected to a PC's EPP
- mode parallel port
- @end itemize
- @itemize @minus
- @item @b{ft2232}
- FTDI FT2232 based devices using either the open-source libftdi or the binary only
- FTD2XX driver. The FTD2XX is superior in performance, but not available on every
- platform. The libftdi uses libusb, and should be portable to all systems that provide
- libusb.
- @end itemize
- @itemize @minus
- @item @b{ep93xx}
- Cirrus Logic EP93xx based single-board computer bit-banging (in development)
- @end itemize
- @itemize @minus
- @item @b{presto}
- ASIX PRESTO USB JTAG programmer.
- @end itemize
- @itemize @minus
- @item @b{usbprog}
- usbprog is a freely programmable USB adapter.
- @end itemize
- @itemize @minus
- @item @b{gw16012}
- Gateworks GW16012 JTAG programmer.
- @end itemize
- @itemize @minus
- @item @b{jlink}
- Segger jlink usb adapter
- @end itemize
- @end itemize
-
- @itemize @bullet
- @item @b{jtag_speed} <@var{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.
-
- The speed used during reset can be adjusted using setting jtag_speed during
- pre_reset and post_reset events.
- @itemize @minus
-
- @item wiggler: maximum speed / @var{number}
- @item ft2232: 6MHz / (@var{number}+1)
- @item amt jtagaccel: 8 / 2**@var{number}
- @item jlink: maximum speed in kHz (0-12000), 0 will use RTCK
- @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{jtag_khz} <@var{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.
- If the JTAG interface provides SRST, but the target doesn't connect that signal properly,
- then OpenOCD can't use it. <@var{signals}> can be @option{none}, @option{trst_only},
- @option{srst_only} or @option{trst_and_srst}.
-
- [@var{combination}] is an optional value specifying broken reset signal implementations.
- @option{srst_pulls_trst} states that the testlogic is reset together with the reset of
- the system (e.g. Philips LPC2000, "broken" board layout), @option{trst_pulls_srst} says
- that the system is reset together with the test logic (only hypothetical, I haven't
- seen hardware with such a bug, and can be worked around).
- @option{combined} imples both @option{srst_pulls_trst} and @option{trst_pulls_srst}.
- The default behaviour if no option given is @option{separate}.
-
- The [@var{trst_type}] and [@var{srst_type}] parameters allow the driver type of the
- reset lines to be specified. Possible values are @option{trst_push_pull} (default)
- and @option{trst_open_drain} for the test reset signal, and @option{srst_open_drain}
- (default) and @option{srst_push_pull} for the system reset. These values only affect
- JTAG interfaces with support for different drivers, like the Amontec JTAGkey and JTAGAccelerator.
-
- @item @b{jtag_device} <@var{IR length}> <@var{IR capture}> <@var{IR mask}> <@var{IDCODE instruction}>
- @cindex jtag_device
- @*Describes the devices that form the JTAG daisy chain, with the first device being
- the one closest to TDO. The parameters are the length of the instruction register
- (4 for all ARM7/9s), the value captured during Capture-IR (0x1 for ARM7/9), and a mask
- of bits that should be validated when doing IR scans (all four bits (0xf) for ARM7/9).
- The IDCODE instruction will in future be used to query devices for their JTAG
- identification code. This line is the same for all ARM7 and ARM9 devices.
- Other devices, like CPLDs, require different parameters. An example configuration
- line for a Xilinx XC9500 CPLD would look like this:
- @smallexample
- jtag_device 8 0x01 0x0e3 0xfe
- @end smallexample
- The instruction register (IR) is 8 bits long, during Capture-IR 0x01 is loaded into
- the IR, but only bits 0-1 and 5-7 should be checked, the others (2-4) might vary.
- The IDCODE instruction is 0xfe.
-
- @item @b{jtag_nsrst_delay} <@var{ms}>
- @cindex jtag_nsrst_delay
- @*How long (in milliseconds) OpenOCD should wait after deasserting nSRST before
- starting new JTAG operations.
- @item @b{jtag_ntrst_delay} <@var{ms}>
- @cindex jtag_ntrst_delay
- @*Same @b{jtag_nsrst_delay}, but for nTRST
-
- The jtag_n[st]rst_delay options are useful if reset circuitry (like a reset supervisor,
- or on-chip features) keep a reset line asserted for some time after the external reset
- got deasserted.
- @end itemize
-
- @section parport options
-
- @itemize @bullet
- @item @b{parport_port} <@var{number}>
- @cindex parport_port
- @*Either the address of the I/O port (default: 0x378 for LPT1) or the number of
- the @file{/dev/parport} device
-
- When using PPDEV to access the parallel port, use the number of the parallel port:
- @option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
- you may encounter a problem.
- @item @b{parport_cable} <@var{name}>
- @cindex parport_cable
- @*The layout of the parallel port cable used to connect to the target.
- Currently supported cables are
- @itemize @minus
- @item @b{wiggler}
- @cindex wiggler
- The original Wiggler layout, also supported by several clones, such
- as the Olimex ARM-JTAG
- @item @b{wiggler2}
- @cindex wiggler2
- Same as original wiggler except an led is fitted on D5.
- @item @b{wiggler_ntrst_inverted}
- @cindex wiggler_ntrst_inverted
- Same as original wiggler except TRST is inverted.
- @item @b{old_amt_wiggler}
- @cindex old_amt_wiggler
- The Wiggler configuration that comes with Amontec's Chameleon Programmer. The new
- version available from the website uses the original Wiggler layout ('@var{wiggler}')
- @item @b{chameleon}
- @cindex chameleon
- The Amontec Chameleon's CPLD when operated in configuration mode. This is only used to
- program the Chameleon itself, not a connected target.
- @item @b{dlc5}
- @cindex dlc5
- The Xilinx Parallel cable III.
- @item @b{triton}
- @cindex triton
- The parallel port adapter found on the 'Karo Triton 1 Development Board'.
- This is also the layout used by the HollyGates design
- (see @uref{http://www.lartmaker.nl/projects/jtag/}).
- @item @b{flashlink}
- @cindex flashlink
- The ST Parallel cable.
- @item @b{arm-jtag}
- @cindex arm-jtag
- Same as original wiggler except SRST and TRST connections reversed and
- TRST is also inverted.
- @item @b{altium}
- @cindex altium
- Altium Universal JTAG cable.
- @end itemize
- @item @b{parport_write_on_exit} <@var{on}|@var{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
- @itemize @bullet
- @item @b{parport_port} <@var{number}>
- @cindex parport_port
- @*Either the address of the I/O port (default: 0x378 for LPT1) or the number of the
- @file{/dev/parport} device
- @end itemize
- @section ft2232 options
-
- @itemize @bullet
- @item @b{ft2232_device_desc} <@var{description}>
- @cindex ft2232_device_desc
- @*The USB device description of the FTDI FT2232 device. If not specified, the FTDI
- default value is used. This setting is only valid if compiled with FTD2XX support.
- @item @b{ft2232_serial} <@var{serial-number}>
- @cindex ft2232_serial
- @*The serial number of the FTDI FT2232 device. If not specified, the FTDI default
- values are used.
- @item @b{ft2232_layout} <@var{name}>
- @cindex ft2232_layout
- @*The layout of the FT2232 GPIO signals used to control output-enables and reset
- signals. Valid layouts are
- @itemize @minus
- @item @b{usbjtag}
- "USBJTAG-1" layout described in the original OpenOCD diploma thesis
- @item @b{jtagkey}
- Amontec JTAGkey and JTAGkey-tiny
- @item @b{signalyzer}
- Signalyzer
- @item @b{olimex-jtag}
- Olimex ARM-USB-OCD
- @item @b{m5960}
- American Microsystems M5960
- @item @b{evb_lm3s811}
- Luminary Micro EVB_LM3S811 as a JTAG interface (not onboard processor), no TRST or
- SRST signals on external connector
- @item @b{comstick}
- Hitex STR9 comstick
- @item @b{stm32stick}
- Hitex STM32 Performance Stick
- @item @b{flyswatter}
- Tin Can Tools Flyswatter
- @item @b{turtelizer2}
- egnite Software turtelizer2
- @item @b{oocdlink}
- OOCDLink
- @end itemize
-
- @item @b{ft2232_vid_pid} <@var{vid}> <@var{pid}>
- @*The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI
- default values are used. Multiple <@var{vid}>, <@var{pid}> pairs may be given, eg.
- @smallexample
- ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003
- @end smallexample
- @item @b{ft2232_latency} <@var{ms}>
- @*On some systems using ft2232 based JTAG interfaces the FT_Read function call in
- ft2232_read() fails to return the expected number of bytes. This can be caused by
- USB communication delays and has proved hard to reproduce and debug. Setting the
- FT2232 latency timer to a larger value increases delays for short USB packages but it
- also reduces the risk of timeouts before receiving the expected number of bytes.
- The OpenOCD default value is 2 and for some systems a value of 10 has proved useful.
- @end itemize
-
- @section ep93xx options
- @cindex ep93xx options
- Currently, there are no options available for the ep93xx interface.
-
- @page
- @section Target configuration
-
- @itemize @bullet
- @item @b{target} <@var{type}> <@var{endianess}> <@var{JTAG pos}>
- <@var{variant}>
- @cindex target
- @*Defines a target that should be debugged. Currently supported types are:
- @itemize @minus
- @item @b{arm7tdmi}
- @item @b{arm720t}
- @item @b{arm9tdmi}
- @item @b{arm920t}
- @item @b{arm922t}
- @item @b{arm926ejs}
- @item @b{arm966e}
- @item @b{cortex_m3}
- @item @b{feroceon}
- @item @b{xscale}
- @item @b{arm11}
- @item @b{mips_m4k}
- @end itemize
-
- If you want to use a target board that is not on this list, see Adding a new
- target board.
- The @option{target types} command can be used to get the list of targets supported from within openocd.
-
- Endianess may be @option{little} or @option{big}.
-
- @item @b{target_script} <@var{target#}> <@var{event}> <@var{script_file}>
- @cindex target_script
- @*Event is one of the following:
- @option{pre_reset}, @option{reset}, @option{post_reset}, @option{post_halt},
- @option{pre_resume} or @option{gdb_program_config}.
- @option{post_reset} and @option{reset} will produce the same results.
-
- @item @b{working_area} <@var{target#}> <@var{address}> <@var{size}> <@var{backup}|@var{nobackup}> [@option{virtual address}]
- @cindex working_area
- @*Specifies a working area for the debugger to use. This may be used to speed-up
- downloads to target memory and flash operations, or to perform otherwise unavailable
- operations (some coprocessor operations on ARM7/9 systems, for example). The last
- parameter decides whether the memory should be preserved (<@var{backup}>) or can simply be overwritten (<@var{nobackup}>). If possible, use
- a working_area that doesn't need to be backed up, as performing a backup slows down operation.
- @end itemize
-
- @subsection arm7tdmi options
- @cindex arm7tdmi options
- target arm7tdmi <@var{endianess}> <@var{jtag#}>
- @*The arm7tdmi target definition requires at least one additional argument, specifying
- the position of the target in the JTAG daisy-chain. The first JTAG device is number 0.
- The optional [@var{variant}] parameter has been removed in recent versions.
- The correct feature set is determined at runtime.
-
- @subsection arm720t options
- @cindex arm720t options
- ARM720t options are similar to ARM7TDMI options.
-
- @subsection arm9tdmi options
- @cindex arm9tdmi options
- ARM9TDMI options are similar to ARM7TDMI options. Supported variants are
- @option{arm920t}, @option{arm922t} and @option{arm940t}.
- This enables the hardware single-stepping support found on these cores.
-
- @subsection arm920t options
- @cindex arm920t options
- ARM920t options are similar to ARM9TDMI options.
-
- @subsection arm966e options
- @cindex arm966e options
- ARM966e options are similar to ARM9TDMI options.
-
- @subsection cortex_m3 options
- @cindex cortex_m3 options
- use variant <@var{variant}> @option{lm3s} when debugging luminary lm3s targets. This will cause
- openocd to use a software reset rather than asserting SRST to avoid a issue with clearing
- the debug registers. This is fixed in Fury Rev B, DustDevil Rev B, Tempest, these revisions will
- be detected and the normal reset behaviour used.
-
- @subsection xscale options
- @cindex xscale options
- Supported variants are @option{ixp42x}, @option{ixp45x}, @option{ixp46x},
- @option{pxa250}, @option{pxa255}, @option{pxa26x}.
-
- @subsection arm11 options
- @cindex arm11 options
-
- @subsection mips_m4k options
- @cindex mips_m4k options
- Use variant @option{ejtag_srst} when debugging targets that
- do not provide a functional SRST line on the EJTAG connector.
- This causes openocd to instead use an EJTAG software reset command to reset the processor.
- You still need to enable @option{srst} on the reset configuration command to enable openocd hardware reset functionality.
-
- @section Flash configuration
- @cindex Flash configuration
-
- @itemize @bullet
- @item @b{flash bank} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}>
- <@var{bus_width}> <@var{target#}> [@var{driver_options ...}]
- @cindex flash bank
- @*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>.
- @end itemize
-
- @subsection lpc2000 options
- @cindex lpc2000 options
-
- @b{flash bank lpc2000} <@var{base}> <@var{size}> 0 0 <@var{target#}> <@var{variant}>
- <@var{clock}> [@var{calc_checksum}]
- @*LPC flashes don't require the chip and bus width to be specified. Additional
- parameters are the <@var{variant}>, which may be @var{lpc2000_v1} (older LPC21xx and LPC22xx)
- or @var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx), the number
- of the target this flash belongs to (first is 0), the frequency at which the core
- is currently running (in kHz - must be an integral number), and the optional keyword
- @var{calc_checksum}, telling the driver to calculate a valid checksum for the exception
- vector table.
-
- @subsection cfi options
- @cindex cfi options
-
- @b{flash bank cfi} <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}>
- <@var{target#}> [@var{jedec_probe}|@var{x16_as_x8}]
- @*CFI flashes require the number of the target they're connected to as an additional
- 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.
-
- The @var{jedec_probe} option is used to detect certain non-CFI flash roms, like AM29LV010 and similar types.
-
- @var{x16_as_x8} ???
-
- @subsection at91sam7 options
- @cindex at91sam7 options
-
- @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 str7 options
-
- @b{flash bank str7x} <@var{base}> <@var{size}> 0 0 <@var{target#}> <@var{variant}>
- @*variant can be either STR71x, STR73x or STR75x.
-
- @subsection str9 options
- @cindex str9 options
-
- @b{flash bank str9x} <@var{base}> <@var{size}> 0 0 <@var{target#}>
- @*The str9 needs the flash controller to be configured prior to Flash programming, eg.
- @smallexample
- str9x flash_config 0 4 2 0 0x80000
- @end smallexample
- This will setup the BBSR, NBBSR, BBADR and NBBADR registers respectively.
-
- @subsection str9 options (str9xpec driver)
-
- @b{flash bank str9xpec} <@var{base}> <@var{size}> 0 0 <@var{target#}>
- @*Before using the flash commands the turbo mode will need enabling using str9xpec
- @option{enable_turbo} <@var{num>.}
-
- Only use this driver for locking/unlocking the device or configuring the option bytes.
- Use the standard str9 driver for programming.
-
- @subsection stellaris (LM3Sxxx) options
- @cindex stellaris (LM3Sxxx) options
-
- @b{flash bank stellaris} <@var{base}> <@var{size}> 0 0 <@var{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 @var{target#}.
-
- @subsection aduc702x options
- @cindex aduc702x options
-
- @b{flash bank aduc702x} <@var{base}> <@var{size}> 0 0 <@var{target#}>
- @*aduc702x flash plugin require the flash @var{base}, @var{size} and @var{target#}.
-
- @section mFlash configuration
- @cindex mFlash configuration
-
- @itemize @bullet
- @item @b{mflash bank} <@var{soc}> <@var{base}> <@var{chip_width}> <@var{bus_width}>
- <@var{RST pin}> <@var{WP pin}> <@var{DPD pin}> <@var{target #}>
- @cindex mflash bank
- @*Configures a mflash for <@var{soc}> host bank at <@var{base}>. <@var{chip_width}> and
- <@var{bus_width}> are bytes order. Pin number format is dependent on host GPIO calling convention.
- If WP or DPD pin was not used, write -1. Currently, mflash bank support s3c2440 and pxa270.
- @end itemize
- (ex. of s3c2440) mflash <@var{RST pin}> is GPIO B1, <@var{WP pin}> and <@var{DPD pin}> are not used.
- @smallexample
- mflash bank s3c2440 0x10000000 2 2 1b -1 -1 0
- @end smallexample
- (ex. of pxa270) mflash <@var{RST pin}> is GPIO 43, <@var{DPD pin}> is not used and <@var{DPD pin}> is GPIO 51.
- @smallexample
- mflash bank pxa270 0x08000000 2 2 43 -1 51 0
- @end smallexample
-
- @node Target library
- @chapter Target library
- @cindex Target library
-
- OpenOCD comes with a target configuration script library. These scripts can be
- used as-is or serve as a starting point.
-
- The target library is published together with the openocd executable and
- the path to the target library is in the OpenOCD script search path.
- Similarly there are example scripts for configuring the JTAG interface.
-
- The command line below uses the example parport configuration scripts
- that ship with OpenOCD, then configures the str710.cfg target and
- finally issues the init and reset command. The communication speed
- is set to 10kHz for reset and 8MHz for post reset.
-
-
- @smallexample
- openocd -f interface/parport.cfg -f target/str710.cfg -c "init" -c "reset"
- @end smallexample
-
-
- To list the target scripts available:
-
- @smallexample
- $ ls /usr/local/lib/openocd/target
-
- arm7_fast.cfg lm3s6965.cfg pxa255.cfg stm32.cfg xba_revA3.cfg
- at91eb40a.cfg lpc2148.cfg pxa255_sst.cfg str710.cfg zy1000.cfg
- at91r40008.cfg lpc2294.cfg sam7s256.cfg str912.cfg
- at91sam9260.cfg nslu2.cfg sam7x256.cfg wi-9c.cfg
- @end smallexample
-
-
- @node Commands
- @chapter Commands
- @cindex commands
-
- OpenOCD allows user interaction through a GDB server (default: port 3333),
- a telnet interface (default: port 4444), and a TCL interface (default: port 5555). The command line interpreter
- is available from both the telnet interface and a GDB session. To issue commands to the
- interpreter from within a GDB session, use the @option{monitor} command, e.g. use
- @option{monitor poll} to issue the @option{poll} command. All output is relayed through the
- GDB session.
-
- The TCL interface is used as a simplified RPC mechanism that feeds all the
- input into the TCL interpreter and returns the output from the evaluation of
- the commands.
-
- @section Daemon
-
- @itemize @bullet
- @item @b{sleep} <@var{msec}>
- @cindex sleep
- @*Wait for n milliseconds before resuming. Useful in connection with script files
- (@var{script} command and @var{target_script} configuration).
-
- @item @b{shutdown}
- @cindex shutdown
- @*Close the OpenOCD daemon, disconnecting all clients (GDB, Telnet, Other).
-
- @item @b{debug_level} [@var{n}]
- @cindex debug_level
- @anchor{debug_level}
- @*Display or adjust debug level to n<0-3>
-
- @item @b{fast} [@var{enable|disable}]
- @cindex fast
- @*Default disabled. Set default behaviour of OpenOCD to be "fast and dangerous". For instance ARM7/9 DCC memory
- downloads and fast memory access will work if the JTAG interface isn't too fast and
- the core doesn't run at a too low frequency. Note that this option only changes the default
- and that the indvidual options, like DCC memory downloads, can be enabled and disabled
- individually.
-
- The target specific "dangerous" optimisation tweaking options may come and go
- as more robust and user friendly ways are found to ensure maximum throughput
- and robustness with a minimum of configuration.
-
- Typically the "fast enable" is specified first on the command line:
-
- @smallexample
- openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg
- @end smallexample
-
- @item @b{log_output} <@var{file}>
- @cindex log_output
- @*Redirect logging to <file> (default: stderr)
-
- @item @b{script} <@var{file}>
- @cindex script
- @*Execute commands from <file>
-
- @end itemize
-
- @subsection Target state handling
- @itemize @bullet
- @item @b{power} <@var{on}|@var{off}>
- @cindex reg
- @*Turn power switch to target on/off.
- No arguments: print status.
-
-
- @item @b{reg} [@option{#}|@option{name}] [value]
- @cindex reg
- @*Access a single register by its number[@option{#}] or by its [@option{name}].
- No arguments: list all available registers for the current target.
- Number or name argument: display a register
- Number or name and value arguments: set register value
-
- @item @b{poll} [@option{on}|@option{off}]
- @cindex poll
- @*Poll the target for its current state. If the target is in debug mode, architecture
- specific information about the current state is printed. An optional parameter
- allows continuous polling to be enabled and disabled.
-
- @item @b{halt} [@option{ms}]
- @cindex halt
- @*Send a halt request to the target and wait for it to halt for up to [@option{ms}] milliseconds.
- 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
- @*Single-step the target at its current code position, or at an optional address.
-
- @item @b{reset} [@option{run}|@option{halt}|@option{init}]
- @cindex reset
- @*Perform a hard-reset. The optional parameter specifies what should happen after the reset.
-
- With no arguments a "reset run" is executed
- @itemize @minus
- @item @b{run}
- @cindex reset run
- @*Let the target run.
- @item @b{halt}
- @cindex reset halt
- @*Immediately halt the target (works only with certain configurations).
- @item @b{init}
- @cindex reset init
- @*Immediately halt the target, and execute the reset script (works only with certain
- configurations)
- @end itemize
-
- @item @b{soft_reset_halt}
- @cindex reset
- @*Requesting target halt and executing a soft reset.
- @end itemize
-
- @subsection Memory access commands
- @itemize @bullet
- @item @b{meminfo}
-
- display available ram memory.
- @end itemize
- These commands allow accesses of a specific size to the memory system:
- @itemize @bullet
- @item @b{mdw} <@var{addr}> [@var{count}]
- @cindex mdw
- @*display memory words
- @item @b{mdh} <@var{addr}> [@var{count}]
- @cindex mdh
- @*display memory half-words
- @item @b{mdb} <@var{addr}> [@var{count}]
- @cindex mdb
- @*display memory bytes
- @item @b{mww} <@var{addr}> <@var{value}>
- @cindex mww
- @*write memory word
- @item @b{mwh} <@var{addr}> <@var{value}>
- @cindex mwh
- @*write memory half-word
- @item @b{mwb} <@var{addr}> <@var{value}>
- @cindex mwb
- @*write memory byte
-
- @item @b{load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
- @cindex load_image
- @anchor{load_image}
- @*Load image <@var{file}> to target memory at <@var{address}>
- @item @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 IO overhead is significant(OpenOCD running on embedded
- host), then storing the image in memory and uploading the image to the target
- can be a way to upload e.g. multiple debug sessions when the binary does not change.
- Arguments as @b{load_image}, but image is stored in OpenOCD host
- memory, i.e. does not affect target. This approach is also useful when profiling
- target programming performance as IO and target programming can easily be profiled
- seperately.
- @item @b{fast_load}
- @cindex fast_image
- @anchor{fast_image}
- @*Loads image stored in memory by @b{fast_load_image} to current target. Must be preceeded by fast_load_image.
- @item @b{dump_image} <@var{file}> <@var{address}> <@var{size}>
- @cindex dump_image
- @anchor{dump_image}
- @*Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
- (binary) <@var{file}>.
- @item @b{verify_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
- @cindex verify_image
- @*Verify <@var{file}> against target memory starting at <@var{address}>.
- This will first attempt comparison using a crc checksum, if this fails it will try a binary compare.
- @end itemize
-
- @subsection Breakpoint commands
- @cindex Breakpoint commands
- @itemize @bullet
- @item @b{bp} <@var{addr}> <@var{len}> [@var{hw}]
- @cindex bp
- @*set breakpoint <address> <length> [hw]
- @item @b{rbp} <@var{addr}>
- @cindex rbp
- @*remove breakpoint <adress>
- @item @b{wp} <@var{addr}> <@var{len}> <@var{r}|@var{w}|@var{a}> [@var{value}] [@var{mask}]
- @cindex wp
- @*set watchpoint <address> <length> <r/w/a> [value] [mask]
- @item @b{rwp} <@var{addr}>
- @cindex rwp
- @*remove watchpoint <adress>
- @end itemize
-
- @subsection Flash commands
- @cindex Flash commands
- @itemize @bullet
- @item @b{flash banks}
- @cindex flash banks
- @*List configured flash banks
- @item @b{flash info} <@var{num}>
- @cindex flash info
- @*Print info about flash bank <@option{num}>
- @item @b{flash probe} <@var{num}>
- @cindex flash probe
- @*Identify the flash, or validate the parameters of the configured flash. Operation
- depends on the flash type.
- @item @b{flash erase_check} <@var{num}>
- @cindex flash erase_check
- @*Check erase state of sectors in flash bank <@var{num}>. This is the only operation that
- updates the erase state information displayed by @option{flash info}. That means you have
- to issue an @option{erase_check} command after erasing or programming the device to get
- updated information.
- @item @b{flash protect_check} <@var{num}>
- @cindex flash protect_check
- @*Check protection state of sectors in flash bank <num>.
- @option{flash erase_sector} using the same syntax.
- @item @b{flash erase_sector} <@var{num}> <@var{first}> <@var{last}>
- @cindex flash erase_sector
- @anchor{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 may
- 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}> bytes
- @item @b{flash write_bank} <@var{num}> <@var{file}> <@var{offset}>
- @cindex flash write_bank
- @anchor{flash write_bank}
- @*Write the binary <@var{file}> to flash bank <@var{num}>, starting at
- <@option{offset}> bytes from the beginning of the bank.
- @item @b{flash write_image} [@var{erase}] <@var{file}> [@var{offset}] [@var{type}]
- @cindex flash write_image
- @anchor{flash write_image}
- @*Write the image <@var{file}> to the current target's flash bank(s). A relocation
- [@var{offset}] can be specified and the file [@var{type}] can be specified
- explicitly as @option{bin} (binary), @option{ihex} (Intel hex), @option{elf}
- (ELF file) or @option{s19} (Motorola s19). Flash memory will be erased prior to programming
- if the @option{erase} parameter is given.
- @item @b{flash protect} <@var{num}> <@var{first}> <@var{last}> <@option{on}|@option{off}>
- @cindex flash protect
- @*Enable (@var{on}) or disable (@var{off}) protection of flash sectors <@var{first}> to
- <@var{last}> of @option{flash bank} <@var{num}>.
- @end itemize
-
- @subsection mFlash commands
- @cindex mFlash commands
- @itemize @bullet
- @item @b{mflash probe}
- @cindex mflash probe
- Probe mflash.
- @item @b{mflash write} <@var{num}> <@var{file}> <@var{offset}>
- @cindex mflash write
- Write the binary <@var{file}> to mflash bank <@var{num}>, starting at
- <@var{offset}> bytes from the beginning of the bank.
- @item @b{mflash dump} <@var{num}> <@var{file}> <@var{offset}> <@var{size}>
- @cindex mflash dump
- Dump <size> bytes, starting at <@var{offset}> bytes from the beginning of the <@var{num}> bank
- to a <@var{file}>.
- @end itemize
-
- @page
- @section Target Commands
- @cindex Target Commands
-
- @subsection Overview
- @cindex Overview
- Pre "TCL" - many commands in OpenOCD where implemented as C functions. Post "TCL"
- (Jim-Tcl to be more exact, June 2008) TCL became a bigger part of OpenOCD.
-
- One of the biggest changes is the introduction of 'target specific'
- commands. When every time you create a target, a special command name is
- created specifically for that target.
- For example - in TCL/TK - if you create a button (or any other screen object) you
- can specify various "button configuration parameters". One of those parameters is
- the "object cmd/name" [ In TK - this is referred to as the object path ]. Later
- you can use that 'path' as a command to modify the button, for example to make it
- "grey", or change the color. In effect, the "path" function is an 'object
- oriented command'. The TCL change in OpenOCD follows the same principle, you create
- a target, and a specific "targetname" command is created.
-
- There are two methods of creating a target:
-
- @enumerate
- @item
- Using the old syntax (deprecated). Target names are autogenerated as:
- "target0", "target1", etc.;
- @cindex old syntax
- @item
- Using the new syntax, you can specify the name of the target.
- @cindex new syntax
- @end enumerate
-
- As most users will have a single JTAG target, and by default the command name will
- probably default to "target0", thus for reasons of simplicity the instructions below
- use the name "target0".
-
- @subsection Commands
- @cindex Commands
- OpenOCD has the following 'target' or 'target-like' commands:
-
- @enumerate
- @item
- @b{targets (plural)} - lists all known targets and a little bit of information about each
- target, most importantly the target *COMMAND*NAME* (it also lists the target number);
- @cindex targets
- @item
- @b{target (singular)} - used to create, configure list, etc the targets;
- @cindex target
- @item
- @b{target0} - the command object for the first target. Unless you specified another name.
- @cindex target0
- @end enumerate
-
- @subsubsection Targets Command
- @cindex Targets Command
- The "targets" command has 2 functions:
-
- @itemize
- @item
- With a parameter, you can change the current command line target.
-
- NOTE: "with a parameter" is really only useful with 'multiple JTAG targets' not something
- you normally encounter (ie: If you had 2 arm chips - sharing the same JTAG chain).
- @verbatim
- # using a target name.
- (gdb) mon targets target0
- # or a target by number.
- (gdb) mon targets 3
- @end verbatim
- @cindex with a parameter
- @item
- Plain, without any parameter lists targets, for example:
-
- @verbatim
- (gdb) mon targets
- CmdName Type Endian ChainPos State
- -- ---------- ---------- ---------- -------- ----------
- 0: target0 arm7tdmi little 0 halted
- @end verbatim
-
- This shows:
- @enumerate a
- @item
- in this example, a single target;
- @item
- target number 0 (1st column);
- @item
- the 'object name' is target0 (the default name);
- @item
- it is an arm7tdmi;
- @item
- little endian;
- @item
- the position in the JTAG chain;
- @item
- and is currently halted.
- @end enumerate
- @cindex without any parameter
- @end itemize
-
- @subsubsection Target Command
- @cindex Target Command
-
- The "target" command has the following options:
- @itemize
- @item
- target create
-
- @verbatim
- target create CMDNAME TYPE ... config options ...
- argv[0] = 'target'
- argv[1] = 'create'
- argv[2] = the 'object command'
- (normally, target0, see (3) above)
- argv[3] = the target type, ie: arm7tdmi
- argv[4..N] = configuration parameters
- @end verbatim
- @item
- target types
-
- Lists all supported target types; ie: arm7tdmi, xscale, fericon, cortex-m3.
- The result TCL list of all known target types (and is human readable).
- @item
- target names
-
- Returns a TCL list of all known target commands (and is human readable).
-
- Example:
- @verbatim
- foreach t [target names] {
- puts [format "Target: %s\n" $t]
- }
- @end verbatim
- @item
- target current
-
- Returns the TCL command name of the current target.
-
- Example:
- @verbatim
- set ct [target current]
- set t [$ct cget -type]
-
- puts "Current target name is: $ct, and is a: $t"
- @end verbatim
- @item
- target number <VALUE>
-
- Returns the TCL command name of the specified target.
-
- Example
- @verbatim
- set thename [target number $x]
- puts [format "Target %d is: %s\n" $x $thename]
- @end verbatim
- For instance, assuming the defaults
- @verbatim
- target number 0
- @end verbatim
- Would return 'target0' (or whatever you called it)
- @item
- target count
-
- Returns the larget+1 target number.
-
- Example:
- @verbatim
- set c [target count]
- for { set x 0 } { $x < $c } { incr x } {
- # Assuming you have this function..
- print_target_details $x
- }
- @end verbatim
- @end itemize
-
- @subsubsection Target0 Command
- @cindex Target0 Command
- The "target0" command (the "Target Object" command):
-
- Once a target is 'created' a command object by that targets name is created, for example
- @verbatim
- target create BiGRed arm7tdmi -endian little -chain-position 3
- @end verbatim
-
- Would create a [case sensitive] "command" BiGRed
-
- If you use the old [deprecated] syntax, the name is automatically
- generated and is in the form:
- @verbatim
- target0, target1, target2, target3, ... etc.
- @end verbatim
-
- @subsubsection Target CREATE, CONFIGURE and CGET Options Command
- @cindex Target CREATE, CONFIGURE and CGET Options Command
- The commands:
- @verbatim
- target create CMDNAME TYPE [configure-options]
- CMDNAME configure [configure-options]
- CMDNAME cget [configure-options]
- @end verbatim
- @itemize
- @item
- In the 'create' case, one is creating the target and can specify any
- number of configuration parameters.
- @item
- In the 'CMDNAME configure' case, one can change the setting [Not all things can, or should be changed].
- @item
- In the 'CMDNAME cget' case, the goal is to query the target for a
- specific configuration option.
- @end itemize
-
- In the above, the "default" name target0 is 'target0'.
-
- Example:
-
- From the (gdb) prompt, one can type this:
-
- @verbatim
- (gdb) mon target0 configure -endian big
- @end verbatim
-
- And change target0 to 'big-endian'. This is a contrived example,
- specifically for this document - don't expect changing endian
- 'mid-operation' to work you should set the endian at creation.
-
- Known options [30/august/2008] are:
- @itemize
- @item
- [Mandatory 'create' Options]
- @itemize
- @item
- type arm7tdmi|arm720|etc ...
- @item
- chain-position NUMBER
- @item
- endian ENDIAN
- @end itemize
- @item
- Optional
- @itemize
- @item
- event EVENTNAME "tcl-action"
- @item
- reset RESETACTION
- @item
- work-area-virt ADDR
- @item
- work-area-phys ADDR
- @item
- work-area-size ADDR
- @item
- work-area-backup BOOLEAN
- @end itemize
- @end itemize
- Hint: To get a list of available options, try this:
- @verbatim
- (gdb) mon target0 cget -BLAHBLAHBLAH
- @end verbatim
-
- the above causes an error - and a helpful list of valid options.
-
- One can query any of the above options at run time, for example:
- @verbatim
- (gdb) mon target0 cget -OPTION [param]
- @end verbatim
-
- Example TCL script
-
- @verbatim
- # For all targets...
- set c [target count]
- for { set x 0 } { $x < $c } { incr x ] {
- set n [target number $x]
- set t [$n cget -type]
- set e [$n cget -endian]
- puts [format "%d: %s, %s, endian: %s\n" $x $n $t $n]
- }
- @end verbatim
-
- Might produce:
-
- @verbatim
- 0: pic32chip, mips_m4k, endain: little
- 1: arm7, arm7tdmi, endian: big
- 2: blackfin, bf534, endian: little
- @end verbatim
-
- Notice the above example is not target0, target1, target2 Why? Because in this contrived multi-target example -
- more human understandable target names might be helpful.
-
- For example these two are the same:
-
- @verbatim
- (gdb) mon blackfin configure -event FOO {puts "Hi mom"}
- @end verbatim
-
- or:
-
- @verbatim
- (gdb) mon [target number 2] configure -event FOO {puts "Hi mom"}
- @end verbatim
-
- In the second case, we use [] to get the command name of target #2, in this contrived example - it is "blackfin".
-
- Two important configuration options are:
-
- "-event" and "-reset"
-
- The "-reset" option specifies what should happen when the chip is reset, for example should it 'halt', 're-init',
- or what.
-
- The "-event" option less you specify a TCL command to occur when a specific event occurs.
-
- @subsubsection Other Target Commands
- @cindex Other Target Commands
- @itemize
- @item @b{profile} <@var{seconds}> <@var{gmon.out}>
-
- Profiling samples the CPU PC as quickly as OpenOCD is able, which will be used as a random sampling of PC.
- @end itemize
-
- @subsection Target Events
- @cindex Target Events
-
- @subsubsection Overview
- @cindex Overview
- At various points in time - certain 'target' events happen. You can create a custom event action to occur at that time.
- For example - after reset, the PLLs and CLOCKs may need to be reconfigured, or perhaps the SDRAM needs to be re-initialized.
- Often the easiest way to do that is to create a simple script file containing the series of (mww [poke memory]) commands
- you would type by hand, to reconfigure the target clocks. You could specify the "event action" like this:
-
- @verbatim
- (gdb) mon target0 configure -event reset-init "script cfg.clocks"
- @end verbatim
-
- In the above example, when the event "reset-init" occurs, the "action-string" will be evaluated as if you typed it at the
- console:
- @itemize
- @item @b{Option1} - The simple approach (above) is to create a script file with lots of "mww" (memory write word) commands
- to configure your targets clocks and/or external memory;
- @item @b{Option2} - You can instead create a fancy TCL procedure and invoke that procedure instead of sourcing a file [In fact,
- "script" is a TCL procedure that loads a file].
- @end itemize
-
- @subsubsection Details
- @cindex Details
- There are many events one could use, to get a current list of events type the following invalid command, you'll get a helpful
- "runtime error" message, see below [list valid as of 30/august/2008]:
-
- @verbatim
- (gdb) mon target0 cget -event FAFA
- Runtime error, file "../../../openocd23/src/helper/command.c", line 433:
- -event: Unknown: FAFA, try one of: old-pre_reset,
- old-gdb_program_config, old-post_reset, halted,
- resumed, resume-start, resume-end, reset-start,
- reset-assert-pre, reset-assert-post,
- reset-deassert-pre, reset-deassert-post,
- reset-halt-pre, reset-halt-post, reset-wait-pre,
- reset-wait-post, reset-init, reset-end,
- examine-start, examine-end, debug-halted,
- debug-resumed, gdb-attach, gdb-detach,
- gdb-flash-write-start, gdb-flash-write-end,
- gdb-flash-erase-start, gdb-flash-erase-end,
- resume-start, resume-ok, or resume-end
- @end verbatim
-
- NOTE: The event-names "old-*" are deprecated and exist only to help old scripts continue to function, and the old "target_script"
- command to work. Please do not rely on them.
-
- These are some other important names:
- @itemize
- @item gdb-flash-erase-start
- @item gdb-flash-erase-end
- @item gdb-flash-write-start
- @item gdb-flash-write-end
- @end itemize
-
- These occur when GDB/OpenOCD attempts to erase & program the FLASH chip via GDB. For example - some PCBs may have a simple GPIO
- pin that acts like a "flash write protect" you might need to write a script that disables "write protect".
-
- To get a list of current 'event actions', type the following command:
-
- @verbatim
- (gdb) mon target0 eventlist
-
- Event actions for target (0) target0
-
- Event | Body
- ------------------------- | ----------------------------------------
- old-post_reset | script event/sam7x256_reset.script
- @end verbatim
-
- Here is a simple example for all targets:
-
- @verbatim
- (gdb) mon foreach x [target names] { $x eventlist }
- @end verbatim
-
- The above uses some TCL tricks:
- @enumerate a
- @item foreach VARIABLE LIST BODY
- @item to generate the list, we use [target names]
- @item the BODY, contains $x - the loop variable and expands to the target specific name
- @end enumerate
-
- Recalling the earlier discussion - the "object command" there are other things you can
- do besides "configure" the target.
-
- Note: Many of these commands exist as "global" commands, and they also exist as target
- specific commands. For example, the "mww" (memory write word) operates on the current
- target if you have more then 1 target, you must switch. In contrast to the normal
- commands, these commands operate on the specific target. For example, the command "mww"
- writes data to the *current* command line target.
-
- Often, you have only a single target - but if you have multiple targets (ie: a PIC32
- and an at91sam7 - your reset-init scripts might get a bit more complicated, ie: you must
- specify which of the two chips you want to write to. Writing 'pic32' clock configuration
- to an at91sam7 does not work).
-
- The commands are [as of 30/august/2008]:
- @verbatim
- TNAME mww ADDRESS VALUE
- TNAME mwh ADDRESS VALUE
- TNAME mwb ADDRESS VALUE
- Write(poke): 32, 16, 8bit values to memory.
-
- TNAME mdw ADDRESS VALUE
- TNAME mdh ADDRESS VALUE
- TNAME mdb ADDRESS VALUE
- Human 'hexdump' with ascii 32, 16, 8bit values
-
- TNAME mem2array [see mem2array command]
- TNAME array2mem [see array2mem command]
-
- TNAME curstate
- Returns the current state of the target.
-
- TNAME examine
- See 'advanced target reset'
- TNAME poll
- See 'advanced target reset'
- TNAME reset assert
- See 'advanced target reset'
- TNAME reset deassert
- See 'advanced target reset'
- TNAME halt
- See 'advanced target reset'
- TNAME waitstate STATENAME
- See 'advanced target reset'
- @end verbatim
-
- @page
- @section Target Specific Commands
- @cindex Target Specific Commands
-
- @subsection AT91SAM7 specific commands
- @cindex AT91SAM7 specific commands
- The flash configuration is deduced from the chip identification register. The flash
- controller handles erases automatically on a page (128/265 byte) basis so erase is
- not necessary for flash programming. AT91SAM7 processors with less than 512K flash
- only have a single flash bank embedded on chip. AT91SAM7xx512 have two flash planes
- that can be erased separatly. Only an EraseAll command is supported by the controller
- for each flash plane and this is called with
- @itemize @bullet
- @item @b{flash erase} <@var{num}> @var{first_plane} @var{last_plane}
- @*bulk erase flash planes first_plane to last_plane.
- @item @b{at91sam7 gpnvm} <@var{num}> <@var{bit}> <@option{set}|@option{clear}>
- @cindex at91sam7 gpnvm
- @*set or clear a gpnvm bit for the processor
- @end itemize
-
- @subsection STR9 specific commands
- @cindex STR9 specific commands
- These are flash specific commands when using the str9xpec driver.
- @itemize @bullet
- @item @b{str9xpec enable_turbo} <@var{num}>
- @cindex str9xpec enable_turbo
- @*enable turbo mode, simply this will remove the str9 from the chain and talk
- directly to the embedded flash controller.
- @item @b{str9xpec disable_turbo} <@var{num}>
- @cindex str9xpec disable_turbo
- @*restore the str9 into jtag chain.
- @item @b{str9xpec lock} <@var{num}>
- @cindex str9xpec lock
- @*lock str9 device. The str9 will only respond to an unlock command that will
- erase the device.
- @item @b{str9xpec unlock} <@var{num}>
- @cindex str9xpec unlock
- @*unlock str9 device.
- @item @b{str9xpec options_read} <@var{num}>
- @cindex str9xpec options_read
- @*read str9 option bytes.
- @item @b{str9xpec options_write} <@var{num}>
- @cindex str9xpec options_write
- @*write str9 option bytes.
- @end itemize
-
- @subsection STR9 configuration
- @cindex STR9 configuration
- @itemize @bullet
- @item @b{str9x flash_config} <@var{bank}> <@var{BBSR}> <@var{NBBSR}>
- <@var{BBADR}> <@var{NBBADR}>
- @cindex str9x flash_config
- @*Configure str9 flash controller.
- @smallexample
- eg. str9x flash_config 0 4 2 0 0x80000
- This will setup
- BBSR - Boot Bank Size register
- NBBSR - Non Boot Bank Size register
- BBADR - Boot Bank Start Address register
- NBBADR - Boot Bank Start Address register
- @end smallexample
- @end itemize
-
- @subsection STR9 option byte configuration
- @cindex STR9 option byte configuration
- @itemize @bullet
- @item @b{str9xpec options_cmap} <@var{num}> <@option{bank0}|@option{bank1}>
- @cindex str9xpec options_cmap
- @*configure str9 boot bank.
- @item @b{str9xpec options_lvdthd} <@var{num}> <@option{2.4v}|@option{2.7v}>
- @cindex str9xpec options_lvdthd
- @*configure str9 lvd threshold.
- @item @b{str9xpec options_lvdsel} <@var{num}> <@option{vdd}|@option{vdd_vddq}>
- @cindex str9xpec options_lvdsel
- @*configure str9 lvd source.
- @item @b{str9xpec options_lvdwarn} <@var{bank}> <@option{vdd}|@option{vdd_vddq}>
- @cindex str9xpec options_lvdwarn
- @*configure str9 lvd reset warning source.
- @end itemize
-
- @subsection STM32x specific commands
- @cindex STM32x specific commands
-
- These are flash specific commands when using the stm32x driver.
- @itemize @bullet
- @item @b{stm32x lock} <@var{num}>
- @cindex stm32x lock
- @*lock stm32 device.
- @item @b{stm32x unlock} <@var{num}>
- @cindex stm32x unlock
- @*unlock stm32 device.
- @item @b{stm32x options_read} <@var{num}>
- @cindex stm32x options_read
- @*read stm32 option bytes.
- @item @b{stm32x options_write} <@var{num}> <@option{SWWDG}|@option{HWWDG}>
- <@option{RSTSTNDBY}|@option{NORSTSTNDBY}> <@option{RSTSTOP}|@option{NORSTSTOP}>
- @cindex stm32x options_write
- @*write stm32 option bytes.
- @item @b{stm32x mass_erase} <@var{num}>
- @cindex stm32x mass_erase
- @*mass erase flash memory.
- @end itemize
-
- @subsection Stellaris specific commands
- @cindex Stellaris specific commands
-
- These are flash specific commands when using the Stellaris driver.
- @itemize @bullet
- @item @b{stellaris mass_erase} <@var{num}>
- @cindex stellaris mass_erase
- @*mass erase flash memory.
- @end itemize
-
- @page
- @section Architecture Specific Commands
- @cindex Architecture Specific Commands
-
- @subsection ARMV4/5 specific commands
- @cindex ARMV4/5 specific commands
-
- These commands are specific to ARM architecture v4 and v5, like all ARM7/9 systems
- or Intel XScale (XScale isn't supported yet).
- @itemize @bullet
- @item @b{armv4_5 reg}
- @cindex armv4_5 reg
- @*Display a list of all banked core registers, fetching the current value from every
- core mode if necessary. OpenOCD versions before rev. 60 didn't fetch the current
- register value.
- @item @b{armv4_5 core_mode} [@var{arm}|@var{thumb}]
- @cindex armv4_5 core_mode
- @*Displays the core_mode, optionally changing it to either ARM or Thumb mode.
- The target is resumed in the currently set @option{core_mode}.
- @end itemize
-
- @subsection ARM7/9 specific commands
- @cindex ARM7/9 specific commands
-
- These commands are specific to ARM7 and ARM9 targets, like ARM7TDMI, ARM720t,
- ARM920t or ARM926EJ-S.
- @itemize @bullet
- @item @b{arm7_9 dbgrq} <@var{enable}|@var{disable}>
- @cindex arm7_9 dbgrq
- @*Enable use of the DBGRQ bit to force entry into debug mode. This should be
- safe for all but ARM7TDMI--S cores (like Philips LPC).
- @item @b{arm7_9 fast_memory_access} <@var{enable}|@var{disable}>
- @cindex arm7_9 fast_memory_access
- @anchor{arm7_9 fast_memory_access}
- @*Allow OpenOCD to read and write memory without checking completion of
- the operation. This provides a huge speed increase, especially with USB JTAG
- cables (FT2232), but might be unsafe if used with targets running at a very low
- speed, like the 32kHz startup clock of an AT91RM9200.
- @item @b{arm7_9 dcc_downloads} <@var{enable}|@var{disable}>
- @cindex arm7_9 dcc_downloads
- @*Enable the use of the debug communications channel (DCC) to write larger (>128 byte)
- amounts of memory. DCC downloads offer a huge speed increase, but might be potentially
- unsafe, especially with targets running at a very low speed. This command was introduced
- with OpenOCD rev. 60.
- @end itemize
-
- @subsection ARM720T specific commands
- @cindex ARM720T specific commands
-
- @itemize @bullet
- @item @b{arm720t cp15} <@var{num}> [@var{value}]
- @cindex arm720t cp15
- @*display/modify cp15 register <@option{num}> [@option{value}].
- @item @b{arm720t md<bhw>_phys} <@var{addr}> [@var{count}]
- @cindex arm720t md<bhw>_phys
- @*Display memory at physical address addr.
- @item @b{arm720t mw<bhw>_phys} <@var{addr}> <@var{value}>
- @cindex arm720t mw<bhw>_phys
- @*Write memory at physical address addr.
- @item @b{arm720t virt2phys} <@var{va}>
- @cindex arm720t virt2phys
- @*Translate a virtual address to a physical address.
- @end itemize
-
- @subsection ARM9TDMI specific commands
- @cindex ARM9TDMI specific commands
-
- @itemize @bullet
- @item @b{arm9tdmi vector_catch} <@var{all}|@var{none}>
- @cindex arm9tdmi vector_catch
- @*Catch arm9 interrupt vectors, can be @option{all} @option{none} or any of the following:
- @option{reset} @option{undef} @option{swi} @option{pabt} @option{dabt} @option{reserved}
- @option{irq} @option{fiq}.
-
- Can also be used on other arm9 based cores, arm966, arm920t and arm926ejs.
- @end itemize
-
- @subsection ARM966E specific commands
- @cindex ARM966E specific commands
-
- @itemize @bullet
- @item @b{arm966e cp15} <@var{num}> [@var{value}]
- @cindex arm966e cp15
- @*display/modify cp15 register <@option{num}> [@option{value}].
- @end itemize
-
- @subsection ARM920T specific commands
- @cindex ARM920T specific commands
-
- @itemize @bullet
- @item @b{arm920t cp15} <@var{num}> [@var{value}]
- @cindex arm920t cp15
- @*display/modify cp15 register <@option{num}> [@option{value}].
- @item @b{arm920t cp15i} <@var{num}> [@var{value}] [@var{address}]
- @cindex arm920t cp15i
- @*display/modify cp15 (interpreted access) <@option{opcode}> [@option{value}] [@option{address}]
- @item @b{arm920t cache_info}
- @cindex arm920t cache_info
- @*Print information about the caches found. This allows you to see if your target
- is a ARM920T (2x16kByte cache) or ARM922T (2x8kByte cache).
- @item @b{arm920t md<bhw>_phys} <@var{addr}> [@var{count}]
- @cindex arm920t md<bhw>_phys
- @*Display memory at physical address addr.
- @item @b{arm920t mw<bhw>_phys} <@var{addr}> <@var{value}>
- @cindex arm920t mw<bhw>_phys
- @*Write memory at physical address addr.
- @item @b{arm920t read_cache} <@var{filename}>
- @cindex arm920t read_cache
- @*Dump the content of ICache and DCache to a file.
- @item @b{arm920t read_mmu} <@var{filename}>
- @cindex arm920t read_mmu
- @*Dump the content of the ITLB and DTLB to a file.
- @item @b{arm920t virt2phys} <@var{va}>
- @cindex arm920t virt2phys
- @*Translate a virtual address to a physical address.
- @end itemize
-
- @subsection ARM926EJS specific commands
- @cindex ARM926EJS specific commands
-
- @itemize @bullet
- @item @b{arm926ejs cp15} <@var{num}> [@var{value}]
- @cindex arm926ejs cp15
- @*display/modify cp15 register <@option{num}> [@option{value}].
- @item @b{arm926ejs cache_info}
- @cindex arm926ejs cache_info
- @*Print information about the caches found.
- @item @b{arm926ejs md<bhw>_phys} <@var{addr}> [@var{count}]
- @cindex arm926ejs md<bhw>_phys
- @*Display memory at physical address addr.
- @item @b{arm926ejs mw<bhw>_phys} <@var{addr}> <@var{value}>
- @cindex arm926ejs mw<bhw>_phys
- @*Write memory at physical address addr.
- @item @b{arm926ejs virt2phys} <@var{va}>
- @cindex arm926ejs virt2phys
- @*Translate a virtual address to a physical address.
- @end itemize
-
- @page
- @section Debug commands
- @cindex Debug commands
- The following commands give direct access to the core, and are most likely
- only useful while debugging OpenOCD.
- @itemize @bullet
- @item @b{arm7_9 write_xpsr} <@var{32-bit value}> <@option{0=cpsr}, @option{1=spsr}>
- @cindex arm7_9 write_xpsr
- @*Immediately write either the current program status register (CPSR) or the saved
- program status register (SPSR), without changing the register cache (as displayed
- by the @option{reg} and @option{armv4_5 reg} commands).
- @item @b{arm7_9 write_xpsr_im8} <@var{8-bit value}> <@var{rotate 4-bit}>
- <@var{0=cpsr},@var{1=spsr}>
- @cindex arm7_9 write_xpsr_im8
- @*Write the 8-bit value rotated right by 2*rotate bits, using an immediate write
- operation (similar to @option{write_xpsr}).
- @item @b{arm7_9 write_core_reg} <@var{num}> <@var{mode}> <@var{value}>
- @cindex arm7_9 write_core_reg
- @*Write a core register, without changing the register cache (as displayed by the
- @option{reg} and @option{armv4_5 reg} commands). The <@var{mode}> argument takes the
- encoding of the [M4:M0] bits of the PSR.
- @end itemize
-
- @page
- @section JTAG commands
- @cindex JTAG commands
- @itemize @bullet
- @item @b{scan_chain}
- @cindex scan_chain
- @*Print current scan chain configuration.
- @item @b{jtag_reset} <@var{trst}> <@var{srst}>
- @cindex jtag_reset
- @*Toggle reset lines.
- @item @b{endstate} <@var{tap_state}>
- @cindex endstate
- @*Finish JTAG operations in <@var{tap_state}>.
- @item @b{runtest} <@var{num_cycles}>
- @cindex runtest
- @*Move to Run-Test/Idle, and execute <@var{num_cycles}>
- @item @b{statemove} [@var{tap_state}]
- @cindex statemove
- @*Move to current endstate or [@var{tap_state}]
- @item @b{irscan} <@var{device}> <@var{instr}> [@var{dev2}] [@var{instr2}] ...
- @cindex irscan
- @*Execute IR scan <@var{device}> <@var{instr}> [@var{dev2}] [@var{instr2}] ...
- @item @b{drscan} <@var{device}> [@var{dev2}] [@var{var2}] ...
- @cindex drscan
- @*Execute DR scan <@var{device}> [@var{dev2}] [@var{var2}] ...
- @item @b{verify_ircapture} <@option{enable}|@option{disable}>
- @cindex verify_ircapture
- @*Verify value captured during Capture-IR. Default is enabled.
- @item @b{var} <@var{name}> [@var{num_fields}|@var{del}] [@var{size1}] ...
- @cindex var
- @*Allocate, display or delete variable <@var{name}> [@var{num_fields}|@var{del}] [@var{size1}] ...
- @item @b{field} <@var{var}> <@var{field}> [@var{value}|@var{flip}]
- @cindex field
- Display/modify variable field <@var{var}> <@var{field}> [@var{value}|@var{flip}].
- @end itemize
-
- @page
- @section Target Requests
- @cindex Target Requests
- OpenOCD can handle certain target requests, currently debugmsg are only supported for arm7_9 and cortex_m3.
- See libdcc in the contrib dir for more details.
- @itemize @bullet
- @item @b{target_request debugmsgs} <@var{enable}|@var{disable}>
- @cindex target_request debugmsgs
- @*Enable/disable target debugmsgs requests. debugmsgs enable messages to be sent to the debugger while the target is running.
- @end itemize
-
- @node TFTP
- @chapter TFTP
- @cindex TFTP
- If OpenOCD runs on an embedded host(as ZY1000 does), then tftp can
- be used to access files on PCs(either developer PC or some other PC).
-
- The way this works is to prefix a filename by "/tftp/ip/" and append
- the tftp path on the tftp server(tftpd). E.g. "load_image /tftp/10.0.0.96/c:\temp\abc.elf"
- will load c:\temp\abc.elf from the developer pc (10.0.0.96) into memory as
- if the file was hosted on the embedded host.
-
- In order to achieve decent performance, you must choose a tftp server
- that supports a packet size bigger than the default packet size(512 bytes). There
- are numerous tftp servers out there(free and commercial) and you will have to do
- a bit of googling to find something that fits your requirements.
-
- @node Sample Scripts
- @chapter Sample Scripts
- @cindex scripts
-
- This page shows how to use the target library.
-
- The configuration script can be divided in the following section:
- @itemize @bullet
- @item daemon configuration
- @item interface
- @item jtag scan chain
- @item target configuration
- @item flash configuration
- @end itemize
-
- Detailed information about each section can be found at OpenOCD configuration.
-
- @section AT91R40008 example
- @cindex AT91R40008 example
- To start OpenOCD with a target script for the AT91R40008 CPU and reset
- the CPU upon startup of the OpenOCD daemon.
- @smallexample
- openocd -f interface/parport.cfg -f target/at91r40008.cfg -c init -c reset
- @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
- Use GDB 6.7 or newer with OpenOCD if you run into trouble. For instance 6.3 has a
- known bug where it produces bogus memory access errors, which has since
- been fixed: look up 1836 in http://sourceware.org/cgi-bin/gnatsweb.pl?database=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 sent to gdb, this can be disabled by
- the following OpenOCD config option:
- @smallexample
- gdb_memory_map disable
- @end smallexample
- For this to function correctly a valid flash config must also be configured
- in OpenOCD. For faster performance you should 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{gdb_breakpoint_override} is not required when
- using a memory map. @xref{gdb_breakpoint_override}.
-
- 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.
-
- GDB 6.8 and higher set any memory area not in the memory map as inaccessible,
- this can be changed to the old behaviour by using the following gdb command.
- @smallexample
- set mem inaccessible-by-default off
- @end smallexample
-
- 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.
-
- If 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 TCL and OpenOCD
- @chapter TCL and OpenOCD
- @cindex TCL and OpenOCD
- OpenOCD embeds a TCL interpreter (see JIM) for command parsing and scripting
- support.
-
- The TCL interpreter can be invoked from the interactive command line, files, and a network port.
-
- The command and file interfaces are fairly straightforward, while the network
- port is geared toward intergration with external clients. A small example
- of an external TCL script that can connect to openocd is shown below.
-
- @verbatim
- # Simple tcl client to connect to openocd
- puts "Use empty line to exit"
- set fo [socket 127.0.0.1 6666]
- puts -nonewline stdout "> "
- flush stdout
- while {[gets stdin line] >= 0} {
- if {$line eq {}} break
- puts $fo $line
- flush $fo
- gets $fo line
- puts $line
- puts -nonewline stdout "> "
- flush stdout
- }
- close $fo
- @end verbatim
-
- This script can easily be modified to front various GUIs or be a sub
- component of a larger framework for control and interaction.
-
-
- @node TCL scripting API
- @chapter TCL scripting API
- @cindex TCL scripting API
- API rules
-
- The commands are stateless. E.g. the telnet command line has a concept
- of currently active target, the Tcl API proc's take this sort of state
- information as an argument to each proc.
-
- There are three main types of return values: single value, name value
- pair list and lists.
-
- Name value pair. The proc 'foo' below returns a name/value pair
- list.
-
- @verbatim
-
- > set foo(me) Duane
- > set foo(you) Oyvind
- > set foo(mouse) Micky
- > set foo(duck) Donald
-
- If one does this:
-
- > set foo
-
- The result is:
-
- me Duane you Oyvind mouse Micky duck Donald
-
- Thus, to get the names of the associative array is easy:
-
- foreach { name value } [set foo] {
- puts "Name: $name, Value: $value"
- }
- @end verbatim
-
- Lists returned must be relatively small. Otherwise a range
- should be passed in to the proc in question.
-
- Low level commands are prefixed with "openocd_", e.g. openocd_flash_banks
- is the low level API upon which "flash banks" is implemented.
-
- @itemize @bullet
- @item @b{ocd_mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
-
- Read memory and return as a TCL array for script processing
- @item @b{ocd_array2mem} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
-
- Convert a TCL array to memory locations and write the values
- @item @b{ocd_flash_banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...]
-
- Return information about the flash banks
- @end itemize
-
- OpenOCD commands can consist of two words, e.g. "flash banks". The
- startup.tcl "unknown" proc will translate this into a tcl proc
- called "flash_banks".
-
-
- @node Upgrading
- @chapter Deprecated/Removed Commands
- @cindex Deprecated/Removed Commands
- Certain OpenOCD commands have been deprecated/removed during the various revisions.
-
- @itemize @bullet
- @item @b{load_binary}
- @cindex load_binary
- @*use @option{load_image} command with same args. @xref{load_image}.
- @item @b{target}
- @cindex target
- @*@option{target} no longer take the reset_init, reset_run, run_and_halt, run_and_init. The @option{reset} command
- always does a @option{reset run} when passed no arguments.
- @item @b{dump_binary}
- @cindex dump_binary
- @*use @option{dump_image} command with same args. @xref{dump_image}.
- @item @b{flash erase}
- @cindex flash erase
- @*use @option{flash erase_sector} command with same args. @xref{flash erase_sector}.
- @item @b{flash write}
- @cindex flash write
- @*use @option{flash write_bank} command with same args. @xref{flash write_bank}.
- @item @b{flash write_binary}
- @cindex flash write_binary
- @*use @option{flash write_bank} command with same args. @xref{flash write_bank}.
- @item @b{arm7_9 fast_writes}
- @cindex arm7_9 fast_writes
- @*use @option{arm7_9 fast_memory_access} command with same args. @xref{arm7_9 fast_memory_access}.
- @item @b{flash auto_erase}
- @cindex flash auto_erase
- @*use @option{flash write_image} command passing @option{erase} as the first parameter. @xref{flash write_image}.
- @item @b{daemon_startup}
- @cindex daemon_startup
- @*this config option has been removed, simply adding @option{init} and @option{reset halt} to
- the end of your config script will give the same behaviour as using @option{daemon_startup reset}
- and @option{target cortex_m3 little reset_halt 0}.
- @item @b{arm7_9 sw_bkpts}
- @cindex arm7_9 sw_bkpts
- @*On by default. See also @option{gdb_breakpoint_override}. @xref{gdb_breakpoint_override}.
- @item @b{arm7_9 force_hw_bkpts}
- @cindex arm7_9 force_hw_bkpts
- @*Use @option{gdb_breakpoint_override} instead. Note that GDB will use hardware breakpoints
- for flash if the gdb memory map has been set up(default when flash is declared in
- target configuration). @xref{gdb_breakpoint_override}.
- @item @b{run_and_halt_time}
- @cindex run_and_halt_time
- @*This command has been removed for simpler reset behaviour, it can be simulated with the
- following commands:
- @smallexample
- reset run
- sleep 100
- halt
- @end smallexample
- @end itemize
-
- @node FAQ
- @chapter FAQ
- @cindex faq
- @enumerate
- @item Why does not backslashes in paths under Windows doesn't work?
-
- OpenOCD uses Tcl and a backslash is an escape char. Use @{ and @}
- around Windows filenames.
-
- @smallexample
- > echo \a
-
- > echo @{\a@}
- \a
- > echo "\a"
-
- >
- @end smallexample
- To
-
- @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
- OpenOCD from the Cygwin shell.
-
- @item I'm trying to set a breakpoint using GDB (or a frontend like Insight or
- Eclipse), but OpenOCD complains that "Info: arm7_9_common.c:213
- arm7_9_add_breakpoint(): sw breakpoint requested, but software breakpoints not enabled".
-
- 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.
-
- @item When erasing or writing LPC2000 on-chip flash, the operation fails sometimes
- and works sometimes fine.
-
- Make sure the core frequency specified in the @option{flash lpc2000} line matches the
- clock at the time you're programming the flash. If you've specified the crystal's
- frequency, make sure the PLL is disabled, if you've specified the full core speed
- (e.g. 60MHz), make sure the PLL is enabled.
-
- @item When debugging using an Amontec Chameleon in its JTAG Accelerator configuration,
- I keep getting "Error: amt_jtagaccel.c:184 amt_wait_scan_busy(): amt_jtagaccel timed
- 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).
-
- @item When debugging with OpenOCD and GDB (plain GDB, Insight, or Eclipse),
- I get lots of "Error: arm7_9_common.c:1771 arm7_9_read_memory():
- memory read caused data abort".
-
- The errors are non-fatal, and are the result of GDB trying to trace stack frames
- beyond the last valid frame. It might be possible to prevent this by setting up
- a proper "initial" stack frame, if you happen to know what exactly has to
- be done, feel free to add this here.
-
- @item I get the following message in the OpenOCD console (or log file):
- "Warning: arm7_9_common.c:679 arm7_9_assert_reset(): srst resets test logic, too".
-
- This warning doesn't indicate any serious problem, as long as you don't want to
- debug your core right out of reset. Your .cfg file specified @option{jtag_reset
- trst_and_srst srst_pulls_trst} to tell OpenOCD that either your board,
- your debugger or your target uC (e.g. LPC2000) can't assert the two reset signals
- independently. With this setup, it's not possible to halt the core right out of
- reset, everything else should work fine.
-
- @item When using OpenOCD in conjunction with Amontec JTAGkey and the Yagarto
- 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 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.
-
- @item When using the Amontec JTAGkey, sometimes OpenOCD crashes with the
- following error messages: "Error: ft2232.c:201 ft2232_read(): FT_Read returned:
- 4" and "Error: ft2232.c:365 ft2232_send_and_recv(): couldn't read from FT2232".
- 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.
-
- @item When using the Amontec JTAGkey, sometimes OpenOCD crashes with the following
- error message: "Error: gdb_server.c:101 gdb_get_char(): read: 10054".
- What does that mean and what might be the reason for this?
-
- Error code 10054 corresponds to WSAECONNRESET, which means that the debugger (GDB)
- 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 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?
-
- No. The clock frequency specified here must be given as an integral number.
- However, this clock frequency is used by the In-Application-Programming (IAP)
- routines of the LPC2000 family only, which seems to be very tolerant concerning
- the given clock frequency, so a slight difference between the specified clock
- frequency and the actual clock frequency will not cause any trouble.
-
- @item Do I have to keep a specific order for the commands in the configuration file?
-
- Well, yes and no. Commands can be given in arbitrary order, yet the devices
- listed for the JTAG scan chain must be given in the right order (jtag_device),
- with the device closest to the TDO-Pin being listed first. In general,
- whenever objects of the same type exist which require an index number, then
- these objects must be given in the right order (jtag_devices, targets and flash
- 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
-
- @include fdl.texi
-
- @node Index
- @unnumbered Index
-
- @printindex cp
-
- @bye
|