X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=77a0ad3b73f7ea19eb7073b7f28f8a1f6d258705;hp=83a6369cf8f30e4d892d0d7b4933f0f8ecd7cc66;hb=50d5441e2a615fb2c44b41a777e4373901f7a2e6;hpb=d37ed9094a62ec144b9d9fdc214d8c7723caadec diff --git a/doc/openocd.texi b/doc/openocd.texi index 83a6369cf8..77a0ad3b73 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -21,7 +21,7 @@ of the Open On-Chip Debugger (OpenOCD). @itemize @bullet @item Copyright @copyright{} 2008 The OpenOCD Project @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-2010 Oyvind Harboe @email{oyvind.harboe@@zylin.com} @item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com} @item Copyright @copyright{} 2009-2010 David Brownell @end itemize @@ -332,7 +332,7 @@ and one can be used for a UART adapter at the same time the other one is used to provide a debug adapter. Also, some development boards integrate an FT2232 chip to serve as -a built-in low coast debug adapter and usb-to-serial solution. +a built-in low cost debug adapter and usb-to-serial solution. @itemize @bullet @item @b{usbjtag} @@ -537,7 +537,7 @@ command interpreter today is a mixture of (newer) JIM-Tcl commands, and (older) the orginal command interpreter. @item @b{Commands} -@* At the OpenOCD telnet command line (or via the GDB mon command) one +@* At the OpenOCD telnet command line (or via the GDB monitor command) one can type a Tcl for() loop, set variables, etc. Some of the commands documented in this guide are implemented as Tcl scripts, from a @file{startup.tcl} file internal to the server. @@ -574,7 +574,6 @@ bash$ openocd --help --debug | -d set debug level <0-3> --log_output | -l redirect log output to file --command | -c run ---pipe | -p use pipes when talking to gdb @end verbatim If you don't give any @option{-f} or @option{-c} options, @@ -2093,12 +2092,20 @@ target. @end deffn @deffn Command {interface_list} -List the interface drivers that have been built into +List the debug adapter drivers that have been built into the running copy of OpenOCD. @end deffn +@deffn Command {interface transports} transport_name+ +Specifies the transports supported by this debug adapter. +The adapter driver builds-in similar knowledge; use this only +when external configuration (such as jumpering) changes what +the hardware can support. +@end deffn + + -@deffn Command {jtag interface} -Returns the name of the interface driver being used. +@deffn Command {adapter_name} +Returns the name of the debug adapter driver being used. @end deffn @section Interface Drivers @@ -2251,11 +2258,11 @@ 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 +usb_blaster_vid_pid 0x09FB 0x6001 @end example The following VID/PID is for Kolja Waschk's USB JTAG: @example -ft2232_vid_pid 0x16C0 0x06AD +usb_blaster_vid_pid 0x16C0 0x06AD @end example @end deffn @@ -2417,6 +2424,7 @@ which are not currently documented here. @deffn {Interface Driver} {ZY1000} This is the Zylin ZY1000 JTAG debugger. +@end deffn @quotation Note This defines some driver-specific commands, @@ -2428,7 +2436,41 @@ Turn power switch to target on/off. No arguments: print status. @end deffn -@end deffn +@section Transport Configuration +As noted earlier, depending on the version of OpenOCD you use, +and the debug adapter you are using, +several transports may be available to +communicate with debug targets (or perhaps to program flash memory). +@deffn Command {transport list} +displays the names of the transports supported by this +version of OpenOCD. +@end deffn + +@deffn Command {transport select} transport_name +Select which of the supported transports to use in this OpenOCD session. +The transport must be supported by the debug adapter hardware and by the +version of OPenOCD you are using (including the adapter's driver). +No arguments: returns name of session's selected transport. +@end deffn + +@subsection JTAG Transport +JTAG is the original transport supported by OpenOCD, and most +of the OpenOCD commands support it. +JTAG transports expose a chain of one or more Test Access Points (TAPs), +each of which must be explicitly declared. +JTAG supports both debugging and boundary scan testing. +Flash programming support is built on top of debug support. +@subsection SWD Transport +SWD (Serial Wire Debug) is an ARM-specific transport which exposes one +Debug Access Point (DAP, which must be explicitly declared. +(SWD uses fewer signal wires than JTAG.) +SWD is debug-oriented, and does not support boundary scan testing. +Flash programming support is built on top of debug support. +(Some processors support both JTAG and SWD.) +@subsection SPI Transport +The Serial Peripheral Interface (SPI) is a general purpose transport +which uses four wire signaling. Some processors use it as part of a +solution for flash programming. @anchor{JTAG Speed} @section JTAG Speed @@ -3432,7 +3474,7 @@ At this writing, the supported CPU types and variants are: @item @code{arm11} -- this is a generation of ARMv6 cores @item @code{arm720t} -- this is an ARMv4 core with an MMU @item @code{arm7tdmi} -- this is an ARMv4 core -@item @code{arm920t} -- this is an ARMv5 core with an MMU +@item @code{arm920t} -- this is an ARMv4 core with an MMU @item @code{arm926ejs} -- this is an ARMv5 core with an MMU @item @code{arm966e} -- this is an ARMv5 core @item @code{arm9tdmi} -- this is an ARMv4 core @@ -3784,7 +3826,8 @@ proc my_attach_proc @{ @} @{ mychip.cpu configure -event gdb-attach my_attach_proc mychip.cpu configure -event gdb-attach @{ echo "Reset..." - reset halt + # To make flash probe and gdb load to flash work we need a reset init. + reset init @} @end example @@ -3804,7 +3847,11 @@ The following target events are defined: @* Currently not used (goal: when JTAG examine starts) @end ignore @item @b{gdb-attach} -@* When GDB connects +@* When GDB connects. This is before any communication with the target, so this +can be used to set up the target so it is possible to probe flash. Probing flash +is necessary during gdb connect if gdb load is to write the image to flash. Another +use of the flash memory map is for GDB to automatically hardware/software breakpoints +depending on whether the breakpoint is in RAM or read only memory. @item @b{gdb-detach} @* When GDB disconnects @item @b{gdb-end} @@ -4038,7 +4085,7 @@ 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} [@option{pad}] address length +@deffn Command {flash erase_address} [@option{pad}] [@option{unlock}] 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. @@ -4048,6 +4095,8 @@ 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 the start of the bank, the whole flash is erased. +If @option{unlock} is specified, then the flash is unprotected +before erase starts. @end deffn @deffn Command {flash fillw} address word length @@ -4122,9 +4171,8 @@ The @var{num} parameter is a value shown by @command{flash banks}. @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, which may be -incorrect (outdated) unless you first issue a -@command{flash protect_check num} command. +This command will first query the hardware, it does not print cached +and possibly stale information. @end deffn @anchor{flash protect} @@ -4137,14 +4185,6 @@ 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 protect_check} num -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} @section Flash Driver List As noted above, the @command{flash bank} command requires a driver name, @@ -4674,6 +4714,26 @@ the flash clock. @end deffn @end deffn +@deffn {Flash Driver} virtual +This is a special driver that maps a previously defined bank to another +address. All bank settings will be copied from the master physical bank. + +The @var{virtual} driver defines one mandatory parameters, + +@itemize +@item @var{master_bank} The bank that this virtual address refers to. +@end itemize + +So in the following example addresses 0xbfc00000 and 0x9fc00000 refer to +the flash bank defined at address 0x1fc00000. Any cmds executed on +the virtual banks are actually performed on the physical banks. +@example +flash bank $_FLASHNAME pic32mx 0x1fc00000 0 0 0 $_TARGETNAME +flash bank vbank0 virtual 0xbfc00000 0 0 0 $_TARGETNAME $_FLASHNAME +flash bank vbank1 virtual 0x9fc00000 0 0 0 $_TARGETNAME $_FLASHNAME +@end example +@end deffn + @subsection str9xpec driver @cindex str9xpec @@ -5099,7 +5159,7 @@ be removed in a future release. @section Other NAND commands @cindex NAND other commands -@deffn Command {nand check_bad_blocks} [offset length] +@deffn Command {nand check_bad_blocks} num [offset length] Checks for manufacturer bad block markers on the specified NAND device. If no parameters are provided, checks the whole device; otherwise, starts at the specified @var{offset} and @@ -5369,25 +5429,6 @@ file (which is normally the server's standard output). @xref{Running}. @end deffn -@deffn Command fast (@option{enable}|@option{disable}) -Default disabled. -Set default behaviour of OpenOCD to be "fast and dangerous". - -At this writing, this only affects the defaults for two ARM7/ARM9 parameters: -fast memory access, and DCC downloads. Those parameters may still be -individually overridden. - -The target specific "dangerous" optimisation tweaking options may come and go -as more robust and user friendly ways are found to ensure maximum throughput -and robustness with a minimum of configuration. - -Typically the "fast enable" is specified first on the command line: - -@example -openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg -@end example -@end deffn - @deffn Command echo message Logs a message at "user" priority. Output @var{message} to stdout. @@ -5666,10 +5707,20 @@ separately. @end deffn @anchor{load_image} -@deffn Command {load_image} filename address [@option{bin}|@option{ihex}|@option{elf}] -Load image from file @var{filename} to target memory at @var{address}. +@deffn Command {load_image} filename address [[@option{bin}|@option{ihex}|@option{elf}] @option{min_addr} @option{max_length}] +Load image from file @var{filename} to target memory offset by @var{address} from its load address. The file format may optionally be specified -(@option{bin}, @option{ihex}, or @option{elf}) +(@option{bin}, @option{ihex}, or @option{elf}). +In addition the following arguments may be specifed: +@var{min_addr} - ignore data below @var{min_addr} (this is w.r.t. to the target's load address + @var{address}) +@var{max_length} - maximum number of bytes to load. +@example +proc load_image_bin @{fname foffset address length @} @{ + # Load data from fname filename at foffset offset to + # target at address. Load at most length bytes. + load_image $fname [expr $address - $foffset] bin $address $length +@} +@end example @end deffn @deffn Command {test_image} filename [address [@option{bin}|@option{ihex}|@option{elf}]] @@ -6285,10 +6336,10 @@ handler. However, this means that the complete first cacheline in the mini-IC is marked valid, which makes the CPU fetch all exception handlers from the mini-IC, ignoring the code in RAM. -OpenOCD currently does not sync the mini-IC entries with the RAM -contents (which would fail anyway while the target is running), so -the user must provide appropriate values using the @code{xscale -vector_table} command. +To address this situation, OpenOCD provides the @code{xscale +vector_table} command, which allows the user to explicity write +individual entries to either the high or low vector table stored in +the mini-IC. It is recommended to place a pc-relative indirect branch in the vector table, and put the branch destination somewhere in memory. Doing so @@ -6315,11 +6366,38 @@ _vectors: .long real_fiq_handler @end example +Alternatively, you may choose to keep some or all of the mini-IC +vector table entries synced with those written to memory by your +system software. The mini-IC can not be modified while the processor +is executing, but for each vector table entry not previously defined +using the @code{xscale vector_table} command, OpenOCD will copy the +value from memory to the mini-IC every time execution resumes from a +halt. This is done for both high and low vector tables (although the +table not in use may not be mapped to valid memory, and in this case +that copy operation will silently fail). This means that you will +need to briefly halt execution at some strategic point during system +start-up; e.g., after the software has initialized the vector table, +but before exceptions are enabled. A breakpoint can be used to +accomplish this once the appropriate location in the start-up code has +been identified. A watchpoint over the vector table region is helpful +in finding the location if you're not sure. Note that the same +situation exists any time the vector table is modified by the system +software. + The debug handler must be placed somewhere in the address space using the @code{xscale debug_handler} command. The allowed locations for the debug handler are either (0x800 - 0x1fef800) or (0xfe000800 - 0xfffff800). The default value is 0xfe000800. +XScale has resources to support two hardware breakpoints and two +watchpoints. However, the following restrictions on watchpoint +functionality apply: (1) the value and mask arguments to the @code{wp} +command are not supported, (2) the watchpoint length must be a +power of two and not less than four, and can not be greater than the +watchpoint address, and (3) a watchpoint with a length greater than +four consumes all the watchpoint hardware resources. This means that +at any one time, you can have enabled either two watchpoints with a +length of four, or one watchpoint with a length greater than four. These commands are available to XScale based CPUs, which are implementations of the ARMv5TE architecture. @@ -6522,6 +6600,21 @@ must also be explicitly enabled. This finishes by listing the current vector catch configuration. @end deffn +@deffn Command {cortex_m3 reset_config} (@option{srst}|@option{sysresetreq}|@option{vectreset}) +Control reset handling. The default @option{srst} is to use srst if fitted, +otherwise fallback to @option{vectreset}. +@itemize @minus +@item @option{srst} use hardware srst if fitted otherwise fallback to @option{vectreset}. +@item @option{sysresetreq} use NVIC SYSRESETREQ to reset system. +@item @option{vectreset} use NVIC VECTRESET to reset system. +@end itemize +Using @option{vectreset} is a safe option for all current Cortex-M3 cores. +This however has the disadvantage of only resetting the core, all peripherals +are uneffected. A solution would be to use a @code{reset-init} event handler to manually reset +the peripherals. +@xref{Target Events}. +@end deffn + @anchor{Software Debug Messages and Tracing} @section Software Debug Messages and Tracing @cindex Linux-ARM DCC support @@ -6958,11 +7051,12 @@ This would cause GDB to connect to the gdbserver on the local pc using port 3333 @item A pipe connection is typically started as follows: @example -target remote | openocd --pipe +target remote | openocd -c "gdb_port pipe; log_output openocd.log" @end example This would cause GDB to run OpenOCD and communicate using pipes (stdin/stdout). Using this method has the advantage of GDB starting/stopping OpenOCD for the debug -session. +session. log_output sends the log output to a file to ensure that the pipe is +not saturated when using higher debug level outputs. @end enumerate To list the available OpenOCD commands type @command{monitor help} on the @@ -7139,10 +7233,10 @@ Low-level commands are (should be) prefixed with "ocd_", e.g. is the low level API upon which @command{flash banks} is implemented. @itemize @bullet -@item @b{ocd_mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}> +@item @b{mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}> Read memory and return as a Tcl array for script processing -@item @b{ocd_array2mem} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}> +@item @b{array2mem} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}> Convert a Tcl array to memory locations and write the values @item @b{ocd_flash_banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...]