@* 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
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:
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
driver-specific options and behaviors.
Some controllers also activate controller-specific commands.
+@deffn {NAND Driver} at91sam9
+This driver handles the NAND controllers found on AT91SAM9 family chips from
+Atmel. It takes two extra parameters: address of the NAND chip;
+address of the ECC controller.
+@example
+nand device $NANDFLASH at91sam9 $CHIPNAME 0x40000000 0xfffffe800
+@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
+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}
+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}
+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
+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}
+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}
+is the base address of the PIO controller and @var{pin} is the pin number.
+@end deffn
+@end deffn
+
@deffn {NAND Driver} davinci
This driver handles the NAND controllers found on DaVinci family
chips from Texas Instruments.
@end itemize
@end deffn
-@deffn Command {etm trigger_percent} [percent]
-This displays, or optionally changes, the trace port driver's
-behavior after the ETM's configured @emph{trigger} event fires.
-It controls how much more trace data is saved after the (single)
-trace trigger becomes active.
+@deffn Command {etm trigger_debug} (@option{enable}|@option{disable})
+Displays whether ETM triggering debug entry (like a breakpoint) is
+enabled or disabled, after optionally modifying that configuration.
+The default behaviour is @option{disable}.
+Any change takes effect after the next @command{etm start}.
-@itemize
-@item The default corresponds to @emph{trace around} usage,
-recording 50 percent data before the event and the rest
-afterwards.
-@item The minimum value of @var{percent} is 2 percent,
-recording almost exclusively data before the trigger.
-Such extreme @emph{trace before} usage can help figure out
-what caused that event to happen.
-@item The maximum value of @var{percent} is 100 percent,
-recording data almost exclusively after the event.
-This extreme @emph{trace after} usage might help sort out
-how the event caused trouble.
-@end itemize
-@c REVISIT allow "break" too -- enter debug mode.
+By using script commands to configure ETM registers, you can make the
+processor enter debug state automatically when certain conditions,
+more complex than supported by the breakpoint hardware, happen.
@end deffn
@subsection ETM Trace Operation
Associates the ETM for @var{target} with the ETB at @var{etb_tap}.
You can see the ETB registers using the @command{reg} command.
@end deffn
+@deffn Command {etb trigger_percent} [percent]
+This displays, or optionally changes, ETB behavior after the
+ETM's configured @emph{trigger} event fires.
+It controls how much more trace data is saved after the (single)
+trace trigger becomes active.
+
+@itemize
+@item The default corresponds to @emph{trace around} usage,
+recording 50 percent data before the event and the rest
+afterwards.
+@item The minimum value of @var{percent} is 2 percent,
+recording almost exclusively data before the trigger.
+Such extreme @emph{trace before} usage can help figure out
+what caused that event to happen.
+@item The maximum value of @var{percent} is 100 percent,
+recording data almost exclusively after the event.
+This extreme @emph{trace after} usage might help sort out
+how the event caused trouble.
+@end itemize
+@c REVISIT allow "break" too -- enter debug mode.
+@end deffn
+
@end deffn
@deffn {Trace Port Driver} oocd_trace
@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
projects / fw / openocd / blobdiff