* Building OpenOCD:: Building OpenOCD From SVN
* JTAG Hardware Dongles:: JTAG Hardware Dongles
* Running:: Running OpenOCD
-* Simple Configuration Files:: Simple Configuration Files
+* OpenOCD Project Setup:: OpenOCD Project Setup
* Config File Guidelines:: Config File Guidelines
* About JIM-Tcl:: About JIM-Tcl
* Daemon Configuration:: Daemon Configuration
* General Commands:: General Commands
* Architecture and Core Commands:: Architecture and Core Commands
* JTAG Commands:: JTAG Commands
-* Sample Scripts:: Sample Target Scripts
* TFTP:: TFTP
* GDB and OpenOCD:: Using GDB and OpenOCD
* Tcl Scripting API:: Tcl Scripting API
suggestions:
@enumerate
-@item @b{Always build with printer ports enabled.}
-@item @b{Try to use LIBFTDI + LIBUSB where possible. You cover more bases.}
+@item Send patches, including config files, upstream.
+@item Always build with printer ports enabled.
+@item Use libftdi + libusb for FT2232 support.
@end enumerate
-@itemize @bullet
-@item @b{Why YES to LIBFTDI + LIBUSB?}
-@itemize @bullet
-@item @b{LESS} work - libusb perhaps already there
-@item @b{LESS} work - identical code, multiple platforms
-@item @b{MORE} dongles are supported
-@item @b{MORE} platforms are supported
-@item @b{MORE} complete solution
-@end itemize
-@item @b{Why not LIBFTDI + LIBUSB} (i.e.: ftd2xx instead)?
-@itemize @bullet
-@item @b{LESS} speed - some say it is slower
-@item @b{LESS} complex to distribute (external dependencies)
-@end itemize
-@end itemize
-
@section Building From Source
You can download the current SVN version with an SVN client of your choice from the
@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{http://www.amontec.com}). The JTAGkey uses a non-standard VID/PID.
+@item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm}),
+or the Amontec version (from @uref{http://www.amontec.com}),
+for easier support of JTAGkey's vendor and product IDs.
@end itemize
libftdi is supported under Windows. Do not use versions earlier than 0.14.
+To use the newer FT2232H chips, supporting RTCK and USB high speed (480 Mbps),
+you need libftdi version 0.16 or newer.
-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.
+Some people say that FTDI's libftd2xx code provides better performance.
+However, it is binary-only, while OpenOCD is licenced according
+to GNU GPLv2 without any exceptions.
+That means that @emph{distributing} copies of OpenOCD built with
+the FTDI code would violate the OpenOCD licensing terms.
+You may, however, build such copies for personal use.
To build OpenOCD (on both Linux and Cygwin), use the following commands:
@item
@option{--enable-gw16012} - Enable building support for the Gateworks GW16012 JTAG programmer.
@item
-@option{--enable-ft2232_ftd2xx} - Numerous USB type ARM JTAG dongles use the FT2232C chip from this FTDICHIP.COM chip (closed source).
+@option{--enable-ft2232_ftd2xx} - Support FT2232-family chips using
+the closed-source library from FTDICHIP.COM
+(result not for re-distribution).
@item
-@option{--enable-ft2232_libftdi} - An open source (free) alternative to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin).
+@option{--enable-ft2232_libftdi} - Support FT2232-family chips using
+a GPL'd ft2232 support library (result OK for re-distribution).
@item
@option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c driver,
give the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
There are 2 methods of using the FTD2232, either (1) using the
FTDICHIP.COM closed source driver, or (2) the open (and free) driver
-libftdi. Some claim the (closed) FTDICHIP.COM solution is faster.
+libftdi. Some claim the (closed) FTDICHIP.COM solution is faster,
+which is the motivation for supporting it even though its licensing
+restricts it to non-redistributable OpenOCD binaries, and it is
+not available for all operating systems used with OpenOCD.
The FTDICHIP drivers come as either a (win32) ZIP file, or a (Linux)
TAR.GZ file. You must unpack them ``some where'' convient. As of this
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 Simple Configuration Files
-@chapter Simple Configuration Files
-@cindex configuration
+@node OpenOCD Project Setup
+@chapter OpenOCD Project Setup
-@section Outline
-There are 4 basic ways of ``configurating'' OpenOCD to run, they are:
+To use OpenOCD with your development projects, you need to do more than
+just connecting the JTAG adapter hardware (dongle) to your development board
+and then starting the OpenOCD server.
+You also need to configure that server so that it knows
+about that adapter and board, and helps your work.
+
+@section Hooking up the JTAG Adapter
+
+Today's most common case is a dongle with a JTAG cable on one side
+(such as a ribbon cable with a 10-pin or 20-pin IDC connector)
+and a USB cable on the other.
+Instead of USB, some cables use Ethernet;
+older ones may use a PC parallel port, or even a serial port.
@enumerate
-@item A small openocd.cfg file which ``sources'' other configuration files
-@item A monolithic openocd.cfg file
-@item Many -f filename options on the command line
-@item Your Mixed Solution
+@item @emph{Start with power to your target board turned off},
+and nothing connected to your JTAG adapter.
+If you're particularly paranoid, unplug power to the board.
+It's important to have the ground signal properly set up,
+unless you are using a JTAG adapter which provides
+galvanic isolation between the target board and the
+debugging host.
+
+@item @emph{Be sure it's the right kind of JTAG connector.}
+If your dongle has a 20-pin ARM connector, you need some kind
+of adapter (or octopus, see below) to hook it up to
+boards using 14-pin or 10-pin connectors ... or to 20-pin
+connectors which don't use ARM's pinout.
+
+In the same vein, make sure the voltage levels are compatible.
+Not all JTAG adapters have the level shifters needed to work
+with 1.2 Volt boards.
+
+@item @emph{Be certain the cable is properly oriented} or you might
+damage your board. In most cases there are only two possible
+ways to connect the cable.
+Connect the JTAG cable from your adapter to the board.
+Be sure it's firmly connected.
+
+In the best case, the connector is keyed to physically
+prevent you from inserting it wrong.
+This is most often done using a slot on the board's male connector
+housing, which must match a key on the JTAG cable's female connector.
+If there's no housing, then you must look carefully and
+make sure pin 1 on the cable hooks up to pin 1 on the board.
+Ribbon cables are frequently all grey except for a wire on one
+edge, which is red. The red wire is pin 1.
+
+Sometimes dongles provide cables where one end is an ``octopus'' of
+color coded single-wire connectors, instead of a connector block.
+These are great when converting from one JTAG pinout to another,
+but are tedious to set up.
+Use these with connector pinout diagrams to help you match up the
+adapter signals to the right board pins.
+
+@item @emph{Connect the adapter's other end} once the JTAG cable is connected.
+A USB, parallel, or serial port connector will go to the host which
+you are using to run OpenOCD.
+For Ethernet, consult the documentation and your network administrator.
+
+For USB based JTAG adapters you have an easy sanity check at this point:
+does the host operating system see the JTAG adapter?
+
+@item @emph{Connect the adapter's power supply, if needed.}
+This step is primarily for non-USB adapters,
+but sometimes USB adapters need extra power.
+
+@item @emph{Power up the target board.}
+Unless you just let the magic smoke escape,
+you're now ready to set up the OpenOCD server
+so you can use JTAG to work with that board.
+
@end enumerate
-@section Small configuration file method
+Talk with the OpenOCD server using
+telnet (@code{telnet localhost 4444} on many systems) or GDB.
+@xref{GDB and OpenOCD}.
+
+@section Project Directory
+
+There are many ways you can configure OpenOCD and start it up.
+
+A simple way to organize them all involves keeping a
+single directory for your work with a given board.
+When you start OpenOCD from that directory,
+it searches there first for configuration files
+and for code you upload to the target board.
+It is also be the natural place to write files,
+such as log files and data you download from the board.
-This is the preferred method. It is simple and works well for many
-people. The developers of OpenOCD would encourage you to use this
-method. If you create a new configuration please email new
-configurations to the development list.
+@section Configuration Basics
-Here is an example of an openocd.cfg file for an ATMEL at91sam7x256
+There are two basic ways of configuring OpenOCD, and
+a variety of ways you can mix them.
+Think of the difference as just being how you start the server:
+
+@itemize
+@item Many @option{-f file} or @option{-c command} options on the command line
+@item No options, but a @dfn{user config file}
+in the current directory named @file{openocd.cfg}
+@end itemize
+
+Here is an example @file{openocd.cfg} file for a setup
+using a Signalyzer FT2232-based JTAG adapter to talk to
+a board with an Atmel AT91SAM7X256 microcontroller:
@example
source [find interface/signalyzer.cfg]
source [find target/sam7x256.cfg]
@end example
-There are many example configuration scripts you can work with. You
-should look in the directory: @t{$(INSTALLDIR)/lib/openocd}. You
-should find:
+Here is the command line equivalent of that configuration:
-@enumerate
-@item @b{board} - eval board level configurations
-@item @b{interface} - specific dongle configurations
-@item @b{target} - the target chips
-@item @b{tcl} - helper scripts
-@item @b{xscale} - things specific to the xscale.
-@end enumerate
+@example
+openocd -f interface/signalyzer.cfg \
+ -c "gdb_memory_map enable" \
+ -c "gdb_flash_program enable" \
+ -f target/sam7x256.cfg
+@end example
+
+You could wrap such long command lines in shell scripts,
+each supporting a different development task.
+One might re-flash the board with specific firmware version.
+Another might set up a particular debugging or run-time environment.
+
+Here we will focus on the simpler solution: one user config
+file, including basic configuration plus any TCL procedures
+to simplify your work.
-Look first in the ``boards'' area, then the ``targets'' area. Often a board
-configuration is a good example to work from.
+@section User Config Files
+@cindex config file
+@cindex user config file
-@section Many -f filename options
-Some believe this is a wonderful solution, others find it painful.
+A user configuration file ties together all the parts of a project
+in one place.
+One of the following will match your situation best:
-You can use a series of ``-f filename'' options on the command line,
-OpenOCD will read each filename in sequence, for example:
+@itemize
+@item Ideally almost everything comes from configuration files
+provided by someone else.
+For example, OpenOCD distributes a @file{scripts} directory
+(probably in @file{/usr/share/openocd/scripts} on Linux);
+board and tool vendors can provide these too.
+The AT91SAM7X256 example above works this way.
+
+Three main types of non-user configuration file each have their
+own subdirectory in the @file{scripts} directory:
+
+@enumerate
+@item @b{interface} -- one for each kind of JTAG adapter/dongle
+@item @b{board} -- one for each different board
+@item @b{target} -- the chips which integrate CPUs and other JTAG TAPs
+@end enumerate
+
+Best case: include just two files, and they handle everything else.
+The first is an interface config file.
+The second is board-specific, and it sets up the JTAG TAPs and
+their GDB targets (by deferring to some @file{target.cfg} file),
+declares all flash memory, and leaves you nothing to do except
+meet your deadline:
@example
-openocd -f file1.cfg -f file2.cfg -f file2.cfg
+source [find interface/olimex-jtag-tiny.cfg]
+source [find board/csb337.cfg]
@end example
-You can also intermix various commands with the ``-c'' command line
-option.
+Boards with a single microcontroller often won't need more
+than the target config file, as in the AT91SAM7X256 example.
+That's because there is no external memory (flash, DDR RAM), and
+the board differences are encapsulated by application code.
-@section Monolithic file
-The ``Monolithic File'' dispenses with all ``source'' statements and
-puts everything in one self contained (monolithic) file. This is not
-encouraged.
+@item You can often reuse some standard config files but
+need to write a few new ones, probably a @file{board.cfg} file.
+You will be using commands described later in this User's Guide,
+and working with the guidelines in the next chapter.
-Please try to ``source'' various files or use the multiple -f
-technique.
+For example, there may be configuration files for your JTAG adapter
+and target chip, but you need a new board-specific config file
+giving access to your particular flash chips.
+Or you might need to write another target chip configuration file
+for a new chip built around the Cortex M3 core.
-@section Advice for you
-Often, one uses a ``mixed approach''. Where possible, please try to
-``source'' common things, and if needed cut/paste parts of the
-standard distribution configuration files as needed.
+@quotation Note
+When you write new configuration files, please submit
+them for inclusion in the next OpenOCD release.
+For example, a @file{board/newboard.cfg} file will help the
+next users of that board, and a @file{target/newcpu.cfg}
+will help support users of any board using that chip.
+@end quotation
-@b{REMEMBER:} The ``important parts'' of your configuration file are:
+@item
+You may may need to write some C code.
+It may be as simple as a supporting a new new ft2232 or parport
+based dongle; a bit more involved, like a NAND or NOR flash
+controller driver; or a big piece of work like supporting
+a new chip architecture.
+@end itemize
-@enumerate
-@item @b{Interface} - Defines the dongle
-@item @b{Taps} - Defines the JTAG Taps
-@item @b{GDB Targets} - What GDB talks to
-@item @b{Flash Programing} - Very Helpful
-@end enumerate
+Reuse the existing config files when you can.
+Look first in the @file{scripts/boards} area, then @file{scripts/targets}.
+You may find a board configuration that's a good example to follow.
-Some key things you should look at and understand are:
+When you write config files, separate the reusable parts
+(things every user of that interface, chip, or board needs)
+from ones specific to your environment and debugging approach.
-@enumerate
-@item The reset configuration of your debug environment as a whole
-@item Is there a ``work area'' that OpenOCD can use?
-@* For ARM - work areas mean up to 10x faster downloads.
-@item For MMU/MPU based ARM chips (i.e.: ARM9 and later) will that work area still be available?
-@item For complex targets (multiple chips) the JTAG SPEED becomes an issue.
-@end enumerate
+For example, a @code{gdb-attach} event handler that invokes
+the @command{reset init} command will interfere with debugging
+early boot code, which performs some of the same actions
+that the @code{reset-init} event handler does.
+Likewise, the @command{arm9tdmi vector_catch} command (or
+its @command{xscale vector_catch} sibling) can be a timesaver
+during some debug sessions, but don't make everyone use that either.
+Keep those kinds of debugging aids in your user config file.
+
+@section Project-Specific Utilities
+A few project-specific utility
+routines may well speed up your work.
+Write them, and keep them in your project's user config file.
+
+For example, if you are making a boot loader work on a
+board, it's nice to be able to debug the ``after it's
+loaded to RAM'' parts separately from the finicky early
+code which sets up the DDR RAM controller and clocks.
+A script like this one, or a more GDB-aware sibling,
+may help:
+
+@example
+proc ramboot @{ @} @{
+ # Reset, running the target's "reset-init" scripts
+ # to initialize clocks and the DDR RAM controller.
+ # Leave the CPU halted.
+ reset init
+
+ # Load CONFIG_SKIP_LOWLEVEL_INIT version into DDR RAM.
+ load_image u-boot.bin 0x20000000
+
+ # Start running.
+ resume 0x20000000
+@}
+@end example
+
+Then once that code is working you will need to make it
+boot from NOR flash; a different utility would help.
+Alternatively, some developers write to flash using GDB.
+(You might use a similar script if you're working with a flash
+based microcontroller application instead of a boot loader.)
+
+@example
+proc newboot @{ @} @{
+ # Reset, leaving the CPU halted. The "reset-init" event
+ # proc gives faster access to the CPU and to NOR flash;
+ # "reset halt" would be slower.
+ reset init
+
+ # Write standard version of U-Boot into the first two
+ # sectors of NOR flash ... the standard version should
+ # do the same lowlevel init as "reset-init".
+ flash protect 0 0 1 off
+ flash erase_sector 0 0 1
+ flash write_bank 0 u-boot.bin 0x0
+ flash protect 0 0 1 on
+
+ # Reboot from scratch using that new boot loader.
+ reset run
+@}
+@end example
+
+You may need more complicated utility procedures when booting
+from NAND.
+That often involves an extra bootloader stage,
+running from on-chip SRAM to perform DDR RAM setup so it can load
+the main bootloader code (which won't fit into that SRAM).
+
+Other helper scripts might be used to write production system images,
+involving considerably more than just a three stage bootloader.
@node Config File Guidelines
various commands specific to their situation.
@section Interface Config Files
+@cindex config file
The user should be able to source one of these files via a command like this:
Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
@section Board Config Files
+@cindex config file
@b{Note: BOARD directory NEW as of 28/nov/2008}
@end enumerate
@section Target Config Files
+@cindex config file
The user should be able to source one of these files via a command like this:
-work-area-size 0x4000 -work-area-backup 0
@end example
-@subsection Reset Configuration
+@subsection Chip Reset Setup
As a rule, you should put the @command{reset_config} command
into the board file. Most things you think you know about a
managed. In the unusual case that these are @emph{chip specific}
and can never be changed by board wiring, they could go here.
+Some chips need special attention during reset handling if
+they're going to be used with JTAG.
+An example might be needing to send some commands right
+after the target's TAP has been reset, providing a
+@code{reset-deassert-post} event handler that writes a chip
+register to report that JTAG debugging is being done.
+
@subsection ARM Core Specific Hacks
If the chip has a DCC, enable it. If the chip is an ARM9 with some
special high speed download features - enable it.
-If the chip has an ARM ``vector catch'' feature - by default enable
-it for Undefined Instructions, Data Abort, and Prefetch Abort, if the
-user is really writing a handler for those situations - they can
-easily disable it. Experiance has shown the ``vector catch'' is
-helpful - for common programing errors.
-
If present, the MMU, the MPU and the CACHE should be disabled.
Some ARM cores are equipped with trace support, which permits
@cindex TCP port
@cindex server
@cindex port
+@cindex security
The OpenOCD server accepts remote commands in several syntaxes.
Each syntax uses a different TCP/IP port, which you may specify
only during configuration (before those ports are opened).
+For reasons including security, you may wish to prevent remote
+access using one or more of these ports.
+In such cases, just specify the relevant port number as zero.
+If you disable all access through TCP/IP, you will need to
+use the command line @option{-pipe} option.
+
@deffn {Command} gdb_port (number)
@cindex GDB server
Specify or query the first port used for incoming GDB connections.
first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
When not specified during the configuration stage,
the port @var{number} defaults to 3333.
+When specified as zero, this port is not activated.
@end deffn
@deffn {Command} tcl_port (number)
Intended as a machine interface.
When not specified during the configuration stage,
the port @var{number} defaults to 6666.
+When specified as zero, this port is not activated.
@end deffn
@deffn {Command} telnet_port (number)
This port is intended for interaction with one human through TCL commands.
When not specified during the configuration stage,
the port @var{number} defaults to 4444.
+When specified as zero, this port is not activated.
@end deffn
@anchor{GDB Configuration}
Resets also interact with @var{reset-init} event handlers,
which do things like setting up clocks and DRAM, and
JTAG clock rates. (@xref{JTAG Speed}.)
+They can also interact with JTAG routers.
Please see the various board files for examples.
@quotation Note
Normally the board configuration file
should define it and assume that the JTAG adapter supports
everything that's wired up to the board's JTAG connector.
+
However, the target configuration file could also make note
of something the silicon vendor has done inside the chip,
which will be true for most (or all) boards using that chip.
And when the JTAG adapter doesn't support everything, the
-system configuration file will need to override parts of
+user configuration file will need to override parts of
the reset configuration provided by other files.
@end quotation
board-specific script might do things like setting up DRAM.
(@xref{Reset Command}.)
+@anchor{SRST and TRST Issues}
@section SRST and TRST Issues
Because SRST and TRST are hardware signals, they can have a
SRST or TRST to the JTAG connector. Some JTAG adapters don't
support such signals even if they are wired up.
Use the @command{reset_config} @var{signals} options to say
-when one of those signals is not connected.
+when either of those signals is not connected.
When SRST is not available, your code might not be able to rely
on controllers having been fully reset during code startup.
+Missing TRST is not a problem, since JTAG level resets can
+be triggered using with TMS signaling.
@item @emph{Signals shorted} ... Sometimes a chip, board, or
adapter will connect SRST to TRST, instead of keeping them separate.
of your combination of JTAG board and target in target
configuration scripts.
-If you have an interface that does not support SRST and
-TRST(unlikely), then you may be able to work around that
-problem by using a reset_config command to override any
-settings in the target configuration script.
-
-SRST and TRST has a fairly well understood definition and
-behaviour in the JTAG specification, but vendors take
-liberties to achieve various more or less clearly understood
-goals. Sometimes documentation is available, other times it
-is not. OpenOCD has the reset_config command to allow OpenOCD
-to deal with the various common cases.
+Information earlier in this section describes the kind of problems
+the command is intended to address (@pxref{SRST and TRST Issues}).
+As a rule this command belongs only in board config files,
+describing issues like @emph{board doesn't connect TRST};
+or in user config files, addressing limitations derived
+from a particular combination of interface and board.
+(An unlikely example would be using a TRST-only adapter
+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},
@section Scan Chains
-OpenOCD uses a JTAG adapter (interface) to talk to your board,
-which has a daisy chain of TAPs.
-That daisy chain is called a @dfn{scan chain}.
-Simple configurations may have a single TAP in the scan chain,
-perhaps for a microcontroller.
-Complex configurations might have a dozen or more TAPs:
+TAPs are part of a hardware @dfn{scan chain},
+which is daisy chain of TAPs.
+They also need to be added to
+OpenOCD's software mirror of that hardware list,
+giving each member a name and associating other data with it.
+Simple scan chains, with a single TAP, are common in
+systems with a single microcontroller or microprocessor.
+More complex chips may have several TAPs internally.
+Very complex scan chains might have a dozen or more TAPs:
several in one chip, more in the next, and connecting
to other boards with their own chips and TAPs.
+You can display the list with the @command{scan_chain} command.
+(Don't confuse this with the list displayed by the @command{targets}
+command, presented in the next chapter.
+That only displays TAPs for CPUs which are configured as
+debugging targets.)
+Here's what the scan chain might look like for a chip more than one TAP:
+
+@verbatim
+ TapName Enabled IdCode Expected IrLen IrCap IrMask Instr
+-- ------------------ ------- ---------- ---------- ----- ----- ------ -----
+ 0 omap5912.dsp Y 0x03df1d81 0x03df1d81 38 0 0 0x...
+ 1 omap5912.arm Y 0x0692602f 0x0692602f 4 0x1 0 0xc
+ 2 omap5912.unknown Y 0x00000000 0x00000000 8 0 0 0xff
+@end verbatim
+
Unfortunately those TAPs can't always be autoconfigured,
because not all devices provide good support for that.
-(JTAG doesn't require supporting IDCODE instructions.)
+JTAG doesn't require supporting IDCODE instructions, and
+chips with JTAG routers may not link TAPs into the chain
+until they are told to do so.
+
The configuration mechanism currently supported by OpenOCD
requires explicit configuration of all TAP devices using
-@command{jtag newtap} commands.
-One like this would declare a tap and name it @code{chip1.cpu}:
+@command{jtag newtap} commands, as detailed later in this chapter.
+A command like this would declare one tap and name it @code{chip1.cpu}:
@example
jtag newtap chip1 cpu -irlen 7 -ircapture 0x01 -irmask 0x55
@option{str912}, to support more than one chip of each type.
@xref{Config File Guidelines}.
+At this writing there is only a single command to work with
+scan chains, and there is no support for enumerating
+TAPs or examining their attributes.
+
+@deffn Command {scan_chain}
+Displays the TAPs in the scan chain configuration,
+and their status.
+The set of TAPs listed by this command is fixed by
+exiting the OpenOCD configuration stage,
+but systems with a JTAG router can
+enable or disable TAPs dynamically.
+In addition to the enable/disable status, the contents of
+each TAP's instruction register can also change.
+@end deffn
+
+@c FIXME! there should be commands to enumerate TAPs
+@c and get their attributes, like there are for targets.
+@c "jtag cget ..." will handle attributes.
+@c "jtag names" for enumerating TAPs, maybe.
+
+@c Probably want "jtag eventlist", and a "tap-reset" event
+@c (on entry to RESET state).
+
@section TAP Names
When TAP objects are declared with @command{jtag newtap},
should not be counted upon.
Update all of your scripts to use TAP names rather than numbers.
Using TAP numbers in target configuration scripts prevents
-reusing on boards with multiple targets.
+reusing those scripts on boards with multiple targets.
@end quotation
@section TAP Declaration Commands
@itemize @bullet
@item @code{-disable} (or @code{-enable})
-@*Use the @code{-disable} paramater to flag a TAP which is not
-linked in to the scan chain when it is declared.
+@*Use the @code{-disable} parameter to flag a TAP which is not
+linked in to the scan chain after a reset using either TRST
+or the JTAG state machine's @sc{reset} state.
You may use @code{-enable} to highlight the default state
(the TAP is linked in).
@xref{Enabling and Disabling TAPs}.
@* The target has resumed (i.e.: gdb said run)
@item @b{early-halted}
@* Occurs early in the halt process
+@ignore
@item @b{examine-end}
@* Currently not used (goal: when JTAG examine completes)
@item @b{examine-start}
@* Currently not used (goal: when JTAG examine starts)
+@end ignore
@item @b{gdb-attach}
@* When GDB connects
@item @b{gdb-detach}
@* When GDB disconnects
@item @b{gdb-end}
-@* When the taret has halted and GDB is not doing anything (see early halt)
+@* When the target has halted and GDB is not doing anything (see early halt)
@item @b{gdb-flash-erase-start}
@* Before the GDB flash process tries to erase the flash
@item @b{gdb-flash-erase-end}
@item @b{gdb-flash-write-end}
@* After GDB writes to the flash
@item @b{gdb-start}
-@* Before the taret steps, gdb is trying to start/resume the target
+@* Before the target steps, gdb is trying to start/resume the target
@item @b{halted}
@* The target has halted
+@ignore
@item @b{old-gdb_program_config}
@* DO NOT USE THIS: Used internally
@item @b{old-pre_resume}
@* DO NOT USE THIS: Used internally
+@end ignore
@item @b{reset-assert-pre}
@* Issued as part of @command{reset} processing
after SRST and/or TRST were activated and deactivated,
when reset has been released on the tap.
@item @b{reset-end}
@* Issued as the final step in @command{reset} processing.
+@ignore
@item @b{reset-halt-post}
-@* Currently not usd
+@* Currently not used
@item @b{reset-halt-pre}
@* Currently not used
+@end ignore
@item @b{reset-init}
@* Used by @b{reset init} command for board-specific initialization.
This event fires after @emph{reset-deassert-post}.
@item @b{reset-start}
@* Issued as part of @command{reset} processing
before either SRST or TRST are activated.
+@ignore
@item @b{reset-wait-pos}
@* Currently not used
@item @b{reset-wait-pre}
@* Currently not used
+@end ignore
@item @b{resume-start}
@* Before any target is resumed
@item @b{resume-end}
at @var{address} for @var{length} bytes.
This is a software breakpoint, unless @option{hw} is specified
in which case it will be a hardware breakpoint.
+
+(@xref{arm9tdmi vector_catch}, or @pxref{xscale vector_catch},
+for similar mechanisms that do not consume hardware breakpoints.)
@end deffn
@deffn Command {rbp} address
or processors resembling ARM9TDMI, and can use these commands.
Such cores include the ARM920T, ARM926EJ-S, and ARM966.
-@deffn Command {arm9tdmi vector_catch} (@option{all}|@option{none}|list)
-Catch arm9 interrupt vectors, can be @option{all}, @option{none},
+@c 9-june-2009: tried this on arm920t, it didn't work.
+@c no-params always lists nothing caught, and that's how it acts.
+
+@anchor{arm9tdmi vector_catch}
+@deffn Command {arm9tdmi vector_catch} [@option{all}|@option{none}|list]
+Vector Catch hardware provides a sort of dedicated breakpoint
+for hardware events such as reset, interrupt, and abort.
+You can use this to conserve normal breakpoint resources,
+so long as you're not concerned with code that branches directly
+to those hardware vectors.
+
+This always finishes by listing the current configuration.
+If parameters are provided, it first reconfigures the
+vector catch hardware to intercept
+@option{all} of the hardware vectors,
+@option{none} of them,
or a list with one or more of the following:
@option{reset} @option{undef} @option{swi} @option{pabt} @option{dabt} @option{reserved}
@option{irq} @option{fiq}.
@option{mem}, or @option{builder}.
@end deffn
-@deffn Command {xscale vector_catch} mask
-Provide a bitmask showing the vectors to catch.
+@anchor{xscale vector_catch}
+@deffn Command {xscale vector_catch} [mask]
+Display a bitmask showing the hardware vectors to catch.
+If the optional parameter is provided, first set the bitmask to that value.
@end deffn
@section ARMv6 Architecture
to execute before they take effect.
@end deffn
-@deffn Command {scan_chain}
-Displays the TAPs in the scan chain configuration,
-and their status.
-The set of TAPs listed by this command is fixed by
-exiting the OpenOCD configuration stage,
-but systems with a JTAG router can
-enable or disable TAPs dynamically.
-In addition to the enable/disable status, the contents of
-each TAP's instruction register can also change.
-@end deffn
-
@c tms_sequence (short|long)
@c ... temporary, debug-only, probably gone before 0.2 ships
@end itemize
Note that only six of those states are fully ``stable'' in the
-face of TMS fixed (usually low)
+face of TMS fixed (low except for @sc{reset})
and a free-running JTAG clock. For all the
others, the next TCK transition changes to a new state.
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 into the following sections:
-@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.
-@example
-openocd -f interface/parport.cfg -f target/at91r40008.cfg \
- -c "init" -c "reset"
-@end example
-
-
@node GDB and OpenOCD
@chapter GDB and OpenOCD
@cindex GDB
Code Review / openocd.git / blobdiff