X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=14835a919cb292d22e898d95d7d3950114abf75c;hp=5a803d2c7b61a83101cfab3484763b78cd28fe9c;hb=751e2454bf076708d3e695833c4def460ab41d8b;hpb=f3b1405fddf0b32af27ad3894841f7d1702d8e5a diff --git a/doc/openocd.texi b/doc/openocd.texi index 5a803d2c7b..14835a919c 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 @@ -471,7 +470,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 +700,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 +735,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 +1296,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 +1315,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 @@ -2331,6 +2127,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 +2196,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 +2678,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} @@ -4218,14 +4031,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 @@ -4549,7 +4362,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 @@ -4836,6 +4650,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. @@ -4918,6 +4744,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 @@ -4962,6 +4808,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 @@ -5014,6 +4903,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 @@ -5031,6 +4933,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 @@ -5078,6 +4983,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} @@ -5166,6 +5077,13 @@ 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 @@ -5231,6 +5149,19 @@ 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 @@ -5421,6 +5352,53 @@ 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} 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. @@ -5493,6 +5471,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 @@ -5634,7 +5635,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 @@ -5668,87 +5670,14 @@ 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. - -Some tms470-specific commands are defined: - -@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 Command {tms470 osc_mhz} clock_mhz -Reports the clock speed, which is used to calculate timings. -@end deffn - -@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 +@deffn {Flash Driver} str9xpec @cindex 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. + Here is some background info to help you better understand how this driver works. OpenOCD has two flash drivers for the str9: @@ -5786,12 +5715,6 @@ When performing a unlock remember that you will not be able to halt the str9 - i 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 @@ -5842,128 +5765,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 @@ -6027,7 +5866,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, @@ -6084,7 +5923,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 @@ -6226,7 +6065,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] @@ -6270,7 +6109,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. @@ -6390,6 +6229,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 @@ -6434,11 +6367,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) @@ -6811,7 +6746,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 @@ -7664,6 +7600,58 @@ 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 @@ -7672,7 +7660,7 @@ Defaulting to 0. @cindex ITM @cindex ETM -@deffn Command {tpiu config} (@option{disable} | ((@option{external} | @option{internal @var{filename}}) @ +@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}])) @@ -7696,6 +7684,8 @@ 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 @@ -7736,9 +7726,13 @@ $ stty -F /dev/ttyUSB1 38400 (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 @code{openocd -f interface/stlink-v2-1.cfg -c "transport select -hla_swd" -f target/stm32l1.cfg -c "tpiu config external uart off -24000000 12000000"} +@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 @@ -8615,9 +8609,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 @@ -8630,8 +8632,15 @@ _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 @@ -8782,6 +8791,28 @@ 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