* TAP Declaration:: TAP Declaration
* CPU Configuration:: CPU Configuration
* Flash Commands:: Flash Commands
+* Flash Programming:: Flash Programming
* NAND Flash Commands:: NAND Flash Commands
* PLD/FPGA Commands:: PLD/FPGA Commands
* General Commands:: General Commands
@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and
-Cortex-M3 (Stellaris LM3 and ST STM32) based cores to be
+Cortex-M3 (Stellaris LM3, ST STM32 and Energy Micro EFM32) based cores to be
debugged via the GDB protocol.
@b{Flash Programing:} Flash writing is supported for external CFI
compatible NOR flashes (Intel and AMD/Spansion command set) and several
-internal flashes (LPC1700, LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and
-STM32x). Preliminary support for various NAND flash controllers
+internal flashes (LPC1700, LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3,
+STM32x and EFM32). Preliminary support for various NAND flash controllers
(LPC3180, Orion, S3C24xx, more) controller is included.
@section OpenOCD Web Site
The user's guide you are now reading may not be the latest one
available. A version for more recent code may be available.
-Its HTML form is published irregularly at:
+Its HTML form is published regularly at:
@uref{http://openocd.sourceforge.net/doc/html/index.html}
@uref{http://forum.sparkfun.com/viewforum.php?f=18}
+@section OpenOCD User's Mailing List
+
+The OpenOCD User Mailing List provides the primary means of
+communication between users:
+
+@uref{https://lists.sourceforge.net/mailman/listinfo/openocd-user}
+
+@section OpenOCD IRC
+
+Support can also be found on irc:
+@uref{irc://irc.freenode.net/openocd}
@node Developers
@chapter OpenOCD Developer Resources
@item @b{signalyzer}
@* See: @url{http://www.signalyzer.com}
@item @b{Stellaris Eval Boards}
-@* See: @url{http://www.luminarymicro.com} - The Stellaris eval boards
+@* See: @url{http://www.ti.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 in a "pass through" mode 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
+@item @b{TI/Luminary ICDI}
+@* See: @url{http://www.ti.com} - TI/Luminary In-Circuit Debug
Interface (ICDI) Boards are included in Stellaris LM3S9B9x
Evaluation Kits. Like the non-detachable FT2232 support on the other
Stellaris eval boards, they can be used to debug other target boards.
@* Link @url{http://www.dlpdesign.com/usb/usb1232h.shtml}
@item @b{digilent-hs1}
@* Link @url{http://www.digilentinc.com/Products/Detail.cfm?Prod=JTAG-HS1}
+@item @b{opendous}
+@* Link @url{http://code.google.com/p/opendous/wiki/JTAG} FT2232H-based
+(OpenHardware).
@end itemize
@section USB-JTAG / Altera USB-Blaster compatibles
@item add "options usb-storage quirks=483:3744:i" to /etc/modprobe.conf
@end itemize
+@section USB TI/Stellaris ICDI based
+Texas Instruments has an adapter called @b{ICDI}.
+It is not to be confused with the FTDI based adapters that were originally fitted to their
+evaluation boards. This is the adapter fitted to the Stellaris LaunchPad.
+
@section USB Other
@itemize @bullet
@item @b{USBprog}
@* Link: @url{http://dangerousprototypes.com/bus-pirate-manual/}
@item @b{opendous}
-@* Link: @url{http://code.google.com/p/opendous-jtag/}
+@* Link: @url{http://code.google.com/p/opendous-jtag/} - which uses an AT90USB162
@item @b{estick}
@* Link: @url{http://code.google.com/p/estick-jtag/}
+
+@item @b{Keil ULINK v1}
+@* Link: @url{http://www.keil.com/ulink1/}
@end itemize
@section IBM PC Parallel Printer Port Based
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
+altera-usb-blaster.cfg hilscher_nxhx50_etm.cfg openrd.cfg
+arm-jtag-ew.cfg hilscher_nxhx50_re.cfg osbdm.cfg
+arm-usb-ocd.cfg hitex_str9-comstick.cfg parport.cfg
+at91rm9200.cfg icebear.cfg parport_dlc5.cfg
+axm0432.cfg jlink.cfg redbee-econotag.cfg
+busblaster.cfg jtagkey2.cfg redbee-usb.cfg
+buspirate.cfg jtagkey2p.cfg rlink.cfg
+calao-usb-a9260-c01.cfg jtagkey.cfg sheevaplug.cfg
+calao-usb-a9260-c02.cfg jtagkey-tiny.cfg signalyzer.cfg
+calao-usb-a9260.cfg kt-link.cfg signalyzer-h2.cfg
+chameleon.cfg lisa-l.cfg signalyzer-h4.cfg
+cortino.cfg luminary.cfg signalyzer-lite.cfg
+digilent-hs1.cfg luminary-icdi.cfg stlink-v1.cfg
+dlp-usb1232h.cfg luminary-lm3s811.cfg stlink-v2.cfg
+dummy.cfg minimodule.cfg stm32-stick.cfg
+estick.cfg neodb.cfg turtelizer2.cfg
+flashlink.cfg ngxtech.cfg ulink.cfg
+flossjtag.cfg olimex-arm-usb-ocd.cfg usb-jtag.cfg
+flossjtag-noeeprom.cfg olimex-arm-usb-ocd-h.cfg usbprog.cfg
+flyswatter2.cfg olimex-arm-usb-tiny-h.cfg vpaclink.cfg
+flyswatter.cfg olimex-jtag-tiny.cfg vsllink.cfg
+hilscher_nxhx10_etm.cfg oocdlink.cfg xds100v2.cfg
+hilscher_nxhx500_etm.cfg opendous.cfg
+hilscher_nxhx500_re.cfg openocd-usb.cfg
$
@end example
@item @file{board} ...
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
+actux3.cfg logicpd_imx27.cfg
+am3517evm.cfg lubbock.cfg
+arm_evaluator7t.cfg mcb1700.cfg
+at91cap7a-stk-sdram.cfg microchip_explorer16.cfg
+at91eb40a.cfg mini2440.cfg
+at91rm9200-dk.cfg mini6410.cfg
+at91rm9200-ek.cfg olimex_LPC2378STK.cfg
+at91sam9261-ek.cfg olimex_lpc_h2148.cfg
+at91sam9263-ek.cfg olimex_sam7_ex256.cfg
+at91sam9g20-ek.cfg olimex_sam9_l9260.cfg
+atmel_at91sam7s-ek.cfg olimex_stm32_h103.cfg
+atmel_at91sam9260-ek.cfg olimex_stm32_h107.cfg
+atmel_at91sam9rl-ek.cfg olimex_stm32_p107.cfg
+atmel_sam3n_ek.cfg omap2420_h4.cfg
+atmel_sam3s_ek.cfg open-bldc.cfg
+atmel_sam3u_ek.cfg openrd.cfg
+atmel_sam3x_ek.cfg osk5912.cfg
+atmel_sam4s_ek.cfg phytec_lpc3250.cfg
+balloon3-cpu.cfg pic-p32mx.cfg
+colibri.cfg propox_mmnet1001.cfg
+crossbow_tech_imote2.cfg pxa255_sst.cfg
+csb337.cfg redbee.cfg
+csb732.cfg rsc-w910.cfg
+da850evm.cfg sheevaplug.cfg
+digi_connectcore_wi-9c.cfg smdk6410.cfg
+diolan_lpc4350-db1.cfg spear300evb.cfg
+dm355evm.cfg spear300evb_mod.cfg
+dm365evm.cfg spear310evb20.cfg
+dm6446evm.cfg spear310evb20_mod.cfg
+efikamx.cfg spear320cpu.cfg
+eir.cfg spear320cpu_mod.cfg
+ek-lm3s1968.cfg steval_pcc010.cfg
+ek-lm3s3748.cfg stm320518_eval_stlink.cfg
+ek-lm3s6965.cfg stm32100b_eval.cfg
+ek-lm3s811.cfg stm3210b_eval.cfg
+ek-lm3s811-revb.cfg stm3210c_eval.cfg
+ek-lm3s9b9x.cfg stm3210e_eval.cfg
+ek-lm4f232.cfg stm3220g_eval.cfg
+embedded-artists_lpc2478-32.cfg stm3220g_eval_stlink.cfg
+ethernut3.cfg stm3241g_eval.cfg
+glyn_tonga2.cfg stm3241g_eval_stlink.cfg
+hammer.cfg stm32f0discovery.cfg
+hilscher_nxdb500sys.cfg stm32f4discovery.cfg
+hilscher_nxeb500hmi.cfg stm32ldiscovery.cfg
+hilscher_nxhx10.cfg stm32vldiscovery.cfg
+hilscher_nxhx500.cfg str910-eval.cfg
+hilscher_nxhx50.cfg telo.cfg
+hilscher_nxsb100.cfg ti_beagleboard.cfg
+hitex_lpc2929.cfg ti_beagleboard_xm.cfg
+hitex_stm32-performancestick.cfg ti_beaglebone.cfg
+hitex_str9-comstick.cfg ti_blaze.cfg
+iar_lpc1768.cfg ti_pandaboard.cfg
+iar_str912_sk.cfg ti_pandaboard_es.cfg
+icnova_imx53_sodimm.cfg topas910.cfg
+icnova_sam9g45_sodimm.cfg topasa900.cfg
+imx27ads.cfg twr-k60n512.cfg
+imx27lnst.cfg tx25_stk5.cfg
+imx28evk.cfg tx27_stk5.cfg
+imx31pdk.cfg unknown_at91sam9260.cfg
+imx35pdk.cfg uptech_2410.cfg
+imx53loco.cfg verdex.cfg
+keil_mcb1700.cfg voipac.cfg
+keil_mcb2140.cfg voltcraft_dso-3062c.cfg
+kwikstik.cfg x300t.cfg
+linksys_nslu2.cfg zy1000.cfg
+lisa-l.cfg
$
@end example
@item @file{target} ...
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 stm32f1x.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
-$
+$duc702x.cfg ixp42x.cfg
+am335x.cfg k40.cfg
+amdm37x.cfg k60.cfg
+ar71xx.cfg lpc1768.cfg
+at32ap7000.cfg lpc2103.cfg
+at91r40008.cfg lpc2124.cfg
+at91rm9200.cfg lpc2129.cfg
+at91sam3ax_4x.cfg lpc2148.cfg
+at91sam3ax_8x.cfg lpc2294.cfg
+at91sam3ax_xx.cfg lpc2378.cfg
+at91sam3nXX.cfg lpc2460.cfg
+at91sam3sXX.cfg lpc2478.cfg
+at91sam3u1c.cfg lpc2900.cfg
+at91sam3u1e.cfg lpc2xxx.cfg
+at91sam3u2c.cfg lpc3131.cfg
+at91sam3u2e.cfg lpc3250.cfg
+at91sam3u4c.cfg lpc4350.cfg
+at91sam3u4e.cfg mc13224v.cfg
+at91sam3uxx.cfg nuc910.cfg
+at91sam3XXX.cfg omap2420.cfg
+at91sam4sXX.cfg omap3530.cfg
+at91sam4XXX.cfg omap4430.cfg
+at91sam7se512.cfg omap4460.cfg
+at91sam7sx.cfg omap5912.cfg
+at91sam7x256.cfg omapl138.cfg
+at91sam7x512.cfg pic32mx.cfg
+at91sam9260.cfg pxa255.cfg
+at91sam9260_ext_RAM_ext_flash.cfg pxa270.cfg
+at91sam9261.cfg pxa3xx.cfg
+at91sam9263.cfg readme.txt
+at91sam9.cfg samsung_s3c2410.cfg
+at91sam9g10.cfg samsung_s3c2440.cfg
+at91sam9g20.cfg samsung_s3c2450.cfg
+at91sam9g45.cfg samsung_s3c4510.cfg
+at91sam9rl.cfg samsung_s3c6410.cfg
+atmega128.cfg sharp_lh79532.cfg
+avr32.cfg smp8634.cfg
+c100.cfg spear3xx.cfg
+c100config.tcl stellaris.cfg
+c100helper.tcl stm32.cfg
+c100regs.tcl stm32f0x_stlink.cfg
+cs351x.cfg stm32f1x.cfg
+davinci.cfg stm32f1x_stlink.cfg
+dragonite.cfg stm32f2x.cfg
+dsp56321.cfg stm32f2x_stlink.cfg
+dsp568013.cfg stm32f2xxx.cfg
+dsp568037.cfg stm32f4x.cfg
+epc9301.cfg stm32f4x_stlink.cfg
+faux.cfg stm32l.cfg
+feroceon.cfg stm32lx_stlink.cfg
+fm3.cfg stm32_stlink.cfg
+hilscher_netx10.cfg stm32xl.cfg
+hilscher_netx500.cfg str710.cfg
+hilscher_netx50.cfg str730.cfg
+icepick.cfg str750.cfg
+imx21.cfg str912.cfg
+imx25.cfg swj-dp.tcl
+imx27.cfg test_reset_syntax_error.cfg
+imx28.cfg test_syntax_error.cfg
+imx31.cfg ti_dm355.cfg
+imx35.cfg ti_dm365.cfg
+imx51.cfg ti_dm6446.cfg
+imx53.cfg tmpa900.cfg
+imx.cfg tmpa910.cfg
+is5114.cfg u8500.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.
@deffn {Interface Driver} {ft2232}
FTDI FT2232 (USB) based devices over one of the userspace libraries.
+
+Note that this driver has several flaws and the @command{ftdi} driver is
+recommended as its replacement.
+
These interfaces have several commands, used to configure the driver
before initializing the JTAG scan chain:
@item @b{axm0432_jtag} Axiom AXM-0432
@item @b{comstick} Hitex STR9 comstick
@item @b{cortino} Hitex Cortino JTAG interface
-@item @b{evb_lm3s811} Luminary Micro EVB_LM3S811 as a JTAG interface,
+@item @b{evb_lm3s811} TI/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)
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
+@item @b{luminary_icdi} This layout should be used with most TI/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.
The OpenOCD default value is 2 and for some systems a value of 10 has proved useful.
@end deffn
+@deffn {Config Command} {ft2232_channel} channel
+Used to select the channel of the ft2232 chip to use (between 1 and 4).
+The default value is 1.
+@end deffn
+
For example, the interface config file for a
Turtelizer JTAG Adapter looks something like this:
@end example
@end deffn
+@deffn {Interface Driver} {ftdi}
+This driver is for adapters using the MPSSE (Multi-Protocol Synchronous Serial
+Engine) mode built into many FTDI chips, such as the FT2232, FT4232 and FT232H.
+It is a complete rewrite to address a large number of problems with the ft2232
+interface driver.
+
+The driver is using libusb-1.0 in asynchronous mode to talk to the FTDI device,
+bypassing intermediate libraries like libftdi of D2XX. Performance-wise it is
+consistently faster than the ft2232 driver, sometimes several times faster.
+
+A major improvement of this driver is that support for new FTDI based adapters
+can be added competely through configuration files, without the need to patch
+and rebuild OpenOCD.
+
+The driver uses a signal abstraction to enable Tcl configuration files to
+define outputs for one or several FTDI GPIO. These outputs can then be
+controlled using the @command{ftdi_set_signal} command. Special signal names
+are reserved for nTRST, nSRST and LED (for blink) so that they, if defined,
+will be used for their customary purpose.
+
+Depending on the type of buffer attached to the FTDI GPIO, the outputs have to
+be controlled differently. In order to support tristateable signals such as
+nSRST, both a data GPIO and an output-enable GPIO can be specified for each
+signal. The following output buffer configurations are supported:
+
+@itemize @minus
+@item Push-pull with one FTDI output as (non-)inverted data line
+@item Open drain with one FTDI output as (non-)inverted output-enable
+@item Tristate with one FTDI output as (non-)inverted data line and another
+ FTDI output as (non-)inverted output-enable
+@item Unbuffered, using the FTDI GPIO as a tristate output directly by
+ switching data and direction as necessary
+@end itemize
+
+These interfaces have several commands, used to configure the driver
+before initializing the JTAG scan chain:
+
+@deffn {Config Command} {ftdi_vid_pid} [vid pid]+
+The vendor ID and product ID of the adapter. If not specified, the FTDI
+default values are used.
+Currently, up to eight [@var{vid}, @var{pid}] pairs may be given, e.g.
+@example
+ftdi_vid_pid 0x0403 0xcff8 0x15ba 0x0003
+@end example
+@end deffn
+
+@deffn {Config Command} {ftdi_device_desc} description
+Provides the USB device description (the @emph{iProduct string})
+of the adapter. If not specified, the device description is ignored
+during device selection.
+@end deffn
+
+@deffn {Config Command} {ftdi_serial} serial-number
+Specifies the @var{serial-number} of the adapter to use,
+in case the vendor provides unique IDs and more than one adapter
+is connected to the host.
+If not specified, serial numbers are not considered.
+(Note that USB serial numbers can be arbitrary Unicode strings,
+and are not restricted to containing only decimal digits.)
+@end deffn
+
+@deffn {Config Command} {ftdi_channel} channel
+Selects the channel of the FTDI device to use for MPSSE operations. Most
+adapters use the default, channel 0, but there are exceptions.
+@end deffn
+
+@deffn {Config Command} {ftdi_layout_init} data direction
+Specifies the initial values of the FTDI GPIO data and direction registers.
+Each value is a 16-bit number corresponding to the concatenation of the high
+and low FTDI GPIO registers. The values should be selected based on the
+schematics of the adapter, such that all signals are set to safe levels with
+minimal impact on the target system. Avoid floating inputs, conflicting outputs
+and initially asserted reset signals.
+@end deffn
+
+@deffn {Config Command} {ftdi_layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-oe}|@option{-noe} oe_mask]
+Creates a signal with the specified @var{name}, controlled by one or more FTDI
+GPIO pins via a range of possible buffer connections. The masks are FTDI GPIO
+register bitmasks to tell the driver the connection and type of the output
+buffer driving the respective signal. @var{data_mask} is the bitmask for the
+pin(s) connected to the data input of the output buffer. @option{-ndata} is
+used with inverting data inputs and @option{-data} with non-inverting inputs.
+The @option{-oe} (or @option{-noe}) option tells where the output-enable (or
+not-output-enable) input to the output buffer is connected.
+
+Both @var{data_mask} and @var{oe_mask} need not be specified. For example, a
+simple open-collector transistor driver would be specified with @option{-oe}
+only. In that case the signal can only be set to drive low or to Hi-Z and the
+driver will complain if the signal is set to drive high. Which means that if
+it's a reset signal, @command{reset_config} must be specified as
+@option{srst_open_drain}, not @option{srst_push_pull}.
+
+A special case is provided when @option{-data} and @option{-oe} is set to the
+same bitmask. Then the FTDI pin is considered being connected straight to the
+target without any buffer. The FTDI pin is then switched between output and
+input as necessary to provide the full set of low, high and Hi-Z
+characteristics. In all other cases, the pins specified in a signal definition
+are always driven by the FTDI.
+@end deffn
+
+@deffn {Command} {ftdi_set_signal} name @option{0}|@option{1}|@option{z}
+Set a previously defined signal to the specified level.
+@itemize @minus
+@item @option{0}, drive low
+@item @option{1}, drive high
+@item @option{z}, set to high-impedance
+@end itemize
+@end deffn
+
+For example adapter definitions, see the configuration files shipped in the
+@file{interface/ftdi} directory.
+@end deffn
+
@deffn {Interface Driver} {remote_bitbang}
Drive JTAG from a remote process. This sets up a UNIX or TCP socket connection
with a remote process and sends ASCII encoded bitbang requests to that process
@end deffn
@deffn {Interface Driver} {jlink}
-Segger jlink USB adapter
-@c command: jlink caps
-@c dumps jlink capabilities
-@c command: jlink config
-@c access J-Link configurationif no argument this will dump the config
-@c command: jlink config kickstart [val]
-@c set Kickstart power on JTAG-pin 19.
-@c command: jlink config mac_address [ff:ff:ff:ff:ff:ff]
-@c set the MAC Address
-@c command: jlink config ip [A.B.C.D[/E] [F.G.H.I]]
-@c set the ip address of the J-Link Pro, "
-@c where A.B.C.D is the ip,
-@c E the bit of the subnet mask
-@c F.G.H.I the subnet mask
-@c command: jlink config reset
-@c reset the current config
-@c command: jlink config save
-@c save the current config
-@c command: jlink config usb_address [0x00 to 0x03 or 0xff]
-@c set the USB-Address,
-@c This will change the product id
-@c command: jlink info
-@c dumps status
-@c command: jlink hw_jtag (2|3)
-@c sets version 2 or 3
-@c command: jlink pid
-@c set the pid of the interface we want to use
+Segger J-Link family of USB adapters. It currently supports only the JTAG transport.
+
+@quotation Compatibility Note
+Segger released many firmware versions for the many harware versions they
+produced. OpenOCD was extensively tested and intended to run on all of them,
+but some combinations were reported as incompatible. As a general
+recommendation, it is advisable to use the latest firmware version
+available for each hardware version. However the current V8 is a moving
+target, and Segger firmware versions released after the OpenOCD was
+released may not be compatible. In such cases it is recommended to
+revert to the last known functional version. For 0.5.0, this is from
+"Feb 8 2012 14:30:39", packed with 4.42c. For 0.6.0, the last known
+version is from "May 3 2012 18:36:22", packed with 4.46f.
+@end quotation
+
+@deffn {Command} {jlink caps}
+Display the device firmware capabilities.
+@end deffn
+@deffn {Command} {jlink info}
+Display various device information, like hardware version, firmware version, current bus status.
+@end deffn
+@deffn {Command} {jlink hw_jtag} [@option{2}|@option{3}]
+Set the JTAG protocol version to be used. Without argument, show the actual JTAG protocol version.
+@end deffn
+@deffn {Command} {jlink config}
+Display the J-Link configuration.
+@end deffn
+@deffn {Command} {jlink config kickstart} [val]
+Set the Kickstart power on JTAG-pin 19. Without argument, show the Kickstart configuration.
+@end deffn
+@deffn {Command} {jlink config mac_address} [@option{ff:ff:ff:ff:ff:ff}]
+Set the MAC address of the J-Link Pro. Without argument, show the MAC address.
+@end deffn
+@deffn {Command} {jlink config ip} [@option{A.B.C.D}(@option{/E}|@option{F.G.H.I})]
+Set the IP configuration of the J-Link Pro, where A.B.C.D is the IP address,
+ E the bit of the subnet mask and
+ F.G.H.I the subnet mask. Without arguments, show the IP configuration.
+@end deffn
+@deffn {Command} {jlink config usb_address} [@option{0x00} to @option{0x03} or @option{0xff}]
+Set the USB address; this will also change the product id. Without argument, show the USB address.
+@end deffn
+@deffn {Command} {jlink config reset}
+Reset the current configuration.
+@end deffn
+@deffn {Command} {jlink config save}
+Save the current configuration to the internal persistent storage.
+@end deffn
+@deffn {Config} {jlink pid} val
+Set the USB PID of the interface. As a configuration command, it can be used only before 'init'.
+@end deffn
@end deffn
@deffn {Interface Driver} {parport}
@end quotation
@end deffn
-@deffn {Interface Driver} {stlink}
-ST Micro ST-LINK adapter.
+@deffn {Interface Driver} {hla}
+This is a driver that supports multiple High Level Adapters.
+This type of adapter does not expose some of the lower level api's
+that OpenOCD would normally use to access the target.
-@deffn {Config Command} {stlink_device_desc} description
+Currently supported adapters include the ST STLINK and TI ICDI.
+
+@deffn {Config Command} {hla_device_desc} description
Currently Not Supported.
@end deffn
-@deffn {Config Command} {stlink_serial} serial
+@deffn {Config Command} {hla_serial} serial
Currently Not Supported.
@end deffn
-@deffn {Config Command} {stlink_layout} (@option{sg}|@option{usb})
-Specifies the stlink layout to use.
+@deffn {Config Command} {hla_layout} (@option{stlink}|@option{icdi})
+Specifies the adapter layout to use.
@end deffn
-@deffn {Config Command} {stlink_vid_pid} vid pid
-The vendor ID and product ID of the STLINK device.
+@deffn {Config Command} {hla_vid_pid} vid pid
+The vendor ID and product ID of the device.
@end deffn
@deffn {Config Command} {stlink_api} api_level
-Manually sets the stlink api used, valid options are 1 or 2.
+Manually sets the stlink api used, valid options are 1 or 2. (@b{STLINK Only}).
@end deffn
@end deffn
opendous-jtag is a freely programmable USB adapter.
@end deffn
+@deffn {Interface Driver} {ulink}
+This is the Keil ULINK v1 JTAG debugger.
+@end deffn
+
@deffn {Interface Driver} {ZY1000}
This is the Zylin ZY1000 JTAG debugger.
@end deffn
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{gates},
-@var{trst_type},
-and @var{srst_type} -- may be specified at a time.
+of each type -- @var{signals}, @var{combination}, @var{gates},
+@var{trst_type}, @var{srst_type} and @var{connect_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.
For example, this means that you don't need to say anything at all about
while SRST is asserted.
Its converse is @option{srst_nogate}, indicating that JTAG commands
can safely be issued while SRST is active.
+
+@item
+The @var{connect_type} tokens control flags that describe some cases where
+SRST is asserted while connecting to the target. @option{srst_nogate}
+is required to use this option.
+@option{connect_deassert_srst} (default)
+indicates that SRST will not be asserted while connecting to the target.
+Its converse is @option{connect_assert_srst}, indicating that SRST will
+be asserted before any target connection.
+Only some targets support this feature, STM32 and STR9 are examples.
+This feature is useful if you are unable to connect to your target due
+to incorrect options byte config or illegal program execution.
@end itemize
The optional @var{trst_type} and @var{srst_type} parameters allow the
@code{-work-area-phys} address, set up by the current operating system.
@item @code{-rtos} @var{rtos_type} -- enable rtos support for target,
-@var{rtos_type} can be one of @option{auto}|@option{eCos}|@option{threadx}|
-@option{freertos}|@option{linux}.
+@var{rtos_type} can be one of @option{auto}|@option{eCos}|@option{ThreadX}|
+@option{FreeRTOS}|@option{linux}|@option{ChibiOS}.
@end itemize
@end deffn
@* The target has resumed (i.e.: gdb said run)
@item @b{early-halted}
@* Occurs early in the halt process
-@ignore
-@item @b{examine-end}
-@* Currently not used (goal: when JTAG examine completes)
@item @b{examine-start}
-@* Currently not used (goal: when JTAG examine starts)
-@end ignore
+@* Before target examine is called.
+@item @b{examine-end}
+@* After target examine is called with no errors.
@item @b{gdb-attach}
@* 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
@* Before the target steps, gdb is trying to start/resume the target
@item @b{halted}
@* The target has halted
-@ignore
-@item @b{old-gdb_program_config}
-@* DO NOT USE THIS: Used internally
-@item @b{old-pre_resume}
-@* DO NOT USE THIS: Used internally
-@end ignore
@item @b{reset-assert-pre}
@* Issued as part of @command{reset} processing
after @command{reset_init} was triggered
@* Before any target is resumed
@item @b{resume-end}
@* After all targets have resumed
-@item @b{resume-ok}
-@* Success
@item @b{resumed}
@* Target has resumed
@end itemize
-
@node Flash Commands
@chapter Flash Commands
@cindex flash reading
@cindex flash writing
@cindex flash programming
+@anchor{Flash Programming Commands}
One feature distinguishing NOR flash from NAND or serial flash technologies
is that for read access, it acts exactly like any other addressible memory.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
+@anchor{program}
+@deffn Command {program} filename [verify] [reset] [offset]
+This is a helper script that simplifies using OpenOCD as a standalone
+programmer. The only required parameter is @option{filename}, the others are optional.
+@xref{Flash Programming}.
+@end deffn
+
@anchor{Flash Driver List}
@section Flash Driver List
As noted above, the @command{flash bank} command requires a driver name,
@c "cfi part_id" disabled
@end deffn
+@deffn {Flash Driver} lpcspifi
+@cindex NXP SPI Flash Interface
+@cindex SPIFI
+@cindex lpcspifi
+NXP's LPC43xx and LPC18xx families include a proprietary SPI
+Flash Interface (SPIFI) peripheral that can drive and provide
+memory mapped access to external SPI flash devices.
+
+The lpcspifi driver initializes this interface and provides
+program and erase functionality for these serial flash devices.
+Use of this driver @b{requires} a working area of at least 1kB
+to be configured on the target device; more than this will
+significantly reduce flash programming times.
+
+The setup command only requires the @var{base} parameter. All
+other parameters are ignored, and the flash size and layout
+are configured by the driver.
+
+@example
+flash bank $_FLASHNAME lpcspifi 0x14000000 0 0 0 $_TARGETNAME
+@end example
+
+@end deffn
+
@deffn {Flash Driver} stmsmi
@cindex STMicroelectronics Serial Memory Interface
@cindex SMI
@comment - defines mass_erase ... pointless given flash_erase_address
@end deffn
+@deffn {Flash Driver} efm32
+All members of the EFM32 microcontroller family from Energy Micro include
+internal flash and use ARM Cortex M3 cores. The driver automatically recognizes
+a number of these chips using the chip identification register, and
+autoconfigures itself.
+@example
+flash bank $_FLASHNAME efm32 0 0 0 0 $_TARGETNAME
+@end example
+@emph{The current implementation is incomplete. Unprotecting flash pages is not
+supported.}
+@end deffn
+
@deffn {Flash Driver} lpc2000
Most members of the LPC1700 and LPC2000 microcontroller families from NXP
include internal flash and use Cortex-M3 (LPC1700) or ARM7TDMI (LPC2000) cores.
@example
flash bank $_FLASHNAME stellaris 0 0 0 0 $_TARGETNAME
@end example
-@end deffn
@deffn Command {stellaris recover bank_id}
Performs the @emph{Recovering a "Locked" Device} procedure to
applied to all of them.
@end quotation
@end deffn
+@end deffn
@deffn {Flash Driver} stm32f1x
-All members of the STM32f1x microcontroller family from ST Microelectronics
-include internal flash and use ARM Cortex M3 cores.
+All members of the STM32F0, STM32F1 and STM32F3 microcontroller families
+from ST Microelectronics include internal flash and use ARM Cortex-M0/M3/M4 cores.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
flash bank $_FLASHNAME stm32f1x 0 0 0 0 $_TARGETNAME
@end example
+Note that some devices have been found that have a flash size register that contains
+an invalid value, to workaround this issue you can override the probed value used by
+the flash driver.
+
+@example
+flash bank $_FLASHNAME stm32f1x 0 0x20000 0 0 $_TARGETNAME
+@end example
+
If you have a target with dual flash banks then define the second bank
as per the following example.
@example
@end deffn
@deffn {Flash Driver} stm32f2x
-All members of the STM32f2x microcontroller family from ST Microelectronics
-include internal flash and use ARM Cortex M3 cores.
+All members of the STM32F2 and STM32F4 microcontroller families from ST Microelectronics
+include internal flash and use ARM Cortex-M3/M4 cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+
+Note that some devices have been found that have a flash size register that contains
+an invalid value, to workaround this issue you can override the probed value used by
+the flash driver.
+
+@example
+flash bank $_FLASHNAME stm32f2x 0 0x20000 0 0 $_TARGETNAME
+@end example
+
+Some stm32f2x-specific commands are defined:
+
+@deffn Command {stm32f2x lock} num
+Locks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32f2x unlock} num
+Unlocks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} stm32lx
+All members of the STM32L microcontroller families from ST Microelectronics
+include internal flash and use ARM Cortex-M3 cores.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
+
+Note that some devices have been found that have a flash size register that contains
+an invalid value, to workaround this issue you can override the probed value used by
+the flash driver.
+
+@example
+flash bank $_FLASHNAME stm32lx 0 0x20000 0 0 $_TARGETNAME
+@end example
@end deffn
@deffn {Flash Driver} str7x
@var{offset} bytes from the beginning of the bank.
@end deffn
+@node Flash Programming
+@chapter Flash Programming
+
+OpenOCD implements numerous ways to program the target flash, whether internal or external.
+Programming can be acheived by either using GDB @ref{Programming using GDB}, or using the cmds given in @ref{Flash Programming Commands}.
+
+@*To simplify using the flash cmds directly a jimtcl script is available that handles the programming and verify stage.
+OpenOCD will program/verify/reset the target and shutdown.
+
+The script is executed as follows and by default the following actions will be peformed.
+@enumerate
+@item 'init' is executed.
+@item 'reset init' is called to reset and halt the target, any 'reset init' scripts are executed.
+@item @code{flash write_image} is called to erase and write any flash using the filename given.
+@item @code{verify_image} is called if @option{verify} parameter is given.
+@item @code{reset run} is called if @option{reset} parameter is given.
+@item OpenOCD is shutdown.
+@end enumerate
+
+An example of usage is given below. @xref{program}.
+
+@example
+# program and verify using elf/hex/s19. verify and reset
+# are optional parameters
+openocd -f board/stm32f3discovery.cfg \
+ -c "program filename.elf verify reset"
+
+# binary files need the flash address passing
+openocd -f board/stm32f3discovery.cfg \
+ -c "program filename.bin 0x08000000"
+@end example
+
@node NAND Flash Commands
@chapter NAND Flash Commands
@cindex NAND
target remote localhost:3333
@end example
This would cause GDB to connect to the gdbserver on the local pc using port 3333.
+
+It is also possible to use the GDB extended remote protocol as follows:
+@example
+target extended-remote localhost:3333
+@end example
@item
A pipe connection is typically started as follows:
@example
@section Programming using GDB
@cindex Programming using GDB
+@anchor{Programming using GDB}
By default the target memory map is sent to GDB. This can be disabled by
the following OpenOCD configuration option:
projects / openocd / blobdiff