X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=d4e60a8042bd049bce7387dbb2e6a52e1c32588c;hp=bb3e51ac1e61b6d988653ed57ceb1214e241879a;hb=3ea9e62189205cfa84a04ec6955aaf1f5184a937;hpb=9abad965ab358c1d598f1354842967cad637b284 diff --git a/doc/openocd.texi b/doc/openocd.texi index bb3e51ac1e..d4e60a8042 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -23,7 +23,7 @@ of the Open On-Chip Debugger (OpenOCD). @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 @@ -60,7 +60,7 @@ Free Documentation License''. @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 @@ -152,7 +152,11 @@ PDF form is likewise published at: @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} @@ -219,9 +223,16 @@ communication between developers: @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 @@ -288,10 +299,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 +328,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 @@ -483,9 +520,10 @@ bash$ openocd --help --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 @@ -912,6 +950,33 @@ handling issues like: @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 @@ -934,7 +999,12 @@ via the @code{WFI} instruction (or its coprocessor equivalent, before ARMv7). 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. @@ -965,6 +1035,86 @@ various kinds of message. @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 @@ -1600,9 +1750,14 @@ supported. 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, @@ -1686,17 +1841,17 @@ In such cases, just specify the relevant port number as zero. 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. @@ -1706,7 +1861,7 @@ the port @var{number} defaults to 6666. 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. @@ -1805,6 +1960,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 +2098,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,13 +2149,55 @@ 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: -@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 @@ -2013,7 +2216,8 @@ These interfaces have several commands, used to configure the driver 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 @@ -2041,9 +2245,11 @@ several clones, such as the Olimex ARM-JTAG @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 @@ -2086,25 +2292,26 @@ match for the jtag_khz rate you specified; be conservative. @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} @@ -2420,7 +2627,7 @@ signal implementations. 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). @@ -3656,7 +3863,7 @@ see the driver-specific documentation. @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 @@ -3685,14 +3892,14 @@ Use it in board specific configuration files, not interactively. @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 @@ -3754,8 +3961,12 @@ specifies "to the end of the flash bank". 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 @@ -3797,8 +4008,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 @@ -3808,17 +4040,14 @@ each image segment. 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} @@ -3835,6 +4064,8 @@ The @var{num} parameter is a value shown by @command{flash banks}. 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} @@ -4001,7 +4232,7 @@ plane (of up to 256KB), and it will be used automatically when you issue @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). @@ -4041,13 +4272,19 @@ which must appear in the following order: @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. @@ -4571,7 +4808,7 @@ NAND chips must be declared in configuration scripts, 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 @@ -4586,8 +4823,8 @@ configuration files, not interactively. @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 @@ -4812,6 +5049,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. @@ -4862,7 +5134,8 @@ change any behavior. @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} @@ -4961,13 +5234,15 @@ port is 5555. 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}] @@ -5512,6 +5787,17 @@ trace stream without an image of the code. @end itemize @end deffn +@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}. + +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 After setting up the ETM, you can use it to collect data. @@ -5685,7 +5971,7 @@ and using the MCR instruction. 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. @@ -5704,7 +5990,7 @@ core mode if necessary. @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. @@ -5717,26 +6003,36 @@ ARM9TDMI, ARM920T or ARM926EJ-S. 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 @@ -5761,9 +6057,13 @@ which are implementations of the ARMv4T architecture 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 @@ -5814,13 +6114,21 @@ is an ARM920T (2x16kByte cache) or ARM922T (2x8kByte cache). @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 @@ -5858,6 +6166,10 @@ and ARM9 commands. @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 @@ -5933,7 +6245,7 @@ else if a @var{value} is provided, that value is written to that register. 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 @@ -5941,17 +6253,18 @@ Enables or disable the CPU's data cache. 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]] @@ -5983,7 +6296,7 @@ The mask bits correspond with bit 16..23 in the DCSR: @end deffn @anchor{xscale vector_table} -@deffn Command {xscale vector_table} [ ] +@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 @@ -6002,27 +6315,29 @@ Without arguments, the current settings are displayed. @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] @@ -6048,26 +6363,28 @@ These commands are specific to ARM architecture v7 Debug Access Port (DAP), 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 @@ -6508,8 +6825,10 @@ 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 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 @@ -6526,8 +6845,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 +6870,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 @@ -6580,6 +6931,24 @@ 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. +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 @@ -6694,11 +7063,12 @@ variables. JimTCL, as implemented in OpenOCD creates $ocd_HOSTOS which 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 @@ -6723,36 +7093,48 @@ is jim, not real tcl). 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 @@ -6789,8 +7171,9 @@ ARM11 cores use an 8:1 division. 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