X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=500faf9a590dd05c147ff1c610c2c5db5b33dd60;hp=8156de4d19b092da9ebe54b223e1cfeb755bb59c;hb=7556a93aed97c3fad2c0a904a115168cd3dd61a8;hpb=7c7467b34f11939fbce41e39dfa1b6b0e110a89c diff --git a/doc/openocd.texi b/doc/openocd.texi index 8156de4d19..500faf9a59 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -82,7 +82,6 @@ Free Documentation License''. * GDB and OpenOCD:: Using GDB and OpenOCD * Tcl Scripting API:: Tcl Scripting API * Upgrading:: Deprecated/Removed Commands -* Target Library:: Target Library * FAQ:: Frequently Asked Questions * Tcl Crash Course:: Tcl Crash Course * License:: GNU Free Documentation License @@ -171,38 +170,38 @@ documentation, as well as more conventional bug fixes and enhancements. The resources in this chapter are available for developers wishing to explore or expand the OpenOCD source code. -@section OpenOCD Subversion Repository +@section OpenOCD GIT Repository -You can download the current SVN version with an SVN client of your -choice from the following repositories: +During the 0.3.x release cycle, OpenOCD switched from Subversion to +a GIT repository hosted at SourceForge. The repository URL is: - @uref{svn://svn.berlios.de/openocd/trunk} +@uref{git://openocd.git.sourceforge.net/gitroot/openocd/openocd} -or +You may prefer to use a mirror and the HTTP protocol: - @uref{http://svn.berlios.de/svnroot/repos/openocd/trunk} +@uref{http://repo.or.cz/r/openocd.git} -Using the SVN command line client, you can use the following command to -fetch the latest version (make sure there is no (non-svn) directory -called "openocd" in the current directory): +With standard GIT tools, use @command{git clone} to initialize +a local repository, and @command{git pull} to update it. +There are also gitweb pages letting you browse the repository +with a web browser, or download arbitrary snapshots without +needing a GIT client: - svn checkout svn://svn.berlios.de/openocd/trunk openocd +@uref{http://openocd.git.sourceforge.net/git/gitweb.cgi?p=openocd/openocd} -If you prefer GIT based tools, the @command{git-svn} package works too: +@uref{http://repo.or.cz/w/openocd.git} - git svn clone -s svn://svn.berlios.de/openocd - -The ``README'' file contains the instructions for building the project -from the repository. +The @file{README} file contains the instructions for building the project +from the repository or a snapshot. Developers that want to contribute patches to the OpenOCD system are -@b{strongly} encouraged to base their work off of the most recent trunk -revision. Patches created against older versions may require additional +@b{strongly} encouraged to work against mainline. +Patches created against older versions may require additional work from their submitter in order to be updated for newer releases. @section Doxygen Developer Manual -During the development of the 0.2.0 release, the OpenOCD project began +During the 0.2.x release cycle, the OpenOCD project began providing a Doxygen reference manual. This document contains more technical information about the software internals, development processes, and similar documentation: @@ -211,7 +210,7 @@ processes, and similar documentation: This document is a work-in-progress, but contributions would be welcome to fill in the gaps. All of the source files are provided in-tree, -listed in the Doxyfile configuration in the top of the repository trunk. +listed in the Doxyfile configuration in the top of the source tree. @section OpenOCD Developer Mailing List @@ -220,10 +219,9 @@ communication between developers: @uref{https://lists.berlios.de/mailman/listinfo/openocd-development} -All drivers developers are enouraged to also subscribe to the list of -SVN commits to keep pace with the ongoing changes: - -@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn} +Discuss and submit patches to this list. +The @file{PATCHES} file contains basic information about how +to prepare patches. @node JTAG Hardware Dongles @@ -670,6 +668,14 @@ each supporting a different development task. One might re-flash the board with a specific firmware version. Another might set up a particular debugging or run-time environment. +@quotation Important +At this writing (October 2009) the command line method has +problems with how it treats variables. +For example, after @option{-c "set VAR value"}, or doing the +same in a script, the variable @var{VAR} will have no value +that can be tested in a later script. +@end quotation + Here we will focus on the simpler solution: one user config file, including basic configuration plus any TCL procedures to simplify your work. @@ -902,19 +908,68 @@ including developers and integrators of OpenOCD and any user who needs to get a new board working smoothly. It provides guidelines for creating those files. -You should find the following directories under @t{$(INSTALLDIR)/scripts}: - +You should find the following directories under @t{$(INSTALLDIR)/scripts}, +with files including the ones listed here. +Use them as-is where you can; or as models for new files. @itemize @bullet @item @file{interface} ... think JTAG Dongle. Files that configure JTAG adapters go here. +@example +$ ls interface +arm-jtag-ew.cfg hitex_str9-comstick.cfg oocdlink.cfg +arm-usb-ocd.cfg icebear.cfg openocd-usb.cfg +at91rm9200.cfg jlink.cfg parport.cfg +axm0432.cfg jtagkey2.cfg parport_dlc5.cfg +calao-usb-a9260-c01.cfg jtagkey.cfg rlink.cfg +calao-usb-a9260-c02.cfg jtagkey-tiny.cfg sheevaplug.cfg +calao-usb-a9260.cfg luminary.cfg signalyzer.cfg +chameleon.cfg luminary-icdi.cfg stm32-stick.cfg +cortino.cfg luminary-lm3s811.cfg turtelizer2.cfg +dummy.cfg olimex-arm-usb-ocd.cfg usbprog.cfg +flyswatter.cfg olimex-jtag-tiny.cfg vsllink.cfg +$ +@end example @item @file{board} ... think Circuit Board, PWA, PCB, they go by many names. Board files -contain initialization items that are specific to a board. For +contain initialization items that are specific to a board. +They reuse target configuration files, since the same +microprocessor chips are used on many boards, +but support for external parts varies widely. For example, the SDRAM initialization sequence for the board, or the type of external flash and what address it uses. Any initialization sequence to enable that external flash or SDRAM should be found in the board file. Boards may also contain multiple targets: two CPUs; or -a CPU and an FPGA or CPLD. +a CPU and an FPGA. +@example +$ ls board +arm_evaluator7t.cfg keil_mcb1700.cfg +at91rm9200-dk.cfg keil_mcb2140.cfg +at91sam9g20-ek.cfg linksys_nslu2.cfg +atmel_at91sam7s-ek.cfg logicpd_imx27.cfg +atmel_at91sam9260-ek.cfg mini2440.cfg +atmel_sam3u_ek.cfg olimex_LPC2378STK.cfg +crossbow_tech_imote2.cfg olimex_lpc_h2148.cfg +csb337.cfg olimex_sam7_ex256.cfg +csb732.cfg olimex_sam9_l9260.cfg +digi_connectcore_wi-9c.cfg olimex_stm32_h103.cfg +dm355evm.cfg omap2420_h4.cfg +dm365evm.cfg osk5912.cfg +dm6446evm.cfg pic-p32mx.cfg +eir.cfg propox_mmnet1001.cfg +ek-lm3s1968.cfg pxa255_sst.cfg +ek-lm3s3748.cfg sheevaplug.cfg +ek-lm3s811.cfg stm3210e_eval.cfg +ek-lm3s9b9x.cfg stm32f10x_128k_eval.cfg +hammer.cfg str910-eval.cfg +hitex_lpc2929.cfg telo.cfg +hitex_stm32-performancestick.cfg ti_beagleboard.cfg +hitex_str9-comstick.cfg topas910.cfg +iar_str912_sk.cfg topasa900.cfg +imx27ads.cfg unknown_at91sam9260.cfg +imx27lnst.cfg x300t.cfg +imx31pdk.cfg zy1000.cfg +$ +@end example @item @file{target} ... think chip. The ``target'' directory represents the JTAG TAPs on a chip @@ -922,6 +977,37 @@ which OpenOCD should control, not a board. Two common types of targets are ARM chips and FPGA or CPLD chips. When a chip has multiple TAPs (maybe it has both ARM and DSP cores), the target config file defines all of them. +@example +$ ls target +aduc702x.cfg imx27.cfg pxa255.cfg +ar71xx.cfg imx31.cfg pxa270.cfg +at91eb40a.cfg imx35.cfg readme.txt +at91r40008.cfg is5114.cfg sam7se512.cfg +at91rm9200.cfg ixp42x.cfg sam7x256.cfg +at91sam3u1c.cfg lm3s1968.cfg samsung_s3c2410.cfg +at91sam3u1e.cfg lm3s3748.cfg samsung_s3c2440.cfg +at91sam3u2c.cfg lm3s6965.cfg samsung_s3c2450.cfg +at91sam3u2e.cfg lm3s811.cfg samsung_s3c4510.cfg +at91sam3u4c.cfg lm3s9b9x.cfg samsung_s3c6410.cfg +at91sam3u4e.cfg lpc1768.cfg sharp_lh79532.cfg +at91sam3uXX.cfg lpc2103.cfg smdk6410.cfg +at91sam7sx.cfg lpc2124.cfg smp8634.cfg +at91sam9260.cfg lpc2129.cfg stm32.cfg +c100.cfg lpc2148.cfg str710.cfg +c100config.tcl lpc2294.cfg str730.cfg +c100helper.tcl lpc2378.cfg str750.cfg +c100regs.tcl lpc2478.cfg str912.cfg +cs351x.cfg lpc2900.cfg telo.cfg +davinci.cfg mega128.cfg ti_dm355.cfg +dragonite.cfg netx500.cfg ti_dm365.cfg +epc9301.cfg omap2420.cfg ti_dm6446.cfg +feroceon.cfg omap3530.cfg tmpa900.cfg +icepick.cfg omap5912.cfg tmpa910.cfg +imx21.cfg pic32mx.cfg xba_revA3.cfg +$ +@end example +@item @emph{more} ... browse for other library files which may be useful. +For example, there are various generic and CPU-specific utilities. @end itemize The @file{openocd.cfg} user config @@ -1099,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. @@ -1377,6 +1465,46 @@ Examples: @item pxa270 - again - CS0 flash - it goes in the board file. @end itemize +@anchor{Translating Configuration Files} +@section Translating Configuration Files +@cindex translation +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 procedures to translate the syntax into OpenOCD syntax. This +can avoid manual translation errors and make it easier to +convert other scripts later on. + +Example of transforming quirky arguments to a simple search and +replace job: + +@example +# Lauterbach syntax(?) +# +# Data.Set c15:0x042f %long 0x40000015 +# +# OpenOCD syntax when using procedure below. +# +# setc15 0x01 0x00050078 + +proc setc15 @{regs value@} @{ + global TARGETNAME + + 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 +@} +@end example + + + @node Daemon Configuration @chapter Daemon Configuration @cindex initialization @@ -1436,6 +1564,22 @@ read/write memory on your target, @command{init} must occur before the memory read/write commands. This includes @command{nand probe}. @end deffn +@deffn {Overridable Procedure} jtag_init +This is invoked at server startup to verify that it can talk +to the scan chain (list of TAPs) which has been configured. + +The default implementation first tries @command{jtag arp_init}, +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} @section TCP/IP Ports @cindex TCP port @@ -1499,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 @@ -2065,8 +2204,9 @@ issues (not limited to errata). For example, certain JTAG commands might need to be issued while the system as a whole is in a reset state (SRST active) but the JTAG scan chain is usable (TRST inactive). -(@xref{JTAG Commands}, where the @command{jtag_reset} -command is presented.) +Many systems treat combined assertion of SRST and TRST as a +trigger for a harder reset than SRST alone. +Such custom reset handling is discussed later in this chapter. @end itemize There can also be other issues. @@ -2086,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. @@ -2093,13 +2239,19 @@ 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. @end deffn @deffn {Command} reset_config mode_flag ... -This command tells OpenOCD the reset configuration +This command displays or modifies the reset configuration of your combination of JTAG board and target in target configuration scripts. @@ -2113,7 +2265,9 @@ from a particular combination of interface and board. with a board that only wires up SRST.) The @var{mode_flag} options can be specified in any order, but only one -of each type -- @var{signals}, @var{combination}, @var{trst_type}, +of each type -- @var{signals}, @var{combination}, +@var{gates}, +@var{trst_type}, and @var{srst_type} -- may be specified at a time. If you don't provide a new value for a given type, its previous value (perhaps the default) is unchanged. @@ -2121,6 +2275,8 @@ For example, this means that you don't need to say anything at all about TRST just to declare that if the JTAG adapter should want to drive SRST, it must explicitly be driven high (@option{srst_push_pull}). +@itemize +@item @var{signals} can specify which of the reset signals are connected. For example, If the JTAG interface provides SRST, but the board doesn't connect that signal properly, then OpenOCD can't use it. @@ -2128,10 +2284,11 @@ Possible values are @option{none} (the default), @option{trst_only}, @option{srst_only} and @option{trst_and_srst}. @quotation Tip -If your board provides SRST or TRST through the JTAG connector, -you must declare that or else those signals will not be used. +If your board provides SRST and/or TRST through the JTAG connector, +you must declare that so those signals can be used. @end quotation +@item The @var{combination} is an optional value specifying broken reset signal implementations. The default behaviour if no option given is @option{separate}, @@ -2144,26 +2301,113 @@ haven't seen hardware with such a bug, and can be worked around). @option{combined} implies both @option{srst_pulls_trst} and @option{trst_pulls_srst}. -@option{srst_gates_jtag} indicates that asserting SRST gates the +@item +The @var{gates} tokens control flags that describe some cases where +JTAG may be unvailable during reset. +@option{srst_gates_jtag} (default) +indicates that asserting SRST gates the JTAG clock. This means that no communication can happen on JTAG while SRST is asserted. +Its converse is @option{srst_nogate}, indicating that JTAG commands +can safely be issued while SRST is active. +@end itemize The optional @var{trst_type} and @var{srst_type} parameters allow the driver mode of each reset line to be specified. These values only affect JTAG interfaces with support for different driver modes, like the Amontec -JTAGkey and JTAGAccelerator. Also, they are necessarily ignored if the +JTAGkey and JTAG Accelerator. Also, they are necessarily ignored if the relevant signal (TRST or SRST) is not connected. +@itemize +@item Possible @var{trst_type} driver modes for the test reset signal (TRST) -are @option{trst_push_pull} (default) and @option{trst_open_drain}. +are the default @option{trst_push_pull}, and @option{trst_open_drain}. Most boards connect this signal to a pulldown, so the JTAG TAPs never leave reset unless they are hooked up to a JTAG adapter. +@item Possible @var{srst_type} driver modes for the system reset signal (SRST) are the default @option{srst_open_drain}, and @option{srst_push_pull}. Most boards connect this signal to a pullup, and allow the signal to be pulled low by various events including system powerup and pressing a reset button. +@end itemize +@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. +The commands shown in the previous section give standard parameters. +There are also @emph{event handlers} associated with TAPs or Targets. +Those handlers are Tcl procedures you can provide, which are invoked +at particular points in the reset sequence. + +After configuring those mechanisms, you might still +find your board doesn't start up or reset correctly. +For example, maybe it needs a slightly different sequence +of SRST and/or TRST manipulations, because of quirks that +the @command{reset_config} mechanism doesn't address; +or asserting both might trigger a stronger reset, which +needs special attention. + +Experiment with lower level operations, such as @command{jtag_reset} +and the @command{jtag arp_*} operations shown here, +to find a sequence of operations that works. +@xref{JTAG Commands}. +When you find a working sequence, it can be used to override +@command{jtag_init}, which fires during OpenOCD startup +(@pxref{Configuration Stage}); +or @command{init_reset}, which fires during reset processing. + +You might also want to provide some project-specific reset +schemes. For example, on a multi-target board the standard +@command{reset} command would reset all targets, but you +may need the ability to reset only one target at time and +thus want to avoid using the board-wide SRST signal. + +@deffn {Overridable Procedure} init_reset mode +This is invoked near the beginning of the @command{reset} command, +usually to provide as much of a cold (power-up) reset as practical. +By default it is also invoked from @command{jtag_init} if +the scan chain does not respond to pure JTAG operations. +The @var{mode} parameter is the parameter given to the +low level reset command (@option{halt}, +@option{init}, or @option{run}), @option{setup}, +or potentially some other value. + +The default implementation just invokes @command{jtag arp_init-reset}. +Replacements will normally build on low level JTAG +operations such as @command{jtag_reset}. +Operations here must not address individual TAPs +(or their associated targets) +until the JTAG scan chain has first been verified to work. + +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 + +@deffn Command {jtag arp_init} +This validates the scan chain using just the four +standard JTAG signals (TMS, TCK, TDI, TDO). +It starts by issuing a JTAG-only reset. +Then it performs checks to verify that the scan chain configuration +matches the TAPs it can observe. +Those checks include checking IDCODE values for each active TAP, +and verifying the length of their instruction registers using +TAP @code{-ircapture} and @code{-irmask} values. +If these tests all pass, TAP @code{setup} events are +issued to all TAPs with handlers for that event. +@end deffn + +@deffn Command {jtag arp_init-reset} +This uses TRST and SRST to try resetting +everything on the JTAG scan chain +(and anything else connected to SRST). +It then invokes the logic of @command{jtag arp_init}. @end deffn @@ -2397,9 +2641,6 @@ there seems to be no problems with JTAG scan chain operations. @section Other TAP commands -@c @deffn Command {jtag arp_init-reset} -@c ... more or less "toggle TRST ... and SRST too, what the heck" - @deffn Command {jtag cget} dotted.name @option{-event} name @deffnx Command {jtag configure} dotted.name @option{-event} name string At this writing this TAP attribute @@ -3075,7 +3316,7 @@ The following target events are defined: @end ignore @item @b{reset-assert-pre} @* Issued as part of @command{reset} processing -after SRST and/or TRST were activated and deactivated, +after @command{reset_init} was triggered but before SRST alone is re-asserted on the tap. @item @b{reset-assert-post} @* Issued as part of @command{reset} processing @@ -3105,10 +3346,11 @@ multiplexing, and so on. the target clocks are fully set up.) @item @b{reset-start} @* Issued as part of @command{reset} processing -before either SRST or TRST are activated. +before @command{reset_init} is called. -This is the most robust place to switch to a low JTAG clock rate, if -SRST disables PLLs needed to use a fast clock. +This is the most robust place to use @command{jtag_rclk} +or @command{jtag_khz} to switch to a low JTAG clock rate, +when reset disables PLLs needed to use a fast clock. @ignore @item @b{reset-wait-pos} @* Currently not used @@ -3295,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. @@ -3304,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 @@ -5507,7 +5750,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 @@ -5526,13 +5773,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; @@ -5840,6 +6080,28 @@ The @command{reset_config} command should already have been used to configure how the board and JTAG adapter treat these two signals, and to say if either signal is even present. @xref{Reset Configuration}. + +Note that TRST is specially handled. +It actually signifies JTAG's @sc{reset} state. +So if the board doesn't support the optional TRST signal, +or it doesn't support it along with the specified SRST value, +JTAG reset is triggered with TMS and TCK signals +instead of the TRST signal. +And no matter how that JTAG reset is triggered, once +the scan chain enters @sc{reset} with TRST inactive, +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} @@ -5869,23 +6131,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} ... should act as if TRST were active -@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 @@ -5903,7 +6172,7 @@ may not be as expected. @item @sc{run/idle}, @sc{drpause}, and @sc{irpause} are reasonable choices after @command{drscan} or @command{irscan} commands, since they are free of JTAG side effects. -However, @sc{run/idle} may have side effects that appear at other +@item @sc{run/idle} may have side effects that appear at non-JTAG levels, such as advancing the ARM9E-S instruction pipeline. Consult the documentation for the TAP(s) you are working with. @end itemize @@ -5955,6 +6224,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 @@ -6885,38 +7175,6 @@ foreach who @{A B C D E@} @} @end example -@node Target Library -@chapter Target Library -@cindex Target Library - -OpenOCD comes with a target configuration script library. These scripts can be -used as-is or serve as a starting point. - -The target library is published together with the OpenOCD executable and -the path to the target library is in the OpenOCD script search path. -Similarly there are example scripts for configuring the JTAG interface. - -The command line below uses the example parport configuration script -that ship with OpenOCD, then configures the str710.cfg target and -finally issues the init and reset commands. The communication speed -is set to 10kHz for reset and 8MHz for post reset. - -@example -openocd -f interface/parport.cfg -f target/str710.cfg \ - -c "init" -c "reset" -@end example - -To list the target scripts available: - -@example -$ ls /usr/local/lib/openocd/target - -arm7_fast.cfg lm3s6965.cfg pxa255.cfg stm32.cfg xba_revA3.cfg -at91eb40a.cfg lpc2148.cfg pxa255_sst.cfg str710.cfg zy1000.cfg -at91r40008.cfg lpc2294.cfg sam7s256.cfg str912.cfg -at91sam9260.cfg nslu2.cfg sam7x256.cfg wi-9c.cfg -@end example - @include fdl.texi @node OpenOCD Concept Index