X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=9f3a8515c94ff884e63c2d329f717202e9d4eade;hp=323136f373813f7bf447fa79fca893ae7a3fdf88;hb=2467da4b4aad750d2b3d56998bcf07674047687a;hpb=5793056d96fd88845cde0d107c002a5fce413909 diff --git a/doc/openocd.texi b/doc/openocd.texi index 323136f373..9f3a8515c9 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -72,6 +72,7 @@ Free Documentation License''. * 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 @@ -155,13 +156,13 @@ OpenOCD internally. @xref{Debug Adapter Hardware}. @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 @@ -174,7 +175,7 @@ The OpenOCD web site provides the latest public news from the community: 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} @@ -192,6 +193,17 @@ instead of this forum. @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 @@ -309,7 +321,7 @@ RTCK support? Also known as ``adaptive clocking'' @section Stand alone Systems -@b{ZY1000} See: @url{http://www.zylin.com/zy1000.html} Technically, not a +@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/33-zylin-zy1000-jtag-probe} Technically, not a dongle, but a standalone box. The ZY1000 has the advantage that it does not require any drivers installed on the developer PC. It also has a built in web interface. It supports RTCK/RCLK or adaptive clocking @@ -336,7 +348,7 @@ a built-in low cost debug adapter and usb-to-serial solution. @itemize @bullet @item @b{usbjtag} -@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html} +@* Link @url{http://elk.informatik.fh-augsburg.de/hhweb/doc/openocd/usbjtag/usbjtag.html} @item @b{jtagkey} @* See: @url{http://www.amontec.com/jtagkey.shtml} @item @b{jtagkey2} @@ -346,19 +358,19 @@ a built-in low cost debug adapter and usb-to-serial solution. @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. @item @b{olimex-jtag} @* See: @url{http://www.olimex.com} -@item @b{flyswatter} +@item @b{Flyswatter/Flyswatter2} @* See: @url{http://www.tincantools.com} @item @b{turtelizer2} @* See: @@ -369,11 +381,14 @@ Stellaris eval boards, they can be used to debug other target boards. @item @b{stm32stick} @* Link @url{http://www.hitex.com/stm32-stick} @item @b{axm0432_jtag} -@* Axiom AXM-0432 Link @url{http://www.axman.com} +@* Axiom AXM-0432 Link @url{http://www.axman.com} - NOTE: This JTAG does not appear +to be available anymore as of April 2012. @item @b{cortino} @* Link @url{http://www.hitex.com/index.php?id=cortino} @item @b{dlp-usb1232h} @* 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} @end itemize @section USB-JTAG / Altera USB-Blaster compatibles @@ -390,7 +405,7 @@ product. The driver can be configured to search for any VID/PID pair @itemize @item @b{USB-JTAG} Kolja Waschk's USB Blaster-compatible adapter -@* Link: @url{http://www.ixo.de/info/usb_jtag/} +@* Link: @url{http://ixo-jtag.sourceforge.net/} @item @b{Altera USB-Blaster} @* Link: @url{http://www.altera.com/literature/ug/ug_usb_blstr.pdf} @end itemize @@ -406,7 +421,7 @@ AT91SAM764 internally. @item @b{SEGGER JLINK} @* Link: @url{http://www.segger.com/jlink.html} @item @b{IAR J-Link} -@* Link: @url{http://www.iar.com/website1/1.0.1.0/369/1/index.php} +@* Link: @url{http://www.iar.com/en/products/hardware-debug-probes/iar-j-link/} @end itemize @section USB RLINK based @@ -414,7 +429,7 @@ Raisonance has an adapter called @b{RLink}. It exists in a stripped-down form o @itemize @bullet @item @b{Raisonance RLink} -@* Link: @url{http://www.raisonance.com/products/RLink.php} +@* Link: @url{http://www.mcu-raisonance.com/~rlink-debugger-programmer__microcontrollers__tool~tool__T018:4cn9ziz4bnx6.html} @item @b{STM32 Primer} @* Link: @url{http://www.stm32circle.com/resources/stm32primer.php} @item @b{STM32 Primer2} @@ -423,7 +438,7 @@ Raisonance has an adapter called @b{RLink}. It exists in a stripped-down form o @section USB ST-LINK based ST Micro has an adapter called @b{ST-LINK}. -They only works with ST Micro chips, notably STM32 and STM8. +They only work with ST Micro chips, notably STM32 and STM8. @itemize @bullet @item @b{ST-LINK} @@ -436,34 +451,48 @@ They only works with ST Micro chips, notably STM32 and STM8. For info the original ST-LINK enumerates using the mass storage usb class, however it's implementation is completely broken. The result is this causes issues under linux. -The simplest solution is to get linux to ignore the ST-LINK using one of the following method's: +The simplest solution is to get linux to ignore the ST-LINK using one of the following methods: @itemize @bullet @item modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i @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://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604 +@* Link: @url{http://shop.embedded-projects.net/} - which uses an Atmel MEGA32 and a UBN9604 @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} +@* Link: @url{http://www.versaloon.com} @item @b{ARM-JTAG-EW} @* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html} @item @b{Buspirate} @* Link: @url{http://dangerousprototypes.com/bus-pirate-manual/} + +@item @b{opendous} +@* Link: @url{http://code.google.com/p/opendous-jtag/} + +@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 The two well known ``JTAG Parallel Ports'' cables are the Xilnx DLC5 -and the MacGraigor Wiggler. There are many clones and variations of +and the Macraigor Wiggler. There are many clones and variations of these on the market. Note that parallel ports are becoming much less common, so if you @@ -486,8 +515,7 @@ produced, PDF schematics are easily found and it is easy to make. @* Link: @url{http://www.gateworks.com/products/avila_accessories/gw16042.php} @item @b{Wiggler2} -@*@uref{http://www.ccac.rwth-aachen.de/@/~michaels/@/index.php/hardware/@/armjtag, -Improved parallel-port wiggler-style JTAG adapter} +@* Link: @url{http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag} @item @b{Wiggler_ntrst_inverted} @* Yet another variation - See the source code, src/jtag/parport.c @@ -510,8 +538,7 @@ Improved parallel-port wiggler-style JTAG adapter} @item @b{flashlink} @* From ST Microsystems; -@uref{http://www.st.com/stonline/@/products/literature/um/7889.pdf, -FlashLINK JTAG programing cable for PSD and uPSD} +@* Link: @url{http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATA_BRIEF/DM00039500.pdf} @end itemize @@ -1224,17 +1251,30 @@ These are for debug adapters. 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} ... @@ -1250,32 +1290,72 @@ board file. Boards may also contain multiple targets: two CPUs; or 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} ... @@ -1287,32 +1367,71 @@ 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 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. @@ -2344,6 +2463,10 @@ Cirrus Logic EP93xx based single-board computer bit-banging (in development) @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: @@ -2371,12 +2494,12 @@ Currently valid layout @var{name} values include: @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. @@ -2427,6 +2550,119 @@ ft2232_vid_pid 0x0403 0xbdc8 @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 @@ -2517,33 +2753,56 @@ This is a write-once setting. @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} @@ -2668,8 +2927,40 @@ which are not currently documented here. @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. + +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} {hla_serial} serial +Currently Not Supported. +@end deffn + +@deffn {Config Command} {hla_layout} (@option{stlink}|@option{icdi}) +Specifies the adapter layout to use. +@end deffn + +@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. (@b{STLINK Only}). +@end deffn +@end deffn + +@deffn {Interface Driver} {opendous} +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} @@ -2992,10 +3283,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{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 @@ -3037,6 +3327,18 @@ 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. + +@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 @@ -3909,6 +4211,10 @@ base @var{address} to be used when an MMU is active. The value should normally correspond to a static mapping for 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}|@option{ChibiOS}. + @end itemize @end deffn @@ -4100,12 +4406,10 @@ The following target events are defined: @* 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 @@ -4128,12 +4432,6 @@ depending on whether the breakpoint is in RAM or read only memory. @* 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 @@ -4193,13 +4491,10 @@ when reset disables PLLs needed to use a fast clock. @* 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 @@ -4302,6 +4597,7 @@ but most don't bother. @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. @@ -4445,6 +4741,13 @@ specifies "to the end of the flash bank". 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, @@ -4495,6 +4798,30 @@ flash bank $_FLASHNAME cfi 0x00000000 0x02000000 2 4 $_TARGETNAME @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 @@ -4537,6 +4864,7 @@ flash bank $_FLASHNAME aduc702x 0 0 0 0 $_TARGETNAME @end example @end deffn +@anchor{at91sam3} @deffn {Flash Driver} at91sam3 @cindex at91sam3 All members of the AT91SAM3 microcontroller family from @@ -4601,6 +4929,13 @@ This command shows/sets the slow clock frequency used in the @end deffn @end deffn +@deffn {Flash Driver} at91sam4 +@cindex at91sam4 +All members of the AT91SAM4 microcontroller family from +Atmel include internal flash and use ARM's Cortex-M4 core. +This driver uses the same cmd names/syntax as @xref{at91sam3}. +@end deffn + @deffn {Flash Driver} at91sam7 All members of the AT91SAM7 microcontroller family from Atmel include internal flash and use ARM7TDMI cores. The driver automatically @@ -4654,11 +4989,16 @@ The AVR 8-bit microcontrollers from Atmel integrate flash memory. @comment - defines mass_erase ... pointless given flash_erase_address @end deffn -@deffn {Flash Driver} ecosflash -@emph{No idea what this is...} -The @var{ecosflash} driver defines one mandatory parameter, -the name of a modules of target code which is downloaded -and executed. +@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 @@ -4885,7 +5225,6 @@ standard @command{flash erase_address} command.} @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 @@ -4901,10 +5240,11 @@ if more than one Stellaris chip is connected, the procedure is 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. @@ -4912,6 +5252,20 @@ 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 +flash bank $_FLASHNAME stm32f1x 0x08080000 0 0 0 $_TARGETNAME +@end example + Some stm32f1x-specific commands @footnote{Currently there is a @command{stm32f1x mass_erase} command. That seems pointless since the same effect can be had using the @@ -4941,10 +5295,45 @@ The @var{num} parameter is a value shown by @command{flash banks}. @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 @@ -5200,6 +5589,38 @@ Write the binary file @var{filename} to mflash bank @var{num}, starting at @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 @@ -7391,6 +7812,11 @@ A socket (TCP/IP) connection is typically started as follows: 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 @@ -7486,6 +7912,7 @@ using @command{gdb -x filename}. @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: