X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=655a3537be1e66522432ff85ce30d975b8307b51;hb=42c24acebd23d758c543c9bf2c2b97bdbd083c35;hp=0e197c3ca2acb18af60739ffd3a24b30d4243ecd;hpb=ee5ecb8a299fa22f7a7882adebf2a74263fc909f;p=fw%2Fopenocd diff --git a/doc/openocd.texi b/doc/openocd.texi index 0e197c3ca..655a3537b 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 @@ -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 @@ -2127,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] @@ -2191,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 @@ -2673,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} @@ -4633,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. @@ -4715,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 @@ -4759,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 @@ -4811,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 @@ -4963,6 +5068,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 @@ -5028,6 +5140,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 @@ -5218,6 +5343,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. @@ -5290,6 +5462,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 @@ -5466,87 +5661,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: @@ -5584,12 +5706,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 @@ -5640,162 +5756,28 @@ 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 Command {tms470 osc_mhz} clock_mhz +Reports the clock speed, which is used to calculate timings. @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 - -@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 - -@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. +@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 - -@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 @@ -5859,7 +5841,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, @@ -5916,7 +5898,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 @@ -6058,7 +6040,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] @@ -6102,7 +6084,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. @@ -6222,6 +6204,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 @@ -6266,11 +6342,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) @@ -7497,6 +7575,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 @@ -7505,7 +7635,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}])) @@ -7529,6 +7659,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 @@ -8452,11 +8584,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 -@raggedright +@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, uxCurrentNumberOfTasks, uxTopUsedPriority. -@end raggedright +\par +\endgroup +@end tex @item linux symbols init_task. @item ChibiOS symbols @@ -8628,6 +8766,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