@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}
Engine) mode built into many FTDI chips, such as the FT2232, FT4232 and FT232H.
The driver is using libusb-1.0 in asynchronous mode to talk to the FTDI device,
-bypassing intermediate libraries like libftdi of D2XX.
+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
@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.
@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:
@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}|
-@option{uCOS-III}
+@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 @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
@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.
@example
flash bank $_FLASHNAME kinetis 0 0 0 0 $_TARGETNAME
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:
projects / openocd / blobdiff