* Running:: Running OpenOCD
* OpenOCD Project Setup:: OpenOCD Project Setup
* Config File Guidelines:: Config File Guidelines
-* Daemon Configuration:: Daemon Configuration
+* Server Configuration:: Server Configuration
* Debug Adapter Configuration:: Debug Adapter Configuration
* Reset Configuration:: Reset Configuration
* TAP Declaration:: TAP Declaration
@item @b{bcm2835gpio}
@* A BCM2835-based board (e.g. Raspberry Pi) using the GPIO pins of the expansion header.
+@item @b{imx_gpio}
+@* A NXP i.MX-based board (e.g. Wandboard) using the GPIO pins (should work on any i.MX processor).
+
@item @b{jtag_vpi}
@* A JTAG driver acting as a client for the JTAG VPI server interface.
@* Link: @url{http://github.com/fjullien/jtag_vpi}
--version | -v display OpenOCD version
--file | -f use configuration file <name>
--search | -s dir to search for config files and scripts
---debug | -d set debug level <0-3>
+--debug | -d set debug level to 3
+ | -d<n> set debug level to <level>
--log_output | -l redirect log output to file <name>
--command | -c run <command>
@end verbatim
At the end of the configuration stage it verifies the JTAG scan
chain defined using those commands; your configuration should
ensure that this always succeeds.
-Normally, OpenOCD then starts running as a daemon.
+Normally, OpenOCD then starts running as a server.
Alternatively, commands may be used to terminate the configuration
stage early, perform work (such as updating some flash memory),
-and then shut down without acting as a daemon.
+and then shut down without acting as a server.
-Once OpenOCD starts running as a daemon, it waits for connections from
-clients (Telnet, GDB, Other) and processes the commands issued through
+Once OpenOCD starts running as a server, it waits for connections from
+clients (Telnet, GDB, RPC) and processes the commands issued through
those channels.
If you are having problems, you can enable internal debug messages via
setting from within a telnet or gdb session using @command{debug_level<n>}
(@pxref{debuglevel,,debug_level}).
-You can redirect all output from the daemon to a file using the
+You can redirect all output from the server to a file using the
@option{-l <logfile>} switch.
Note! OpenOCD will launch the GDB & telnet server even if it can not
a board with an Atmel AT91SAM7X256 microcontroller:
@example
-source [find interface/signalyzer.cfg]
+source [find interface/ftdi/signalyzer.cfg]
# GDB can also flash my flash!
gdb_memory_map enable
Here is the command line equivalent of that configuration:
@example
-openocd -f interface/signalyzer.cfg \
+openocd -f interface/ftdi/signalyzer.cfg \
-c "gdb_memory_map enable" \
-c "gdb_flash_program enable" \
-f target/sam7x256.cfg
-@node Daemon Configuration
-@chapter Daemon Configuration
+@node Server Configuration
+@chapter Server Configuration
@cindex initialization
The commands here are commonly found in the openocd.cfg file and are
used to specify what TCP/IP ports are used, and how GDB should be
the normal use cases.
No arguments reports GDB port. "pipe" means listen to stdin
-output to stdout, an integer is base port number, "disable"
+output to stdout, an integer is base port number, "disabled"
disables the gdb server.
When using "pipe", also use log_output to redirect the log
Cirrus Logic EP93xx based single-board computer bit-banging (in development)
@end deffn
-@deffn {Interface Driver} {ft2232}
-FTDI FT2232 (USB) based devices over one of the userspace libraries.
-
-Note that this driver has several flaws and the @command{ftdi} driver is
-recommended as its replacement.
-
-These interfaces have several commands, used to configure the driver
-before initializing the JTAG scan chain:
-
-@deffn {Config Command} {ft2232_device_desc} description
-Provides the USB device description (the @emph{iProduct string})
-of the FTDI FT2232 device. If not
-specified, the FTDI default value is used. This setting is only valid
-if compiled with FTD2XX support.
-@end deffn
-
-@deffn {Config Command} {ft2232_serial} serial-number
-Specifies the @var{serial-number} of the FTDI FT2232 device to use,
-in case the vendor provides unique IDs and more than one FT2232 device
-is connected to the host.
-If not specified, serial numbers are not considered.
-(Note that USB serial numbers can be arbitrary Unicode strings,
-and are not restricted to containing only decimal digits.)
-@end deffn
-
-@deffn {Config Command} {ft2232_layout} name
-Each vendor's FT2232 device can use different GPIO signals
-to control output-enables, reset signals, and LEDs.
-Currently valid layout @var{name} values include:
-@itemize @minus
-@item @b{axm0432_jtag} Axiom AXM-0432
-@item @b{comstick} Hitex STR9 comstick
-@item @b{cortino} Hitex Cortino JTAG interface
-@item @b{evb_lm3s811} TI/Luminary Micro EVB_LM3S811 as a JTAG interface,
-either for the local Cortex-M3 (SRST only)
-or in a passthrough mode (neither SRST nor TRST)
-This layout can not support the SWO trace mechanism, and should be
-used only for older boards (before rev C).
-@item @b{luminary_icdi} This layout should be used with most TI/Luminary
-eval boards, including Rev C LM3S811 eval boards and the eponymous
-ICDI boards, to debug either the local Cortex-M3 or in passthrough mode
-to debug some other target. It can support the SWO trace mechanism.
-@item @b{flyswatter} Tin Can Tools Flyswatter
-@item @b{icebear} ICEbear JTAG adapter from Section 5
-@item @b{jtagkey} Amontec JTAGkey and JTAGkey-Tiny (and compatibles)
-@item @b{jtagkey2} Amontec JTAGkey2 (and compatibles)
-@item @b{m5960} American Microsystems M5960
-@item @b{olimex-jtag} Olimex ARM-USB-OCD and ARM-USB-Tiny
-@item @b{oocdlink} OOCDLink
-@c oocdlink ~= jtagkey_prototype_v1
-@item @b{redbee-econotag} Integrated with a Redbee development board.
-@item @b{redbee-usb} Integrated with a Redbee USB-stick development board.
-@item @b{sheevaplug} Marvell Sheevaplug development kit
-@item @b{signalyzer} Xverve Signalyzer
-@item @b{stm32stick} Hitex STM32 Performance Stick
-@item @b{turtelizer2} egnite Software turtelizer2
-@item @b{usbjtag} "USBJTAG-1" layout described in the OpenOCD diploma thesis
-@end itemize
-@end deffn
-
-@deffn {Config Command} {ft2232_vid_pid} [vid pid]+
-The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI
-default values are used.
-Currently, up to eight [@var{vid}, @var{pid}] pairs may be given, e.g.
-@example
-ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003
-@end example
-@end deffn
-
-@deffn {Config Command} {ft2232_latency} ms
-On some systems using FT2232 based JTAG interfaces the FT_Read function call in
-ft2232_read() fails to return the expected number of bytes. This can be caused by
-USB communication delays and has proved hard to reproduce and debug. Setting the
-FT2232 latency timer to a larger value increases delays for short USB packets but it
-also reduces the risk of timeouts before receiving the expected number of bytes.
-The OpenOCD default value is 2 and for some systems a value of 10 has proved useful.
-@end deffn
-
-@deffn {Config Command} {ft2232_channel} channel
-Used to select the channel of the ft2232 chip to use (between 1 and 4).
-The default value is 1.
-@end deffn
-
-For example, the interface config file for a
-Turtelizer JTAG Adapter looks something like this:
-
-@example
-interface ft2232
-ft2232_device_desc "Turtelizer JTAG/RS232 Adapter"
-ft2232_layout turtelizer2
-ft2232_vid_pid 0x0403 0xbdc8
-@end example
-@end deffn
-
@deffn {Interface Driver} {ftdi}
This driver is for adapters using the MPSSE (Multi-Protocol Synchronous Serial
Engine) mode built into many FTDI chips, such as the FT2232, FT4232 and FT232H.
-It is a complete rewrite to address a large number of problems with the ft2232
-interface driver.
The driver is using libusb-1.0 in asynchronous mode to talk to the FTDI device,
-bypassing intermediate libraries like libftdi of D2XX. Performance-wise it is
-consistently faster than the ft2232 driver, sometimes several times faster.
+bypassing intermediate libraries like libftdi or D2XX.
-A major improvement of this driver is that support for new FTDI based adapters
-can be added competely through configuration files, without the need to patch
-and rebuild OpenOCD.
+Support for new FTDI based adapters can be added competely through
+configuration files, without the need to patch and rebuild OpenOCD.
The driver uses a signal abstraction to enable Tcl configuration files to
define outputs for one or several FTDI GPIO. These outputs can then be
will be used for their customary purpose. Inputs can be read using the
@command{ftdi_get_signal} command.
+To support SWD, a signal named SWD_EN must be defined. It is set to 1 when the
+SWD protocol is selected. When set, the adapter should route the SWDIO pin to
+the data input. An SWDIO_OE signal, if defined, will be set to 1 or 0 as
+required by the protocol, to tell the adapter to drive the data output onto
+the SWDIO pin or keep the SWDIO pin Hi-Z, respectively.
+
Depending on the type of buffer attached to the FTDI GPIO, the outputs have to
be controlled differently. In order to support tristateable signals such as
nSRST, both a data GPIO and an output-enable GPIO can be specified for each
before initializing the JTAG scan chain:
@deffn {Config Command} {ftdi_vid_pid} [vid pid]+
-The vendor ID and product ID of the adapter. If not specified, the FTDI
-default values are used.
-Currently, up to eight [@var{vid}, @var{pid}] pairs may be given, e.g.
+The vendor ID and product ID of the adapter. Up to eight
+[@var{vid}, @var{pid}] pairs may be given, e.g.
@example
ftdi_vid_pid 0x0403 0xcff8 0x15ba 0x0003
@end example
@end example
@end deffn
-@deffn {Command} {usb_blaster_lowlevel_driver} (@option{ftdi}|@option{ftd2xx}|@option{ublast2})
+@deffn {Command} {usb_blaster_lowlevel_driver} (@option{ftdi}|@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}.
@deffn {Command} {jlink config write}
Write the current configuration to the internal persistent storage.
@end deffn
+@deffn {Command} {jlink emucom write <channel> <data>}
+Write data to an EMUCOM channel. The data needs to be encoded as hexadecimal
+pairs.
+
+The following example shows how to write the three bytes 0xaa, 0x0b and 0x23 to
+the EMUCOM channel 0x10:
+@example
+> jlink emucom write 0x10 aa0b23
+@end example
+@end deffn
+@deffn {Command} {jlink emucom read <channel> <length>}
+Read data from an EMUCOM channel. The read data is encoded as hexadecimal
+pairs.
+
+The following example shows how to read 4 bytes from the EMUCOM channel 0x0:
+@example
+> jlink emucom read 0x0 4
+77a90000
+@end example
+@end deffn
@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
@end deffn
@end deffn
+@deffn {Interface Driver} {kitprog}
+This driver is for Cypress Semiconductor's KitProg adapters. The KitProg is an
+SWD-only adapter that is designed to be used with Cypress's PSoC and PRoC device
+families, but it is possible to use it with some other devices. If you are using
+this adapter with a PSoC or a PRoC, you may need to add
+@command{kitprog_init_acquire_psoc} or @command{kitprog acquire_psoc} to your
+configuration script.
+
+Note that this driver is for the proprietary KitProg protocol, not the CMSIS-DAP
+mode introduced in firmware 2.14. If the KitProg is in CMSIS-DAP mode, it cannot
+be used with this driver, and must either be used with the cmsis-dap driver or
+switched back to KitProg mode. See the Cypress KitProg User Guide for
+instructions on how to switch KitProg modes.
+
+Known limitations:
+@itemize @bullet
+@item The frequency of SWCLK cannot be configured, and varies between 1.6 MHz
+and 2.7 MHz.
+@item For firmware versions below 2.14, "JTAG to SWD" sequences are replaced by
+"SWD line reset" in the driver. This is for two reasons. First, the KitProg does
+not support sending arbitrary SWD sequences, and only firmware 2.14 and later
+implement both "JTAG to SWD" and "SWD line reset" in firmware. Earlier firmware
+versions only implement "SWD line reset". Second, due to a firmware quirk, an
+SWD sequence must be sent after every target reset in order to re-establish
+communications with the target.
+@item Due in part to the limitation above, KitProg devices with firmware below
+version 2.14 will need to use @command{kitprog_init_acquire_psoc} in order to
+communicate with PSoC 5LP devices. This is because, assuming debug is not
+disabled on the PSoC, the PSoC 5LP needs its JTAG interface switched to SWD
+mode before communication can begin, but prior to firmware 2.14, "JTAG to SWD"
+could only be sent with an acquisition sequence.
+@end itemize
+
+@deffn {Config Command} {kitprog_init_acquire_psoc}
+Indicate that a PSoC acquisition sequence needs to be run during adapter init.
+Please be aware that the acquisition sequence hard-resets the target.
+@end deffn
+
+@deffn {Config Command} {kitprog_serial} serial
+Select a KitProg device by its @var{serial}. If left unspecified, the first
+device detected by OpenOCD will be used.
+@end deffn
+
+@deffn {Command} {kitprog acquire_psoc}
+Run a PSoC acquisition sequence immediately. Typically, this should not be used
+outside of the target-specific configuration scripts since it hard-resets the
+target as a side-effect.
+This is necessary for "reset halt" on some PSoC 4 series devices.
+@end deffn
+
+@deffn {Command} {kitprog info}
+Display various adapter information, such as the hardware version, firmware
+version, and target voltage.
+@end deffn
+@end deffn
+
@deffn {Interface Driver} {parport}
Supports PC parallel port bit-banging cables:
Wigglers, PLD download cable, and more.
Specifies the adapter layout to use.
@end deffn
-@deffn {Config Command} {hla_vid_pid} vid pid
-The vendor ID and product ID of the device.
+@deffn {Config Command} {hla_vid_pid} [vid pid]+
+Pairs of vendor IDs and product IDs of the device.
@end deffn
@deffn {Command} {hla_command} command
@end deffn
+@deffn {Interface Driver} {imx_gpio}
+i.MX SoC is present in many community boards. Wandboard is an example
+of the one which is most popular.
+
+This driver is mostly the same as bcm2835gpio.
+
+See @file{interface/imx-native.cfg} for a sample config and
+pinout.
+
+@end deffn
+
+
+@deffn {Interface Driver} {openjtag}
+OpenJTAG compatible USB adapter.
+This defines some driver-specific commands:
+
+@deffn {Config Command} {openjtag_variant} variant
+Specifies the variant of the OpenJTAG adapter (see @uref{http://www.openjtag.org/}).
+Currently valid @var{variant} values include:
+
+@itemize @minus
+@item @b{standard} Standard variant (default).
+@item @b{cy7c65215} Cypress CY7C65215 Dual Channel USB-Serial Bridge Controller
+(see @uref{http://www.cypress.com/?rID=82870}).
+@end itemize
+@end deffn
+
+@deffn {Config Command} {openjtag_device_desc} string
+The USB device description string of the adapter.
+This value is only used with the standard variant.
+@end deffn
+@end deffn
+
@section Transport Configuration
@cindex Transport
As noted earlier, depending on the version of OpenOCD you use,
@item @code{cortex_a} -- this is an ARMv7 core with an MMU
@item @code{cortex_m} -- this is an ARMv7 core, supporting only the
compact Thumb2 instruction set.
+@item @code{aarch64} -- this is an ARMv8-A core with an MMU
@item @code{dragonite} -- resembles arm966e
@item @code{dsp563xx} -- implements Freescale's 24-bit DSP.
(Support for this is still incomplete.)
licenced, not a vendor brand which incorporates that design.
Name prefixes like arm7, arm9, arm11, and cortex
reflect design generations;
-while names like ARMv4, ARMv5, ARMv6, and ARMv7
+while names like ARMv4, ARMv5, ARMv6, ARMv7 and ARMv8
reflect an architecture version implemented by a CPU design.
@anchor{targetconfiguration}
@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{mqx}
+@var{rtos_type} can be one of @option{auto}, @option{eCos},
+@option{ThreadX}, @option{FreeRTOS}, @option{linux}, @option{ChibiOS},
+@option{embKernel}, @option{mqx}, @option{uCOS-III}
@xref{gdbrtossupport,,RTOS Support}.
+@item @code{-defer-examine} -- skip target examination at initial JTAG chain
+scan and after a reset. A manual call to arp_examine is required to
+access the target for debugging.
+
+@item @code{-ap-num} @var{ap_number} -- set DAP access port for target,
+@var{ap_number} is the numeric index of the DAP AP the target is connected to.
+Use this option with systems where multiple, independent cores are connected
+to separate access ports of the same DAP.
+
+@item @code{-ctibase} @var{address} -- set base address of Cross-Trigger interface (CTI) connected
+to the target. Currently, only the @code{aarch64} target makes use of this option, where it is
+a mandatory configuration for the target run control.
@end itemize
@end deffn
The commands supported by OpenOCD target objects are:
-@deffn Command {$target_name arp_examine}
+@deffn Command {$target_name arp_examine} @option{allow-defer}
@deffnx Command {$target_name arp_halt}
@deffnx Command {$target_name arp_poll}
@deffnx Command {$target_name arp_reset}
released on the scan chain.
@item @b{reset-end}
@* Issued as the final step in @command{reset} processing.
-@ignore
-@item @b{reset-halt-post}
-@* Currently not used
-@item @b{reset-halt-pre}
-@* Currently not used
-@end ignore
@item @b{reset-init}
@* Used by @b{reset init} command for board-specific initialization.
This event fires after @emph{reset-deassert-post}.
This is the most robust place to use @command{jtag_rclk}
or @command{adapter_khz} to switch to a low JTAG clock rate,
when reset disables PLLs needed to use a fast clock.
-@ignore
-@item @b{reset-wait-pos}
-@* Currently not used
-@item @b{reset-wait-pre}
-@* Currently not used
-@end ignore
@item @b{resume-start}
@* Before any target is resumed
@item @b{resume-end}
@end deffn
@comment no current checks for errors if fill blocks touch multiple banks!
-@deffn Command {flash write_bank} num filename offset
+@deffn Command {flash write_bank} num filename [offset]
Write the binary @file{filename} to flash bank @var{num},
-starting at @var{offset} bytes from the beginning of the bank.
+starting at @var{offset} bytes from the beginning of the bank. If @var{offset}
+is omitted, start at the beginning of the flash bank.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {flash read_bank} num filename offset length
+@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}.
+and write the contents to the binary @file{filename}. If @var{offset} is
+omitted, start at the beginning of the flash bank. If @var{length} is omitted,
+read the remaining bytes from the flash bank.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {flash verify_bank} num filename offset
+@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.
+flash bank @var{num} starting at @var{offset}. If @var{offset} is omitted,
+start at the beginning of the flash bank. Fail if the contents do not match.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {flash info} num
-Print info about flash bank @var{num}
+@deffn Command {flash info} num [sectors]
+Print info about flash bank @var{num}, a list of protection blocks
+and their status. Use @option{sectors} to show a list of sectors instead.
+
The @var{num} parameter is a value shown by @command{flash banks}.
This command will first query the hardware, it does not print cached
and possibly stale information.
@anchor{flashprotect}
@deffn Command {flash protect} num first last (@option{on}|@option{off})
-Enable (@option{on}) or disable (@option{off}) protection of flash sectors
-in flash bank @var{num}, starting at sector @var{first}
+Enable (@option{on}) or disable (@option{off}) protection of flash blocks
+in flash bank @var{num}, starting at protection block @var{first}
and continuing up to and including @var{last}.
-Providing a @var{last} sector of @option{last}
+Providing a @var{last} block of @option{last}
specifies "to the end of the flash bank".
The @var{num} parameter is a value shown by @command{flash banks}.
+The protection block is usually identical to a flash sector.
+Some devices may utilize a protection block distinct from flash sector.
+See @command{flash info} for a list of protection blocks.
@end deffn
@deffn Command {flash padded_value} num value
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
+flash bank vbank0 virtual 0xbfc00000 0 0 0 \
+ $_TARGETNAME $_FLASHNAME
+flash bank vbank1 virtual 0x9fc00000 0 0 0 \
+ $_TARGETNAME $_FLASHNAME
@end example
@end deffn
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.
+@file{contrib/loaders/flash/fpga/xilinx_bscan_spi.py}. It requires
+@uref{https://github.com/m-labs/migen, 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
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
+flash bank $_FLASHNAME spi 0x0 0 0 0 \
+ $_TARGETNAME $_XILINX_USER1 $_DR_LENGTH
@end example
@end deffn
@end deffn
+@deffn {Flash Driver} ath79
+@cindex Atheros ath79 SPI driver
+@cindex ath79
+Members of ATH79 SoC family from Atheros include a SPI interface with 3
+chip selects.
+On reset a SPI flash connected to the first chip select (CS0) is made
+directly read-accessible in the CPU address space (up to 16MBytes)
+and is usually used to store the bootloader and operating system.
+Normal OpenOCD commands like @command{mdw} can be used to display
+the flash content while it is in memory-mapped mode (only the first
+4MBytes are accessible without additional configuration on reset).
+
+The setup command only requires the @var{base} parameter in order
+to identify the memory bank. The actual value for the base address
+is not otherwise used by the driver. However the mapping is passed
+to gdb. Thus for the memory mapped flash (chipselect CS0) the base
+address should be the actual memory mapped base address. For unmapped
+chipselects (CS1 and CS2) care should be taken to use a base address
+that does not overlap with real memory regions.
+Additional information, like flash size, are detected automatically.
+An optional additional parameter sets the chipselect for the bank,
+with the default CS0.
+CS1 and CS2 require additional GPIO setup before they can be used
+since the alternate function must be enabled on the GPIO pin
+CS1/CS2 is routed to on the given SoC.
+
+@example
+flash bank $_FLASHNAME ath79 0 0 0 0 $_TARGETNAME
+
+# When using multiple chipselects the base should be different for each,
+# otherwise the write_image command is not able to distinguish the
+# banks.
+flash bank flash0 ath79 0x00000000 0 0 0 $_TARGETNAME cs0
+flash bank flash1 ath79 0x10000000 0 0 0 $_TARGETNAME cs1
+flash bank flash2 ath79 0x20000000 0 0 0 $_TARGETNAME cs2
+@end example
+
+@end deffn
+
@subsection Internal Flash (Microcontrollers)
@deffn {Flash Driver} aduc702x
# Flash bank 0
flash bank $_FLASHNAME ambiqmicro 0 0x00040000 0 0 $_TARGETNAME
# Flash bank 1 - same size as bank0, starts after bank 0.
-flash bank $_FLASHNAME ambiqmicro 0x00040000 0x00040000 0 0 $_TARGETNAME
+flash bank $_FLASHNAME ambiqmicro 0x00040000 0x00040000 0 0 \
+ $_TARGETNAME
@end example
Flash is programmed using custom entry points into the bootloader.
characters) ignored.
@example
-flash bank $@{_FLASHNAME@}0 fm4 0x00000000 0 0 0 $_TARGETNAME S6E2CCAJ0A
-flash bank $@{_FLASHNAME@}1 fm4 0x00100000 0 0 0 $_TARGETNAME S6E2CCAJ0A
+flash bank $@{_FLASHNAME@}0 fm4 0x00000000 0 0 0 \
+ $_TARGETNAME S6E2CCAJ0A
+flash bank $@{_FLASHNAME@}1 fm4 0x00100000 0 0 0 \
+ $_TARGETNAME S6E2CCAJ0A
@end example
@emph{The current implementation is incomplete. Protection is not supported,
nor is Chip Erase (only Sector Erase is implemented).}
@deffn {Flash Driver} kinetis
@cindex kinetis
-Kx and KLx members of the Kinetis microcontroller family from Freescale include
+Kx, KLx, KVx and KE1x members of the Kinetis microcontroller family
+from NXP (former Freescale) include
internal flash and use ARM Cortex-M0+ or M4 cores. The driver automatically
recognizes flash size and a number of flash banks (1-4) using the chip
identification register, and autoconfigures itself.
+Use kinetis_ke driver for KE0x devices.
+
+The @var{kinetis} driver defines option:
+@itemize
+@item -sim-base @var{addr} ... base of System Integration Module where chip identification resides. Driver tries two known locations if option is omitted.
+@end itemize
@example
flash bank $_FLASHNAME kinetis 0 0 0 0 $_TARGETNAME
@end example
+@deffn Command {kinetis create_banks}
+Configuration command enables automatic creation of additional flash banks
+based on real flash layout of device. Banks are created during device probe.
+Use 'flash probe 0' to force probe.
+@end deffn
+
+@deffn Command {kinetis fcf_source} [protection|write]
+Select what source is used when writing to a Flash Configuration Field.
+@option{protection} mode builds FCF content from protection bits previously
+set by 'flash protect' command.
+This mode is default. MCU is protected from unwanted locking by immediate
+writing FCF after erase of relevant sector.
+@option{write} mode enables direct write to FCF.
+Protection cannot be set by 'flash protect' command. FCF is written along
+with the rest of a flash image.
+@emph{BEWARE: Incorrect flash configuration may permanently lock the device!}
+@end deffn
+
+@deffn Command {kinetis fopt} [num]
+Set value to write to FOPT byte of Flash Configuration Field.
+Used in kinetis 'fcf_source protection' mode only.
+@end deffn
+
@deffn Command {kinetis mdm check_security}
Checks status of device security lock. Used internally in examine-end event.
@end deffn
@deffn {Flash Driver} kinetis_ke
@cindex kinetis_ke
-KE members of the Kinetis microcontroller family from Freescale include
+KE0x members of the Kinetis microcontroller family from Freescale include
internal flash and use ARM Cortex-M0+. The driver automatically recognizes
-the KE family and sub-family using the chip identification register, and
+the KE0x sub-family using the chip identification register, and
autoconfigures itself.
+Use kinetis (not kinetis_ke) driver for KE1x devices.
@example
flash bank $_FLASHNAME kinetis_ke 0 0 0 0 $_TARGETNAME
@end deffn
-@deffn {Flash Driver} nrf51
+@deffn {Flash Driver} nrf5
All members of the nRF51 microcontroller families from Nordic Semiconductor
include internal flash and use ARM Cortex-M0 core.
+Also, the nRF52832 microcontroller from Nordic Semiconductor, which include
+internal flash and use an ARM Cortex-M4F core.
@example
-flash bank $_FLASHNAME nrf51 0 0x00000000 0 0 $_TARGETNAME
+flash bank $_FLASHNAME nrf5 0 0x00000000 0 0 $_TARGETNAME
@end example
-Some nrf51-specific commands are defined:
+Some nrf5-specific commands are defined:
-@deffn Command {nrf51 mass_erase}
+@deffn Command {nrf5 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
families from Texas Instruments include internal flash. The driver
automatically recognizes a number of these chips using the chip
identification register, and autoconfigures itself.
-@footnote{Currently there is a @command{stellaris mass_erase} command.
-That seems pointless since the same effect can be had using the
-standard @command{flash erase_address} command.}
@example
flash bank $_FLASHNAME stellaris 0 0 0 0 $_TARGETNAME
flash bank $_FLASHNAME stm32f1x 0x08080000 0 0 0 $_TARGETNAME
@end example
-Some stm32f1x-specific commands
-@footnote{Currently there is a @command{stm32f1x mass_erase} command.
-That seems pointless since the same effect can be had using the
-standard @command{flash erase_address} command.}
-are defined:
+Some stm32f1x-specific commands are defined:
@deffn Command {stm32f1x lock} num
Locks the entire stm32 device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
+@deffn Command {stm32f1x mass_erase} num
+Mass erases the entire stm32f1x device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
@deffn Command {stm32f1x options_read} num
Read and display the stm32 option bytes written by
the @command{stm32f1x options_write} command.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
+@example
+flash bank $_FLASHNAME stm32f2x 0 0 0 0 $_TARGETNAME
+@end example
+
Note that some devices have been found that have a flash size register that contains
an invalid value, to workaround this issue you can override the probed value used by
the flash driver.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
+@deffn Command {stm32f2x mass_erase} num
+Mass erases the entire stm32f2x device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
@deffn Command {stm32f2x options_read} num
-Reads and displays user options and (where implemented) boot_addr0 and boot_addr1.
+Reads and displays user options and (where implemented) boot_addr0, boot_addr1, optcr2.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@deffn Command {stm32f2x options_write} num user_options boot_addr0 boot_addr1
Writes user options and (where implemented) boot_addr0 and boot_addr1 in raw format.
Warning: The meaning of the various bits depends on the device, always check datasheet!
-The @var{num} parameter is a value shown by @command{flash banks}, user_options a
-12 bit value, consisting of bits 31-28 and 7-0 of FLASH_OPTCR, boot_addr0 and boot_addr1
-two halfwords (of FLASH_OPTCR1).
+The @var{num} parameter is a value shown by @command{flash banks}, @var{user_options} a
+12 bit value, consisting of bits 31-28 and 7-0 of FLASH_OPTCR, @var{boot_addr0} and
+@var{boot_addr1} two halfwords (of FLASH_OPTCR1).
+@end deffn
+
+@deffn Command {stm32f2x optcr2_write} num optcr2
+Writes FLASH_OPTCR2 options. Warning: Clearing PCROPi bits requires a full mass erase!
+The @var{num} parameter is a value shown by @command{flash banks}, @var{optcr2} a 32-bit word.
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} stm32h7x
+All members of the STM32H7 microcontroller families from ST Microelectronics
+include internal flash and use ARM Cortex-M7 core.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+
+@example
+flash bank $_FLASHNAME stm32h7x 0 0 0 0 $_TARGETNAME
+@end example
+
+Note that some devices have been found that have a flash size register that contains
+an invalid value, to workaround this issue you can override the probed value used by
+the flash driver.
+
+@example
+flash bank $_FLASHNAME stm32h7x 0 0x20000 0 0 $_TARGETNAME
+@end example
+
+Some stm32h7x-specific commands are defined:
+
+@deffn Command {stm32h7x lock} num
+Locks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32h7x unlock} num
+Unlocks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32h7x mass_erase} num
+Mass erases the entire stm32h7x device.
+The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@end deffn
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
+@example
+flash bank $_FLASHNAME stm32lx 0 0 0 0 $_TARGETNAME
+@end example
+
Note that some devices have been found that have a flash size register that contains
an invalid value, to workaround this issue you can override the probed value used by
the flash driver. If you use 0 as the bank base address, it tells the
Some stm32lx-specific commands are defined:
+@deffn Command {stm32lx lock} num
+Locks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32lx unlock} num
+Unlocks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
@deffn Command {stm32lx mass_erase} num
Mass erases the entire stm32lx device (all flash banks and EEPROM
data). This is the only way to unlock a protected flash (unless RDP
@end deffn
@end deffn
+@deffn {Flash Driver} stm32l4x
+All members of the STM32L4 microcontroller families from ST Microelectronics
+include internal flash and use ARM Cortex-M4 cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+
+@example
+flash bank $_FLASHNAME stm32l4x 0 0 0 0 $_TARGETNAME
+@end example
+
+Note that some devices have been found that have a flash size register that contains
+an invalid value, to workaround this issue you can override the probed value used by
+the flash driver.
+
+@example
+flash bank $_FLASHNAME stm32l4x 0x08000000 0x40000 0 0 $_TARGETNAME
+@end example
+
+Some stm32l4x-specific commands are defined:
+
+@deffn Command {stm32l4x lock} num
+Locks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32l4x unlock} num
+Unlocks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32l4x mass_erase} num
+Mass erases the entire stm32l4x device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+@end deffn
+
@deffn {Flash Driver} str7x
All members of the STR7 microcontroller family from ST Microelectronics
include internal flash and use ARM7TDMI cores.
@end itemize
-@section Daemon Commands
+@section Server Commands
@deffn {Command} exit
Exits the current telnet session.
@end deffn
@deffn Command shutdown [@option{error}]
-Close the OpenOCD daemon, disconnecting all clients (GDB, telnet,
+Close the OpenOCD server, 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
@deffn Command debug_level [n]
@cindex message level
Display debug level.
-If @var{n} (from 0..3) is provided, then set it to that level.
+If @var{n} (from 0..4) is provided, then set it to that level.
This affects the kind of messages sent to the server log.
Level 0 is error messages only;
level 1 adds warnings;
level 2 adds informational messages;
-and level 3 adds debugging messages.
+level 3 adds debugging messages;
+and level 4 adds verbose low-level debug messages.
The default is level 2, but that can be overridden on
the command line along with the location of that log
file (which is normally the server's standard output).
This will first attempt a comparison using a CRC checksum, if this fails it will try a binary compare.
@end deffn
+@deffn Command {verify_image_checksum} filename address [@option{bin}|@option{ihex}|@option{elf}]
+Verify @var{filename} against target memory starting at @var{address}.
+The file format may optionally be specified
+(@option{bin}, @option{ihex}, or @option{elf})
+This perform a comparison using a CRC checksum only
+@end deffn
+
@section Breakpoint and Watchpoint commands
@cindex breakpoint
Supervisor Call vector by OpenOCD.
@end deffn
+@deffn Command {arm semihosting_cmdline} [@option{enable}|@option{disable}]
+@cindex ARM semihosting
+Set the command line to be passed to the debuggee.
+
+@example
+arm semihosting_cmdline argv0 argv1 argv2 ...
+@end example
+
+This option lets one set the command line arguments to be passed to
+the program. The first argument (argv0) is the program name in a
+standard C environment (argv[0]). Depending on the program (not much
+programs look at argv[0]), argv0 is ignored and can be any string.
+@end deffn
+
+@deffn Command {arm semihosting_fileio} [@option{enable}|@option{disable}]
+@cindex ARM semihosting
+Display status of semihosting fileio, after optionally changing that
+status.
+
+Enabling this option forwards semihosting I/O to GDB process using the
+File-I/O remote protocol extension. This is especially useful for
+interacting with remote files or displaying console messages in the
+debugger.
+@end deffn
+
@section ARMv4 and ARMv5 Architecture
@cindex ARMv4
@cindex ARMv5
cores @emph{except the ARM1176} use the same six bits.
@end deffn
-@section ARMv7 Architecture
+@section ARMv7 and ARMv8 Architecture
@cindex ARMv7
+@cindex ARMv8
-@subsection ARMv7 Debug Access Port (DAP) specific commands
+@subsection ARMv7 and ARMv8 Debug Access Port (DAP) specific commands
@cindex Debug Access Port
@cindex DAP
-These commands are specific to ARM architecture v7 Debug Access Port (DAP),
+These commands are specific to ARM architecture v7 and v8 Debug Access Port (DAP),
included on Cortex-M and Cortex-A systems.
They are available in addition to other core-specific commands that may be available.
@xref{targetevents,,Target Events}.
@end deffn
+@subsection ARMv8-A specific commands
+@cindex ARMv8-A
+@cindex aarch64
+
+@deffn Command {aarch64 cache_info}
+Display information about target caches
+@end deffn
+
+@deffn Command {aarch64 dbginit}
+This command enables debugging by clearing the OS Lock and sticky power-down and reset
+indications. It also establishes the expected, basic cross-trigger configuration the aarch64
+target code relies on. In a configuration file, the command would typically be called from a
+@code{reset-end} or @code{reset-deassert-post} handler, to re-enable debugging after a system reset.
+However, normally it is not necessary to use the command at all.
+@end deffn
+
+@deffn Command {aarch64 smp_on|smp_off}
+Enable and disable SMP handling. The state of SMP handling influences the way targets in an SMP group
+are handled by the run control. With SMP handling enabled, issuing halt or resume to one core will trigger
+halting or resuming of all cores in the group. The command @code{target smp} defines which targets are in the SMP
+group. With SMP handling disabled, all targets need to be treated individually.
+@end deffn
+
@section Intel Architecture
Intel Quark X10xx is the first product in the Quark family of SoCs. It is an IA-32
@anchor{gdbrtossupport}
OpenOCD includes RTOS support, this will however need enabling as it defaults to disabled.
-It can be enabled by passing @option{-rtos} arg to the target @xref{rtostype,,RTOS Type}.
+It can be enabled by passing @option{-rtos} arg to the target. @xref{rtostype,,RTOS Type}.
+
+@xref{Threads, Debugging Programs with Multiple Threads,
+Debugging Programs with Multiple Threads, gdb, GDB manual}, for details about relevant
+GDB commands.
@* An example setup is below:
@item @option{ChibiOS}
@item @option{embKernel}
@item @option{mqx}
+@item @option{uCOS-III}
@end itemize
@quotation Note
Rtos::sListSuspended, Rtos::sMaxPriorities, Rtos::sCurrentTaskCount.
@item mqx symbols
_mqx_kernel_data, MQX_init_struct.
+@item uC/OS-III symbols
+OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty
@end table
For most RTOS supported the above symbols will be exported by default. However for
-some, eg. FreeRTOS, extra steps must be taken.
+some, eg. FreeRTOS and uC/OS-III, 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
+@item uC/OS-III
+contrib/rtos-helpers/uCOS-III-openocd.c
@end table
@node Tcl Scripting API
@b{Laptops running on battery have this problem too...}
-@item @b{USB Power} When using the Amontec JTAGkey, sometimes OpenOCD crashes with the
-following error messages: "Error: ft2232.c:201 ft2232_read(): FT_Read returned:
-4" and "Error: ft2232.c:365 ft2232_send_and_recv(): couldn't read from FT2232".
-What does that mean and what might be the reason for this?
-
-First of all, the reason might be the USB power supply. Try using a self-powered
-hub instead of a direct connection to your computer. Secondly, the error code 4
-corresponds to an FT_IO_ERROR, which means that the driver for the FTDI USB
-chip ran into some sort of error - this points us to a USB problem.
-
@item @b{GDB Disconnects} When using the Amontec JTAGkey, sometimes OpenOCD crashes with the following
error message: "Error: gdb_server.c:101 gdb_get_char(): read: 10054".
What does that mean and what might be the reason for this?
Code Review / openocd.git / blobdiff