X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=0608a28d231060c8b04dc45c8b7361cb6d4bf8cd;hb=4124e5deb4d95be490a6127ae15f28b1403a969e;hp=140e86b406756acee46d22af62dadf8350153ef9;hpb=2d99a0defa8fde13d4f421d54dbb6246b908303d;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 140e86b406..0608a28d23 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -2126,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] @@ -4644,6 +4649,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. @@ -4790,6 +4807,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 @@ -5072,6 +5132,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 @@ -5262,6 +5335,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. @@ -5334,6 +5454,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 @@ -5626,89 +5769,6 @@ the flash clock. @end deffn @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 - -@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} 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 NAND Flash Commands @cindex NAND @@ -7515,7 +7575,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}])) @@ -7539,6 +7599,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 @@ -8644,6 +8706,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