* Running:: Running OpenOCD
* OpenOCD Project Setup:: OpenOCD Project Setup
* Config File Guidelines:: Config File Guidelines
+* Translating Configuration Files:: Translating Configuration Files
* Daemon Configuration:: Daemon Configuration
* Interface - Dongle Configuration:: Interface - Dongle Configuration
* Reset Configuration:: Reset Configuration
* GDB and OpenOCD:: Using GDB and OpenOCD
* Tcl Scripting API:: Tcl Scripting API
* Upgrading:: Deprecated/Removed Commands
-* Target Library:: Target Library
* FAQ:: Frequently Asked Questions
* Tcl Crash Course:: Tcl Crash Course
* License:: GNU Free Documentation License
The resources in this chapter are available for developers wishing to explore
or expand the OpenOCD source code.
-@section OpenOCD Subversion Repository
+@section OpenOCD GIT Repository
-You can download the current SVN version with an SVN client of your
-choice from the following repositories:
+During the 0.3.x release cycle, OpenOCD switched from Subversion to
+a GIT repository hosted at SourceForge. The repository URL is:
- @uref{svn://svn.berlios.de/openocd/trunk}
+@uref{git://openocd.git.sourceforge.net/gitroot/openocd/openocd}
-or
+You may prefer to use a mirror and the HTTP protocol:
- @uref{http://svn.berlios.de/svnroot/repos/openocd/trunk}
+@uref{http://repo.or.cz/r/openocd.git}
-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):
+With standard GIT tools, use @command{git clone} to initialize
+a local repository, and @command{git pull} to update it.
+There are also gitweb pages letting you browse the repository
+with a web browser, or download arbitrary snapshots without
+needing a GIT client:
- svn checkout svn://svn.berlios.de/openocd/trunk openocd
+@uref{http://openocd.git.sourceforge.net/git/gitweb.cgi?p=openocd/openocd}
-If you prefer GIT based tools, the @command{git-svn} package works too:
+@uref{http://repo.or.cz/w/openocd.git}
- git svn clone -s svn://svn.berlios.de/openocd
-
-The ``README'' file contains the instructions for building the project
-from the repository.
+The @file{README} file contains the instructions for building the project
+from the repository or a snapshot.
Developers that want to contribute patches to the OpenOCD system are
-@b{strongly} encouraged to base their work off of the most recent trunk
-revision. Patches created against older versions may require additional
+@b{strongly} encouraged to work against mainline.
+Patches created against older versions may require additional
work from their submitter in order to be updated for newer releases.
@section Doxygen Developer Manual
-During the development of the 0.2.0 release, the OpenOCD project began
+During the 0.2.x release cycle, the OpenOCD project began
providing a Doxygen reference manual. This document contains more
technical information about the software internals, development
processes, and similar documentation:
This document is a work-in-progress, but contributions would be welcome
to fill in the gaps. All of the source files are provided in-tree,
-listed in the Doxyfile configuration in the top of the repository trunk.
+listed in the Doxyfile configuration in the top of the source tree.
@section OpenOCD Developer Mailing List
@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
-All drivers developers are enouraged to also subscribe to the list of
-SVN commits to keep pace with the ongoing changes:
-
-@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
+Discuss and submit patches to this list.
+The @file{PATCHES} file contains basic information about how
+to prepare patches.
@node JTAG Hardware Dongles
One might re-flash the board with a specific firmware version.
Another might set up a particular debugging or run-time environment.
+@quotation Important
+At this writing (October 2009) the command line method has
+problems with how it treats variables.
+For example, after @option{-c "set VAR value"}, or doing the
+same in a script, the variable @var{VAR} will have no value
+that can be tested in a later script.
+@end quotation
+
Here we will focus on the simpler solution: one user config
file, including basic configuration plus any TCL procedures
to simplify your work.
needs to get a new board working smoothly.
It provides guidelines for creating those files.
-You should find the following directories under @t{$(INSTALLDIR)/scripts}:
-
+You should find the following directories under @t{$(INSTALLDIR)/scripts},
+with files including the ones listed here.
+Use them as-is where you can; or as models for new files.
@itemize @bullet
@item @file{interface} ...
think JTAG Dongle. Files that configure JTAG adapters go here.
+@example
+$ ls interface
+arm-jtag-ew.cfg hitex_str9-comstick.cfg oocdlink.cfg
+arm-usb-ocd.cfg icebear.cfg openocd-usb.cfg
+at91rm9200.cfg jlink.cfg parport.cfg
+axm0432.cfg jtagkey2.cfg parport_dlc5.cfg
+calao-usb-a9260-c01.cfg jtagkey.cfg rlink.cfg
+calao-usb-a9260-c02.cfg jtagkey-tiny.cfg sheevaplug.cfg
+calao-usb-a9260.cfg luminary.cfg signalyzer.cfg
+chameleon.cfg luminary-icdi.cfg stm32-stick.cfg
+cortino.cfg luminary-lm3s811.cfg turtelizer2.cfg
+dummy.cfg olimex-arm-usb-ocd.cfg usbprog.cfg
+flyswatter.cfg olimex-jtag-tiny.cfg vsllink.cfg
+$
+@end example
@item @file{board} ...
think Circuit Board, PWA, PCB, they go by many names. Board files
-contain initialization items that are specific to a board. For
+contain initialization items that are specific to a board.
+They reuse target configuration files, since the same
+microprocessor chips are used on many boards,
+but support for external parts varies widely. For
example, the SDRAM initialization sequence for the board, or the type
of external flash and what address it uses. Any initialization
sequence to enable that external flash or SDRAM should be found in the
board file. Boards may also contain multiple targets: two CPUs; or
-a CPU and an FPGA or CPLD.
+a CPU and an FPGA.
+@example
+$ ls board
+arm_evaluator7t.cfg keil_mcb1700.cfg
+at91rm9200-dk.cfg keil_mcb2140.cfg
+at91sam9g20-ek.cfg linksys_nslu2.cfg
+atmel_at91sam7s-ek.cfg logicpd_imx27.cfg
+atmel_at91sam9260-ek.cfg mini2440.cfg
+atmel_sam3u_ek.cfg olimex_LPC2378STK.cfg
+crossbow_tech_imote2.cfg olimex_lpc_h2148.cfg
+csb337.cfg olimex_sam7_ex256.cfg
+csb732.cfg olimex_sam9_l9260.cfg
+digi_connectcore_wi-9c.cfg olimex_stm32_h103.cfg
+dm355evm.cfg omap2420_h4.cfg
+dm365evm.cfg osk5912.cfg
+dm6446evm.cfg pic-p32mx.cfg
+eir.cfg propox_mmnet1001.cfg
+ek-lm3s1968.cfg pxa255_sst.cfg
+ek-lm3s3748.cfg sheevaplug.cfg
+ek-lm3s811.cfg stm3210e_eval.cfg
+ek-lm3s9b9x.cfg stm32f10x_128k_eval.cfg
+hammer.cfg str910-eval.cfg
+hitex_lpc2929.cfg telo.cfg
+hitex_stm32-performancestick.cfg ti_beagleboard.cfg
+hitex_str9-comstick.cfg topas910.cfg
+iar_str912_sk.cfg topasa900.cfg
+imx27ads.cfg unknown_at91sam9260.cfg
+imx27lnst.cfg x300t.cfg
+imx31pdk.cfg zy1000.cfg
+$
+@end example
@item @file{target} ...
think chip. The ``target'' directory represents the JTAG TAPs
on a chip
are ARM chips and FPGA or CPLD chips.
When a chip has multiple TAPs (maybe it has both ARM and DSP cores),
the target config file defines all of them.
+@example
+$ ls target
+aduc702x.cfg imx27.cfg pxa255.cfg
+ar71xx.cfg imx31.cfg pxa270.cfg
+at91eb40a.cfg imx35.cfg readme.txt
+at91r40008.cfg is5114.cfg sam7se512.cfg
+at91rm9200.cfg ixp42x.cfg sam7x256.cfg
+at91sam3u1c.cfg lm3s1968.cfg samsung_s3c2410.cfg
+at91sam3u1e.cfg lm3s3748.cfg samsung_s3c2440.cfg
+at91sam3u2c.cfg lm3s6965.cfg samsung_s3c2450.cfg
+at91sam3u2e.cfg lm3s811.cfg samsung_s3c4510.cfg
+at91sam3u4c.cfg lm3s9b9x.cfg samsung_s3c6410.cfg
+at91sam3u4e.cfg lpc1768.cfg sharp_lh79532.cfg
+at91sam3uXX.cfg lpc2103.cfg smdk6410.cfg
+at91sam7sx.cfg lpc2124.cfg smp8634.cfg
+at91sam9260.cfg lpc2129.cfg stm32.cfg
+c100.cfg lpc2148.cfg str710.cfg
+c100config.tcl lpc2294.cfg str730.cfg
+c100helper.tcl lpc2378.cfg str750.cfg
+c100regs.tcl lpc2478.cfg str912.cfg
+cs351x.cfg lpc2900.cfg telo.cfg
+davinci.cfg mega128.cfg ti_dm355.cfg
+dragonite.cfg netx500.cfg ti_dm365.cfg
+epc9301.cfg omap2420.cfg ti_dm6446.cfg
+feroceon.cfg omap3530.cfg tmpa900.cfg
+icepick.cfg omap5912.cfg tmpa910.cfg
+imx21.cfg pic32mx.cfg xba_revA3.cfg
+$
+@end example
+@item @emph{more} ... browse for other library files which may be useful.
+For example, there are various generic and CPU-specific utilities.
@end itemize
The @file{openocd.cfg} user config
@item pxa270 - again - CS0 flash - it goes in the board file.
@end itemize
+@node Translating Configuration Files
+@chapter Translating Configuration Files
+@cindex translation
+If you have a configuration file for another hardware debugger(Abatron,
+BDI2000, BDI3000, Lauterbach, Segger, MacRaigor, etc.), translating
+it into OpenOCD syntax is often quite straightforward. The most tricky
+part of creating a configuration script is oftentimes the reset init
+sequence where e.g. PLLs, DRAM and the like is set up.
+
+One trick that you can use when translating is to write small
+Tcl proc's to translate the syntax into OpenOCD syntax. This
+can avoid manual translation errors and make it easier to
+convert other scripts later on.
+
+Example of transforming quirky arguments to a simple search and
+replace job:
+
+@example
+# rewrite commands of the form below to arm11 mcr...
+#
+# Lauterbach syntax(?)
+#
+# Data.Set c15:0x042f %long 0x40000015
+#
+# OpenOCD syntax when using procedure below.
+#
+# setc15 0x01 0x00050078
+#
+#
+proc setc15 @{regs value@} @{
+ global TARGETNAME
+
+ echo [format "set p15 0x%04x, 0x%08x" $regs $value]
+
+ arm11 mcr $TARGETNAME 15 [expr ($regs>>12)&0x7] [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] [expr ($regs>>8)&0x7] $value
+@}
+@end example
+
+
+
@node Daemon Configuration
@chapter Daemon Configuration
@cindex initialization
@end deffn
@deffn {Command} reset_config mode_flag ...
-This command tells OpenOCD the reset configuration
+This command displays or modifies the reset configuration
of your combination of JTAG board and target in target
configuration scripts.
with a board that only wires up SRST.)
The @var{mode_flag} options can be specified in any order, but only one
-of each type -- @var{signals}, @var{combination}, @var{trst_type},
+of each type -- @var{signals}, @var{combination},
+@var{gates},
+@var{trst_type},
and @var{srst_type} -- may be specified at a time.
If you don't provide a new value for a given type, its previous
value (perhaps the default) is unchanged.
TRST just to declare that if the JTAG adapter should want to drive SRST,
it must explicitly be driven high (@option{srst_push_pull}).
+@itemize
+@item
@var{signals} can specify which of the reset signals are connected.
For example, If the JTAG interface provides SRST, but the board doesn't
connect that signal properly, then OpenOCD can't use it.
@option{srst_only} and @option{trst_and_srst}.
@quotation Tip
-If your board provides SRST or TRST through the JTAG connector,
+If your board provides SRST and/or TRST through the JTAG connector,
you must declare that or else those signals will not be used.
@end quotation
+@item
The @var{combination} is an optional value specifying broken reset
signal implementations.
The default behaviour if no option given is @option{separate},
@option{combined} implies both @option{srst_pulls_trst} and
@option{trst_pulls_srst}.
-@option{srst_gates_jtag} indicates that asserting SRST gates the
+@item
+The @var{gates} tokens control flags that describe some cases where
+JTAG may be unvailable during reset.
+@option{srst_gates_jtag} (default)
+indicates that asserting SRST gates the
JTAG clock. This means that no communication can happen on JTAG
while SRST is asserted.
+Its converse is @option{srst_nogate}, indicating that JTAG commands
+can safely be issued while SRST is active.
+@end itemize
The optional @var{trst_type} and @var{srst_type} parameters allow the
driver mode of each reset line to be specified. These values only affect
JTAG interfaces with support for different driver modes, like the Amontec
-JTAGkey and JTAGAccelerator. Also, they are necessarily ignored if the
+JTAGkey and JTAG Accelerator. Also, they are necessarily ignored if the
relevant signal (TRST or SRST) is not connected.
+@itemize
+@item
Possible @var{trst_type} driver modes for the test reset signal (TRST)
-are @option{trst_push_pull} (default) and @option{trst_open_drain}.
+are the default @option{trst_push_pull}, and @option{trst_open_drain}.
Most boards connect this signal to a pulldown, so the JTAG TAPs
never leave reset unless they are hooked up to a JTAG adapter.
+@item
Possible @var{srst_type} driver modes for the system reset signal (SRST)
are the default @option{srst_open_drain}, and @option{srst_push_pull}.
Most boards connect this signal to a pullup, and allow the
signal to be pulled low by various events including system
powerup and pressing a reset button.
+@end itemize
@end deffn
@itemize @bullet
@item @b{post-reset}
@* The TAP has just completed a JTAG reset.
-For the first such handler called, the tap is still
-in the JTAG @sc{reset} state.
+The tap may still be in the JTAG @sc{reset} state.
+Handlers for these events might perform initialization sequences
+such as issuing TCK cycles, TMS sequences to ensure
+exit from the ARM SWD mode, and more.
+
Because the scan chain has not yet been verified, handlers for these events
@emph{should not issue commands which scan the JTAG IR or DR registers}
of any particular target.
@b{NOTE:} As this is written (September 2009), nothing prevents such access.
+@item @b{setup}
+@* The scan chain has been reset and verified.
+This handler may enable TAPs as needed.
@item @b{tap-disable}
@* The TAP needs to be disabled. This handler should
implement @command{jtag tapdisable}
@example
jtag configure CHIP.jrc -event post-reset @{
- echo "Reset done"
+ echo "JTAG Reset done"
... non-scan jtag operations to be done after reset
@}
@end example
In OpenOCD, tap enabling/disabling is invoked by the Tcl commands
shown below, and is implemented using TAP event handlers.
So for example, when defining a TAP for a CPU connected to
-a JTAG router, you should define TAP event handlers using
+a JTAG router, your @file{target.cfg} file
+should define TAP event handlers using
code that looks something like this:
@example
jtag configure CHIP.cpu -event tap-enable @{
- echo "Enabling CPU TAP"
... jtag operations using CHIP.jrc
@}
jtag configure CHIP.cpu -event tap-disable @{
- echo "Disabling CPU TAP"
... jtag operations using CHIP.jrc
@}
@end example
+Then you might want that CPU's TAP enabled almost all the time:
+
+@example
+jtag configure $CHIP.jrc -event setup "jtag tapenable $CHIP.cpu"
+@end example
+
+Note how that particular setup event handler declaration
+uses quotes to evaluate @code{$CHIP} when the event is configured.
+Using brackets @{ @} would cause it to be evaluated later,
+at runtime, when it might have a different value.
+
@deffn Command {jtag tapdisable} dotted.name
If necessary, disables the tap
by sending it a @option{tap-disable} event.
@end deffn
@deffn Command {etm status}
-Displays status of the current target's ETM:
+Displays status of the current target's ETM and trace port driver:
is the ETM idle, or is it collecting data?
Did trace data overflow?
Was it triggered?
and any buffered trace data is invalidated.
@itemize
-@item @var{type} ... one of
+@item @var{type} ... describing how data accesses are traced,
+when they pass any ViewData filtering that that was set up.
+The value is one of
@option{none} (save nothing),
@option{data} (save data),
@option{address} (save addresses),
@option{all} (save data and addresses)
@item @var{context_id_bits} ... 0, 8, 16, or 32
@item @var{cycle_accurate} ... @option{enable} or @option{disable}
-@item @var{branch_output} ... @option{enable} or @option{disable}
+cycle-accurate instruction tracing.
+Before ETMv3, enabling this causes much extra data to be recorded.
+@item @var{branch_output} ... @option{enable} or @option{disable}.
+Disable this unless you need to try reconstructing the instruction
+trace stream without an image of the code.
@end itemize
@end deffn
-@deffn Command {etm trigger_percent} percent
-@emph{Buggy and effectively a NOP ... @var{percent} from 2..100}
+@deffn Command {etm trigger_percent} [percent]
+This displays, or optionally changes, the trace port driver's
+behavior after the ETM's configured @emph{trigger} event fires.
+It controls how much more trace data is saved after the (single)
+trace trigger becomes active.
+
+@itemize
+@item The default corresponds to @emph{trace around} usage,
+recording 50 percent data before the event and the rest
+afterwards.
+@item The minimum value of @var{percent} is 2 percent,
+recording almost exclusively data before the trigger.
+Such extreme @emph{trace before} usage can help figure out
+what caused that event to happen.
+@item The maximum value of @var{percent} is 100 percent,
+recording data almost exclusively after the event.
+This extreme @emph{trace after} usage might help sort out
+how the event caused trouble.
+@end itemize
+@c REVISIT allow "break" too -- enter debug mode.
@end deffn
@subsection ETM Trace Operation
@}
@end example
-@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 script
-that ship with OpenOCD, then configures the str710.cfg target and
-finally issues the init and reset commands. The communication speed
-is set to 10kHz for reset and 8MHz for post reset.
-
-@example
-openocd -f interface/parport.cfg -f target/str710.cfg \
- -c "init" -c "reset"
-@end example
-
-To list the target scripts available:
-
-@example
-$ 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 example
-
@include fdl.texi
@node OpenOCD Concept Index
Code Review / openocd.git / blobdiff