X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=02caf5b1290231f7f1f90ebf99349c49b5ea2d6f;hp=9d5652315d306ab7ca3529e54ae083f22137f52e;hb=ec297e4bf10f7d903d8b5fc3237a7c6bbfa6273d;hpb=646ce814b4fb678b7d8d341afe0694c266112426 diff --git a/doc/openocd.texi b/doc/openocd.texi index 9d5652315d..02caf5b129 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -288,10 +288,17 @@ chips are starting to become available in JTAG adapters. @* 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} @@ -310,6 +317,25 @@ chips are starting to become available in JTAG adapters. @* 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 @@ -1805,6 +1831,7 @@ allows background polling to be enabled and disabled. 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 @@ -1942,7 +1969,12 @@ Currently valid layout @var{name} values include: @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) @@ -1988,6 +2020,46 @@ ft2232_vid_pid 0x0403 0xbdc8 @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: @@ -2592,13 +2664,15 @@ 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 + 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 @@ -2659,8 +2733,6 @@ 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! "jtag cget" should be able to return all TAP @@ -3797,8 +3869,29 @@ explicitly as @option{bin} (binary), @option{ihex} (Intel hex), 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 @@ -4812,6 +4905,41 @@ As noted above, the @command{nand device} command allows 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. @@ -5512,26 +5640,15 @@ trace stream without an image of the code. @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 @@ -5617,6 +5734,28 @@ to use on-chip ETB memory. 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 @@ -6526,8 +6665,8 @@ if that's the tool chain used to compile your code. @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: @@ -6551,6 +6690,38 @@ session. 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