@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
@item Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
@item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com}
-@item Copyright @copyright{} 2009 David Brownell
+@item Copyright @copyright{} 2009-2010 David Brownell
@end itemize
@quotation
@menu
* About:: About OpenOCD
-* Developers:: OpenOCD Developers
+* Developers:: OpenOCD Developer Resources
* JTAG Hardware Dongles:: JTAG Hardware Dongles
* About JIM-Tcl:: About JIM-Tcl
* Running:: Running OpenOCD
@section OpenOCD User's Forum
-There is an OpenOCD forum (phpBB) hosted by SparkFun:
+There is an OpenOCD forum (phpBB) hosted by SparkFun,
+which might be helpful to you. Note that if you want
+anything to come to the attention of developers, you
+should post it to the OpenOCD Developer Mailing List
+instead of this forum.
@uref{http://forum.sparkfun.com/viewforum.php?f=18}
@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
Discuss and submit patches to this list.
-The @file{PATCHES} file contains basic information about how
+The @file{PATCHES.txt} file contains basic information about how
to prepare patches.
+@section OpenOCD Bug Database
+
+During the 0.4.x release cycle the OpenOCD project team began
+using Trac for its bug database:
+
+@uref{https://sourceforge.net/apps/trac/openocd}
+
@node JTAG Hardware Dongles
@chapter JTAG Hardware Dongles
@* See: @url{http://www.oocdlink.com} By Joern Kaipf
@item @b{signalyzer}
@* See: @url{http://www.signalyzer.com}
-@item @b{evb_lm3s811}
-@* See: @url{http://www.luminarymicro.com} - The Stellaris LM3S811 eval board has an FTD2232C chip built in.
-@item @b{luminary_icdi}
-@* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug Interface (ICDI) Board, included in the Stellaris LM3S9B90 and LM3S9B92 Evaluation Kits.
+@item @b{Stellaris Eval Boards}
+@* See: @url{http://www.luminarymicro.com} - The Stellaris eval boards
+bundle FT2232-based JTAG and SWD support, which can be used to debug
+the Stellaris chips. Using separate JTAG adapters is optional.
+These boards can also be used as JTAG adapters to other target boards,
+disabling the Stellaris chip.
+@item @b{Luminary ICDI}
+@* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug
+Interface (ICDI) Boards are included in Stellaris LM3S9B90 and LM3S9B92
+Evaluation Kits. Like the non-detachable FT2232 support on the other
+Stellaris eval boards, they can be used to debug other target boards.
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
@item @b{flyswatter}
@* Link @url{http://www.hitex.com/index.php?id=cortino}
@end itemize
+@section USB-JTAG / Altera USB-Blaster compatibles
+
+These devices also show up as FTDI devices, but are not
+protocol-compatible with the FT2232 devices. They are, however,
+protocol-compatible among themselves. USB-JTAG devices typically consist
+of a FT245 followed by a CPLD that understands a particular protocol,
+or emulate this protocol using some other hardware.
+
+They may appear under different USB VID/PID depending on the particular
+product. The driver can be configured to search for any VID/PID pair
+(see the section on driver commands).
+
+@itemize
+@item @b{USB-JTAG} Kolja Waschk's USB Blaster-compatible adapter
+@* Link: @url{http://www.ixo.de/info/usb_jtag/}
+@item @b{Altera USB-Blaster}
+@* Link: @url{http://www.altera.com/literature/ug/ug_usb_blstr.pdf}
+@end itemize
+
@section USB JLINK based
There are several OEM versions of the Segger @b{JLINK} adapter. It is
an example of a micro controller based JTAG adapter, it uses an
--pipe | -p use pipes when talking to gdb
@end verbatim
-By default OpenOCD reads the configuration file @file{openocd.cfg}.
-To specify a different (or multiple)
-configuration file, you can use the @option{-f} option. For example:
+If you don't give any @option{-f} or @option{-c} options,
+OpenOCD tries to read the configuration file @file{openocd.cfg}.
+To specify one or more different
+configuration files, use @option{-f} options. For example:
@example
openocd -f config1.cfg -f config2.cfg -f config3.cfg
@itemize @bullet
+@item @b{Watchdog Timers}...
+Watchog timers are typically used to automatically reset systems if
+some application task doesn't periodically reset the timer. (The
+assumption is that the system has locked up if the task can't run.)
+When a JTAG debugger halts the system, that task won't be able to run
+and reset the timer ... potentially causing resets in the middle of
+your debug sessions.
+
+It's rarely a good idea to disable such watchdogs, since their usage
+needs to be debugged just like all other parts of your firmware.
+That might however be your only option.
+
+Look instead for chip-specific ways to stop the watchdog from counting
+while the system is in a debug halt state. It may be simplest to set
+that non-counting mode in your debugger startup scripts. You may however
+need a different approach when, for example, a motor could be physically
+damaged by firmware remaining inactive in a debug halt state. That might
+involve a type of firmware mode where that "non-counting" mode is disabled
+at the beginning then re-enabled at the end; a watchdog reset might fire
+and complicate the debug session, but hardware (or people) would be
+protected.@footnote{Note that many systems support a "monitor mode" debug
+that is a somewhat cleaner way to address such issues. You can think of
+it as only halting part of the system, maybe just one task,
+instead of the whole thing.
+At this writing, January 2010, OpenOCD based debugging does not support
+monitor mode debug, only "halt mode" debug.}
+
@item @b{ARM Semihosting}...
@cindex ARM semihosting
When linked with a special runtime library provided with many
You may want to @emph{disable that instruction} in source code,
or otherwise prevent using that state,
-to ensure you can get JTAG access at any time.
+to ensure you can get JTAG access at any time.@footnote{As a more
+polite alternative, some processors have special debug-oriented
+registers which can be used to change various features including
+how the low power states are clocked while debugging.
+The STM32 DBGMCU_CR register is an example; at the cost of extra
+power consumption, JTAG can be used during low power states.}
For example, the OpenOCD @command{halt} command may not
work for an idle processor otherwise.
@end itemize
+@section Target Hardware Setup
+
+Chip vendors often provide software development boards which
+are highly configurable, so that they can support all options
+that product boards may require. @emph{Make sure that any
+jumpers or switches match the system configuration you are
+working with.}
+
+Common issues include:
+
+@itemize @bullet
+
+@item @b{JTAG setup} ...
+Boards may support more than one JTAG configuration.
+Examples include jumpers controlling pullups versus pulldowns
+on the nTRST and/or nSRST signals, and choice of connectors
+(e.g. which of two headers on the base board,
+or one from a daughtercard).
+For some Texas Instruments boards, you may need to jumper the
+EMU0 and EMU1 signals (which OpenOCD won't currently control).
+
+@item @b{Boot Modes} ...
+Complex chips often support multiple boot modes, controlled
+by external jumpers. Make sure this is set up correctly.
+For example many i.MX boards from NXP need to be jumpered
+to "ATX mode" to start booting using the on-chip ROM, when
+using second stage bootloader code stored in a NAND flash chip.
+
+Such explicit configuration is common, and not limited to
+booting from NAND. You might also need to set jumpers to
+start booting using code loaded from an MMC/SD card; external
+SPI flash; Ethernet, UART, or USB links; NOR flash; OneNAND
+flash; some external host; or various other sources.
+
+
+@item @b{Memory Addressing} ...
+Boards which support multiple boot modes may also have jumpers
+to configure memory addressing. One board, for example, jumpers
+external chipselect 0 (used for booting) to address either
+a large SRAM (which must be pre-loaded via JTAG), NOR flash,
+or NAND flash. When it's jumpered to address NAND flash, that
+board must also be told to start booting from on-chip ROM.
+
+Your @file{board.cfg} file may also need to be told this jumper
+configuration, so that it can know whether to declare NOR flash
+using @command{flash bank} or instead declare NAND flash with
+@command{nand device}; and likewise which probe to perform in
+its @code{reset-init} handler.
+
+A closely related issue is bus width. Jumpers might need to
+distinguish between 8 bit or 16 bit bus access for the flash
+used to start booting.
+
+@item @b{Peripheral Access} ...
+Development boards generally provide access to every peripheral
+on the chip, sometimes in multiple modes (such as by providing
+multiple audio codec chips).
+This interacts with software
+configuration of pin multiplexing, where for example a
+given pin may be routed either to the MMC/SD controller
+or the GPIO controller. It also often interacts with
+configuration jumpers. One jumper may be used to route
+signals to an MMC/SD card slot or an expansion bus (which
+might in turn affect booting); others might control which
+audio or video codecs are used.
+
+@end itemize
+
+Plus you should of course have @code{reset-init} event handlers
+which set up the hardware to match that jumper configuration.
+That includes in particular any oscillator or PLL used to clock
+the CPU, and any memory controllers needed to access external
+memory and peripherals. Without such handlers, you won't be
+able to access those resources without working target firmware
+which can do that setup ... this can be awkward when you're
+trying to debug that target firmware. Even if there's a ROM
+bootloader which handles a few issues, it rarely provides full
+access to all board-specific capabilities.
+
+
@node Config File Guidelines
@chapter Config File Guidelines
When the OpenOCD server process starts up, it enters a
@emph{configuration stage} which is the only time that
certain commands, @emph{configuration commands}, may be issued.
+Normally, configuration commands are only available
+inside startup scripts.
+
In this manual, the definition of a configuration command is
presented as a @emph{Config Command}, not as a @emph{Command}
which may be issued interactively.
+The runtime @command{help} command also highlights configuration
+commands, and those which may be issued at any time.
Those configuration commands include declaration of TAPs,
flash banks,
If you disable all access through TCP/IP, you will need to
use the command line @option{-pipe} option.
-@deffn {Command} gdb_port (number)
+@deffn {Command} gdb_port [number]
@cindex GDB server
Specify or query the first port used 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.
When not specified during the configuration stage,
the port @var{number} defaults to 3333.
-When specified as zero, this port is not activated.
+When specified as zero, GDB remote access ports are not activated.
@end deffn
-@deffn {Command} tcl_port (number)
+@deffn {Command} tcl_port [number]
Specify or query the port used for a simplified RPC
connection that can be used by clients to issue TCL commands and get the
output from the Tcl engine.
When specified as zero, this port is not activated.
@end deffn
-@deffn {Command} telnet_port (number)
+@deffn {Command} telnet_port [number]
Specify or query the
port on which to listen for incoming telnet connections.
This port is intended for interaction with one human through TCL commands.
You could use this from the TCL command shell, or
from GDB using @command{monitor poll} command.
+Leave background polling enabled while you're using GDB.
@example
> poll
background polling: on
@item @b{evb_lm3s811} Luminary Micro EVB_LM3S811 as a JTAG interface,
either for the local Cortex-M3 (SRST only)
or in a passthrough mode (neither SRST nor TRST)
-@item @b{luminary_icdi} Luminary In-Circuit Debug Interface (ICDI) Board
+This layout can not support the SWO trace mechanism, and should be
+used only for older boards (before rev C).
+@item @b{luminary_icdi} This layout should be used with most Luminary
+eval boards, including Rev C LM3S811 eval boards and the eponymous
+ICDI boards, to debug either the local Cortex-M3 or in passthrough mode
+to debug some other target. It can support the SWO trace mechanism.
@item @b{flyswatter} Tin Can Tools Flyswatter
@item @b{icebear} ICEbear JTAG adapter from Section 5
@item @b{jtagkey} Amontec JTAGkey and JTAGkey-Tiny (and compatibles)
@end example
@end deffn
+@deffn {Interface Driver} {usb_blaster}
+USB JTAG/USB-Blaster compatibles over one of the userspace libraries
+for FTDI chips. These interfaces have several commands, used to
+configure the driver before initializing the JTAG scan chain:
+
+@deffn {Config Command} {usb_blaster_device_desc} description
+Provides the USB device description (the @emph{iProduct string})
+of the FTDI FT245 device. If not
+specified, the FTDI default value is used. This setting is only valid
+if compiled with FTD2XX support.
+@end deffn
+
+@deffn {Config Command} {usb_blaster_vid_pid} vid pid
+The vendor ID and product ID of the FTDI FT245 device. If not specified,
+default values are used.
+Currently, only one @var{vid}, @var{pid} pair may be given, e.g. for
+Altera USB-Blaster (default):
+@example
+ft2232_vid_pid 0x09FB 0x6001
+@end example
+The following VID/PID is for Kolja Waschk's USB JTAG:
+@example
+ft2232_vid_pid 0x16C0 0x06AD
+@end example
+@end deffn
+
+@deffn {Command} {usb_blaster} (@option{pin6}|@option{pin8}) (@option{0}|@option{1})
+Sets the state of the unused GPIO pins on USB-Blasters (pins 6 and 8 on the
+female JTAG header). These pins can be used as SRST and/or TRST provided the
+appropriate connections are made on the target board.
+
+For example, to use pin 6 as SRST (as with an AVR board):
+@example
+$_TARGETNAME configure -event reset-assert \
+ "usb_blaster pin6 1; wait 1; usb_blaster pin6 0"
+@end example
+@end deffn
+
+@end deffn
+
@deffn {Interface Driver} {gw16012}
Gateworks GW16012 JTAG programmer.
This has one driver-specific command:
-@deffn {Config Command} {parport_port} number
-Specifies either the address of the I/O port (default: 0x378 for LPT1) or
-the number of the @file{/dev/parport} device.
+@deffn {Config Command} {parport_port} [port_number]
+Display either the address of the I/O port
+(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
+If a parameter is provided, first switch to use that port.
+This is a write-once setting.
@end deffn
@end deffn
before initializing the JTAG scan chain:
@deffn {Config Command} {parport_cable} name
-The layout of the parallel port cable used to connect to the target.
+Set the layout of the parallel port cable used to connect to the target.
+This is a write-once setting.
Currently valid cable @var{name} values include:
@itemize @minus
@end itemize
@end deffn
-@deffn {Config Command} {parport_port} number
-Either the address of the I/O port (default: 0x378 for LPT1) or the number of
-the @file{/dev/parport} device
+@deffn {Config Command} {parport_port} [port_number]
+Display either the address of the I/O port
+(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
+If a parameter is provided, first switch to use that port.
+This is a write-once setting.
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
@end quotation
@end deffn
-@deffn {Config Command} {parport_write_on_exit} (on|off)
+@deffn {Config Command} {parport_write_on_exit} (@option{on}|@option{off})
This will configure the parallel driver to write a known
-cable-specific value to the parallel interface on exiting OpenOCD
+cable-specific value to the parallel interface on exiting OpenOCD.
@end deffn
For example, the interface configuration file for a
-classic ``Wiggler'' cable might look something like this:
+classic ``Wiggler'' cable on LPT2 might look something like this:
@example
interface parport
-parport_port 0xc8b8
+parport_port 0x278
parport_cable wiggler
@end example
@end deffn
@deffn {Interface Driver} {presto}
ASIX PRESTO USB JTAG programmer.
-@c command: presto_serial str
-@c sets serial number
+@deffn {Config Command} {presto_serial} serial_string
+Configures the USB serial number of the Presto device to use.
+@end deffn
@end deffn
@deffn {Interface Driver} {rlink}
The default behaviour if no option given is @option{separate},
indicating everything behaves normally.
@option{srst_pulls_trst} states that the
-test logic is reset together with the reset of the system (e.g. Philips
+test logic is reset together with the reset of the system (e.g. NXP
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).
@itemize @bullet
@item @var{name} ... may be used to reference the flash bank
-in other flash commands.
+in other flash commands. A number is also available.
@item @var{driver} ... identifies the controller driver
associated with the flash bank being declared.
This is usually @code{cfi} for external flash, or else
@comment the REAL name for this command is "ocd_flash_banks"
@comment less confusing would be: "flash list" (like "nand list")
@deffn Command {flash banks}
-Prints a one-line summary of each device that was
+Prints a one-line summary of each device that was
declared using @command{flash bank}, numbered from zero.
Note that this is the @emph{plural} form;
the @emph{singular} form is a very different command.
@end deffn
@deffn Command {flash list}
-Retrieves a list of associative arrays for each device that was
+Retrieves a list of associative arrays for each device that was
declared using @command{flash bank}, numbered from zero.
This returned list can be manipulated easily from within scripts.
@end deffn
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {flash erase_address} address length
+@deffn Command {flash erase_address} [@option{pad}] address length
Erase sectors starting at @var{address} for @var{length} bytes.
+Unless @option{pad} is specified, @math{address} must begin a
+flash sector, and @math{address + length - 1} must end a sector.
+Specifying @option{pad} erases extra data at the beginning and/or
+end of the specified region, as needed to erase only full sectors.
The flash bank to use is inferred from the @var{address}, and
the specified length must stay within that bank.
As a special case, when @var{length} is zero and @var{address} is
The relevant flash sectors will be erased prior to programming
if the @option{erase} parameter is given. If @option{unlock} is
provided, then the flash banks are unlocked before erase and
-program. The flash bank to use is inferred from the @var{address} of
-each image segment.
+program. The flash bank to use is inferred from the address of
+each image section.
+
+@quotation Warning
+Be careful using the @option{erase} flag when the flash is holding
+data you want to preserve.
+Portions of the flash outside those described in the image's
+sections might be erased with no notice.
+@itemize
+@item
+When a section of the image being written does not fill out all the
+sectors it uses, the unwritten parts of those sectors are necessarily
+also erased, because sectors can't be partially erased.
+@item
+Data stored in sector "holes" between image sections are also affected.
+For example, "@command{flash write_image erase ...}" of an image with
+one byte at the beginning of a flash bank and one byte at the end
+erases the entire bank -- not just the two sectors being written.
+@end itemize
+Also, when flash protection is important, you must re-apply it after
+it has been removed by the @option{unlock} flag.
+@end quotation
+
@end deffn
@section Other Flash commands
Check erase state of sectors in flash bank @var{num},
and display that status.
The @var{num} parameter is a value shown by @command{flash banks}.
-This is the only operation that
-updates the erase state information displayed by @option{flash info}. That means you have
-to issue a @command{flash erase_check} command after erasing or programming the device
-to get updated information.
-(Code execution may have invalidated any state records kept by OpenOCD.)
@end deffn
@deffn Command {flash info} num
Print info about flash bank @var{num}
The @var{num} parameter is a value shown by @command{flash banks}.
-The information includes per-sector protect status.
+The information includes per-sector protect status, which may be
+incorrect (outdated) unless you first issue a
+@command{flash protect_check num} command.
@end deffn
@anchor{flash protect}
Check protection state of sectors in flash bank @var{num}.
The @var{num} parameter is a value shown by @command{flash banks}.
@comment @option{flash erase_sector} using the same syntax.
+This updates the protection information displayed by @option{flash info}.
+(Code execution may have invalidated any state records kept by OpenOCD.)
@end deffn
@anchor{Flash Driver List}
@command{flash erase_sector} or @command{flash erase_address} commands.
@deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
-Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
+Set or clear a ``General Purpose Non-Volatile Memory'' (GPNVM)
bit for the processor. Each processor has a number of such bits,
used for controlling features such as brownout detection (so they
are not truly general purpose).
@itemize
@item @var{variant} ... required, may be
-@var{lpc2000_v1} (older LPC21xx and LPC22xx)
-@var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx)
-or @var{lpc1700} (LPC175x and LPC176x)
+@option{lpc2000_v1} (older LPC21xx and LPC22xx)
+@option{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx)
+or @option{lpc1700} (LPC175x and LPC176x)
@item @var{clock_kHz} ... the frequency, in kiloHertz,
at which the core is running
-@item @var{calc_checksum} ... optional (but you probably want to provide this!),
+@item @option{calc_checksum} ... optional (but you probably want to provide this!),
telling the driver to calculate a valid checksum for the exception vector table.
+@quotation Note
+If you don't provide @option{calc_checksum} when you're writing the vector
+table, the boot ROM will almost certainly ignore your flash image.
+However, if you do provide it,
+with most tool chains @command{verify_image} will fail.
+@end quotation
@end itemize
LPC flashes don't require the chip and bus width to be specified.
plus some additional configuration that's done after
OpenOCD has initialized.
-@deffn {Config Command} {nand device} name controller target [configparams...]
+@deffn {Config Command} {nand device} name driver target [configparams...]
Declares a NAND device, which can be read and written to
after it has been configured through @command{nand probe}.
In OpenOCD, devices are single chips; this is unlike some
@itemize @bullet
@item @var{name} ... may be used to reference the NAND bank
-in other commands.
-@item @var{controller} ... identifies the controller driver
+in most other NAND commands. A number is also available.
+@item @var{driver} ... identifies the NAND controller driver
associated with the NAND device being declared.
@xref{NAND Driver List}.
@item @var{target} ... names the target used when issuing
@end example
AT91SAM9 chips support single-bit ECC hardware. The @code{write_page} and
@code{read_page} methods are used to utilize the ECC hardware unless they are
-disabled by using the @command{nand raw_access} command. There are four
+disabled by using the @command{nand raw_access} command. There are four
additional commands that are needed to fully configure the AT91SAM9 NAND
controller. Two are optional; most boards use the same wiring for ALE/CLE:
@deffn Command {at91sam9 cle} num addr_line
-Configure the address line used for latching commands. The @var{num}
+Configure the address line used for latching commands. The @var{num}
parameter is the value shown by @command{nand list}.
@end deffn
@deffn Command {at91sam9 ale} num addr_line
-Configure the address line used for latching addresses. The @var{num}
+Configure the address line used for latching addresses. The @var{num}
parameter is the value shown by @command{nand list}.
@end deffn
-For the next two commands, it is assumed that the pins have already been
+For the next two commands, it is assumed that the pins have already been
properly configured for input or output.
@deffn Command {at91sam9 rdy_busy} num pio_base_addr pin
-Configure the RDY/nBUSY input from the NAND device. The @var{num}
-parameter is the value shown by @command{nand list}. @var{pio_base_addr}
+Configure the RDY/nBUSY input from the NAND device. The @var{num}
+parameter is the value shown by @command{nand list}. @var{pio_base_addr}
is the base address of the PIO controller and @var{pin} is the pin number.
@end deffn
@deffn Command {at91sam9 ce} num pio_base_addr pin
-Configure the chip enable input to the NAND device. The @var{num}
-parameter is the value shown by @command{nand list}. @var{pio_base_addr}
+Configure the chip enable input to the NAND device. The @var{num}
+parameter is the value shown by @command{nand list}. @var{pio_base_addr}
is the base address of the PIO controller and @var{pin} is the pin number.
@end deffn
@end deffn
@deffnx {NAND Driver} s3c2412
@deffnx {NAND Driver} s3c2440
@deffnx {NAND Driver} s3c2443
-These S3C24xx family controllers don't have any special
+@deffnx {NAND Driver} s3c6400
+These S3C family controllers don't have any special
@command{nand device} options, and don't define any
specialized commands.
At this writing, their drivers don't include @code{write_page}
Exits the current telnet session.
@end deffn
-@c note EXTREMELY ANNOYING word wrap at column 75
-@c even when lines are e.g. 100+ columns ...
-@c coded in startup.tcl
@deffn {Command} help [string]
With no parameters, prints help text for all commands.
Otherwise, prints each helptext containing @var{string}.
Not every command provides helptext.
+
+Configuration commands, and commands valid at any time, are
+explicitly noted in parenthesis.
+In most cases, no such restriction is listed; this indicates commands
+which are only available after the configuration stage has completed.
@end deffn
@deffn Command sleep msec [@option{busy}]
an ARM register.)
@end deffn
-@deffn Command {arm mrc} pX coproc op1 CRn CRm op2
+@deffn Command {arm mrc} pX coproc op1 CRn CRm op2
Read a coprocessor @var{pX} register passing parameters @var{CRn},
@var{CRm}, opcodes @var{opc1} and @var{opc2},
and the MRC instruction.
@cindex ARMv5
The ARMv4 and ARMv5 architectures are widely used in embedded systems,
-and introduced core parts of the instruction set in use today.
+and introduced core parts of the instruction set in use today.
That includes the Thumb instruction set, introduced in the ARMv4T
variant.
They are available in addition to the ARM commands,
and any other core-specific commands that may be available.
-@deffn Command {arm7_9 dbgrq} (@option{enable}|@option{disable})
-Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode,
-instead of breakpoints. This should be
-safe for all but ARM7TDMI--S cores (like Philips LPC).
+@deffn Command {arm7_9 dbgrq} [@option{enable}|@option{disable}]
+Displays the value of the flag controlling use of the
+the EmbeddedIce DBGRQ signal to force entry into debug mode,
+instead of breakpoints.
+If a boolean parameter is provided, first assigns that flag.
+
+This should be
+safe for all but ARM7TDMI-S cores (like NXP LPC).
This feature is enabled by default on most ARM9 cores,
including ARM9TDMI, ARM920T, and ARM926EJ-S.
@end deffn
-@deffn Command {arm7_9 dcc_downloads} (@option{enable}|@option{disable})
+@deffn Command {arm7_9 dcc_downloads} [@option{enable}|@option{disable}]
@cindex DCC
-Control 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
+Displays the value of the flag controlling use of the debug communications
+channel (DCC) to write larger (>128 byte) amounts of memory.
+If a boolean parameter is provided, first assigns that flag.
+
+DCC downloads offer a huge speed increase, but might be
unsafe, especially with targets running at very low speeds. This command was introduced
with OpenOCD rev. 60, and requires a few bytes of working area.
@end deffn
@anchor{arm7_9 fast_memory_access}
-@deffn Command {arm7_9 fast_memory_access} (@option{enable}|@option{disable})
-Enable or disable memory writes and reads that don't check completion of
-the operation. This provides a huge speed increase, especially with USB JTAG
+@deffn Command {arm7_9 fast_memory_access} [@option{enable}|@option{disable}]
+Displays the value of the flag controlling use of memory writes and reads
+that don't check completion of the operation.
+If a boolean parameter is provided, first assigns that flag.
+
+This provides a huge speed increase, especially with USB JTAG
cables (FT2232), but might be unsafe if used with targets running at very low
speeds, like the 32kHz startup clock of an AT91RM9200.
@end deffn
based on the ARM7TDMI-S integer core.
They are available in addition to the ARM and ARM7/ARM9 commands.
-@deffn Command {arm720t cp15} regnum [value]
-Display cp15 register @var{regnum};
+@deffn Command {arm720t cp15} opcode [value]
+@emph{DEPRECATED -- avoid using this.
+Use the @command{arm mrc} or @command{arm mcr} commands instead.}
+
+Display cp15 register returned by the ARM instruction @var{opcode};
else if a @var{value} is provided, that value is written to that register.
+The @var{opcode} should be the value of either an MRC or MCR instruction.
@end deffn
@subsection ARM9 specific commands
@deffn Command {arm920t cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
+This uses "physical access" and the register number is as
+shown in bits 38..33 of table 9-9 in the ARM920T TRM.
+(Not all registers can be written.)
@end deffn
@deffn Command {arm920t cp15i} opcode [value [address]]
-Interpreted access using cp15 @var{opcode}.
+@emph{DEPRECATED -- avoid using this.
+Use the @command{arm mrc} or @command{arm mcr} commands instead.}
+
+Interpreted access using ARM instruction @var{opcode}, which should
+be the value of either an MRC or MCR instruction
+(as shown tables 9-11, 9-12, and 9-13 in the ARM920T TRM).
If no @var{value} is provided, the result is displayed.
Else if that value is written using the specified @var{address},
-or using zero if no other address is not provided.
+or using zero if no other address is provided.
@end deffn
@deffn Command {arm920t read_cache} filename
@deffn Command {arm966e cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
+The six bit @var{regnum} values are bits 37..32 from table 7-2 of the
+ARM966E-S TRM.
+There is no current control over bits 31..30 from that table,
+as required for BIST support.
@end deffn
@subsection XScale specific commands
Changes the address used for the specified target's debug handler.
@end deffn
-@deffn Command {xscale dcache} (@option{enable}|@option{disable})
+@deffn Command {xscale dcache} [@option{enable}|@option{disable}]
Enables or disable the CPU's data cache.
@end deffn
Dumps the raw contents of the trace buffer to @file{filename}.
@end deffn
-@deffn Command {xscale icache} (@option{enable}|@option{disable})
+@deffn Command {xscale icache} [@option{enable}|@option{disable}]
Enables or disable the CPU's instruction cache.
@end deffn
-@deffn Command {xscale mmu} (@option{enable}|@option{disable})
+@deffn Command {xscale mmu} [@option{enable}|@option{disable}]
Enables or disable the CPU's memory management unit.
@end deffn
-@deffn Command {xscale trace_buffer} (@option{enable}|@option{disable}) [@option{fill} [n] | @option{wrap}]
-Enables or disables the trace buffer,
-and controls how it is emptied.
+@deffn Command {xscale trace_buffer} [@option{enable}|@option{disable} [@option{fill} [n] | @option{wrap}]]
+Displays the trace buffer status, after optionally
+enabling or disabling the trace buffer
+and modifying how it is emptied.
@end deffn
@deffn Command {xscale trace_image} filename [offset [type]]
@end deffn
@anchor{xscale vector_table}
-@deffn Command {xscale vector_table} [<low|high> <index> <value>]
+@deffn Command {xscale vector_table} [(@option{low}|@option{high}) index value]
@cindex vector_table
Set an entry in the mini-IC vector table. There are two tables: one for
@subsection ARM11 specific commands
@cindex ARM11
-@deffn Command {arm11 memwrite burst} [value]
+@deffn Command {arm11 memwrite burst} [@option{enable}|@option{disable}]
Displays the value of the memwrite burst-enable flag,
-which is enabled by default. Burst writes are only used
-for memory writes larger than 1 word. Single word writes
-are likely to be from reset init scripts and those writes
-are often to non-memory locations which could easily have
-many wait states, which could easily break burst writes.
-If @var{value} is defined, first assigns that.
+which is enabled by default.
+If a boolean parameter is provided, first assigns that flag.
+Burst writes are only used for memory writes larger than 1 word.
+They improve performance by assuming that the CPU has read each data
+word over JTAG and completed its write before the next word arrives,
+instead of polling for a status flag to verify that completion.
+This is usually safe, because JTAG runs much slower than the CPU.
@end deffn
-@deffn Command {arm11 memwrite error_fatal} [value]
+@deffn Command {arm11 memwrite error_fatal} [@option{enable}|@option{disable}]
Displays the value of the memwrite error_fatal flag,
which is enabled by default.
-If @var{value} is defined, first assigns that.
+If a boolean parameter is provided, first assigns that flag.
+When set, certain memory write errors cause earlier transfer termination.
@end deffn
-@deffn Command {arm11 step_irq_enable} [value]
+@deffn Command {arm11 step_irq_enable} [@option{enable}|@option{disable}]
Displays the value of the flag controlling whether
IRQs are enabled during single stepping;
they are disabled by default.
-If @var{value} is defined, first assigns that.
+If a boolean parameter is provided, first assigns that.
@end deffn
@deffn Command {arm11 vcr} [value]
included on Cortex-M3 and Cortex-A8 systems.
They are available in addition to other core-specific commands that may be available.
-@deffn Command {dap info} [num]
-Displays dap info for ap @var{num}, defaulting to the currently selected AP.
+@deffn Command {dap apid} [num]
+Displays ID register from AP @var{num},
+defaulting to the currently selected AP.
@end deffn
@deffn Command {dap apsel} [num]
Select AP @var{num}, defaulting to 0.
@end deffn
-@deffn Command {dap apid} [num]
-Displays id register from AP @var{num},
+@deffn Command {dap baseaddr} [num]
+Displays debug base address from MEM-AP @var{num},
defaulting to the currently selected AP.
@end deffn
-@deffn Command {dap baseaddr} [num]
-Displays debug base address from AP @var{num},
+@deffn Command {dap info} [num]
+Displays the ROM table for MEM-AP @var{num},
defaulting to the currently selected AP.
@end deffn
@deffn Command {dap memaccess} [value]
-Displays the number of extra tck for mem-ap memory bus access [0-255].
+Displays the number of extra tck cycles in the JTAG idle to use for MEM-AP
+memory bus access [0-255], giving additional time to respond to reads.
If @var{value} is defined, first assigns that.
@end deffn
Setting up GDB to work with OpenOCD can involve several components:
@itemize
-@item OpenOCD itself may need to be configured. @xref{GDB Configuration}.
-@item GDB itself may need configuration, as shown in this chapter.
+@item The OpenOCD server support for GDB may need to be configured.
+@xref{GDB Configuration}.
+@item GDB's support for OpenOCD may need configuration,
+as shown in this chapter.
@item If you have a GUI environment like Eclipse,
that also will probably need to be configured.
@end itemize
@cindex Connecting to GDB
Use GDB 6.7 or newer with OpenOCD if you run into trouble. For
instance GDB 6.3 has a known bug that produces bogus memory access
-errors, which has since been fixed: look up 1836 in
-@url{http://sourceware.org/cgi-bin/gnatsweb.pl?database=gdb}
+errors, which has since been fixed; see
+@url{http://osdir.com/ml/gdb.bugs.discuss/2004-12/msg00018.html}
OpenOCD can communicate with GDB in two ways:
To list the available OpenOCD commands type @command{monitor help} on the
GDB command line.
+@section Sample GDB session startup
+
+With the remote protocol, GDB sessions start a little differently
+than they do when you're debugging locally.
+Here's an examples showing how to start a debug session with a
+small ARM program.
+In this case the program was linked to be loaded into SRAM on a Cortex-M3.
+Most programs would be written into flash (address 0) and run from there.
+
+@example
+$ arm-none-eabi-gdb example.elf
+(gdb) target remote localhost:3333
+Remote debugging using localhost:3333
+...
+(gdb) monitor reset halt
+...
+(gdb) load
+Loading section .vectors, size 0x100 lma 0x20000000
+Loading section .text, size 0x5a0 lma 0x20000100
+Loading section .data, size 0x18 lma 0x200006a0
+Start address 0x2000061c, load size 1720
+Transfer rate: 22 KB/sec, 573 bytes/write.
+(gdb) continue
+Continuing.
+...
+@end example
+
+You could then interrupt the GDB session to make the program break,
+type @command{where} to show the stack, @command{list} to show the
+code around the program counter, @command{step} through code,
+set breakpoints or watchpoints, and so on.
+
@section Configuring GDB for OpenOCD
OpenOCD supports the gdb @option{qSupported} packet, this enables information
only work for code running from flash memory. Most other ARM systems
do not have such restrictions.
+Another example of useful GDB configuration came from a user who
+found that single stepping his Cortex-M3 didn't work well with IRQs
+and an RTOS until he told GDB to disable the IRQs while stepping:
+
+@example
+define hook-step
+mon cortex_m3 maskisr on
+end
+define hookpost-step
+mon cortex_m3 maskisr off
+end
+@end example
+
+Rather than typing such commands interactively, you may prefer to
+save them in a file and have GDB execute them as it starts, perhaps
+using a @file{.gdbinit} in your project directory or starting GDB
+using @command{gdb -x filename}.
+
@section Programming using GDB
@cindex Programming using GDB
holds one of the following values:
@itemize @bullet
-@item @b{winxx} Built using Microsoft Visual Studio
-@item @b{linux} Linux is the underlying operating sytem
-@item @b{darwin} Darwin (mac-os) is the underlying operating sytem.
@item @b{cygwin} Running under Cygwin
+@item @b{darwin} Darwin (Mac-OS) is the underlying operating sytem.
+@item @b{freebsd} Running under FreeBSD
+@item @b{linux} Linux is the underlying operating sytem
@item @b{mingw32} Running under MingW32
+@item @b{winxx} Built using Microsoft Visual Studio
@item @b{other} Unknown, none of the above.
@end itemize
In digital circuit design it is often refered to as ``clock
synchronisation'' the JTAG interface uses one clock (TCK or TCLK)
-operating at some speed, your target is operating at another. The two
-clocks are not synchronised, they are ``asynchronous''
+operating at some speed, your CPU target is operating at another.
+The two clocks are not synchronised, they are ``asynchronous''
-In order for the two to work together they must be synchronised. Otherwise
-the two systems will get out of sync with each other and nothing will
-work. There are 2 basic options:
+In order for the two to work together they must be synchronised
+well enough to work; JTAG can't go ten times faster than the CPU,
+for example. There are 2 basic options:
@enumerate
@item
-Use a special circuit.
+Use a special "adaptive clocking" circuit to change the JTAG
+clock rate to match what the CPU currently supports.
@item
-One clock must be some multiple slower than the other.
+The JTAG clock must be fixed at some speed that's enough slower than
+the CPU clock that all TMS and TDI transitions can be detected.
@end enumerate
@b{Does this really matter?} For some chips and some situations, this
-is a non-issue (i.e.: A 500MHz ARM926) but for others - for example some
-Atmel SAM7 and SAM9 chips start operation from reset at 32kHz -
-program/enable the oscillators and eventually the main clock. It is in
-those critical times you must slow the JTAG clock to sometimes 1 to
-4kHz.
-
-Imagine debugging a 500MHz ARM926 hand held battery powered device
-that ``deep sleeps'' at 32kHz between every keystroke. It can be
-painful.
+is a non-issue, like a 500MHz ARM926 with a 5 MHz JTAG link;
+the CPU has no difficulty keeping up with JTAG.
+Startup sequences are often problematic though, as are other
+situations where the CPU clock rate changes (perhaps to save
+power).
+
+For example, Atmel AT91SAM chips start operation from reset with
+a 32kHz system clock. Boot firmware may activate the main oscillator
+and PLL before switching to a faster clock (perhaps that 500 MHz
+ARM926 scenario).
+If you're using JTAG to debug that startup sequence, you must slow
+the JTAG clock to sometimes 1 to 4kHz. After startup completes,
+JTAG can use a faster clock.
+
+Consider also debugging a 500MHz ARM926 hand held battery powered
+device that enters a low power ``deep sleep'' mode, at 32kHz CPU
+clock, between keystrokes unless it has work to do. When would
+that 5 MHz JTAG clock be usable?
@b{Solution #1 - A special circuit}
-In order to make use of this, your JTAG dongle must support the RTCK
+In order to make use of this,
+both your CPU and your JTAG dongle must support the RTCK
feature. Not all dongles support this - keep reading!
-The RTCK signal often found in some ARM chips is used to help with
+The RTCK ("Return TCK") signal in some ARM chips is used to help with
this problem. ARM has a good description of the problem described at
this link: @url{http://www.arm.com/support/faqdev/4170.html} [checked
28/nov/2008]. Link title: ``How does the JTAG synchronisation logic
Note: Many FTDI2232C based JTAG dongles are limited to 6MHz.
You can still debug the 'low power' situations - you just need to
-manually adjust the clock speed at every step. While painful and
-tedious, it is not always practical.
+either use a fixed and very slow JTAG clock rate ... or else
+manually adjust the clock speed at every step. (Adjusting is painful
+and tedious, and is not always practical.)
It is however easy to ``code your way around it'' - i.e.: Cheat a little,
have a special debug mode in your application that does a ``high power
Code Review / openocd.git / blobdiff