@* 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:
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
+ TapName Enabled IdCode Expected IrLen IrCap IrMask
+-- ------------------ ------- ---------- ---------- ----- ----- ------
+ 0 omap5912.dsp Y 0x03df1d81 0x03df1d81 38 0x01 0x03
+ 1 omap5912.arm Y 0x0692602f 0x0692602f 4 0x01 0x0f
+ 2 omap5912.unknown Y 0x00000000 0x00000000 8 0x01 0x03
@end verbatim
+OpenOCD can detect some of that information, but not all
+of it. @xref{Autoprobing}.
Unfortunately those TAPs can't always be autoconfigured,
because not all devices provide good support for that.
JTAG doesn't require supporting IDCODE instructions, and
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! "jtag cget" should be able to return all TAP
reference manual. Sometimes you may need to probe the JTAG
hardware to find these values.
@xref{Autoprobing}.
+@item @code{-ignore-version}
+@*Specify this to ignore the JTAG version field in the @code{-expected-id}
+option. When vendors put out multiple versions of a chip, or use the same
+JTAG-level ID for several largely-compatible chips, it may be more practical
+to ignore the version field than to update config files to handle all of
+the various chip IDs.
@item @code{-ircapture} @var{NUMBER}
@*The bit pattern loaded by the TAP into the JTAG shift register
on entry to the @sc{ircapture} state, such as 0x01.
be detected and the normal reset behaviour used.
@end itemize
@item @code{dragonite} -- resembles arm966e
+@item @code{dsp563xx} -- implements Freescale's 24-bit DSP.
+(Support for this is still incomplete.)
@item @code{fa526} -- resembles arm920 (w/o Thumb)
@item @code{feroceon} -- resembles arm926
@item @code{mips_m4k} -- a MIPS core. This supports one variant:
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 GDB
OpenOCD complies with the remote gdbserver protocol, and as such can be used
to debug remote targets.
+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 If you have a GUI environment like Eclipse,
+that also will probably need to be configured.
+@end itemize
+
+Of course, the version of GDB you use will need to be one which has
+been built to know about the target CPU you're using. It's probably
+part of the tool chain you're using. For example, if you are doing
+cross-development for ARM on an x86 PC, instead of using the native
+x86 @command{gdb} command you might use @command{arm-none-eabi-gdb}
+if that's the tool chain used to compile your code.
@anchor{Connecting to GDB}
@section Connecting to GDB
@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
to be sent by the GDB remote server (i.e. OpenOCD) to GDB. Typical information includes
packet size and the device's memory map.
+You do not need to configure the packet size by hand,
+and the relevant parts of the memory map should be automatically
+set up when you declare (NOR) flash banks.
+
+However, there are other things which GDB can't currently query.
+You may need to set those up by hand.
+As OpenOCD starts up, you will often see a line reporting
+something like:
+
+@example
+Info : lm3s.cpu: hardware has 6 breakpoints, 4 watchpoints
+@end example
+
+You can pass that information to GDB with these commands:
-Previous versions of OpenOCD required the following GDB options to increase
-the packet size and speed up GDB communication:
@example
-set remote memory-write-packet-size 1024
-set remote memory-write-packet-size fixed
-set remote memory-read-packet-size 1024
-set remote memory-read-packet-size fixed
+set remote hardware-breakpoint-limit 6
+set remote hardware-watchpoint-limit 4
@end example
-This is now handled in the @option{qSupported} PacketSize and should not be required.
+
+With that particular hardware (Cortex-M3) the hardware breakpoints
+only work for code running from flash memory. Most other ARM systems
+do not have such restrictions.
@section Programming using GDB
@cindex Programming using GDB
projects / fw / openocd / blobdiff