X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=8641531944d69faaf2cdbfc916bd1c969f457cf4;hp=e22ff1f61e3b04e9ada039a21ee32fe8112c5a8a;hb=442f1540d5066b9ef091cab677b505f2c8196313;hpb=986102f3f10ef28319cfbc1ede172af6d34451a4 diff --git a/doc/openocd.texi b/doc/openocd.texi index e22ff1f61e..8641531944 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -73,7 +73,6 @@ Free Documentation License''. * 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 * Architecture and Core Commands:: Architecture and Core Commands @@ -170,7 +169,7 @@ controllers (LPC3180, Orion, S3C24xx, more) is included. The OpenOCD web site provides the latest public news from the community: -@uref{http://openocd.sourceforge.net/} +@uref{http://openocd.org/} @section Latest User's Guide: @@ -178,11 +177,11 @@ 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 regularly at: -@uref{http://openocd.sourceforge.net/doc/html/index.html} +@uref{http://openocd.org/doc/html/index.html} PDF form is likewise published at: -@uref{http://openocd.sourceforge.net/doc/pdf/openocd.pdf} +@uref{http://openocd.org/doc/pdf/openocd.pdf} @section OpenOCD User's Forum @@ -256,7 +255,7 @@ providing a Doxygen reference manual. This document contains more technical information about the software internals, development processes, and similar documentation: -@uref{http://openocd.sourceforge.net/doc/doxygen/html/index.html} +@uref{http://openocd.org/doc/doxygen/html/index.html} This document is a work-in-progress, but contributions would be welcome to fill in the gaps. All of the source files are provided in-tree, @@ -292,7 +291,7 @@ communication between developers: The OpenOCD Bug Tracker is hosted on SourceForge: -@uref{https://sourceforge.net/p/openocd/tickets/} +@uref{http://bugs.openocd.org/} @node Debug Adapter Hardware @@ -450,18 +449,17 @@ product. The driver can be configured to search for any VID/PID pair @* Link: @url{http://www.altera.com/literature/ug/ug_usb_blstr.pdf} @end itemize -@section USB JLINK based -There are several OEM versions of the Segger @b{JLINK} adapter. It is -an example of a micro controller based JTAG adapter, it uses an +@section USB J-Link based +There are several OEM versions of the SEGGER @b{J-Link} adapter. It is +an example of a microcontroller based JTAG adapter, it uses an AT91SAM764 internally. @itemize @bullet -@item @b{ATMEL SAMICE} Only works with ATMEL chips! -@* Link: @url{http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3892} -@item @b{SEGGER JLINK} +@item @b{SEGGER J-Link} @* Link: @url{http://www.segger.com/jlink.html} +@item @b{Atmel SAM-ICE} (Only works with Atmel chips!) +@* Link: @url{http://www.atmel.com/tools/atmelsam-ice.aspx} @item @b{IAR J-Link} -@* Link: @url{http://www.iar.com/en/products/hardware-debug-probes/iar-j-link/} @end itemize @section USB RLINK based @@ -471,7 +469,7 @@ SWD and not JTAG, thus not supported. @itemize @bullet @item @b{Raisonance RLink} -@* Link: @url{http://www.mcu-raisonance.com/~rlink-debugger-programmer__microcontrollers__tool~tool__T018:4cn9ziz4bnx6.html} +@* 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} @@ -701,6 +699,7 @@ Configuration files and scripts are searched for in @item any search dir specified on the command line using the @option{-s} option, @item any search dir specified using the @command{add_script_search_dir} command, @item @file{$HOME/.openocd} (not on Windows), +@item a directory in the @env{OPENOCD_SCRIPTS} environment variable (if set), @item the site wide script library @file{$pkgdatadir/site} and @item the OpenOCD-supplied script library @file{$pkgdatadir/scripts}. @end enumerate @@ -735,7 +734,7 @@ If all goes well you'll see output something like @example Open On-Chip Debugger 0.4.0 (2010-01-14-15:06) For bug reports, read - http://openocd.sourceforge.net/doc/doxygen/bugs.html + http://openocd.org/doc/doxygen/bugs.html Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x3) @end example @@ -1296,65 +1295,17 @@ including developers and integrators of OpenOCD and any user who needs to get a new board working smoothly. It provides guidelines for creating those files. -You should find the following directories under @t{$(INSTALLDIR)/scripts}, -with files including the ones listed here. -Use them as-is where you can; or as models for new files. +You should find the following directories under +@t{$(INSTALLDIR)/scripts}, with config files maintained upstream. Use +them as-is where you can; or as models for new files. @itemize @bullet @item @file{interface} ... -These are for debug adapters. -Files that configure JTAG adapters go here. -@example -$ ls interface -R -interface/: -altera-usb-blaster.cfg hilscher_nxhx50_re.cfg openocd-usb-hs.cfg -arm-jtag-ew.cfg hitex_str9-comstick.cfg openrd.cfg -at91rm9200.cfg icebear.cfg osbdm.cfg -axm0432.cfg jlink.cfg parport.cfg -busblaster.cfg jtagkey2.cfg parport_dlc5.cfg -buspirate.cfg jtagkey2p.cfg redbee-econotag.cfg -calao-usb-a9260-c01.cfg jtagkey.cfg redbee-usb.cfg -calao-usb-a9260-c02.cfg jtagkey-tiny.cfg rlink.cfg -calao-usb-a9260.cfg jtag-lock-pick_tiny_2.cfg sheevaplug.cfg -chameleon.cfg kt-link.cfg signalyzer.cfg -cortino.cfg lisa-l.cfg signalyzer-h2.cfg -digilent-hs1.cfg luminary.cfg signalyzer-h4.cfg -dlp-usb1232h.cfg luminary-icdi.cfg signalyzer-lite.cfg -dummy.cfg luminary-lm3s811.cfg stlink-v1.cfg -estick.cfg minimodule.cfg stlink-v2.cfg -flashlink.cfg neodb.cfg stm32-stick.cfg -flossjtag.cfg ngxtech.cfg sysfsgpio-raspberrypi.cfg -flossjtag-noeeprom.cfg olimex-arm-usb-ocd.cfg ti-icdi.cfg -flyswatter2.cfg olimex-arm-usb-ocd-h.cfg turtelizer2.cfg -flyswatter.cfg olimex-arm-usb-tiny-h.cfg ulink.cfg -ftdi olimex-jtag-tiny.cfg usb-jtag.cfg -hilscher_nxhx10_etm.cfg oocdlink.cfg usbprog.cfg -hilscher_nxhx500_etm.cfg opendous.cfg vpaclink.cfg -hilscher_nxhx500_re.cfg opendous_ftdi.cfg vsllink.cfg -hilscher_nxhx50_etm.cfg openocd-usb.cfg xds100v2.cfg - -interface/ftdi: -axm0432.cfg hitex_str9-comstick.cfg olimex-jtag-tiny.cfg -calao-usb-a9260-c01.cfg icebear.cfg oocdlink.cfg -calao-usb-a9260-c02.cfg jtagkey2.cfg opendous_ftdi.cfg -cortino.cfg jtagkey2p.cfg openocd-usb.cfg -dlp-usb1232h.cfg jtagkey.cfg openocd-usb-hs.cfg -dp_busblaster.cfg jtag-lock-pick_tiny_2.cfg openrd.cfg -flossjtag.cfg kt-link.cfg redbee-econotag.cfg -flossjtag-noeeprom.cfg lisa-l.cfg redbee-usb.cfg -flyswatter2.cfg luminary.cfg sheevaplug.cfg -flyswatter.cfg luminary-icdi.cfg signalyzer.cfg -gw16042.cfg luminary-lm3s811.cfg signalyzer-lite.cfg -hilscher_nxhx10_etm.cfg minimodule.cfg stm32-stick.cfg -hilscher_nxhx500_etm.cfg neodb.cfg turtelizer2-revB.cfg -hilscher_nxhx500_re.cfg ngxtech.cfg turtelizer2-revC.cfg -hilscher_nxhx50_etm.cfg olimex-arm-usb-ocd.cfg vpaclink.cfg -hilscher_nxhx50_re.cfg olimex-arm-usb-ocd-h.cfg xds100v2.cfg -hitex_lpc1768stick.cfg olimex-arm-usb-tiny-h.cfg -$ -@end example +These are for debug adapters. Files that specify configuration to use +specific JTAG, SWD and other adapters go here. @item @file{board} ... -think Circuit Board, PWA, PCB, they go by many names. Board files +Think Circuit Board, PWA, PCB, they go by many names. Board files contain initialization items that are specific to a board. + They reuse target configuration files, since the same microprocessor chips are used on many boards, but support for external parts varies widely. For @@ -1363,169 +1314,13 @@ of external flash and what address it uses. Any initialization sequence to enable that external flash or SDRAM should be found in the board file. Boards may also contain multiple targets: two CPUs; or a CPU and an FPGA. -@example -$ ls board -actux3.cfg lpc1850_spifi_generic.cfg -am3517evm.cfg lpc4350_spifi_generic.cfg -arm_evaluator7t.cfg lubbock.cfg -at91cap7a-stk-sdram.cfg mcb1700.cfg -at91eb40a.cfg microchip_explorer16.cfg -at91rm9200-dk.cfg mini2440.cfg -at91rm9200-ek.cfg mini6410.cfg -at91sam9261-ek.cfg netgear-dg834v3.cfg -at91sam9263-ek.cfg olimex_LPC2378STK.cfg -at91sam9g20-ek.cfg olimex_lpc_h2148.cfg -atmel_at91sam7s-ek.cfg olimex_sam7_ex256.cfg -atmel_at91sam9260-ek.cfg olimex_sam9_l9260.cfg -atmel_at91sam9rl-ek.cfg olimex_stm32_h103.cfg -atmel_sam3n_ek.cfg olimex_stm32_h107.cfg -atmel_sam3s_ek.cfg olimex_stm32_p107.cfg -atmel_sam3u_ek.cfg omap2420_h4.cfg -atmel_sam3x_ek.cfg open-bldc.cfg -atmel_sam4s_ek.cfg openrd.cfg -balloon3-cpu.cfg osk5912.cfg -colibri.cfg phone_se_j100i.cfg -crossbow_tech_imote2.cfg phytec_lpc3250.cfg -csb337.cfg pic-p32mx.cfg -csb732.cfg propox_mmnet1001.cfg -da850evm.cfg pxa255_sst.cfg -digi_connectcore_wi-9c.cfg redbee.cfg -diolan_lpc4350-db1.cfg rsc-w910.cfg -dm355evm.cfg sheevaplug.cfg -dm365evm.cfg smdk6410.cfg -dm6446evm.cfg spear300evb.cfg -efikamx.cfg spear300evb_mod.cfg -eir.cfg spear310evb20.cfg -ek-lm3s1968.cfg spear310evb20_mod.cfg -ek-lm3s3748.cfg spear320cpu.cfg -ek-lm3s6965.cfg spear320cpu_mod.cfg -ek-lm3s811.cfg steval_pcc010.cfg -ek-lm3s811-revb.cfg stm320518_eval_stlink.cfg -ek-lm3s8962.cfg stm32100b_eval.cfg -ek-lm3s9b9x.cfg stm3210b_eval.cfg -ek-lm3s9d92.cfg stm3210c_eval.cfg -ek-lm4f120xl.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 stm32f3discovery.cfg -hilscher_nxeb500hmi.cfg stm32f4discovery.cfg -hilscher_nxhx10.cfg stm32ldiscovery.cfg -hilscher_nxhx500.cfg stm32vldiscovery.cfg -hilscher_nxhx50.cfg str910-eval.cfg -hilscher_nxsb100.cfg telo.cfg -hitex_lpc1768stick.cfg ti_am335xevm.cfg -hitex_lpc2929.cfg ti_beagleboard.cfg -hitex_stm32-performancestick.cfg ti_beagleboard_xm.cfg -hitex_str9-comstick.cfg ti_beaglebone.cfg -iar_lpc1768.cfg ti_blaze.cfg -iar_str912_sk.cfg ti_pandaboard.cfg -icnova_imx53_sodimm.cfg ti_pandaboard_es.cfg -icnova_sam9g45_sodimm.cfg topas910.cfg -imx27ads.cfg topasa900.cfg -imx27lnst.cfg twr-k60f120m.cfg -imx28evk.cfg twr-k60n512.cfg -imx31pdk.cfg tx25_stk5.cfg -imx35pdk.cfg tx27_stk5.cfg -imx53loco.cfg unknown_at91sam9260.cfg -keil_mcb1700.cfg uptech_2410.cfg -keil_mcb2140.cfg verdex.cfg -kwikstik.cfg voipac.cfg -linksys_nslu2.cfg voltcraft_dso-3062c.cfg -lisa-l.cfg x300t.cfg -logicpd_imx27.cfg zy1000.cfg -$ -@end example @item @file{target} ... -think chip. The ``target'' directory represents the JTAG TAPs +Think chip. The ``target'' directory represents the JTAG TAPs on a chip which OpenOCD should control, not a board. Two common types of targets are ARM chips and FPGA or CPLD chips. When a chip has multiple TAPs (maybe it has both ARM and DSP cores), the target config file defines all of them. -@example -$ ls target -aduc702x.cfg lpc1764.cfg -am335x.cfg lpc1765.cfg -amdm37x.cfg lpc1766.cfg -ar71xx.cfg lpc1767.cfg -at32ap7000.cfg lpc1768.cfg -at91r40008.cfg lpc1769.cfg -at91rm9200.cfg lpc1788.cfg -at91sam3ax_4x.cfg lpc17xx.cfg -at91sam3ax_8x.cfg lpc1850.cfg -at91sam3ax_xx.cfg lpc2103.cfg -at91sam3nXX.cfg lpc2124.cfg -at91sam3sXX.cfg lpc2129.cfg -at91sam3u1c.cfg lpc2148.cfg -at91sam3u1e.cfg lpc2294.cfg -at91sam3u2c.cfg lpc2378.cfg -at91sam3u2e.cfg lpc2460.cfg -at91sam3u4c.cfg lpc2478.cfg -at91sam3u4e.cfg lpc2900.cfg -at91sam3uxx.cfg lpc2xxx.cfg -at91sam3XXX.cfg lpc3131.cfg -at91sam4sd32x.cfg lpc3250.cfg -at91sam4sXX.cfg lpc4350.cfg -at91sam4XXX.cfg lpc4350.cfg.orig -at91sam7se512.cfg mc13224v.cfg -at91sam7sx.cfg nuc910.cfg -at91sam7x256.cfg omap2420.cfg -at91sam7x512.cfg omap3530.cfg -at91sam9260.cfg omap4430.cfg -at91sam9260_ext_RAM_ext_flash.cfg omap4460.cfg -at91sam9261.cfg omap5912.cfg -at91sam9263.cfg omapl138.cfg -at91sam9.cfg pic32mx.cfg -at91sam9g10.cfg pxa255.cfg -at91sam9g20.cfg pxa270.cfg -at91sam9g45.cfg pxa3xx.cfg -at91sam9rl.cfg readme.txt -atmega128.cfg samsung_s3c2410.cfg -avr32.cfg samsung_s3c2440.cfg -c100.cfg samsung_s3c2450.cfg -c100config.tcl samsung_s3c4510.cfg -c100helper.tcl samsung_s3c6410.cfg -c100regs.tcl sharp_lh79532.cfg -cs351x.cfg sim3x.cfg -davinci.cfg smp8634.cfg -dragonite.cfg spear3xx.cfg -dsp56321.cfg stellaris.cfg -dsp568013.cfg stellaris_icdi.cfg -dsp568037.cfg stm32f0x_stlink.cfg -efm32_stlink.cfg stm32f1x.cfg -epc9301.cfg stm32f1x_stlink.cfg -faux.cfg stm32f2x.cfg -feroceon.cfg stm32f2x_stlink.cfg -fm3.cfg stm32f3x.cfg -hilscher_netx10.cfg stm32f3x_stlink.cfg -hilscher_netx500.cfg stm32f4x.cfg -hilscher_netx50.cfg stm32f4x_stlink.cfg -icepick.cfg stm32l.cfg -imx21.cfg stm32lx_dual_bank.cfg -imx25.cfg stm32lx_stlink.cfg -imx27.cfg stm32_stlink.cfg -imx28.cfg stm32w108_stlink.cfg -imx31.cfg stm32xl.cfg -imx35.cfg str710.cfg -imx51.cfg str730.cfg -imx53.cfg str750.cfg -imx6.cfg str912.cfg -imx.cfg swj-dp.tcl -is5114.cfg test_reset_syntax_error.cfg -ixp42x.cfg test_syntax_error.cfg -k40.cfg ti-ar7.cfg -k60.cfg ti_calypso.cfg -lpc1751.cfg ti_dm355.cfg -lpc1752.cfg ti_dm365.cfg -lpc1754.cfg ti_dm6446.cfg -lpc1756.cfg tmpa900.cfg -lpc1758.cfg tmpa910.cfg -lpc1759.cfg u8500.cfg -lpc1763.cfg -@end example @item @emph{more} ... browse for other library files which may be useful. For example, there are various generic and CPU-specific utilities. @end itemize @@ -2164,7 +1959,7 @@ Examples: @cindex translation If you have a configuration file for another hardware debugger or toolset (Abatron, BDI2000, BDI3000, CCS, -Lauterbach, Segger, Macraigor, etc.), translating +Lauterbach, SEGGER, Macraigor, etc.), translating it into OpenOCD syntax is often quite straightforward. The most tricky part of creating a configuration script is oftentimes the reset init sequence where e.g. PLLs, DRAM and the like is set up. @@ -2331,6 +2126,11 @@ The GDB port for the first target will be the base port, the second target will listen on gdb_port + 1, and so on. When not specified during the configuration stage, the port @var{number} defaults to 3333. + +Note: when using "gdb_port pipe", increasing the default remote timeout in +gdb (with 'set remotetimeout') is recommended. An insufficient timeout may +cause initialization to fail with "Unknown remote qXfer reply: OK". + @end deffn @deffn {Command} tcl_port [number] @@ -2395,7 +2195,7 @@ use @option{enable} see these errors reported. @deffn {Config Command} gdb_target_description (@option{enable}|@option{disable}) Set to @option{enable} to cause OpenOCD to send the target descriptions to gdb via qXfer:features:read packet. -The default behaviour is @option{disable}. +The default behaviour is @option{enable}. @end deffn @deffn {Command} gdb_save_tdesc @@ -2877,18 +2677,30 @@ usb_blaster_vid_pid 0x16C0 0x06AD @end example @end deffn -@deffn {Command} {usb_blaster} (@option{pin6}|@option{pin8}) (@option{0}|@option{1}) -Sets the state of the unused GPIO pins on USB-Blasters (pins 6 and 8 on the -female JTAG header). These pins can be used as SRST and/or TRST provided the -appropriate connections are made on the target board. +@deffn {Command} {usb_blaster_pin} (@option{pin6}|@option{pin8}) (@option{0}|@option{1}|@option{s}|@option{t}) +Sets the state or function of the unused GPIO pins on USB-Blasters +(pins 6 and 8 on the female JTAG header). These pins can be used as +SRST and/or TRST provided the appropriate connections are made on the +target board. -For example, to use pin 6 as SRST (as with an AVR board): +For example, to use pin 6 as SRST: @example -$_TARGETNAME configure -event reset-assert \ - "usb_blaster pin6 1; wait 1; usb_blaster pin6 0" +usb_blaster_pin pin6 s +reset_config srst_only @end example @end deffn +@deffn {Command} {usb_blaster_lowlevel_driver} (@option{ftdi}|@option{ftd2xx}|@option{ublast2}) +Chooses the low level access method for the adapter. If not specified, +@option{ftdi} is selected unless it wasn't enabled during the +configure stage. USB-Blaster II needs @option{ublast2}. +@end deffn + +@deffn {Command} {usb_blaster_firmware} @var{path} +This command specifies @var{path} to access USB-Blaster II firmware +image. To be used with USB-Blaster II only. +@end deffn + @end deffn @deffn {Interface Driver} {gw16012} @@ -2904,63 +2716,69 @@ This is a write-once setting. @end deffn @deffn {Interface Driver} {jlink} -Segger J-Link family of USB adapters. It currently supports JTAG and SWD transports. +SEGGER J-Link family of USB adapters. It currently supports JTAG and SWD +transports. @quotation Compatibility Note -Segger released many firmware versions for the many harware versions they +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 +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. +@deffn {Command} {jlink hwstatus} +Display various hardware related information, for example target voltage and pin +states. @end deffn -@deffn {Command} {jlink info} -Display various device information, like hardware version, firmware version, current bus status. +@deffn {Command} {jlink freemem} +Display free device internal memory. @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. +@deffn {Command} {jlink jtag} [@option{2}|@option{3}] +Set the JTAG command version to be used. Without argument, show the actual JTAG +command version. @end deffn @deffn {Command} {jlink config} -Display the J-Link configuration. +Display the device configuration. @end deffn -@deffn {Command} {jlink config kickstart} [val] -Set the Kickstart power on JTAG-pin 19. Without argument, show the Kickstart configuration. +@deffn {Command} {jlink config targetpower} [@option{on}|@option{off}] +Set the target power state on JTAG-pin 19. Without argument, show the target +power state. @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. +@deffn {Command} {jlink config mac} [@option{ff:ff:ff:ff:ff:ff}] +Set the MAC address of the device. 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. +Set the IP configuration of the device, 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. +@deffn {Command} {jlink config usb} [@option{0} to @option{3}] +Set the USB address of the device. This will also change the USB Product ID +(PID) of the device. 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'. +@deffn {Command} {jlink config write} +Write the current configuration to the internal persistent storage. @end deffn -@deffn {Config} {jlink serial} serial-number -Set the @var{serial-number} of the interface, in case more than one adapter is connected to the host. -If not specified, serial numbers are not considered. +@deffn {Config} {jlink usb} <@option{0} to @option{3}> +Set the USB address of the interface, in case more than one adapter is connected +to the host. If not specified, USB addresses are not considered. Device +selection via USB address is deprecated and the serial number should be used +instead. -Note that there may be leading zeros in the @var{serial-number} string -that will not show in the Segger software, but must be specified here. -Debug level 3 output contains serial numbers if there is a mismatch. +As a configuration command, it can be used only before 'init'. +@end deffn +@deffn {Config} {jlink serial} +Set the serial number of the interface, in case more than one adapter is +connected to the host. If not specified, serial numbers are not considered. As a configuration command, it can be used only before 'init'. @end deffn @@ -3088,6 +2906,7 @@ which are not currently documented here. @end quotation @end deffn +@anchor{hla_interface} @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 @@ -3119,13 +2938,6 @@ The vendor ID and product ID of the device. Execute a custom adapter-specific command. The @var{command} string is passed as is to the underlying adapter layout handler. @end deffn - -@deffn {Config Command} {trace} source_clock_hz [output_file_path] -Enable SWO tracing (if supported). The source clock rate for the -trace port must be specified, this is typically the CPU clock rate. If -the optional output file is specified then raw trace data is appended -to the file, and the file is created if it does not exist. -@end deffn @end deffn @deffn {Interface Driver} {opendous} @@ -3177,11 +2989,20 @@ displays the names of the transports supported by this version of OpenOCD. @end deffn -@deffn Command {transport select} transport_name +@deffn Command {transport select} @option{transport_name} Select which of the supported transports to use in this OpenOCD session. -The transport must be supported by the debug adapter hardware and by the -version of OpenOCD you are using (including the adapter's driver). -No arguments: returns name of session's selected transport. + +When invoked with @option{transport_name}, attempts to select the named +transport. The transport must be supported by the debug adapter +hardware and by the version of OpenOCD you are using (including the +adapter's driver). + +If no transport has been selected and no @option{transport_name} is +provided, @command{transport select} auto-selects the first transport +supported by the debug adapter. + +@command{transport select} always returns the name of the session's selected +transport, if any. @end deffn @subsection JTAG Transport @@ -3192,6 +3013,12 @@ JTAG transports expose a chain of one or more Test Access Points (TAPs), each of which must be explicitly declared. JTAG supports both debugging and boundary scan testing. Flash programming support is built on top of debug support. + +JTAG transport is selected with the command @command{transport select +jtag}. Unless your adapter uses @ref{hla_interface,the hla interface +driver}, in which case the command is @command{transport select +hla_jtag}. + @subsection SWD Transport @cindex SWD @cindex Serial Wire Debug @@ -3201,6 +3028,12 @@ Debug Access Point (DAP, which must be explicitly declared. SWD is debug-oriented, and does not support boundary scan testing. Flash programming support is built on top of debug support. (Some processors support both JTAG and SWD.) + +SWD transport is selected with the command @command{transport select +swd}. Unless your adapter uses @ref{hla_interface,the hla interface +driver}, in which case the command is @command{transport select +hla_swd}. + @deffn Command {swd newdap} ... Declares a single DAP which uses SWD transport. Parameters are currently the same as "jtag newtap" but this is @@ -3212,11 +3045,6 @@ Wire Control Register (WCR). No parameters: displays current settings. @end deffn -@subsection CMSIS-DAP Transport -@cindex CMSIS-DAP -CMSIS-DAP is an ARM-specific transport that is used to connect to -compilant debuggers. - @subsection SPI Transport @cindex SPI @cindex Serial Peripheral Interface @@ -4133,22 +3961,6 @@ are examples; and there are many more. Several commands let you examine the list of targets: -@deffn Command {target count} -@emph{Note: target numbers are deprecated; don't use them. -They will be removed shortly after August 2010, including this command. -Iterate target using @command{target names}, not by counting.} - -Returns the number of targets, @math{N}. -The highest numbered target is @math{N - 1}. -@example -set c [target count] -for @{ set x 0 @} @{ $x < $c @} @{ incr x @} @{ - # Assuming you have created this function - print_target_details $x -@} -@end example -@end deffn - @deffn Command {target current} Returns the name of the current target. @end deffn @@ -4162,18 +3974,6 @@ foreach t [target names] @{ @end example @end deffn -@deffn Command {target number} number -@emph{Note: target numbers are deprecated; don't use them. -They will be removed shortly after August 2010, including this command.} - -The list of targets is numbered starting at zero. -This command returns the name of the target at index @var{number}. -@example -set thename [target number $x] -puts [format "Target %d is: %s\n" $x $thename] -@end example -@end deffn - @c yep, "target list" would have been better. @c plus maybe "target setdefault". @@ -4236,14 +4036,14 @@ not a CPU type. It is based on the ARMv5 architecture. @item @code{openrisc} -- this is an OpenRISC 1000 core. The current implementation supports three JTAG TAP cores: @itemize @minus -@item @code{OpenCores TAP} (See: @emph{http://opencores.org/project,jtag}) -@item @code{Altera Virtual JTAG TAP} (See: @emph{http://www.altera.com/literature/ug/ug_virtualjtag.pdf}) -@item @code{Xilinx BSCAN_* virtual JTAG interface} (See: @emph{http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_2/spartan6_hdl.pdf}) +@item @code{OpenCores TAP} (See: @url{http://opencores.org/project,jtag}) +@item @code{Altera Virtual JTAG TAP} (See: @url{http://www.altera.com/literature/ug/ug_virtualjtag.pdf}) +@item @code{Xilinx BSCAN_* virtual JTAG interface} (See: @url{http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_2/spartan6_hdl.pdf}) @end itemize And two debug interfaces cores: @itemize @minus -@item @code{Advanced debug interface} (See: @emph{http://opencores.org/project,adv_debug_sys}) -@item @code{SoC Debug Interface} (See: @emph{http://opencores.org/project,dbg_interface}) +@item @code{Advanced debug interface} (See: @url{http://opencores.org/project,adv_debug_sys}) +@item @code{SoC Debug Interface} (See: @url{http://opencores.org/project,dbg_interface}) @end itemize @end itemize @end deffn @@ -4387,7 +4187,7 @@ The value should normally correspond to a static mapping for the @anchor{rtostype} @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}|@option{embKernel} +@option{FreeRTOS}|@option{linux}|@option{ChibiOS}|@option{embKernel}|@option{mqx} @xref{gdbrtossupport,,RTOS Support}. @end itemize @@ -4567,7 +4367,8 @@ proc my_attach_proc @{ @} @{ mychip.cpu configure -event gdb-attach my_attach_proc mychip.cpu configure -event gdb-attach @{ echo "Reset..." - # To make flash probe and gdb load to flash work we need a reset init. + # To make flash probe and gdb load to flash work + # we need a reset init. reset init @} @end example @@ -4669,6 +4470,8 @@ when reset disables PLLs needed to use a fast clock. @* After all targets have resumed @item @b{resumed} @* Target has resumed +@item @b{trace-config} +@* After target hardware trace configuration was changed @end itemize @node Flash Commands @@ -4852,6 +4655,18 @@ starting at @var{offset} bytes from the beginning of the bank. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn +@deffn Command {flash read_bank} num filename offset length +Read @var{length} bytes from the flash bank @var{num} starting at @var{offset} +and write the contents to the binary @file{filename}. +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn + +@deffn Command {flash verify_bank} num filename offset +Compare the contents of the binary file @var{filename} with the contents of the +flash @var{num} starting at @var{offset}. Fails if the contents do not match. +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn + @deffn Command {flash write_image} [erase] [unlock] filename [offset] [type] Write the image @file{filename} to the current target's flash bank(s). Only loadable sections from the image are written. @@ -4934,6 +4749,26 @@ As noted above, the @command{flash bank} command requires a driver name, and allows driver-specific options and behaviors. Some drivers also activate driver-specific commands. +@deffn {Flash Driver} virtual +This is a special driver that maps a previously defined bank to another +address. All bank settings will be copied from the master physical bank. + +The @var{virtual} driver defines one mandatory parameters, + +@itemize +@item @var{master_bank} The bank that this virtual address refers to. +@end itemize + +So in the following example addresses 0xbfc00000 and 0x9fc00000 refer to +the flash bank defined at address 0x1fc00000. Any cmds executed on +the virtual banks are actually performed on the physical banks. +@example +flash bank $_FLASHNAME pic32mx 0x1fc00000 0 0 0 $_TARGETNAME +flash bank vbank0 virtual 0xbfc00000 0 0 0 $_TARGETNAME $_FLASHNAME +flash bank vbank1 virtual 0x9fc00000 0 0 0 $_TARGETNAME $_FLASHNAME +@end example +@end deffn + @subsection External Flash @deffn {Flash Driver} cfi @@ -4978,6 +4813,49 @@ flash bank $_FLASHNAME cfi 0x00000000 0x02000000 2 4 $_TARGETNAME @c "cfi part_id" disabled @end deffn +@deffn {Flash Driver} jtagspi +@cindex Generic JTAG2SPI driver +@cindex SPI +@cindex jtagspi +@cindex bscan_spi +Several FPGAs and CPLDs can retrieve their configuration (bitstream) from a +SPI flash connected to them. To access this flash from the host, the device +is first programmed with a special proxy bitstream that +exposes the SPI flash on the device's JTAG interface. The flash can then be +accessed through JTAG. + +Since signaling between JTAG and SPI is compatible, all that is required for +a proxy bitstream is to connect TDI-MOSI, TDO-MISO, TCK-CLK and activate +the flash chip select when the JTAG state machine is in SHIFT-DR. Such +a bitstream for several Xilinx FPGAs can be found in +@file{contrib/loaders/flash/fpga/xilinx_bscan_spi.py}. It requires migen +(@url{http://github.com/m-labs/migen}) and a Xilinx toolchain to build. + +This flash bank driver requires a target on a JTAG tap and will access that +tap directly. Since no support from the target is needed, the target can be a +"testee" dummy. Since the target does not expose the flash memory +mapping, target commands that would otherwise be expected to access the flash +will not work. These include all @command{*_image} and +@command{$target_name m*} commands as well as @command{program}. Equivalent +functionality is available through the @command{flash write_bank}, +@command{flash read_bank}, and @command{flash verify_bank} commands. + +@itemize +@item @var{ir} ... is loaded into the JTAG IR to map the flash as the JTAG DR. +For the bitstreams generated from @file{xilinx_bscan_spi.py} this is the +@var{USER1} instruction. +@item @var{dr_length} ... is the length of the DR register. This will be 1 for +@file{xilinx_bscan_spi.py} bitstreams and most other cases. +@end itemize + +@example +target create $_TARGETNAME testee -chain-position $_CHIPNAME.fpga +set _XILINX_USER1 0x02 +set _DR_LENGTH 1 +flash bank $_FLASHNAME spi 0x0 0 0 0 $_TARGETNAME $_XILINX_USER1 $_DR_LENGTH +@end example +@end deffn + @deffn {Flash Driver} lpcspifi @cindex NXP SPI Flash Interface @cindex SPIFI @@ -5030,6 +4908,19 @@ flash bank $_FLASHNAME stmsmi 0xf8000000 0 0 0 $_TARGETNAME @end deffn +@deffn {Flash Driver} mrvlqspi +This driver supports QSPI flash controller of Marvell's Wireless +Microcontroller platform. + +The flash size is autodetected based on the table of known JEDEC IDs +hardcoded in the OpenOCD sources. + +@example +flash bank $_FLASHNAME mrvlqspi 0x0 0 0 0 $_TARGETNAME 0x46010000 +@end example + +@end deffn + @subsection Internal Flash (Microcontrollers) @deffn {Flash Driver} aduc702x @@ -5047,6 +4938,9 @@ flash bank $_FLASHNAME aduc702x 0 0 0 0 $_TARGETNAME @anchor{at91samd} @deffn {Flash Driver} at91samd @cindex at91samd +All members of the ATSAMD, ATSAMR, ATSAML and ATSAMC microcontroller +families from Atmel include internal flash and use ARM's Cortex-M0+ core. +This driver uses the same cmd names/syntax as @xref{at91sam3}. @deffn Command {at91samd chip-erase} Issues a complete Flash erase via the Device Service Unit (DSU). This can be @@ -5094,6 +4988,12 @@ at91samd bootloader 16384 @end example @end deffn +@deffn Command {at91samd dsu_reset_deassert} +This command releases internal reset held by DSU +and prepares reset vector catch in case of reset halt. +Command is used internally in event event reset-deassert-post. +@end deffn + @end deffn @anchor{at91sam3} @@ -5168,6 +5068,27 @@ 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} at91sam4l +@cindex at91sam4l +All members of the AT91SAM4L 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}. + +The AT91SAM4L driver adds some additional commands: +@deffn Command {at91sam4l smap_reset_deassert} +This command releases internal reset held by SMAP +and prepares reset vector catch in case of reset halt. +Command is used internally in event event reset-deassert-post. +@end deffn +@end deffn + +@deffn {Flash Driver} atsamv +@cindex atsamv +All members of the ATSAMV, ATSAMS, and ATSAME families from +Atmel include internal flash and use ARM's Cortex-M7 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 @@ -5233,10 +5154,23 @@ flash bank $_FLASHNAME efm32 0 0 0 0 $_TARGETNAME supported.} @end deffn +@deffn {Flash Driver} fm3 +All members of the FM3 microcontroller family from Fujitsu +include internal flash and use ARM Cortex M3 cores. +The @var{fm3} driver uses the @var{target} parameter to select the +correct bank config, it can currently be one of the following: +@code{mb9bfxx1.cpu}, @code{mb9bfxx2.cpu}, @code{mb9bfxx3.cpu}, +@code{mb9bfxx4.cpu}, @code{mb9bfxx5.cpu} or @code{mb9bfxx6.cpu}. + +@example +flash bank $_FLASHNAME fm3 0 0 0 0 $_TARGETNAME +@end example +@end deffn + @deffn {Flash Driver} lpc2000 This is the driver to support internal flash of all members of the LPC11(x)00 and LPC1300 microcontroller families and most members of -the LPC800, LPC1500, LPC1700, LPC1800, LPC2000, LPC4300 and LPC54100 +the LPC800, LPC1500, LPC1700, LPC1800, LPC2000, LPC4000 and LPC54100 microcontroller families from NXP. @quotation Note @@ -5253,15 +5187,16 @@ which must appear in the following order: @item @var{variant} ... required, may be @option{lpc2000_v1} (older LPC21xx and LPC22xx) @option{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx) -@option{lpc1700} (LPC175x and LPC176x) +@option{lpc1700} (LPC175x and LPC176x and LPC177x/8x) @option{lpc4300} - available also as @option{lpc1800} alias (LPC18x[2357] and LPC43x[2357]) @option{lpc800} (LPC8xx) @option{lpc1100} (LPC11(x)xx and LPC13xx) @option{lpc1500} (LPC15xx) @option{lpc54100} (LPC541xx) +@option{lpc4000} (LPC40xx) or @option{auto} - automatically detects flash variant and size for LPC11(x)00, -LPC8xx, LPC13xx and LPC17xx +LPC8xx, LPC13xx, LPC17xx and LPC40xx @item @var{clock_kHz} ... the frequency, in kiloHertz, at which the core is running @item @option{calc_checksum} ... optional (but you probably want to provide this!), @@ -5422,6 +5357,113 @@ lpc2900 secure_jtag 0 @end deffn @end deffn +@deffn {Flash Driver} mdr +This drivers handles the integrated NOR flash on Milandr Cortex-M +based controllers. A known limitation is that the Info memory can't be +read or verified as it's not memory mapped. + +@example +flash bank mdr \ + 0 0 @var{type} @var{page_count} @var{sec_count} +@end example + +@itemize @bullet +@item @var{type} - 0 for main memory, 1 for info memory +@item @var{page_count} - total number of pages +@item @var{sec_count} - number of sector per page count +@end itemize + +Example usage: +@example +if @{ [info exists IMEMORY] && [string equal $IMEMORY true] @} @{ + flash bank $@{_CHIPNAME@}_info.flash mdr 0x00000000 0x01000 \ + 0 0 $_TARGETNAME 1 1 4 +@} else @{ + flash bank $_CHIPNAME.flash mdr 0x00000000 0x20000 \ + 0 0 $_TARGETNAME 0 32 4 +@} +@end example +@end deffn + +@deffn {Flash Driver} niietcm4 +This drivers handles the integrated NOR flash on NIIET Cortex-M4 +based controllers. Flash size and sector layout are auto-configured by the driver. +Main flash memory is called "Bootflash" and has main region and info region. +Info region is NOT memory mapped by default, +but it can replace first part of main region if needed. +Full erase, single and block writes are supported for both main and info regions. +There is additional not memory mapped flash called "Userflash", which +also have division into regions: main and info. +Purpose of userflash - to store system and user settings. +Driver has special commands to perform operations with this memmory. + +@example +flash bank $_FLASHNAME niietcm4 0 0 0 0 $_TARGETNAME +@end example + +Some niietcm4-specific commands are defined: + +@deffn Command {niietcm4 uflash_read_byte} bank ('main'|'info') address +Read byte from main or info userflash region. +@end deffn + +@deffn Command {niietcm4 uflash_write_byte} bank ('main'|'info') address value +Write byte to main or info userflash region. +@end deffn + +@deffn Command {niietcm4 uflash_full_erase} bank +Erase all userflash including info region. +@end deffn + +@deffn Command {niietcm4 uflash_erase} bank ('main'|'info') first_sector last_sector +Erase sectors of main or info userflash region, starting at sector first up to and including last. +@end deffn + +@deffn Command {niietcm4 uflash_protect_check} bank ('main'|'info') +Check sectors protect. +@end deffn + +@deffn Command {niietcm4 uflash_protect} bank ('main'|'info') first_sector last_sector ('on'|'off') +Protect sectors of main or info userflash region, starting at sector first up to and including last. +@end deffn + +@deffn Command {niietcm4 bflash_info_remap} bank ('on'|'off') +Enable remapping bootflash info region to 0x00000000 (or 0x40000000 if external memory boot used). +@end deffn + +@deffn Command {niietcm4 extmem_cfg} bank ('gpioa'|'gpiob'|'gpioc'|'gpiod'|'gpioe'|'gpiof'|'gpiog'|'gpioh') pin_num ('func1'|'func3') +Configure external memory interface for boot. +@end deffn + +@deffn Command {niietcm4 service_mode_erase} bank +Perform emergency erase of all flash (bootflash and userflash). +@end deffn + +@deffn Command {niietcm4 driver_info} bank +Show information about flash driver. +@end deffn + +@end deffn + +@deffn {Flash Driver} nrf51 +All members of the nRF51 microcontroller families from Nordic Semiconductor +include internal flash and use ARM Cortex-M0 core. + +@example +flash bank $_FLASHNAME nrf51 0 0x00000000 0 0 $_TARGETNAME +@end example + +Some nrf51-specific commands are defined: + +@deffn Command {nrf51 mass_erase} +Erases the contents of the code memory and user information +configuration registers as well. It must be noted that this command +works only for chips that do not have factory pre-programmed region 0 +code. +@end deffn + +@end deffn + @deffn {Flash Driver} ocl This driver is an implementation of the ``on chip flash loader'' protocol proposed by Pavel Chromy. @@ -5494,6 +5536,29 @@ The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @end deffn +@deffn {Flash Driver} sim3x +All members of the SiM3 microcontroller family from Silicon Laboratories +include internal flash and use ARM Cortex M3 cores. It supports both JTAG +and SWD interface. +The @var{sim3x} driver tries to probe the device to auto detect the MCU. +If this failes, it will use the @var{size} parameter as the size of flash bank. + +@example +flash bank $_FLASHNAME sim3x 0 $_CPUROMSIZE 0 0 $_TARGETNAME +@end example + +There are 2 commands defined in the @var{sim3x} driver: + +@deffn Command {sim3x mass_erase} +Erases the complete flash. This is used to unlock the flash. +And this command is only possible when using the SWD interface. +@end deffn + +@deffn Command {sim3x lock} +Lock the flash. To unlock use the @command{sim3x mass_erase} command. +@end deffn +@end deffn + @deffn {Flash Driver} stellaris All members of the Stellaris LM3Sxxx, LM4x and Tiva C microcontroller families from Texas Instruments include internal flash. The driver @@ -5507,12 +5572,12 @@ standard @command{flash erase_address} command.} flash bank $_FLASHNAME stellaris 0 0 0 0 $_TARGETNAME @end example -@deffn Command {stellaris recover bank_id} -Performs the @emph{Recovering a "Locked" Device} procedure to -restore the flash specified by @var{bank_id} and its associated -nonvolatile registers to their factory default values (erased). -This is the only way to remove flash protection or re-enable -debugging if that capability has been disabled. +@deffn Command {stellaris recover} +Performs the @emph{Recovering a "Locked" Device} procedure to restore +the flash and its associated nonvolatile registers to their factory +default values (erased). This is the only way to remove flash +protection or re-enable debugging if that capability has been +disabled. Note that the final "power cycle the chip" step in this procedure must be performed by hand, since OpenOCD can't do it. @@ -5635,7 +5700,8 @@ The @var{str7x} driver defines one mandatory parameter, @var{variant}, which is either @code{STR71x}, @code{STR73x} or @code{STR75x}. @example -flash bank $_FLASHNAME str7x 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x +flash bank $_FLASHNAME str7x \ + 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x @end example @deffn Command {str7x disable_jtag} bank @@ -5669,134 +5735,55 @@ The @var{num} parameter is a value shown by @command{flash banks}. @end deffn -@deffn {Flash Driver} tms470 -Most members of the TMS470 microcontroller family from Texas Instruments -include internal flash and use ARM7TDMI cores. -This driver doesn't require the chip and bus width to be specified. +@deffn {Flash Driver} str9xpec +@cindex str9xpec -Some tms470-specific commands are defined: +Only use this driver for locking/unlocking the device or configuring the option bytes. +Use the standard str9 driver for programming. +Before using the flash commands the turbo mode must be enabled using the +@command{str9xpec enable_turbo} command. -@deffn Command {tms470 flash_keyset} key0 key1 key2 key3 -Saves programming keys in a register, to enable flash erase and write commands. -@end deffn +Here is some background info to help +you better understand how this driver 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 an +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 -@deffn Command {tms470 osc_mhz} clock_mhz -Reports the clock speed, which is used to calculate timings. -@end deffn +Before we run any commands 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 commands above manually or from a telnet prompt. -@deffn Command {tms470 plldis} (0|1) -Disables (@var{1}) or enables (@var{0}) use of the PLL to speed up -the flash clock. -@end deffn -@end deffn - -@deffn {Flash Driver} virtual -This is a special driver that maps a previously defined bank to another -address. All bank settings will be copied from the master physical bank. - -The @var{virtual} driver defines one mandatory parameters, - -@itemize -@item @var{master_bank} The bank that this virtual address refers to. -@end itemize - -So in the following example addresses 0xbfc00000 and 0x9fc00000 refer to -the flash bank defined at address 0x1fc00000. Any cmds executed on -the virtual banks are actually performed on the physical banks. -@example -flash bank $_FLASHNAME pic32mx 0x1fc00000 0 0 0 $_TARGETNAME -flash bank vbank0 virtual 0xbfc00000 0 0 0 $_TARGETNAME $_FLASHNAME -flash bank vbank1 virtual 0x9fc00000 0 0 0 $_TARGETNAME $_FLASHNAME -@end example -@end deffn - -@deffn {Flash Driver} fm3 -All members of the FM3 microcontroller family from Fujitsu -include internal flash and use ARM Cortex M3 cores. -The @var{fm3} driver uses the @var{target} parameter to select the -correct bank config, it can currently be one of the following: -@code{mb9bfxx1.cpu}, @code{mb9bfxx2.cpu}, @code{mb9bfxx3.cpu}, -@code{mb9bfxx4.cpu}, @code{mb9bfxx5.cpu} or @code{mb9bfxx6.cpu}. - -@example -flash bank $_FLASHNAME fm3 0 0 0 0 $_TARGETNAME -@end example -@end deffn - -@deffn {Flash Driver} sim3x -All members of the SiM3 microcontroller family from Silicon Laboratories -include internal flash and use ARM Cortex M3 cores. It supports both JTAG -and SWD interface. -The @var{sim3x} driver tries to probe the device to auto detect the MCU. -If this failes, it will use the @var{size} parameter as the size of flash bank. - -@example -flash bank $_FLASHNAME sim3x 0 $_CPUROMSIZE 0 0 $_TARGETNAME -@end example - -There are 2 commands defined in the @var{sim3x} driver: - -@deffn Command {sim3x mass_erase} -Erases the complete flash. This is used to unlock the flash. -And this command is only possible when using the SWD interface. -@end deffn - -@deffn Command {sim3x lock} -Lock the flash. To unlock use the @command{sim3x mass_erase} command. -@end deffn - -@end deffn - -@subsection str9xpec driver -@cindex str9xpec - -Here is some background info to help -you better understand how this driver 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 an -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 commands 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 commands above manually or from a telnet prompt. - -@deffn {Flash Driver} str9xpec -Only use this driver for locking/unlocking the device or configuring the option bytes. -Use the standard str9 driver for programming. -Before using the flash commands the turbo mode must be enabled using the -@command{str9xpec enable_turbo} command. - -Several str9xpec-specific commands are defined: - -@deffn Command {str9xpec disable_turbo} num -Restore the str9 into JTAG chain. +Several str9xpec-specific commands are defined: + +@deffn Command {str9xpec disable_turbo} num +Restore the str9 into JTAG chain. @end deffn @deffn Command {str9xpec enable_turbo} num @@ -5843,128 +5830,44 @@ unlock str9 device. @end deffn -@deffn {Flash Driver} nrf51 -All members of the nRF51 microcontroller families from Nordic Semiconductor -include internal flash and use ARM Cortex-M0 core. - -@example -flash bank $_FLASHNAME nrf51 0 0x00000000 0 0 $_TARGETNAME -@end example +@deffn {Flash Driver} tms470 +Most members of the TMS470 microcontroller family from Texas Instruments +include internal flash and use ARM7TDMI cores. +This driver doesn't require the chip and bus width to be specified. -Some nrf51-specific commands are defined: +Some tms470-specific commands are defined: -@deffn Command {nrf51 mass_erase} -Erases the contents of the code memory and user information -configuration registers as well. It must be noted that this command -works only for chips that do not have factory pre-programmed region 0 -code. +@deffn Command {tms470 flash_keyset} key0 key1 key2 key3 +Saves programming keys in a register, to enable flash erase and write commands. @end deffn -@deffn {Flash Driver} mrvlqspi -This driver supports QSPI flash controller of Marvell's Wireless -Microcontroller platform. - -The flash size is autodetected based on the table of known JEDEC IDs -hardcoded in the OpenOCD sources. -@end deffn +@deffn Command {tms470 osc_mhz} clock_mhz +Reports the clock speed, which is used to calculate timings. @end deffn -@section mFlash - -@subsection mFlash Configuration -@cindex mFlash Configuration - -@deffn {Config Command} {mflash bank} soc base RST_pin target -Configures a mflash for @var{soc} host bank at -address @var{base}. -The pin number format depends on the host GPIO naming convention. -Currently, the mflash driver supports s3c2440 and pxa270. - -Example for s3c2440 mflash where @var{RST pin} is GPIO B1: - -@example -mflash bank $_FLASHNAME s3c2440 0x10000000 1b 0 -@end example - -Example for pxa270 mflash where @var{RST pin} is GPIO 43: - -@example -mflash bank $_FLASHNAME pxa270 0x08000000 43 0 -@end example +@deffn Command {tms470 plldis} (0|1) +Disables (@var{1}) or enables (@var{0}) use of the PLL to speed up +the flash clock. @end deffn - -@subsection mFlash commands -@cindex mFlash commands - -@deffn Command {mflash config pll} frequency -Configure mflash PLL. -The @var{frequency} is the mflash input frequency, in Hz. -Issuing this command will erase mflash's whole internal nand and write new pll. -After this command, mflash needs power-on-reset for normal operation. -If pll was newly configured, storage and boot(optional) info also need to be update. @end deffn -@deffn Command {mflash config boot} -Configure bootable option. -If bootable option is set, mflash offer the first 8 sectors -(4kB) for boot. -@end deffn +@deffn {Flash Driver} xmc4xxx +All members of the XMC4xxx microcontroller family from Infineon. +This driver does not require the chip and bus width to be specified. -@deffn Command {mflash config storage} -Configure storage information. -For the normal storage operation, this information must be -written. -@end deffn +Some xmc4xxx-specific commands are defined: -@deffn Command {mflash dump} num filename offset size -Dump @var{size} bytes, starting at @var{offset} bytes from the -beginning of the bank @var{num}, to the file named @var{filename}. +@deffn Command {xmc4xxx flash_password} bank_id passwd1 passwd2 +Saves flash protection passwords which are used to lock the user flash @end deffn -@deffn Command {mflash probe} -Probe mflash. +@deffn Command {xmc4xxx flash_unprotect} bank_id user_level[0-1] +Removes Flash write protection from the selected user bank @end deffn -@deffn Command {mflash write} num filename offset -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{programmingusinggdb,,Programming using GDB}, -or using the cmds given in @ref{flashprogrammingcommands,,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 optionally 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 if @option{exit} parameter is given. -@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 exit" - -# binary files need the flash address passing -openocd -f board/stm32f3discovery.cfg \ - -c "program filename.bin exit 0x08000000" -@end example - -@node NAND Flash Commands -@chapter NAND Flash Commands +@section NAND Flash Commands @cindex NAND Compared to NOR or SPI flash, NAND devices are inexpensive @@ -6028,7 +5931,7 @@ Some larger devices will work, since they are actually multi-chip modules with two smaller chips and individual chipselect lines. @anchor{nandconfiguration} -@section NAND Configuration Commands +@subsection NAND Configuration Commands @cindex NAND configuration NAND chips must be declared in configuration scripts, @@ -6085,7 +5988,7 @@ You must (successfully) probe a device before you can use it with most other NAND commands. @end deffn -@section Erasing, Reading, Writing to NAND Flash +@subsection Erasing, Reading, Writing to NAND Flash @deffn Command {nand dump} num filename offset length [oob_option] @cindex NAND reading @@ -6227,7 +6130,7 @@ hardward-computed ECC before the data is written. This limitation may be removed in a future release. @end deffn -@section Other NAND commands +@subsection Other NAND commands @cindex NAND other commands @deffn Command {nand check_bad_blocks} num [offset length] @@ -6271,7 +6174,7 @@ with the wrong ECC data can cause them to be marked as bad. @end deffn @anchor{nanddriverlist} -@section NAND Driver List +@subsection NAND Driver List As noted above, the @command{nand device} command allows driver-specific options and behaviors. Some controllers also activate controller-specific commands. @@ -6391,6 +6294,100 @@ or @code{read_page} methods, so @command{nand raw_access} won't change any behavior. @end deffn +@section mFlash + +@subsection mFlash Configuration +@cindex mFlash Configuration + +@deffn {Config Command} {mflash bank} soc base RST_pin target +Configures a mflash for @var{soc} host bank at +address @var{base}. +The pin number format depends on the host GPIO naming convention. +Currently, the mflash driver supports s3c2440 and pxa270. + +Example for s3c2440 mflash where @var{RST pin} is GPIO B1: + +@example +mflash bank $_FLASHNAME s3c2440 0x10000000 1b 0 +@end example + +Example for pxa270 mflash where @var{RST pin} is GPIO 43: + +@example +mflash bank $_FLASHNAME pxa270 0x08000000 43 0 +@end example +@end deffn + +@subsection mFlash commands +@cindex mFlash commands + +@deffn Command {mflash config pll} frequency +Configure mflash PLL. +The @var{frequency} is the mflash input frequency, in Hz. +Issuing this command will erase mflash's whole internal nand and write new pll. +After this command, mflash needs power-on-reset for normal operation. +If pll was newly configured, storage and boot(optional) info also need to be update. +@end deffn + +@deffn Command {mflash config boot} +Configure bootable option. +If bootable option is set, mflash offer the first 8 sectors +(4kB) for boot. +@end deffn + +@deffn Command {mflash config storage} +Configure storage information. +For the normal storage operation, this information must be +written. +@end deffn + +@deffn Command {mflash dump} num filename offset size +Dump @var{size} bytes, starting at @var{offset} bytes from the +beginning of the bank @var{num}, to the file named @var{filename}. +@end deffn + +@deffn Command {mflash probe} +Probe mflash. +@end deffn + +@deffn Command {mflash write} num filename offset +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{programmingusinggdb,,Programming using GDB}, +or using the cmds given in @ref{flashprogrammingcommands,,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 optionally 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 if @option{exit} parameter is given. +@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 exit" + +# binary files need the flash address passing +openocd -f board/stm32f3discovery.cfg \ + -c "program filename.bin exit 0x08000000" +@end example + @node PLD/FPGA Commands @chapter PLD/FPGA Commands @cindex PLD @@ -6435,11 +6432,13 @@ Drivers may support PLD-specific options to the @command{pld device} definition command, and may also define commands usable only with that particular type of PLD. -@deffn {FPGA Driver} virtex2 +@deffn {FPGA Driver} virtex2 [no_jstart] Virtex-II is a family of FPGAs sold by Xilinx. It supports the IEEE 1532 standard for In-System Configuration (ISC). -No driver-specific PLD definition options are used, -and one driver-specific command is defined. + +If @var{no_jstart} is non-zero, the JSTART instruction is not used after +loading the bitstream. While required for Series2, Series3, and Series6, it +breaks bitstream loading on Series7. @deffn {Command} {virtex2 read_stat} num Reads and displays the Virtex-II status register (STAT) @@ -6501,8 +6500,10 @@ Useful in connection with script files (@command{script} command and @command{target_name} configuration). @end deffn -@deffn Command shutdown -Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other). +@deffn Command shutdown [@option{error}] +Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, +other). If option @option{error} is used, OpenOCD will return a +non-zero exit code to the parent process. @end deffn @anchor{debuglevel} @@ -6810,7 +6811,8 @@ In addition the following arguments may be specifed: proc load_image_bin @{fname foffset address length @} @{ # Load data from fname filename at foffset offset to # target at address. Load at most length bytes. - load_image $fname [expr $address - $foffset] bin $address $length + load_image $fname [expr $address - $foffset] bin \ + $address $length @} @end example @end deffn @@ -7663,6 +7665,151 @@ fix CSW_SPROT from register AP_REG_CSW on selected dap. Defaulting to 0. @end deffn +@deffn Command {dap ti_be_32_quirks} [@option{enable}] +Set/get quirks mode for TI TMS450/TMS570 processors +Disabled by default +@end deffn + + +@subsection ARMv7-A specific commands +@cindex Cortex-A + +@deffn Command {cortex_a cache_info} +display information about target caches +@end deffn + +@deffn Command {cortex_a dbginit} +Initialize core debug +Enables debug by unlocking the Software Lock and clearing sticky powerdown indications +@end deffn + +@deffn Command {cortex_a smp_off} +Disable SMP mode +@end deffn + +@deffn Command {cortex_a smp_on} +Enable SMP mode +@end deffn + +@deffn Command {cortex_a smp_gdb} [core_id] +Display/set the current core displayed in GDB +@end deffn + +@deffn Command {cortex_a maskisr} [@option{on}|@option{off}] +Selects whether interrupts will be processed when single stepping +@end deffn + +@deffn Command {cache_config l2x} [base way] +configure l2x cache +@end deffn + + +@subsection ARMv7-R specific commands +@cindex Cortex-R + +@deffn Command {cortex_r dbginit} +Initialize core debug +Enables debug by unlocking the Software Lock and clearing sticky powerdown indications +@end deffn + +@deffn Command {cortex_r maskisr} [@option{on}|@option{off}] +Selects whether interrupts will be processed when single stepping +@end deffn + + +@subsection ARMv7-M specific commands +@cindex tracing +@cindex SWO +@cindex SWV +@cindex TPIU +@cindex ITM +@cindex ETM + +@deffn Command {tpiu config} (@option{disable} | ((@option{external} | @option{internal (@var{filename} | -)}) @ + (@option{sync @var{port_width}} | ((@option{manchester} | @option{uart}) @var{formatter_enable})) @ + @var{TRACECLKIN_freq} [@var{trace_freq}])) + +ARMv7-M architecture provides several modules to generate debugging +information internally (ITM, DWT and ETM). Their output is directed +through TPIU to be captured externally either on an SWO pin (this +configuration is called SWV) or on a synchronous parallel trace port. + +This command configures the TPIU module of the target and, if internal +capture mode is selected, starts to capture trace output by using the +debugger adapter features. + +Some targets require additional actions to be performed in the +@b{trace-config} handler for trace port to be activated. + +Command options: +@itemize @minus +@item @option{disable} disable TPIU handling; +@item @option{external} configure TPIU to let user capture trace +output externally (with an additional UART or logic analyzer hardware); +@item @option{internal @var{filename}} configure TPIU and debug adapter to +gather trace data and append it to @var{filename} (which can be +either a regular file or a named pipe); +@item @option{internal -} configure TPIU and debug adapter to +gather trace data, but not write to any file. Useful in conjunction with the @command{tcl_trace} command; +@item @option{sync @var{port_width}} use synchronous parallel trace output +mode, and set port width to @var{port_width}; +@item @option{manchester} use asynchronous SWO mode with Manchester +coding; +@item @option{uart} use asynchronous SWO mode with NRZ (same as +regular UART 8N1) coding; +@item @var{formatter_enable} is @option{on} or @option{off} to enable +or disable TPIU formatter which needs to be used when both ITM and ETM +data is to be output via SWO; +@item @var{TRACECLKIN_freq} this should be specified to match target's +current TRACECLKIN frequency (usually the same as HCLK); +@item @var{trace_freq} trace port frequency. Can be omitted in +internal mode to let the adapter driver select the maximum supported +rate automatically. +@end itemize + +Example usage: +@enumerate +@item STM32L152 board is programmed with an application that configures +PLL to provide core clock with 24MHz frequency; to use ITM output it's +enough to: +@example +#include + ... + ITM_STIM8(0) = c; + ... +@end example +(the most obvious way is to use the first stimulus port for printf, +for that this ITM_STIM8 assignment can be used inside _write(); to make it +blocking to avoid data loss, add @code{while (!(ITM_STIM8(0) & +ITM_STIM_FIFOREADY));}); +@item An FT2232H UART is connected to the SWO pin of the board; +@item Commands to configure UART for 12MHz baud rate: +@example +$ setserial /dev/ttyUSB1 spd_cust divisor 5 +$ stty -F /dev/ttyUSB1 38400 +@end example +(FT2232H's base frequency is 60MHz, spd_cust allows to alias 38400 +baud with our custom divisor to get 12MHz) +@item @code{itmdump -f /dev/ttyUSB1 -d1} +@item OpenOCD invocation line: +@example +openocd -f interface/stlink-v2-1.cfg \ + -c "transport select hla_swd" \ + -f target/stm32l1.cfg \ + -c "tpiu config external uart off 24000000 12000000" +@end example +@end enumerate +@end deffn + +@deffn Command {itm port} @var{port} (@option{0}|@option{1}|@option{on}|@option{off}) +Enable or disable trace output for ITM stimulus @var{port} (counting +from 0). Port 0 is enabled on target creation automatically. +@end deffn + +@deffn Command {itm ports} (@option{0}|@option{1}|@option{on}|@option{off}) +Enable or disable trace output for all ITM stimulus ports. +@end deffn + @subsection Cortex-M specific commands @cindex Cortex-M @@ -8513,6 +8660,7 @@ Currently supported rtos's include: @item @option{linux} @item @option{ChibiOS} @item @option{embKernel} +@item @option{mqx} @end itemize @quotation Note @@ -8526,9 +8674,17 @@ Cyg_Thread::thread_list, Cyg_Scheduler_Base::current_thread. @item ThreadX symbols _tx_thread_current_ptr, _tx_thread_created_ptr, _tx_thread_created_count. @item FreeRTOS symbols +@c The following is taken from recent texinfo to provide compatibility +@c with ancient versions that do not support @raggedright +@tex +\begingroup +\rightskip0pt plus2em \spaceskip.3333em \xspaceskip.5em\relax pxCurrentTCB, pxReadyTasksLists, xDelayedTaskList1, xDelayedTaskList2, pxDelayedTaskList, pxOverflowDelayedTaskList, xPendingReadyList, -xTasksWaitingTermination, xSuspendedTaskList, uxCurrentNumberOfTasks, uxTopUsedPriority. +uxCurrentNumberOfTasks, uxTopUsedPriority. +\par +\endgroup +@end tex @item linux symbols init_task. @item ChibiOS symbols @@ -8536,11 +8692,20 @@ rlist, ch_debug, chSysInit. @item embKernel symbols Rtos::sCurrentTask, Rtos::sListReady, Rtos::sListSleep, Rtos::sListSuspended, Rtos::sMaxPriorities, Rtos::sCurrentTaskCount. +@item mqx symbols +_mqx_kernel_data, MQX_init_struct. @end table For most RTOS supported the above symbols will be exported by default. However for -some, eg. FreeRTOS @option{xTasksWaitingTermination} is only exported -if @option{INCLUDE_vTaskDelete} is defined during the build. +some, eg. FreeRTOS, extra steps must be taken. + +These RTOSes may require additional OpenOCD-specific file to be linked +along with the project: + +@table @code +@item FreeRTOS +contrib/rtos-helpers/FreeRTOS-openocd.c +@end table @node Tcl Scripting API @chapter Tcl Scripting API @@ -8669,6 +8834,50 @@ Remember that most of the OpenOCD commands need to be prefixed with See @file{contrib/rpc_examples/} for specific client implementations. +@section Tcl RPC server notifications +@cindex RPC Notifications + +Notifications are sent asynchronously to other commands being executed over +the RPC server, so the port must be polled continuously. + +Target event, state and reset notifications are emitted as Tcl associative arrays +in the following format. + +@verbatim +type target_event event [event-name] +type target_state state [state-name] +type target_reset mode [reset-mode] +@end verbatim + +@deffn {Command} tcl_notifications [on/off] +Toggle output of target notifications to the current Tcl RPC server. +Only available from the Tcl RPC server. +Defaults to off. + +@end deffn + +@section Tcl RPC server trace output +@cindex RPC trace output + +Trace data is sent asynchronously to other commands being executed over +the RPC server, so the port must be polled continuously. + +Target trace data is emitted as a Tcl associative array in the following format. + +@verbatim +type target_trace data [trace-data-hex-encoded] +@end verbatim + +@deffn {Command} tcl_trace [on/off] +Toggle output of target trace data to the current Tcl RPC server. +Only available from the Tcl RPC server. +Defaults to off. + +See an example application here: +@url{https://github.com/apmorton/OpenOcdTraceUtil} [OpenOcdTraceUtil] + +@end deffn + @node FAQ @chapter FAQ @cindex faq