@itemize @bullet
@item Copyright @copyright{} 2008 The OpenOCD Project
-@item Copyright @copyright{} 2007-2008 Spen @email{spen@@spen-soft.co.uk}
+@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 Duane Ellis @email{openocd@@duaneellis.com}
@end itemize
@b{Dongles:} OpenOCD currently many types of hardware dongles: USB
Based, Parallel Port Based, and other standalone boxes that run
-OpenOCD internally. See the section titled: @xref{JTAG Hardware
-Dongles}.
+OpenOCD internally. See the section titled: @xref{JTAG Hardware Dongles}.
@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920t,
ARM922t, ARM926ej--s, ARM966e--s), XScale (PXA25x, IXP42x) and
@chapter Building
@cindex building OpenOCD
+@section Pre-Built Tools
If you are interested in getting actual work done rather than building
OpenOCD, then check if your interface supplier provides binaries for
you. Chances are that that binary is from some SVN version that is more
stable than SVN trunk where bleeding edge development takes place.
+@section Packagers Please Read!
+
+If you are a @b{PACKAGER} of OpenOCD if you
+
+@enumerate
+@item @b{Sell dongles} and include pre-built binaries
+@item @b{Supply tools} ie: A complete development solution
+@item @b{Supply IDEs} like Eclipse, or RHIDE, etc.
+@item @b{Build packages} ie: RPM files, or DEB files for a Linux Distro
+@end enumerate
+
+As a @b{PACKAGER} - you are at the top of the food chain. You solve
+problems for downstream users. What you fix or solve - solves hundreds
+if not thousands of user questions. If something does not work for you
+please let us know. That said, would also like you to follow a few
+suggestions:
+
+@enumerate
+@item @b{Always build with Printer Ports Enabled}
+@item @b{Try where possible to use LIBFTDI + LIBUSB} You cover more bases
+@end enumerate
+
+It is your decision..
+
+@itemize @bullet
+@item @b{Why YES to LIBFTDI + LIBUSB}
+@itemize @bullet
+@item @b{LESS} work - libusb perhaps already there
+@item @b{LESS} work - identical code multiple platforms
+@item @b{MORE} dongles are supported
+@item @b{MORE} platforms are supported
+@item @b{MORE} complete solution
+@end itemize
+@item @b{Why not LIBFTDI + LIBUSB} (ie: ftd2xx instead)
+@itemize @bullet
+@item @b{LESS} Some say it is slower.
+@item @b{LESS} complex to distribute (external dependencies)
+@end itemize
+@end itemize
+
+@section Building From Source
You can download the current SVN version with SVN client of your choice from the
following repositories:
homepage (@uref{www.amontec.com}), as the JTAGkey uses a non-standard VID/PID.
@end itemize
-libftdi is supported under windows. Versions earlier than 0.13 will require patching.
-see contrib/libftdi for more details.
+libftdi is supported under windows. Do not use versions earlier then 0.14.
In general, the D2XX driver provides superior performance (several times as fast),
but has the draw-back of being binary-only - though that isn't that bad, as it isn't
@end example
Bootstrap generates the configure script, and prepares building on your system.
@example
- ./configure
+ ./configure [options, see below]
@end example
Configure generates the Makefiles used to build OpenOCD.
@example
make
+ make install
@end example
-Make builds OpenOCD, and places the final executable in ./src/.
+Make builds OpenOCD, and places the final executable in ./src/, the last step, ``make install'' is optional.
The configure script takes several options, specifying which JTAG interfaces
should be included:
@itemize @bullet
@item
-@option{--enable-parport}
+@option{--enable-parport} - Bit bang pc printer ports.
+@item
+@option{--enable-parport_ppdev} - Parallel Port [see below]
+@item
+@option{--enable-parport_giveio} - Parallel Port [see below]
@item
-@option{--enable-parport_ppdev}
+@option{--enable-amtjtagaccel} - Parallel Port [Amontec, see below]
@item
-@option{--enable-parport_giveio}
+@option{--enable-ft2232_ftd2xx} - Numerous USB Type ARM JTAG dongles use the FT2232C chip from this FTDICHIP.COM chip (closed source).
@item
-@option{--enable-amtjtagaccel}
+@option{--enable-ft2232_libftdi} - An open source (free) alternate to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin)
@item
-@option{--enable-ft2232_ftd2xx}
-@footnote{Using the latest D2XX drivers from FTDI and following their installation
-instructions, I had to use @option{--enable-ft2232_libftd2xx} for OpenOCD to
-build properly.}
+@option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c, point at the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
@item
-@option{--enable-ft2232_libftdi}
+@option{--with-ftd2xx-linux-tardir=PATH} - Linux only equal of @option{--with-ftd2xx-win32-zipdir}, where you unpacked the TAR.GZ file.
@item
-@option{--with-ftd2xx=/path/to/d2xx/}
+@option{--with-ftd2xx-lib=shared|static} - Linux only. Default: static, specifies how the FTDICHIP.COM libftd2xx driver should be linked. Note 'static' only works in conjunction with @option{--with-ftd2xx-linux-tardir}. Shared is supported (12/26/2008), however you must manually install the required header files and shared libraries in an appropriate place. This uses ``libusb'' internally.
@item
@option{--enable-gw16012}
@item
@item
@option{--enable-presto_ftd2xx}
@item
-@option{--enable-jlink}
+@option{--enable-jlink} - From SEGGER
+@item
+@option{--enable-vsllink}
+@item
+@option{--enable-rlink} - Raisonance.com dongle.
@end itemize
+@section Parallel Port Dongles
+
If you want to access the parallel port using the PPDEV interface you have to specify
both the @option{--enable-parport} AND the @option{--enable-parport_ppdev} option since
the @option{--enable-parport_ppdev} option actually is an option to the parport driver
(see @uref{http://forum.sparkfun.com/viewtopic.php?t=3795} for more info).
-Cygwin users have to specify the location of the FTDI D2XX package. This should be an
-absolute path containing no spaces.
+@section FT2232C Based USB Dongles
+
+There are 2 methods of using the FTD2232, either (1) using the
+FTDICHIP.COM closed source driver, or (2) the open (and free) driver
+libftdi. Some claim the (closed) FTDICHIP.COM solution is faster.
+
+The FTDICHIP drivers come as either a (win32) ZIP file, or a (linux)
+TAR.GZ file. You must unpack them ``some where'' convient. As of this
+writing (12/26/2008) FTDICHIP does not supply means to install these
+files ``in an appropriate place'' As a result, there are two
+``./configure'' options that help.
+
+Below is an example build process:
+
+1) Check out the latest version of ``openocd'' from SVN.
+
+2) Download & Unpack either the Windows or Linux FTD2xx Drivers
+ (@uref{http://www.ftdichip.com/Drivers/D2XX.htm})
+
+@example
+ /home/duane/ftd2xx.win32 => the Cygwin/Win32 ZIP file contents.
+ /home/duane/libftd2xx0.4.16 => the Linux TAR file contents.
+@end example
+
+3) Configure with these options:
-Linux users should copy the various parts of the D2XX package to the appropriate
-locations, i.e. /usr/include, /usr/lib.
+@example
+Cygwin FTCICHIP solution
+ ./configure --prefix=/home/duane/mytools \
+ --enable-ft2232_ftd2xx \
+ --with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32
+
+Linux FTDICHIP solution
+ ./configure --prefix=/home/duane/mytools \
+ --enable-ft2232_ftd2xx \
+ --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
+
+Cygwin/Linux LIBFTDI solution
+ Assumes:
+ 1a) For Windows: The windows port of LIBUSB is in place.
+ 1b) For Linux: libusb has been built and is inplace.
+
+ 2) And libftdi has been built and installed
+ Note: libftdi - relies upon libusb.
+
+ ./configure --prefix=/home/duane/mytools \
+ --enable-ft2232_libftdi
+
+@end example
-Miscellaneous configure options
+4) Then just type ``make'', and perhaps ``make install''.
+
+
+@section Miscellaneous configure options
@itemize @bullet
@item
@itemize @bullet
@item @b{usbjtag}
-@* Link Unknown [not easily verified]
+@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
@item @b{jtagkey}
@* See: @url{http://www.amontec.com/jtagkey.shtml}
@item @b{oocdlink}
@item @b{comstick}
@* Link: @url{http://www.hitex.com/index.php?id=383}
@item @b{stm32stick}
-@* Link Unknown [not easily verified]
+@* Link @url{http://www.hitex.com/stm32-stick}
+@item @b{axm0432_jtag}
+@* Axiom AXM-0432 Link @url{http://www.axman.com}
@end itemize
@section USB JLINK based
@* Link: @url{http://www.iar.com/website1/1.0.1.0/369/1/index.php}
@end itemize
+@section USB RLINK based
+Raisonance has an adapter called @b{RLink}. It exists in a stripped-down form on the STM32 Primer, permanently attached to the JTAG lines. It also exists on the STM32 Primer2, but that is wired for SWD and not JTAG, thus not supported.
+
+@itemize @bullet
+@item @b{Raisonance RLink}
+@* Link: @url{http://www.raisonance.com/products/RLink.php}
+@item @b{STM32 Primer}
+@* Link: @url{http://www.stm32circle.com/resources/stm32primer.php}
+@item @b{STM32 Primer2}
+@* Link: @url{http://www.stm32circle.com/resources/stm32primer2.php}
+@end itemize
+
@section USB Other
@itemize @bullet
@item @b{USBprog}
@item @b{USB - Presto}
@* Link: @url{http://tools.asix.net/prg_presto.htm}
+
+@item @b{Versaloon-Link}
+@* Link: @url{http://www.simonqian.com/en/Versaloon}
@end itemize
@section IBM PC Parallel Printer Port Based
@* Unknown.
@item @b{Lattice}
-@* From Lattice Semiconductor [link unknown]
+@* ispDownload from Lattice Semiconductor @url{http://www.latticesemi.com/lit/docs/devtools/dlcable.pdf}
@item @b{flashlink}
@* From ST Microsystems, link:
--debug | -d set debug level <0-3>
--log_output | -l redirect log output to file <name>
--command | -c run <command>
+--pipe | -p use pipes when talking to gdb
@end verbatim
-By default openocd reads the file configuration file ``openocd.cfg''
+By default OpenOCD reads the file configuration file ``openocd.cfg''
in the current directory. To specify a different (or multiple)
configuration file, you can use the ``-f'' option. For example:
the @option{-s <search>} switch. The current directory and the OpenOCD
target library is in the search path by default.
+For details on the @option{-p} option. @xref{Connecting to GDB}.
+
Note! OpenOCD will launch the GDB & telnet server even if it can not
establish a connection with the target. In general, it is possible for
the JTAG controller to be unresponsive until the target is set up
@cindex configuration
@section Outline
-There are 4 basic ways of ``configurating'' openocd to run, they are:
+There are 4 basic ways of ``configurating'' OpenOCD to run, they are:
@enumerate
@item A small openocd.cfg file which ``sources'' other configuration files
@enumerate
@item The RESET configuration of your debug environment as a hole
-@item Is there a ``work area'' that that OpenOCD can use?
+@item Is there a ``work area'' that OpenOCD can use?
@* For ARM - work areas mean up to 10x faster downloads.
@item For MMU/MPU based ARM chips (ie: ARM9 and later) will that work area still be available?
@item For complex targets (multiple chips) the JTAG SPEED becomes an issue.
every chip. If the @t{-expected-id} is nonzero, OpenOCD attempts
to verify the tap id number verses configuration file and may issue an
error or warning like this. The hope is this will help pin point
-problem openocd configurations.
+problem OpenOCD configurations.
@example
Info: JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
JIM-Tcl commands, and (older) the orginal command interpretor.
@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 mon command) one
can type a Tcl for() loop, set variables, etc.
@item @b{Historical Note}
@node Daemon Configuration
@chapter Daemon Configuration
-The commands here are commonly found inthe openocd.cfg file and are
+The commands here are commonly found in the openocd.cfg file and are
used to specify what TCP/IP ports are used, and how GDB should be
supported.
@section init
# jlink interface
interface jlink
@end verbatim
+@b{A Raisonance RLink}
+@verbatim
+# rlink interface
+interface rlink
+@end verbatim
@b{Parallel Port}
@verbatim
interface parport
@item @b{jlink}
@* Segger jlink usb adapter
+
+@item @b{rlink}
+@* Raisonance RLink usb adapter
+
+@item @b{vsllink}
+@* vsllink is part of Versaloon which is a versatile USB programmer.
@comment - End parameters
@end itemize
@comment - End Interface
@b{TODO:} Confirm the following: On windows the name needs to end with
a ``space A''? Or not? It has to do with the FTD2xx driver. When must
this be added and when must it not be added? Why can't the code in the
-interface or in openocd automatically add this if needed? -- Duane.
+interface or in OpenOCD automatically add this if needed? -- Duane.
@item @b{ft2232_serial} <@var{serial-number}>
@cindex ft2232_serial
egnite Software turtelizer2
@item @b{oocdlink}
OOCDLink
+@item @b{axm0432_jtag}
+Axiom AXM-0432
@end itemize
@item @b{ft2232_vid_pid} <@var{vid}> <@var{pid}>
@item ft2232: 6MHz / (@var{number}+1)
@item amt jtagaccel: 8 / 2**@var{number}
@item jlink: maximum speed in kHz (0-12000), 0 will use RTCK
+@item rlink: 24MHz / @var{number}, but only for certain values of @var{number}
@comment end speed list.
@end itemize
@itemize @bullet
@item @b{-irlen NUMBER} - the length in bits of the instruction register
@item @b{-ircapture NUMBER} - the ID code capture command.
-@item @b{-irmask NUMBER} - the corrisponding mask for the ir register.
+@item @b{-irmask NUMBER} - the corresponding mask for the ir register.
@comment END REQUIRED
@end itemize
An example of a FOOBAR Tap
bits long, during Capture-IR 0x42 is loaded into the IR, and bits
[6,4,2,0] are checked.
-FIXME: The IDCODE - this was not used in the old code, it should be?
-Right? -Duane.
@item @b{Optional configparams}
@comment START Optional
@itemize @bullet
@* @b{Removed: 28/nov/2008} This command has been removed and replaced
by the ``jtag newtap'' command. The documentation remains here so that
one can easily convert the old syntax to the new syntax. About the old
-syntax: The old syntax is positional, ie: The 4th parameter is the
-``irmask'' The new syntax requires named prefixes, and supports
-additional options, for example ``-irmask 4'' Please refer to the
-@b{jtag newtap} command for deails.
+syntax: The old syntax is positional, ie: The 3rd parameter is the
+``irmask''. The new syntax requires named prefixes, and supports
+additional options, for example ``-expected-id 0x3f0f0f0f''. Please refer to the
+@b{jtag newtap} command for details.
@example
-OLD: jtag_device 8 0x01 0x0e3 0xfe
-NEW: jtag newtap CHIPNAME TAPNAME -irlen 8 -ircapture 0xe3 -irmask 0xfe
+OLD: jtag_device 8 0x01 0xe3 0xfe
+NEW: jtag newtap CHIPNAME TAPNAME -irlen 8 -ircapture 0x01 -irmask 0xe3
@end example
@section Enable/Disable Taps
circuit and skipped.
-From OpenOCDs view point, a JTAG TAP is in one of 3 states:
+From OpenOCD's view point, a JTAG TAP is in one of 3 states:
@itemize @bullet
@item @b{Enabled - Not In ByPass} and has a variable bit length
@b{jtag tapisenabled DOTTED.NAME}
-This command return 1 if the named tap is currently enabled, 0 if not.
+This command returns 1 if the named tap is currently enabled, 0 if not.
This command exists so that scripts that manipulate a JRC (like the
Omap3530 has) can determine if OpenOCD thinks a tap is presently
enabled, or disabled.
@section targets [NAME]
@b{Note:} This command name is PLURAL - not singular.
-With NO parameter, this pural @b{targets} command lists all known
+With NO parameter, this plural @b{targets} command lists all known
targets in a human friendly form.
With a parameter, this pural @b{targets} command sets the current
puts [format "The button is %s" $x]
@end example
-In OpenOCDs terms, the ``target'' is an object just like a Tcl/Tk
+In OpenOCD's terms, the ``target'' is an object just like a Tcl/Tk
button. Commands avaialble as a ``target object'' are:
@comment START targetobj commands.
@end itemize
@section Target Events
-At various times, certian things happen, or you want to happen.
+At various times, certain things can happen, or you want them to happen.
Examples:
@itemize @bullet
@item What should happen when GDB connects? Should your target reset?
@item When GDB tries to flash the target, do you need to enable the flash via a special command?
-@item During reset, do you need to write to certian memory locations to reconfigure the SDRAM?
+@item During reset, do you need to write to certain memory location to reconfigure the SDRAM?
@end itemize
All of the above items are handled by target events.
target event name, and BODY is a tcl procedure or string of commands
to execute.
-The programers model is the: ``-command'' option used in Tcl/Tk
+The programmers model is the ``-command'' option used in Tcl/Tk
buttons and events. Below are two identical examples, the first
creates and invokes small procedure. The second inlines the procedure.
mychip.cpu configure -event gdb-attach @{ puts "Reset..." ; reset halt @}
@end example
-Current Events
-
+@section Current Events
+The following events are available:
@itemize @bullet
@item @b{debug-halted}
@* The target has halted for debug reasons (ie: breakpoint)
@* Success
@item @b{resumed}
@* Target has resumed
+@item @b{tap-enable}
+@* Executed by @b{jtag tapenable DOTTED.NAME} command. Example:
+@example
+jtag configure DOTTED.NAME -event tap-enable @{
+ puts "Enabling CPU"
+ ...
+@}
+@end example
+@item @b{tap-disable}
+@*Executed by @b{jtag tapdisable DOTTED.NAME} command. Example:
+@example
+jtag configure DOTTED.NAME -event tap-disable @{
+ puts "Disabling CPU"
+ ...
+@}
+@end example
@end itemize
@comment end TYPES
@end itemize
@item @b{PARAMS}
-@*PARAMs are various target configure parameters, the following are manditory
-at configuration.
-@comment START manditory
+@*PARAMs are various target configure parameters, the following are mandatory
+at configuration:
+@comment START mandatory
@itemize @bullet
@item @b{-endian big|little}
@item @b{-chain-position DOTTED.NAME}
-@comment end MANDITORY
+@comment end MANDATORY
@end itemize
@comment END params
@end itemize
@item @b{-work-area-size [ADDRESS]} specify/set the work area
@item @b{-work-area-backup [0|1]} does the work area get backed up
@item @b{-endian [big|little]}
-@item @b{-variant [NAME]} some chips have varients openocd needs to know about
+@item @b{-variant [NAME]} some chips have varients OpenOCD needs to know about
@item @b{-chain-position DOTTED.NAME} the tap name this target refers to.
@end itemize
Example:
@* None (this is also used as the ARM946)
@item @b{cortex_m3}
@* use variant <@var{-variant lm3s}> when debugging luminary lm3s targets. This will cause
-openocd to use a software reset rather than asserting SRST to avoid a issue with clearing
+OpenOCD to use a software reset rather than asserting SRST to avoid a issue with clearing
the debug registers. This is fixed in Fury Rev B, DustDevil Rev B, Tempest, these revisions will
be detected and the normal reset behaviour used.
@item @b{xscale}
@item @b{mips_m4k}
@* Use variant @option{ejtag_srst} when debugging targets that do not
provide a functional SRST line on the EJTAG connector. This causes
-openocd to instead use an EJTAG software reset command to reset the
+OpenOCD to instead use an EJTAG software reset command to reset the
processor. You still need to enable @option{srst} on the reset
-configuration command to enable openocd hardware reset functionality.
+configuration command to enable OpenOCD hardware reset functionality.
@comment END varients
@end itemize
@section working_area - Command Removed
@cindex flash protect_check
@*Check protection state of sectors in flash bank <num>.
@option{flash erase_sector} using the same syntax.
-@subsection fash erase_sector
+@subsection flash erase_sector
@b{flash erase_sector} <@var{num}> <@var{first}> <@var{last}>
@cindex flash erase_sector
@anchor{flash erase_sector}
@end itemize
@section flash bank command
-The @b{flash bank} command is used to configure one or more flash chips (or banks in openocd terms)
+The @b{flash bank} command is used to configure one or more flash chips (or banks in OpenOCD terms)
@example
@b{flash bank} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}>
@option{enable_turbo} <@var{num>.}
Only use this driver for locking/unlocking the device or configuring the option bytes.
-Use the standard str9 driver for programming.
+Use the standard str9 driver for programming. @xref{STR9 specific commands}.
@subsubsection stellaris (LM3Sxxx) options
@cindex stellaris (LM3Sxxx) options
@subsection STR9 specific commands
@cindex STR9 specific commands
+@anchor{STR9 specific commands}
These are flash specific commands when using the str9xpec driver.
@itemize @bullet
@item @b{str9xpec enable_turbo} <@var{num}>
@*write str9 option bytes.
@end itemize
+Note: Before using the str9xpec driver here is some background info to help
+you better understand how the drivers works. OpenOCD has two flash drivers for
+the str9.
+@enumerate
+@item
+Standard driver @option{str9x} programmed via the str9 core. Normally used for
+flash programming as it is faster than the @option{str9xpec} driver.
+@item
+Direct programming @option{str9xpec} using the flash controller, this is
+ISC compilant (IEEE 1532) tap connected in series with the str9 core. The str9
+core does not need to be running to program using this flash driver. Typical use
+for this driver is locking/unlocking the target and programming the option bytes.
+@end enumerate
+
+Before we run any cmds using the @option{str9xpec} driver we must first disable
+the str9 core. This example assumes the @option{str9xpec} driver has been
+configured for flash bank 0.
+@example
+# assert srst, we do not want core running
+# while accessing str9xpec flash driver
+jtag_reset 0 1
+# turn off target polling
+poll off
+# disable str9 core
+str9xpec enable_turbo 0
+# read option bytes
+str9xpec options_read 0
+# re-enable str9 core
+str9xpec disable_turbo 0
+poll on
+reset halt
+@end example
+The above example will read the str9 option bytes.
+When performing a unlock remember that you will not be able to halt the str9 - it
+has been locked. Halting the core is not required for the @option{str9xpec} driver
+as mentioned above, just issue the cmds above manually or from a telnet prompt.
+
@subsection STR9 configuration
@cindex STR9 configuration
@itemize @bullet
@section Daemon Commands
-@subsection sleep
-@b{sleep} <@var{msec}>
+@subsection sleep [@var{msec}]
@cindex sleep
@*Wait for n milliseconds before resuming. Useful in connection with script files
(@var{script} command and @var{target_script} configuration).
-@subsection sleep
-@b{shutdown}
+@subsection shutdown
@cindex shutdown
@*Close the OpenOCD daemon, disconnecting all clients (GDB, Telnet, Other).
example if you need to control a JTAG Route Controller (ie: the
OMAP3530 on the Beagle Board has one) you might use these commands in
a script or an event procedure.
-
+@section Commands
+@cindex Commands
@itemize @bullet
@item @b{scan_chain}
@cindex scan_chain
Display/modify variable field <@var{var}> <@var{field}> [@var{value}|@var{flip}].
@end itemize
+@section Tap states
+@cindex Tap states
+Available tap_states are:
+@itemize @bullet
+@item @b{RESET}
+@cindex RESET
+@item @b{IDLE}
+@cindex IDLE
+@item @b{DRSELECT}
+@cindex DRSELECT
+@item @b{DRCAPTURE}
+@cindex DRCAPTURE
+@item @b{DRSHIFT}
+@cindex DRSHIFT
+@item @b{DREXIT1}
+@cindex DREXIT1
+@item @b{DRPAUSE}
+@cindex DRPAUSE
+@item @b{DREXIT2}
+@cindex DREXIT2
+@item @b{DRUPDATE}
+@cindex DRUPDATE
+@item @b{IRSELECT}
+@cindex IRSELECT
+@item @b{IRCAPTURE}
+@cindex IRCAPTURE
+@item @b{IRSHIFT}
+@cindex IRSHIFT
+@item @b{IREXIT1}
+@cindex IREXIT1
+@item @b{IRPAUSE}
+@cindex IRPAUSE
+@item @b{IREXIT2}
+@cindex IREXIT2
+@item @b{IRUPDATE}
+@cindex IRUPDATE
+@end itemize
+
@node TFTP
@chapter TFTP
OpenOCD complies with the remote gdbserver protocol, and as such can be used
to debug remote targets.
-@section Connecting to gdb
-@cindex Connecting to gdb
+@section Connecting to GDB
+@cindex Connecting to GDB
+@anchor{Connecting to GDB}
Use GDB 6.7 or newer with OpenOCD if you run into trouble. For
instance 6.3 has a known bug where it produces bogus memory access
errors, which has since been fixed: look up 1836 in
@url{http://sourceware.org/cgi-bin/gnatsweb.pl?database=gdb}
-
-A connection is typically started as follows:
+@*OpenOCD can communicate with GDB in two ways:
+@enumerate
+@item
+A socket (tcp) connection is typically started as follows:
@example
target remote localhost:3333
@end example
-This would cause gdb to connect to the gdbserver on the local pc using port 3333.
+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
+@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.
+@end enumerate
-To see a list of available OpenOCD commands type @option{monitor help} on the
-gdb commandline.
+@*To see a list of available OpenOCD commands type @option{monitor help} on the
+GDB commandline.
OpenOCD supports the gdb @option{qSupported} packet, this enables information
-to be sent by the gdb server (openocd) to gdb. Typical information includes
+to be sent by the gdb server (OpenOCD) to GDB. Typical information includes
packet size and device memory map.
-Previous versions of OpenOCD required the following gdb options to increase
-the packet size and speed up gdb communication.
+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
@end example
-This is now handled in the @option{qSupported} PacketSize.
+This is now handled in the @option{qSupported} PacketSize and should not be required.
-@section Programming using gdb
-@cindex Programming using gdb
+@section Programming using GDB
+@cindex Programming using GDB
-By default the target memory map is sent to gdb, this can be disabled by
+By default the target memory map is sent to GDB, this can be disabled by
the following OpenOCD config option:
@example
gdb_memory_map disable
in OpenOCD. For faster performance you should also configure a valid
working area.
-Informing gdb of the memory map of the target will enable gdb to protect any
+Informing GDB of the memory map of the target will enable GDB to protect any
flash area of the target and use hardware breakpoints by default. This means
that the OpenOCD option @option{gdb_breakpoint_override} is not required when
using a memory map. @xref{gdb_breakpoint_override}.
-To view the configured memory map in gdb, use the gdb command @option{info mem}
-All other unasigned addresses within gdb are treated as RAM.
+To view the configured memory map in GDB, use the gdb command @option{info mem}
+All other unasigned addresses within GDB are treated as RAM.
GDB 6.8 and higher set any memory area not in the memory map as inaccessible,
-this can be changed to the old behaviour by using the following gdb command.
+this can be changed to the old behaviour by using the following GDB command.
@example
set mem inaccessible-by-default off
@end example
-If @option{gdb_flash_program enable} is also used, gdb will be able to
+If @option{gdb_flash_program enable} is also used, GDB will be able to
program any flash memory using the vFlash interface.
-gdb will look at the target memory map when a load command is given, if any
+GDB will look at the target memory map when a load command is given, if any
areas to be programmed lie within the target flash area the vFlash packets
will be used.
-If the target needs configuring before gdb programming, an event
+If the target needs configuring before GDB programming, an event
script can be executed.
@example
$_TARGETNAME configure -event EVENTNAME BODY
@end example
-To verify any flash programming the gdb command @option{compare-sections}
+To verify any flash programming the GDB command @option{compare-sections}
can be used.
@node TCL scripting API
@*
In digital circuit design it is often refered to as ``clock
-syncronization'' the JTAG interface uses one clock (TCK or TCLK)
+synchronisation'' the JTAG interface uses one clock (TCK or TCLK)
operating at some speed, your target is operating at another. The two
-clocks are not syncronized, they are ``asynchronous''
+clocks are not synchronised, they are ``asynchronous''
-In order for the two to work together they must syncronize. Otherwise
+In order for the two to work together they must be synchronised. Otherwise
the two systems will get out of sync with each other and nothing will
-work. There are 2 basic options. @b{1.} use a special circuit or
-@b{2.} one clock must be some multile slower the the other.
+work. There are 2 basic options.
+@enumerate
+@item
+Use a special circuit.
+@item
+One clock must be some multiple slower the the other.
+@end enumerate
@b{Does this really matter?} For some chips and some situations, this
-is a non-issue (ie: A 500mhz ARM926) but for others - for example some
-ATMEL SAM7 and SAM9 chips start operation from reset at 32khz -
+is a non-issue (ie: A 500MHz ARM926) but for others - for example some
+ATMEL SAM7 and SAM9 chips start operation from reset at 32kHz -
program/enable the oscillators and eventually the main clock. It is in
those critical times you must slow the jtag clock to sometimes 1 to
-4khz.
+4kHz.
-Imagine debugging that 500mhz arm926 hand held battery powered device
-that ``deep sleeps'' at 32khz between every keystroke. It can be
+Imagine debugging that 500MHz ARM926 hand held battery powered device
+that ``deep sleeps'' at 32kHz between every keystroke. It can be
painful.
@b{Solution #1 - A special circuit}
this problem. ARM has a good description of the problem described at
this link: @url{http://www.arm.com/support/faqdev/4170.html} [checked
28/nov/2008]. Link title: ``How does the jtag synchronisation logic
-work? / how does adaptive clocking working?''.
+work? / how does adaptive clocking work?''.
The nice thing about adaptive clocking is that ``battery powered hand
held device example'' - the adaptiveness works perfectly all the
time. One can set a break point or halt the system in the deep power
down code, slow step out until the system speeds up.
-@b{Solution #2 - Always works - but is slower}
+@b{Solution #2 - Always works - but may be slower}
Often this is a perfectly acceptable solution.
based systems require an 8:1 division. @b{Xilinx Rule of thumb} is
1/12 the clock speed.
-Note: Many FTDI2232C based JTAG dongles are limited to 6mhz.
+Note: Many FTDI2232C based JTAG dongles are limited to 6MHz.
You can still debug the 'lower power' situations - you just need to
manually adjust the clock speed at every step. While painful and
To set the JTAG frequency use the command:
@example
- # Example: 1.234mhz
+ # Example: 1.234MHz
jtag_khz 1234
@end example
Many newer devices have multiple JTAG taps. For example: ST
Microsystems STM32 chips have two taps, a ``boundary scan tap'' and
-``cortexM3'' tap. Example: The STM32 reference manual, Document ID:
+``CortexM3'' tap. Example: The STM32 reference manual, Document ID:
RM0008, Section 26.5, Figure 259, page 651/681, the ``TDI'' pin is
connected to the Boundary Scan Tap, which then connects to the
CortexM3 Tap, which then connects to the TDO pin.
@section TCL Rule #1
There is a famous joke, it goes like this:
@enumerate
-@item Rule #1: The wife is aways correct
+@item Rule #1: The wife is always correct
@item Rule #2: If you think otherwise, See Rule #1
@end enumerate
@item Rule #2: If you think otherwise, See Rule #1
@end enumerate
-As in the famous joke, the consiquences of Rule #1 are profound. Once
+As in the famous joke, the consequences of Rule #1 are profound. Once
you understand Rule #1, you will understand TCL.
@section TCL Rule #1b
28/nov/2008, Jim/OpenOCD does not have a date command.
@end itemize
-@section Consiquences of Rule 1/2/3/4
+@section Consequences of Rule 1/2/3/4
-The consiquences of Rule 1 is profound.
+The consequences of Rule 1 is profound.
@subsection Tokenizing & Execution.
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 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.
Code Review / openocd.git / blobdiff