X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=2e0143edff4db78b7af7e91cf1ff938c08cd6621;hp=ef395ea2b444eaea1e1c6ca97734a059f25e8faa;hb=c1cb20971ea89e4602bb23ba66180d647880bbef;hpb=927ae6899df12e4667d181575cc0494bf12ff209 diff --git a/doc/openocd.texi b/doc/openocd.texi index ef395ea2b4..2e0143edff 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -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,7 +223,7 @@ 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. @@ -288,10 +292,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 +321,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 @@ -1600,9 +1630,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, @@ -1805,6 +1840,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 +1978,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 +2029,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: @@ -2420,7 +2501,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). @@ -2592,13 +2673,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 +2742,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 @@ -2763,6 +2844,12 @@ are provided in vendors' chip documentation, usually a technical 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. @@ -3151,6 +3238,8 @@ This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will 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: @@ -3677,14 +3766,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 @@ -3789,8 +3878,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 @@ -4804,6 +4914,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. @@ -4953,13 +5098,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}] @@ -5504,26 +5651,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 @@ -5609,6 +5745,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 @@ -5677,7 +5835,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. @@ -5696,7 +5854,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. @@ -5709,26 +5867,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 @@ -5753,9 +5921,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 @@ -5806,13 +5978,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 @@ -5850,6 +6030,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 @@ -5925,7 +6109,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 @@ -5933,17 +6117,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]] @@ -5975,7 +6160,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 @@ -5994,27 +6179,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] @@ -6040,26 +6227,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 @@ -6497,14 +6686,29 @@ a bit of googling to find something that fits your requirements. @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: @@ -6528,19 +6732,66 @@ 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 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: -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 +Info : lm3s.cpu: hardware has 6 breakpoints, 4 watchpoints @end example -This is now handled in the @option{qSupported} PacketSize and should not be required. + +You can pass that information to GDB with these commands: + +@example +set remote hardware-breakpoint-limit 6 +set remote hardware-watchpoint-limit 4 +@end example + +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