@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
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
--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
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 @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
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}
@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.
@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}
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
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
projects / fw / openocd / blobdiff