X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=2e0143edff4db78b7af7e91cf1ff938c08cd6621;hp=154ecbcaec5e7ddc850b31bbe7d59e1e9d0ea311;hb=c1cb20971ea89e4602bb23ba66180d647880bbef;hpb=155a6a2c0bacdd4752e944ffd579d441361883db diff --git a/doc/openocd.texi b/doc/openocd.texi index 154ecbcaec..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} @@ -1619,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, @@ -1962,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) @@ -2480,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). @@ -3745,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 @@ -4902,28 +4923,28 @@ 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 +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} +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} +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 +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} +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} +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 @@ -5077,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}] @@ -5812,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. @@ -5831,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. @@ -5844,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 @@ -5888,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 @@ -5941,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 @@ -5985,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 @@ -6060,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 @@ -6068,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]] @@ -6110,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 @@ -6129,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] @@ -6175,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