X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=4f228325c122c33a35cf1f7ec0bb8dccf1e45a55;hb=2783cba8106a86bd81635b509ccb5edb0ebd3d29;hp=bf80e123a421e69afcb84586c5972734208ff414;hpb=bc13c12be96fab35cb2f25df4f37c283cca70b98;p=fw%2Fopenocd diff --git a/doc/openocd.texi b/doc/openocd.texi index bf80e123a..4f228325c 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -66,7 +66,6 @@ Free Documentation License''. * Running:: Running OpenOCD * OpenOCD Project Setup:: OpenOCD Project Setup * Config File Guidelines:: Config File Guidelines -* Translating Configuration Files:: Translating Configuration Files * Daemon Configuration:: Daemon Configuration * Interface - Dongle Configuration:: Interface - Dongle Configuration * Reset Configuration:: Reset Configuration @@ -1186,7 +1185,9 @@ handlers too, if just for developer convenience. Because this is so very board-specific, and chip-specific, no examples are included here. Instead, look at the board config files distributed with OpenOCD. -If you have a boot loader, its source code may also be useful. +If you have a boot loader, its source code will help; so will +configuration files for other JTAG tools +(@pxref{Translating Configuration Files}). @end quotation Some of this code could probably be shared between different boards. @@ -1464,17 +1465,18 @@ Examples: @item pxa270 - again - CS0 flash - it goes in the board file. @end itemize -@node Translating Configuration Files -@chapter Translating Configuration Files +@anchor{Translating Configuration Files} +@section Translating Configuration Files @cindex translation -If you have a configuration file for another hardware debugger(Abatron, -BDI2000, BDI3000, Lauterbach, Segger, MacRaigor, etc.), translating +If you have a configuration file for another hardware debugger +or toolset (Abatron, BDI2000, BDI3000, CCS, +Lauterbach, Segger, Macraigor, etc.), translating it into OpenOCD syntax is often quite straightforward. The most tricky part of creating a configuration script is oftentimes the reset init sequence where e.g. PLLs, DRAM and the like is set up. One trick that you can use when translating is to write small -Tcl proc's to translate the syntax into OpenOCD syntax. This +Tcl procedures to translate the syntax into OpenOCD syntax. This can avoid manual translation errors and make it easier to convert other scripts later on. @@ -1482,23 +1484,22 @@ Example of transforming quirky arguments to a simple search and replace job: @example -# rewrite commands of the form below to arm11 mcr... -# # Lauterbach syntax(?) # -# Data.Set c15:0x042f %long 0x40000015 +# Data.Set c15:0x042f %long 0x40000015 # # OpenOCD syntax when using procedure below. # -# setc15 0x01 0x00050078 -# -# +# setc15 0x01 0x00050078 + proc setc15 @{regs value@} @{ - global TARGETNAME + global TARGETNAME - echo [format "set p15 0x%04x, 0x%08x" $regs $value] + echo [format "set p15 0x%04x, 0x%08x" $regs $value] - arm11 mcr $TARGETNAME 15 [expr ($regs>>12)&0x7] [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] [expr ($regs>>8)&0x7] $value + arm11 mcr $TARGETNAME 15 [expr ($regs>>12)&0x7] \ + [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] \ + [expr ($regs>>8)&0x7] $value @} @end example @@ -1572,6 +1573,11 @@ which uses only a lightweight JTAG reset before examining the scan chain. If that fails, it tries again, using a harder reset from the overridable procedure @command{init_reset}. + +Implementations must have verified the JTAG scan chain before +they return. +This is done by calling @command{jtag arp_init} +(or @command{jtag arp_init-reset}). @end deffn @anchor{TCP/IP Ports} @@ -1637,11 +1643,6 @@ GDB behaviour is not sufficient. GDB normally uses hardware breakpoints if the memory map has been set up for flash regions. @end deffn -@deffn {Config Command} gdb_detach (@option{resume}|@option{reset}|@option{halt}|@option{nothing}) -Configures what OpenOCD will do when GDB detaches from the daemon. -Default behaviour is @option{resume}. -@end deffn - @anchor{gdb_flash_program} @deffn {Config Command} gdb_flash_program (@option{enable}|@option{disable}) Set to @option{enable} to cause OpenOCD to program the flash memory when a @@ -2225,6 +2226,12 @@ needing to cope with both architecture and board specific constraints. @section Commands for Handling Resets +@deffn {Command} jtag_nsrst_assert_width milliseconds +Minimum amount of time (in milliseconds) OpenOCD should wait +after asserting nSRST (active-low system reset) before +allowing it to be deasserted. +@end deffn + @deffn {Command} jtag_nsrst_delay milliseconds How long (in milliseconds) OpenOCD should wait after deasserting nSRST (active-low system reset) before starting new JTAG operations. @@ -2232,6 +2239,12 @@ When a board has a reset button connected to SRST line it will probably have hardware debouncing, implying you should use this. @end deffn +@deffn {Command} jtag_ntrst_assert_width milliseconds +Minimum amount of time (in milliseconds) OpenOCD should wait +after asserting nTRST (active-low JTAG TAP reset) before +allowing it to be deasserted. +@end deffn + @deffn {Command} jtag_ntrst_delay milliseconds How long (in milliseconds) OpenOCD should wait after deasserting nTRST (active-low JTAG TAP reset) before starting new JTAG operations. @@ -2322,6 +2335,7 @@ powerup and pressing a reset button. @end deffn @section Custom Reset Handling +@cindex events OpenOCD has several ways to help support the various reset mechanisms provided by chip and board vendors. @@ -3523,7 +3537,7 @@ The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @anchor{flash write_image} -@deffn Command {flash write_image} [erase] filename [offset] [type] +@deffn Command {flash write_image} [erase] [unlock] filename [offset] [type] Write the image @file{filename} to the current target's flash bank(s). A relocation @var{offset} may be specified, in which case it is added to the base address for each section in the image. @@ -3532,8 +3546,9 @@ explicitly as @option{bin} (binary), @option{ihex} (Intel hex), @option{elf} (ELF file), @option{s19} (Motorola s19). @option{mem}, or @option{builder}. The relevant flash sectors will be erased prior to programming -if the @option{erase} parameter is given. -The flash bank to use is inferred from the @var{address} of +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. @end deffn @@ -4923,23 +4938,27 @@ Please use their TARGET object siblings to avoid making assumptions about what TAP is the current target, or about MMU configuration. @end enumerate -@deffn Command mdw addr [count] -@deffnx Command mdh addr [count] -@deffnx Command mdb addr [count] +@deffn Command mdw [phys] addr [count] +@deffnx Command mdh [phys] addr [count] +@deffnx Command mdb [phys] addr [count] Display contents of address @var{addr}, as 32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}), or 8-bit bytes (@command{mdb}). If @var{count} is specified, displays that many units. +@var{phys} is an optional flag to indicate to use +physical address and bypass MMU (If you want to manipulate the data instead of displaying it, see the @code{mem2array} primitives.) @end deffn -@deffn Command mww addr word -@deffnx Command mwh addr halfword -@deffnx Command mwb addr byte +@deffn Command mww [phys] addr word +@deffnx Command mwh [phys] addr halfword +@deffnx Command mwb [phys] addr byte Writes the specified @var{word} (32 bits), @var{halfword} (16 bits), or @var{byte} (8-bit) pattern, at the specified address @var{addr}. +@var{phys} is an optional flag to indicate to use +physical address and bypass MMU @end deffn @@ -5735,7 +5754,11 @@ one bit in the encoding, effecively a fifth parameter.) @deffn Command {arm11 memwrite burst} [value] Displays the value of the memwrite burst-enable flag, -which is enabled by default. +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. @end deffn @@ -5754,13 +5777,6 @@ one bit in the encoding, effecively a fifth parameter.) Displays the result. @end deffn -@deffn Command {arm11 no_increment} [value] -Displays the value of the flag controlling whether -some read or write operations increment the pointer -(the default behavior) or not (acting like a FIFO). -If @var{value} is defined, first assigns that. -@end deffn - @deffn Command {arm11 step_irq_enable} [value] Displays the value of the flag controlling whether IRQs are enabled during single stepping; @@ -6081,6 +6097,17 @@ TAP @code{post-reset} events are delivered to all TAPs with handlers for that event. @end deffn +@deffn Command {pathmove} start_state [next_state ...] +Start by moving to @var{start_state}, which +must be one of the @emph{stable} states. +Unless it is the only state given, this will often be the +current state, so that no TCK transitions are needed. +Then, in a series of single state transitions +(conforming to the JTAG state machine) shift to +each @var{next_state} in sequence, one per TCK cycle. +The final state must also be stable. +@end deffn + @deffn Command {runtest} @var{num_cycles} Move to the @sc{run/idle} state, and execute at least @var{num_cycles} of the JTAG clock (TCK). @@ -6108,23 +6135,30 @@ Default is enabled. @cindex TAP state names The @var{tap_state} names used by OpenOCD in the @command{drscan}, -and @command{irscan} commands are: +@command{irscan}, and @command{pathmove} commands are the same +as those used in SVF boundary scan documents, except that +SVF uses @sc{idle} instead of @sc{run/idle}. @itemize @bullet -@item @b{RESET} ... acts as if TRST were pulsed -@item @b{RUN/IDLE} ... don't assume this always means IDLE +@item @b{RESET} ... @emph{stable} (with TMS high); +acts as if TRST were pulsed +@item @b{RUN/IDLE} ... @emph{stable}; don't assume this always means IDLE @item @b{DRSELECT} @item @b{DRCAPTURE} -@item @b{DRSHIFT} ... TDI/TDO shifting through the data register +@item @b{DRSHIFT} ... @emph{stable}; TDI/TDO shifting +through the data register @item @b{DREXIT1} -@item @b{DRPAUSE} ... data register ready for update or more shifting +@item @b{DRPAUSE} ... @emph{stable}; data register ready +for update or more shifting @item @b{DREXIT2} @item @b{DRUPDATE} @item @b{IRSELECT} @item @b{IRCAPTURE} -@item @b{IRSHIFT} ... TDI/TDO shifting through the instruction register +@item @b{IRSHIFT} ... @emph{stable}; TDI/TDO shifting +through the instruction register @item @b{IREXIT1} -@item @b{IRPAUSE} ... instruction register ready for update or more shifting +@item @b{IRPAUSE} ... @emph{stable}; instruction register ready +for update or more shifting @item @b{IREXIT2} @item @b{IRUPDATE} @end itemize @@ -6194,6 +6228,27 @@ Unless the @option{quiet} option is specified, messages are logged for comments and some retries. @end deffn +The OpenOCD sources also include two utility scripts +for working with XSVF; they are not currently installed +after building the software. +You may find them useful: + +@itemize +@item @emph{svf2xsvf} ... converts SVF files into the extended XSVF +syntax understood by the @command{xsvf} command; see notes below. +@item @emph{xsvfdump} ... converts XSVF files into a text output format; +understands the OpenOCD extensions. +@end itemize + +The input format accepts a handful of non-standard extensions. +These include three opcodes corresponding to SVF extensions +from Lattice Semiconductor (LCOUNT, LDELAY, LDSR), and +two opcodes supporting a more accurate translation of SVF +(XTRST, XWAITSTATE). +If @emph{xsvfdump} shows a file is using those opcodes, it +probably will not be usable with other XSVF tools. + + @node TFTP @chapter TFTP @cindex TFTP