of the Open On-Chip Debugger (OpenOCD).
@itemize @bullet
-@item Copyright @copyright{} 2008 The OpenOCD Project
+@item Copyright @copyright{} 2008-2022 The OpenOCD Project
@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
@item Copyright @copyright{} 2008-2010 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
@item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com}
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts. A copy of the license is included in the section entitled ``GNU
-Free Documentation License''.
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
@end quotation
@end copying
* JTAG Commands:: JTAG Commands
* Boundary Scan Commands:: Boundary Scan Commands
* Utility Commands:: Utility Commands
-* TFTP:: TFTP
* GDB and OpenOCD:: Using GDB and OpenOCD
* Tcl Scripting API:: Tcl Scripting API
* FAQ:: Frequently Asked Questions
@section OpenOCD IRC
Support can also be found on irc:
-@uref{irc://irc.freenode.net/openocd}
+@uref{irc://irc.libera.chat/openocd}
@node Developers
@chapter OpenOCD Developer Resources
All changes in the OpenOCD Git repository go through the web-based Gerrit
Code Review System:
-@uref{http://openocd.zylin.com/}
+@uref{https://review.openocd.org/}
After a one-time registration and repository setup, anyone can push commits
from their local Git repository directly into Gerrit.
@cindex dongles
@cindex FTDI
@cindex wiggler
-@cindex zy1000
@cindex printer port
@cindex USB Adapter
@cindex RTCK
an adapter .... [snip]
In the OpenOCD case, this generally refers to @b{a small adapter} that
-attaches to your computer via USB or the parallel port. One
-exception is the Ultimate Solutions ZY1000, packaged as a small box you
-attach via an ethernet cable. The ZY1000 has the advantage that it does not
-require any drivers to be installed on the developer PC. It also has
-a built in web interface. It supports RTCK/RCLK or adaptive clocking
-and has a built-in relay to power cycle targets remotely.
+attaches to your computer via USB or the parallel port.
@section Choosing a Dongle
@enumerate
@item @b{Transport} Does it support the kind of communication that you need?
-OpenOCD focusses mostly on JTAG. Your version may also support
+OpenOCD focuses mostly on JTAG. Your version may also support
other ways to communicate with target devices.
@item @b{Voltage} What voltage is your target - 1.8, 2.8, 3.3, or 5V?
Does your dongle support it? You might need a level converter.
RTCK support (also known as ``adaptive clocking'')?
@end enumerate
-@section Stand-alone JTAG Probe
-
-The ZY1000 from Ultimate Solutions is technically not a dongle but a
-stand-alone JTAG probe that, unlike most dongles, doesn't require any drivers
-running on the developer's host computer.
-Once installed on a network using DHCP or a static IP assignment, users can
-access the ZY1000 probe locally or remotely from any host with access to the
-IP address assigned to the probe.
-The ZY1000 provides an intuitive web interface with direct access to the
-OpenOCD debugger.
-Users may also run a GDBSERVER directly on the ZY1000 to take full advantage
-of GCC & GDB to debug any distribution of embedded Linux or NetBSD running on
-the target.
-The ZY1000 supports RTCK & RCLK or adaptive clocking and has a built-in relay
-to power cycle the target remotely.
-
-For more information, visit:
-
-@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/210-zylin-zy1000-main}
-
@section USB FT2232 Based
There are many USB JTAG dongles on the market, many of them based
@item @b{STLINK-V3}
@* This is available standalone and as part of some kits.
@* Link: @url{http://www.st.com/stlink-v3}
+@item @b{STLINK-V3PWR}
+@* This is available standalone.
+Beside the debugger functionality, the probe includes a SMU (source
+measurement unit) aimed at analyzing power consumption during code
+execution. The SMU is not supported by OpenOCD.
+@* Link: @url{http://www.st.com/stlink-v3pwr}
@end itemize
For info the original ST-LINK enumerates using the mass storage usb class; however,
It is not to be confused with the FTDI based adapters that were originally fitted to their
evaluation boards. This is the adapter fitted to the Stellaris LaunchPad.
+@section USB Nuvoton Nu-Link
+Nuvoton has an adapter called @b{Nu-Link}.
+It is available either as stand-alone dongle and embedded on development boards.
+It supports SWD, serial port bridge and mass storage for firmware update.
+Both Nu-Link v1 and v2 are supported.
+
@section USB CMSIS-DAP based
ARM has released a interface standard called CMSIS-DAP that simplifies connecting
debuggers to ARM Cortex based targets @url{http://www.keil.com/support/man/docs/dapdebug/dapdebug_introduction.htm}.
@item @b{ARM-JTAG-EW}
@* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html}
+@item @b{angie}
+@* Link: @url{https://nanoxplore.org/}
+
@item @b{Buspirate}
@* Link: @url{http://dangerousprototypes.com/bus-pirate-manual/}
@* Link: @url{http://www.keil.com/ulink1/}
@item @b{TI XDS110 Debug Probe}
-@* The XDS110 is included as the embedded debug probe on many Texas Instruments
-LaunchPad evaluation boards.
-@* The XDS110 is also available as a stand-alone USB debug probe. The XDS110
-stand-alone probe has the additional ability to supply voltage to the target
-board via its AUX FUNCTIONS port. Use the
-@command{xds110_supply_voltage <millivolts>} command to set the voltage. 0 turns
-off the supply. Otherwise, the supply can be set to any value in the range 1800
-to 3600 millivolts.
-@* Link: @url{http://processors.wiki.ti.com/index.php/XDS110}
-@* Link: @url{http://processors.wiki.ti.com/index.php/XDS_Emulation_Software_Package#XDS110_Support_Utilities}
+@* Link: @url{https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_xds110.html}
+@* Link: @url{https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_xds_software_package_download.html#xds110-support-utilities}
@end itemize
@section IBM PC Parallel Printer Port Based
@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{am335xgpio}
+@* A Texas Instruments AM335x-based board (e.g. BeagleBone Black) using the GPIO pins of the expansion headers.
+
@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}
+@item @b{vdebug}
+@* A driver for Cadence virtual Debug Interface to emulated or simulated targets.
+It implements a client connecting to the vdebug server, which in turn communicates
+with the emulated or simulated RTL model through a transactor. The driver supports
+JTAG and DAP-level transports.
+
+@item @b{jtag_dpi}
+@* A JTAG driver acting as a client for the SystemVerilog Direct Programming
+Interface (DPI) for JTAG devices. DPI allows OpenOCD to connect to the JTAG
+interface of a hardware model written in SystemVerilog, for example, on an
+emulation model of target hardware.
+
+@item @b{xlnx_pcie_xvc}
+@* A JTAG driver exposing Xilinx Virtual Cable over PCI Express to OpenOCD as JTAG/SWD interface.
+
+@item @b{linuxgpiod}
+@* A bitbang JTAG driver using Linux GPIO through library libgpiod.
+
+@item @b{sysfsgpio}
+@* A bitbang JTAG driver using Linux legacy sysfs GPIO.
+This is deprecated from Linux v5.3; prefer using @b{linuxgpiod}.
+
+@item @b{esp_usb_jtag}
+@* A JTAG driver to communicate with builtin debug modules of Espressif ESP32-C3 and ESP32-S3 chips using OpenOCD.
+
@end itemize
@node About Jim-Tcl
@item the current directory,
@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 @file{%APPDATA%/OpenOCD} (only on Windows),
+@item @file{$HOME/Library/Preferences/org.openocd} (only on Darwin),
+@item @file{$XDG_CONFIG_HOME/openocd} (@env{$XDG_CONFIG_HOME} defaults to @file{$HOME/.config}),
+@item @file{$HOME/.openocd},
@item the site wide script library @file{$pkgdatadir/site} and
@item the OpenOCD-supplied script library @file{$pkgdatadir/scripts}.
@end enumerate
Today's most common case is a dongle with a JTAG cable on one side
(such as a ribbon cable with a 10-pin or 20-pin IDC connector)
and a USB cable on the other.
-Instead of USB, some cables use Ethernet;
+Instead of USB, some dongles use Ethernet;
older ones may use a PC parallel port, or even a serial port.
@enumerate
@end quotation
@item
-You may may need to write some C code.
+You may need to write some C code.
It may be as simple as supporting a new FT2232 or parport
based adapter; a bit more involved, like a NAND or NOR flash
controller driver; or a big piece of work like supporting
if you have a new kind of hardware interface
and need to provide a driver for it.
+@deffn {Command} {find} 'filename'
+Prints full path to @var{filename} according to OpenOCD search rules.
+@end deffn
+
+@deffn {Command} {ocd_find} 'filename'
+Prints full path to @var{filename} according to OpenOCD search rules. This
+is a low level function used by the @command{find}. Usually you want
+to use @command{find}, instead.
+@end deffn
+
@section Board Config Files
@cindex config file, board
@cindex board config file
board files may need to distinguish between instances of a chip.
@item @code{ENDIAN} ...
By default @option{little} - although chips may hard-wire @option{big}.
-Chips that can't change endianess don't need to use this variable.
+Chips that can't change endianness don't need to use this variable.
@item @code{CPUTAPID} ...
When OpenOCD examines the JTAG chain, it can be told verify the
chips against the JTAG IDCODE register.
If both the chip and the board support adaptive clocking,
use the @command{jtag_rclk}
command, in case your board is used with JTAG adapter which
-also supports it. Otherwise use @command{adapter_khz}.
+also supports it. Otherwise use @command{adapter speed}.
Set the slow rate at the beginning of the reset sequence,
and the faster rate as soon as the clocks are at full speed.
reset_config trst_and_srst trst_pulls_srst
$_TARGETNAME configure -event reset-start @{
- adapter_khz 100
+ adapter speed 100
@}
$_TARGETNAME configure -event reset-init @{
enable_fast_clock
- adapter_khz 10000
+ adapter speed 10000
@}
@}
@end example
-work-area-size 0x4000 -work-area-backup 0
@end example
-@anchor{definecputargetsworkinginsmp}
@subsection Define CPU targets working in SMP
@cindex SMP
After setting targets, you can define a list of targets working in SMP.
The SMP behaviour can be disabled/enabled dynamically. On cortex_a following
command have been implemented.
@itemize @bullet
-@item cortex_a smp_on : enable SMP mode, behaviour is as described above.
-@item cortex_a smp_off : disable SMP mode, the current target is the one
+@item cortex_a smp on : enable SMP mode, behaviour is as described above.
+@item cortex_a smp off : disable SMP mode, the current target is the one
displayed in the GDB session, only this target is now controlled by GDB
session. This behaviour is useful during system boot up.
+@item cortex_a smp : display current SMP mode.
@item cortex_a smp_gdb : display/fix the core id displayed in GDB session see
following example.
@end itemize
The @code{init_boards} procedure is a similar concept concerning board config files
(@xref{theinitboardprocedure,,The init_board procedure}.)
-@anchor{theinittargeteventsprocedure}
@subsection The init_target_events procedure
@cindex init_target_events procedure
echo [format "set p15 0x%04x, 0x%08x" $regs $value]
- arm mcr 15 [expr ($regs>>12)&0x7] \
- [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] \
- [expr ($regs>>8)&0x7] $value
+ arm mcr 15 [expr @{($regs >> 12) & 0x7@}] \
+ [expr @{($regs >> 0) & 0xf@}] [expr @{($regs >> 4) & 0xf@}] \
+ [expr @{($regs >> 8) & 0x7@}] $value
@}
@end example
After it leaves this stage, configuration commands may no
longer be issued.
+@deffn {Command} {command mode} [command_name]
+Returns the command modes allowed by a command: 'any', 'config', or
+'exec'. If no command is specified, returns the current command
+mode. Returns 'unknown' if an unknown command is given. Command can be
+multiple tokens. (command valid any time)
+
+In this document, the modes are described as stages, 'config' and
+'exec' mode correspond configuration stage and run stage. 'any' means
+the command can be executed in either
+stages. @xref{configurationstage,,Configuration Stage}, and
+@xref{enteringtherunstage,,Entering the Run Stage}.
+@end deffn
+
@anchor{enteringtherunstage}
@section Entering the Run Stage
If you want to use those commands, you may need to force
entry to the run stage.
-@deffn {Config Command} init
+@deffn {Config Command} {init}
This command terminates the configuration stage and
enters the run stage. This helps when you need to have
the startup scripts manage tasks such as resetting the target,
OpenOCD executes the command for you after processing all
configuration files and/or command line options.
-@b{NOTE:} This command normally occurs at or near the end of your
+@b{NOTE:} This command normally occurs near the end of your
openocd.cfg file to force OpenOCD to ``initialize'' and make the
targets ready. For example: If your openocd.cfg file needs to
read/write memory on your target, @command{init} must occur before
the memory read/write commands. This includes @command{nand probe}.
+
+@command{init} calls the following internal OpenOCD commands to initialize
+corresponding subsystems:
+@deffn {Config Command} {target init}
+@deffnx {Command} {transport init}
+@deffnx {Command} {dap init}
+@deffnx {Config Command} {flash init}
+@deffnx {Config Command} {nand init}
+@deffnx {Config Command} {pld init}
+@deffnx {Command} {tpiu init}
+@end deffn
+
+At last, @command{init} executes all the commands that are specified in
+the TCL list @var{post_init_commands}. The commands are executed in the
+same order they occupy in the list. If one of the commands fails, then
+the error is propagated and OpenOCD fails too.
+@example
+lappend post_init_commands @{echo "OpenOCD successfully initialized."@}
+lappend post_init_commands @{echo "Have fun with OpenOCD !"@}
+@end example
+@end deffn
+
+@deffn {Config Command} {noinit}
+Prevent OpenOCD from implicit @command{init} call at the end of startup.
+Allows issuing configuration commands over telnet or Tcl connection.
+When you are done with configuration use @command{init} to enter
+the run stage.
@end deffn
-@deffn {Overridable Procedure} jtag_init
+@deffn {Overridable Procedure} {jtag_init}
This is invoked at server startup to verify that it can talk
to the scan chain (list of TAPs) which has been configured.
If you disable all access through TCP/IP, you will need to
use the command line @option{-pipe} option.
+You can request the operating system to select one of the available
+ports for the server by specifying the relevant port number as "0".
+
@anchor{gdb_port}
-@deffn {Command} gdb_port [number]
+@deffn {Config Command} {gdb_port} [number]
@cindex GDB server
Normally gdb listens to a TCP/IP port, but GDB can also
communicate via pipes(stdin/out or named pipes). The name
When using "pipe", also use log_output to redirect the log
output to a file so as not to flood the stdin/out pipes.
-The -p/--pipe option is deprecated and a warning is printed
-as it is equivalent to passing in -c "gdb_port pipe; log_output openocd.log".
-
Any other string is interpreted as named pipe to listen to.
Output pipe is the same name as input pipe, but with 'o' appended,
e.g. /var/gdb, /var/gdbo.
cause initialization to fail with "Unknown remote qXfer reply: OK".
@end deffn
-@deffn {Command} tcl_port [number]
+@deffn {Config Command} {tcl_port} [number]
Specify or query the port used for a simplified RPC
connection that can be used by clients to issue TCL commands and get the
output from the Tcl engine.
When specified as "disabled", this service is not activated.
@end deffn
-@deffn {Command} telnet_port [number]
+@deffn {Config Command} {telnet_port} [number]
Specify or query the
port on which to listen for incoming telnet connections.
This port is intended for interaction with one human through TCL commands.
@xref{targetevents,,Target Events}, about configuring target-specific event handling.
@anchor{gdbbreakpointoverride}
-@deffn {Command} gdb_breakpoint_override [@option{hard}|@option{soft}|@option{disable}]
+@deffn {Command} {gdb_breakpoint_override} [@option{hard}|@option{soft}|@option{disable}]
Force breakpoint type for gdb @command{break} commands.
This option supports GDB GUIs which don't
distinguish hard versus soft breakpoints, if the default OpenOCD and
@end deffn
@anchor{gdbflashprogram}
-@deffn {Config Command} gdb_flash_program (@option{enable}|@option{disable})
+@deffn {Config Command} {gdb_flash_program} (@option{enable}|@option{disable})
Set to @option{enable} to cause OpenOCD to program the flash memory when a
vFlash packet is received.
The default behaviour is @option{enable}.
@end deffn
-@deffn {Config Command} gdb_memory_map (@option{enable}|@option{disable})
+@deffn {Config Command} {gdb_memory_map} (@option{enable}|@option{disable})
Set to @option{enable} to cause OpenOCD to send the memory configuration to GDB when
requested. GDB will then know when to set hardware breakpoints, and program flash
using the GDB load command. @command{gdb_flash_program enable} must also be enabled
@xref{gdbflashprogram,,gdb_flash_program}.
@end deffn
-@deffn {Config Command} gdb_report_data_abort (@option{enable}|@option{disable})
+@deffn {Config Command} {gdb_report_data_abort} (@option{enable}|@option{disable})
Specifies whether data aborts cause an error to be reported
by GDB memory read packets.
The default behaviour is @option{disable};
use @option{enable} see these errors reported.
@end deffn
-@deffn {Config Command} gdb_report_register_access_error (@option{enable}|@option{disable})
+@deffn {Config Command} {gdb_report_register_access_error} (@option{enable}|@option{disable})
Specifies whether register accesses requested by GDB register read/write
packets report errors or not.
The default behaviour is @option{disable};
use @option{enable} see these errors reported.
@end deffn
-@deffn {Config Command} gdb_target_description (@option{enable}|@option{disable})
+@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{enable}.
@end deffn
-@deffn {Command} gdb_save_tdesc
+@deffn {Command} {gdb_save_tdesc}
Saves the target description file to the local file system.
The file name is @i{target_name}.xml.
There is a command to manage and monitor that polling,
which is normally done in the background.
-@deffn Command poll [@option{on}|@option{off}]
+@deffn {Command} {poll} [@option{on}|@option{off}]
Poll the current target for its current state.
(Also, @pxref{targetcurstate,,target curstate}.)
If that target is in debug mode, architecture
@example
# jlink interface
-interface jlink
+adapter driver jlink
@end example
Most adapters need a bit more configuration than that.
-@section Interface Configuration
+@section Adapter Configuration
-The interface command tells OpenOCD what type of debug adapter you are
+The @command{adapter driver} command tells OpenOCD what type of debug adapter you are
using. Depending on the type of adapter, you may need to use one or
more additional commands to further identify or configure the adapter.
-@deffn {Config Command} {interface} name
-Use the interface driver @var{name} to connect to the
+@deffn {Config Command} {adapter driver} name
+Use the adapter driver @var{name} to connect to the
target.
@end deffn
-@deffn Command {interface_list}
+@deffn {Command} {adapter list}
List the debug adapter drivers that have been built into
the running copy of OpenOCD.
@end deffn
-@deffn Command {interface transports} transport_name+
+@deffn {Config Command} {adapter transports} transport_name+
Specifies the transports supported by this debug adapter.
The adapter driver builds-in similar knowledge; use this only
when external configuration (such as jumpering) changes what
the hardware can support.
@end deffn
+@anchor{adapter gpio}
+@deffn {Config Command} {adapter gpio [ @
+ @option{tdo} | @option{tdi} | @option{tms} | @option{tck} | @option{trst} | @
+ @option{swdio} | @option{swdio_dir} | @option{swclk} | @option{srst} | @
+ @option{led} @
+ [ @
+ gpio_number | @option{-chip} chip_number | @
+ @option{-active-high} | @option{-active-low} | @
+ @option{-push-pull} | @option{-open-drain} | @option{-open-source} | @
+ @option{-pull-none} | @option{-pull-up} | @option{-pull-down} | @
+ @option{-init-inactive} | @option{-init-active} | @option{-init-input} @
+ ] ]}
+
+Define the GPIO mapping that the adapter will use. The following signals can be
+defined:
+
+@itemize @minus
+@item @option{tdo}, @option{tdi}, @option{tms}, @option{tck}, @option{trst}:
+JTAG transport signals
+@item @option{swdio}, @option{swclk}: SWD transport signals
+@item @option{swdio_dir}: optional swdio buffer control signal
+@item @option{srst}: system reset signal
+@item @option{led}: optional activity led
+@end itemize
-@deffn Command {adapter_name}
+Some adapters require that the GPIO chip number is set in addition to the GPIO
+number. The configuration options enable signals to be defined as active-high or
+active-low. The output drive mode can be set to push-pull, open-drain or
+open-source. Most adapters will have to emulate open-drain or open-source drive
+modes by switching between an input and output. Input and output signals can be
+instructed to use a pull-up or pull-down resistor, assuming it is supported by
+the adaptor driver and hardware. The initial state of outputs may also be set,
+"active" state means 1 for active-high outputs and 0 for active-low outputs.
+Bidirectional signals may also be initialized as an input. If the swdio signal
+is buffered the buffer direction can be controlled with the swdio_dir signal;
+the active state means that the buffer should be set as an output with respect
+to the adapter. The command options are cumulative with later commands able to
+override settings defined by earlier ones. The two commands @command{gpio led 7
+-active-high} and @command{gpio led -chip 1 -active-low} sent sequentially are
+equivalent to issuing the single command @command{gpio led 7 -chip 1
+-active-low}. It is not permissible to set the drive mode or initial state for
+signals which are inputs. The drive mode for the srst and trst signals must be
+set with the @command{adapter reset_config} command. It is not permissible to
+set the initial state of swdio_dir as it is derived from the initial state of
+swdio. The command @command{adapter gpio} prints the current configuration for
+all GPIOs while the command @command{adapter gpio gpio_name} prints the current
+configuration for gpio_name. Not all adapters support this generic GPIO mapping,
+some require their own commands to define the GPIOs used. Adapters that support
+the generic mapping may not support all of the listed options.
+@end deffn
+
+@deffn {Command} {adapter name}
Returns the name of the debug adapter driver being used.
@end deffn
-@anchor{adapter_usb_location}
-@deffn Command {adapter usb location} <bus>-<port>[.<port>]...
-Specifies the physical USB port of the adapter to use. The path
+@deffn {Config Command} {adapter usb location} [<bus>-<port>[.<port>]...]
+Displays or specifies the physical USB port of the adapter to use. The path
roots at @var{bus} and walks down the physical ports, with each
@var{port} option specifying a deeper level in the bus topology, the last
@var{port} denoting where the target adapter is actually plugged.
This command is only available if your libusb1 is at least version 1.0.16.
@end deffn
+@deffn {Config Command} {adapter serial} serial_string
+Specifies the @var{serial_string} of the adapter to use.
+If this command is not specified, serial strings are not checked.
+Only the following adapter drivers use the serial string from this command:
+arm-jtag-ew, cmsis_dap, esp_usb_jtag, ft232r, ftdi, hla (stlink, ti-icdi), jlink, kitprog, opendus,
+openjtag, osbdm, presto, rlink, st-link, usb_blaster (ublast2), usbprog, vsllink, xds110.
+@end deffn
+
@section Interface Drivers
Each of the interface drivers listed here must be explicitly
connected to a PC's EPP mode parallel port.
This defines some driver-specific commands:
-@deffn {Config Command} {parport_port} number
+@deffn {Config Command} {parport port} number
Specifies either the address of the I/O port (default: 0x378 for LPT1) or
the number of the @file{/dev/parport} device.
@end deffn
-@deffn {Config Command} rtck [@option{enable}|@option{disable}]
+@deffn {Config Command} {rtck} [@option{enable}|@option{disable}]
Displays status of RTCK option.
Optionally sets that option first.
@end deffn
@end deffn
+@deffn {Interface Driver} {angie}
+This is the NanoXplore's ANGIE USB-JTAG Adapter.
+@end deffn
+
@deffn {Interface Driver} {arm-jtag-ew}
Olimex ARM-JTAG-EW USB adapter
This has one driver-specific command:
-@deffn Command {armjtagew_info}
+@deffn {Command} {armjtagew_info}
Logs some status
@end deffn
@end deffn
@end deffn
@deffn {Interface Driver} {cmsis-dap}
-ARM CMSIS-DAP compliant based adapter.
+ARM CMSIS-DAP compliant based adapter v1 (USB HID based)
+or v2 (USB bulk).
-@deffn {Config Command} {cmsis_dap_vid_pid} [vid pid]+
+@deffn {Config Command} {cmsis-dap vid_pid} [vid pid]+
The vendor ID and product ID of the CMSIS-DAP device. If not specified
the driver will attempt to auto detect the CMSIS-DAP device.
Currently, up to eight [@var{vid}, @var{pid}] pairs may be given, e.g.
@example
-cmsis_dap_vid_pid 0xc251 0xf001 0x0d28 0x0204
+cmsis-dap vid_pid 0xc251 0xf001 0x0d28 0x0204
@end example
@end deffn
-@deffn {Config Command} {cmsis_dap_serial} [serial]
-Specifies the @var{serial} of the CMSIS-DAP device to use.
-If not specified, serial numbers are not considered.
+@deffn {Config Command} {cmsis-dap backend} [@option{auto}|@option{usb_bulk}|@option{hid}]
+Specifies how to communicate with the adapter:
+
+@itemize @minus
+@item @option{hid} Use HID generic reports - CMSIS-DAP v1
+@item @option{usb_bulk} Use USB bulk - CMSIS-DAP v2
+@item @option{auto} First try USB bulk CMSIS-DAP v2, if not found try HID CMSIS-DAP v1.
+This is the default if @command{cmsis-dap backend} is not specified.
+@end itemize
+@end deffn
+
+@deffn {Config Command} {cmsis-dap usb interface} [number]
+Specifies the @var{number} of the USB interface to use in v2 mode (USB bulk).
+In most cases need not to be specified and interfaces are searched by
+interface string or for user class interface.
+@end deffn
+
+@deffn {Command} {cmsis-dap quirk} [@option{enable}|@option{disable}]
+Enables or disables the following workarounds of known CMSIS-DAP adapter
+quirks:
+@itemize @minus
+@item disconnect and re-connect before sending a switch sequence
+@item packets pipelining is suppressed, only one packet at a time is
+submitted to the adapter
+@end itemize
+The quirk workarounds are disabled by default.
+The command without a parameter displays current setting.
@end deffn
@deffn {Command} {cmsis-dap info}
Display various device information, like hardware version, firmware version, current bus status.
@end deffn
+
+@deffn {Command} {cmsis-dap cmd} number number ...
+Execute an arbitrary CMSIS-DAP command. Use for adapter testing or for handling
+of an adapter vendor specific command from a Tcl script.
+
+Take given numbers as bytes, assemble a CMSIS-DAP protocol command packet
+from them and send it to the adapter. The first 4 bytes of the adapter response
+are logged.
+See @url{https://arm-software.github.io/CMSIS_5/DAP/html/group__DAP__Commands__gr.html}
+@end deffn
@end deffn
@deffn {Interface Driver} {dummy}
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 or D2XX.
+bypassing intermediate libraries like libftdi.
Support for new FTDI based adapters can be added completely 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
-controlled using the @command{ftdi_set_signal} command. Special signal names
+controlled using the @command{ftdi set_signal} command. Special signal names
are reserved for nTRST, nSRST and LED (for blink) so that they, if defined,
will be used for their customary purpose. Inputs can be read using the
-@command{ftdi_get_signal} command.
+@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
These interfaces have several commands, used to configure the driver
before initializing the JTAG scan chain:
-@deffn {Config Command} {ftdi_vid_pid} [vid pid]+
+@deffn {Config Command} {ftdi vid_pid} [vid pid]+
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
+ftdi vid_pid 0x0403 0xcff8 0x15ba 0x0003
@end example
@end deffn
-@deffn {Config Command} {ftdi_device_desc} description
+@deffn {Config Command} {ftdi device_desc} description
Provides the USB device description (the @emph{iProduct string})
of the adapter. If not specified, the device description is ignored
during device selection.
@end deffn
-@deffn {Config Command} {ftdi_serial} serial-number
-Specifies the @var{serial-number} of the adapter to use,
-in case the vendor provides unique IDs and more than one adapter
-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} {ftdi_location} <bus>-<port>[.<port>]...
-@emph{DEPRECATED -- avoid using this.
-Use the @xref{adapter_usb_location, adapter usb location} command instead.}
-
-Specifies the physical USB port of the adapter to use. The path
-roots at @var{bus} and walks down the physical ports, with each
-@var{port} option specifying a deeper level in the bus topology, the last
-@var{port} denoting where the target adapter is actually plugged.
-The USB bus topology can be queried with the command @emph{lsusb -t}.
-
-This command is only available if your libusb1 is at least version 1.0.16.
-@end deffn
-
-@deffn {Config Command} {ftdi_channel} channel
+@deffn {Config Command} {ftdi channel} channel
Selects the channel of the FTDI device to use for MPSSE operations. Most
adapters use the default, channel 0, but there are exceptions.
@end deffn
-@deffn {Config Command} {ftdi_layout_init} data direction
+@deffn {Config Command} {ftdi layout_init} data direction
Specifies the initial values of the FTDI GPIO data and direction registers.
Each value is a 16-bit number corresponding to the concatenation of the high
and low FTDI GPIO registers. The values should be selected based on the
and initially asserted reset signals.
@end deffn
-@deffn {Config Command} {ftdi_layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-input}|@option{-ninput} input_mask] [@option{-oe}|@option{-noe} oe_mask] [@option{-alias}|@option{-nalias} name]
+@deffn {Command} {ftdi layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-input}|@option{-ninput} input_mask] [@option{-oe}|@option{-noe} oe_mask] [@option{-alias}|@option{-nalias} name]
Creates a signal with the specified @var{name}, controlled by one or more FTDI
GPIO pins via a range of possible buffer connections. The masks are FTDI GPIO
register bitmasks to tell the driver the connection and type of the output
The @option{-oe} (or @option{-noe}) option tells where the output-enable (or
not-output-enable) input to the output buffer is connected. The options
@option{-input} and @option{-ninput} specify the bitmask for pins to be read
-with the method @command{ftdi_get_signal}.
+with the method @command{ftdi get_signal}.
Both @var{data_mask} and @var{oe_mask} need not be specified. For example, a
simple open-collector transistor driver would be specified with @option{-oe}
@var{name}.
@end deffn
-@deffn {Command} {ftdi_set_signal} name @option{0}|@option{1}|@option{z}
+@deffn {Command} {ftdi set_signal} name @option{0}|@option{1}|@option{z}
Set a previously defined signal to the specified level.
@itemize @minus
@item @option{0}, drive low
@end itemize
@end deffn
-@deffn {Command} {ftdi_get_signal} name
+@deffn {Command} {ftdi get_signal} name
Get the value of a previously defined signal.
@end deffn
-@deffn {Command} {ftdi_tdo_sample_edge} @option{rising}|@option{falling}
+@deffn {Command} {ftdi tdo_sample_edge} @option{rising}|@option{falling}
Configure TCK edge at which the adapter samples the value of the TDO signal
Due to signal propagation delays, sampling TDO on rising TCK can become quite
These interfaces have several commands, used to configure the driver
before initializing the JTAG scan chain:
-@deffn {Config Command} {ft232r_vid_pid} @var{vid} @var{pid}
+@deffn {Config Command} {ft232r vid_pid} @var{vid} @var{pid}
The vendor ID and product ID of the adapter. If not specified, default
0x0403:0x6001 is used.
@end deffn
-@deffn {Config Command} {ft232r_serial_desc} @var{serial}
-Specifies the @var{serial} of the adapter to use, in case the
-vendor provides unique IDs and more than one adapter is connected to
-the host. If not specified, serial numbers are not considered.
-@end deffn
-
-@deffn {Config Command} {ft232r_jtag_nums} @var{tck} @var{tms} @var{tdi} @var{tdo}
+@deffn {Config Command} {ft232r jtag_nums} @var{tck} @var{tms} @var{tdi} @var{tdo}
Set four JTAG GPIO numbers at once.
If not specified, default 0 3 1 2 or TXD CTS RXD RTS is used.
@end deffn
-@deffn {Config Command} {ft232r_tck_num} @var{tck}
+@deffn {Config Command} {ft232r tck_num} @var{tck}
Set TCK GPIO number. If not specified, default 0 or TXD is used.
@end deffn
-@deffn {Config Command} {ft232r_tms_num} @var{tms}
+@deffn {Config Command} {ft232r tms_num} @var{tms}
Set TMS GPIO number. If not specified, default 3 or CTS is used.
@end deffn
-@deffn {Config Command} {ft232r_tdi_num} @var{tdi}
+@deffn {Config Command} {ft232r tdi_num} @var{tdi}
Set TDI GPIO number. If not specified, default 1 or RXD is used.
@end deffn
-@deffn {Config Command} {ft232r_tdo_num} @var{tdo}
+@deffn {Config Command} {ft232r tdo_num} @var{tdo}
Set TDO GPIO number. If not specified, default 2 or RTS is used.
@end deffn
-@deffn {Config Command} {ft232r_trst_num} @var{trst}
+@deffn {Config Command} {ft232r trst_num} @var{trst}
Set TRST GPIO number. If not specified, default 4 or DTR is used.
@end deffn
-@deffn {Config Command} {ft232r_srst_num} @var{srst}
+@deffn {Config Command} {ft232r srst_num} @var{srst}
Set SRST GPIO number. If not specified, default 6 or DCD is used.
@end deffn
-@deffn {Config Command} {ft232r_restore_serial} @var{word}
+@deffn {Config Command} {ft232r restore_serial} @var{word}
Restore serial port after JTAG. This USB bitmode control word
(16-bit) will be sent before quit. Lower byte should
set GPIO direction register to a "sane" state:
@end deffn
@deffn {Interface Driver} {remote_bitbang}
-Drive JTAG from a remote process. This sets up a UNIX or TCP socket connection
-with a remote process and sends ASCII encoded bitbang requests to that process
-instead of directly driving JTAG.
+Drive JTAG and SWD from a remote process. This sets up a UNIX or TCP socket
+connection with a remote process and sends ASCII encoded bitbang requests to
+that process instead of directly driving JTAG and SWD.
The remote_bitbang driver is useful for debugging software running on
processors which are being simulated.
-@deffn {Config Command} {remote_bitbang_port} number
+@deffn {Config Command} {remote_bitbang port} number
Specifies the TCP port of the remote process to connect to or 0 to use UNIX
sockets instead of TCP.
@end deffn
-@deffn {Config Command} {remote_bitbang_host} hostname
+@deffn {Config Command} {remote_bitbang host} hostname
Specifies the hostname of the remote process to connect to using TCP, or the
-name of the UNIX socket to use if remote_bitbang_port is 0.
+name of the UNIX socket to use if remote_bitbang port is 0.
+@end deffn
+
+@deffn {Config Command} {remote_bitbang use_remote_sleep} (on|off)
+If this option is enabled, delays will not be executed locally but instead
+forwarded to the remote host. This is useful if the remote host performs its
+own request queuing rather than executing requests immediately.
+
+This is disabled by default. This option must only be enabled if the given
+remote_bitbang host supports receiving the delay information.
@end deffn
For example, to connect remotely via TCP to the host foobar you might have
something like:
@example
-interface remote_bitbang
-remote_bitbang_port 3335
-remote_bitbang_host foobar
+adapter driver remote_bitbang
+remote_bitbang port 3335
+remote_bitbang host foobar
+@end example
+
+And if you also wished to enable remote sleeping:
+
+@example
+adapter driver remote_bitbang
+remote_bitbang port 3335
+remote_bitbang host foobar
+remote_bitbang use_remote_sleep on
@end example
To connect to another process running locally via UNIX sockets with socket
named mysocket:
@example
-interface remote_bitbang
-remote_bitbang_port 0
-remote_bitbang_host mysocket
+adapter driver remote_bitbang
+remote_bitbang port 0
+remote_bitbang host mysocket
@end example
@end deffn
for FTDI chips. These interfaces have several commands, used to
configure the driver before initializing the JTAG scan chain:
-@deffn {Config Command} {usb_blaster_device_desc} description
-Provides the USB device description (the @emph{iProduct string})
-of the FTDI FT245 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} {usb_blaster_vid_pid} vid pid
+@deffn {Config Command} {usb_blaster vid_pid} vid pid
The vendor ID and product ID of the FTDI FT245 device. If not specified,
default values are used.
Currently, only one @var{vid}, @var{pid} pair may be given, e.g. for
Altera USB-Blaster (default):
@example
-usb_blaster_vid_pid 0x09FB 0x6001
+usb_blaster vid_pid 0x09FB 0x6001
@end example
The following VID/PID is for Kolja Waschk's USB JTAG:
@example
-usb_blaster_vid_pid 0x16C0 0x06AD
+usb_blaster vid_pid 0x16C0 0x06AD
@end example
@end deffn
-@deffn {Command} {usb_blaster_pin} (@option{pin6}|@option{pin8}) (@option{0}|@option{1}|@option{s}|@option{t})
+@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
For example, to use pin 6 as SRST:
@example
-usb_blaster_pin pin6 s
+usb_blaster pin pin6 s
reset_config srst_only
@end example
@end deffn
-@deffn {Command} {usb_blaster_lowlevel_driver} (@option{ftdi}|@option{ublast2})
+@deffn {Config 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}.
@end deffn
-@deffn {Command} {usb_blaster_firmware} @var{path}
+@deffn {Config 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
Gateworks GW16012 JTAG programmer.
This has one driver-specific command:
-@deffn {Config Command} {parport_port} [port_number]
+@deffn {Config Command} {parport port} [port_number]
Display either the address of the I/O port
(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
If a parameter is provided, first switch to use that port.
@deffn {Command} {jlink config write}
Write the current configuration to the internal persistent storage.
@end deffn
-@deffn {Command} {jlink emucom write <channel> <data>}
+@deffn {Command} {jlink emucom write} <channel> <data>
Write data to an EMUCOM channel. The data needs to be encoded as hexadecimal
pairs.
> jlink emucom write 0x10 aa0b23
@end example
@end deffn
-@deffn {Command} {jlink emucom read <channel> <length>}
+@deffn {Command} {jlink emucom read} <channel> <length>
Read data from an EMUCOM channel. The read data is encoded as hexadecimal
pairs.
77a90000
@end example
@end deffn
-@deffn {Config} {jlink usb} <@option{0} to @option{3}>
+@deffn {Config Command} {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
-selection via USB address is deprecated and the serial number should be used
-instead.
-
-As a configuration command, it can be used only before 'init'.
-@end deffn
-@deffn {Config} {jlink serial} <serial number>
-Set the serial number of the interface, in case more than one adapter is
-connected to the host. If not specified, serial numbers are not considered.
+selection via USB address is not always unambiguous. It is recommended to use
+the serial number instead, if possible.
As a configuration command, it can be used only before 'init'.
@end deffn
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
+@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
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
+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}
+@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
These interfaces have several commands, used to configure the driver
before initializing the JTAG scan chain:
-@deffn {Config Command} {parport_cable} name
+@deffn {Config Command} {parport cable} name
Set the layout of the parallel port cable used to connect to the target.
This is a write-once setting.
Currently valid cable @var{name} values include:
@end itemize
@end deffn
-@deffn {Config Command} {parport_port} [port_number]
+@deffn {Config Command} {parport port} [port_number]
Display either the address of the I/O port
(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
If a parameter is provided, first switch to use that port.
This is a write-once setting.
When using PPDEV to access the parallel port, use the number of the parallel port:
-@option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
+@option{parport port 0} (the default). If @option{parport port 0x378} is specified
you may encounter a problem.
@end deffn
-@deffn Command {parport_toggling_time} [nanoseconds]
+@deffn {Config Command} {parport toggling_time} [nanoseconds]
Displays how many nanoseconds the hardware needs to toggle TCK;
the parport driver uses this value to obey the
-@command{adapter_khz} configuration.
+@command{adapter speed} configuration.
When the optional @var{nanoseconds} parameter is given,
that setting is changed before displaying the current value.
To measure the toggling time with a logic analyzer or a digital storage
oscilloscope, follow the procedure below:
@example
-> parport_toggling_time 1000
-> adapter_khz 500
+> parport toggling_time 1000
+> adapter speed 500
@end example
This sets the maximum JTAG clock speed of the hardware, but
the actual speed probably deviates from the requested 500 kHz.
large set of samples.
Update the setting to match your measurement:
@example
-> parport_toggling_time <measured nanoseconds>
+> parport toggling_time <measured nanoseconds>
@end example
-Now the clock speed will be a better match for @command{adapter_khz rate}
-commands given in OpenOCD scripts and event handlers.
+Now the clock speed will be a better match for @command{adapter speed}
+command given in OpenOCD scripts and event handlers.
You can do something similar with many digital multimeters, but note
that you'll probably need to run the clock continuously for several
seconds before it decides what clock rate to show. Adjust the
toggling time up or down until the measured clock rate is a good
-match for the adapter_khz rate you specified; be conservative.
+match with the rate you specified in the @command{adapter speed} command;
+be conservative.
@end quotation
@end deffn
-@deffn {Config Command} {parport_write_on_exit} (@option{on}|@option{off})
+@deffn {Config Command} {parport write_on_exit} (@option{on}|@option{off})
This will configure the parallel driver to write a known
cable-specific value to the parallel interface on exiting OpenOCD.
@end deffn
classic ``Wiggler'' cable on LPT2 might look something like this:
@example
-interface parport
-parport_port 0x278
-parport_cable wiggler
+adapter driver parport
+parport port 0x278
+parport cable wiggler
@end example
@end deffn
@deffn {Interface Driver} {presto}
ASIX PRESTO USB JTAG programmer.
-@deffn {Config Command} {presto_serial} serial_string
-Configures the USB serial number of the Presto device to use.
-@end deffn
@end deffn
@deffn {Interface Driver} {rlink}
This type of adapter does not expose some of the lower level api's
that OpenOCD would normally use to access the target.
-Currently supported adapters include the STMicroelectronics ST-LINK and TI ICDI.
+Currently supported adapters include the STMicroelectronics ST-LINK, TI ICDI
+and Nuvoton Nu-Link.
ST-LINK firmware version >= V2.J21.S4 recommended due to issues with earlier
versions of firmware where serial number is reset after first use. Suggest
using ST firmware update utility to upgrade ST-LINK firmware even if current
Currently Not Supported.
@end deffn
-@deffn {Config Command} {hla_serial} serial
-Specifies the serial number of the adapter.
-@end deffn
-
-@deffn {Config Command} {hla_layout} (@option{stlink}|@option{icdi})
+@deffn {Config Command} {hla_layout} (@option{stlink}|@option{icdi}|@option{nulink})
Specifies the adapter layout to use.
@end deffn
Pairs of vendor IDs and product IDs of the device.
@end deffn
+@deffn {Config Command} {hla_stlink_backend} (usb | tcp [port])
+@emph{ST-Link only:} Choose between 'exclusive' USB communication (the default backend) or
+'shared' mode using ST-Link TCP server (the default port is 7184).
+
+@emph{Note:} ST-Link TCP server is a binary application provided by ST
+available from @url{https://www.st.com/en/development-tools/st-link-server.html,
+ST-LINK server software module}.
+@end deffn
+
@deffn {Command} {hla_command} command
Execute a custom adapter-specific command. The @var{command} string is
passed as is to the underlying adapter layout handler.
@end deffn
@end deffn
+@anchor{st_link_dap_interface}
+@deffn {Interface Driver} {st-link}
+This is a driver that supports STMicroelectronics adapters ST-LINK/V2
+(from firmware V2J24), STLINK-V3 and STLINK-V3PWR, thanks to a new API that provides
+directly access the arm ADIv5 DAP.
+
+The new API provide access to multiple AP on the same DAP, but the
+maximum number of the AP port is limited by the specific firmware version
+(e.g. firmware V2J29 has 3 as maximum AP number, while V2J32 has 8).
+An error is returned for any AP number above the maximum allowed value.
+
+@emph{Note:} Either these same adapters and their older versions are
+also supported by @ref{hla_interface, the hla interface driver}.
+
+@deffn {Config Command} {st-link backend} (usb | tcp [port])
+Choose between 'exclusive' USB communication (the default backend) or
+'shared' mode using ST-Link TCP server (the default port is 7184).
+
+@emph{Note:} ST-Link TCP server is a binary application provided by ST
+available from @url{https://www.st.com/en/development-tools/st-link-server.html,
+ST-LINK server software module}.
+
+@emph{Note:} ST-Link TCP server does not support the SWIM transport.
+@end deffn
+
+@deffn {Config Command} {st-link vid_pid} [vid pid]+
+Pairs of vendor IDs and product IDs of the device.
+@end deffn
+
+@deffn {Command} {st-link cmd} rx_n (tx_byte)+
+Sends an arbitrary command composed by the sequence of bytes @var{tx_byte}
+and receives @var{rx_n} bytes.
+
+For example, the command to read the target's supply voltage is one byte 0xf7 followed
+by 15 bytes zero. It returns 8 bytes, where the first 4 bytes represent the ADC sampling
+of the reference voltage 1.2V and the last 4 bytes represent the ADC sampling of half
+the target's supply voltage.
+@example
+> st-link cmd 8 0xf7 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
+0xf1 0x05 0x00 0x00 0x0b 0x08 0x00 0x00
+@end example
+The result can be converted to Volts (ignoring the most significant bytes, always zero)
+@example
+> set a [st-link cmd 8 0xf7 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
+> set n [expr @{[lindex $a 4] + 256 * [lindex $a 5]@}]
+> set d [expr @{[lindex $a 0] + 256 * [lindex $a 1]@}]
+> echo [expr @{2 * 1.2 * $n / $d@}]
+3.24891518738
+@end example
+@end deffn
+@end deffn
+
@deffn {Interface Driver} {opendous}
opendous-jtag is a freely programmable USB adapter.
@end deffn
This is the Keil ULINK v1 JTAG debugger.
@end deffn
-@deffn {Interface Driver} {ZY1000}
-This is the Zylin ZY1000 JTAG debugger.
+@deffn {Interface Driver} {xds110}
+The XDS110 is included as the embedded debug probe on many Texas Instruments
+LaunchPad evaluation boards. The XDS110 is also available as a stand-alone USB
+debug probe with the added capability to supply power to the target board. The
+following commands are supported by the XDS110 driver:
+
+@deffn {Config Command} {xds110 supply} voltage_in_millivolts
+Available only on the XDS110 stand-alone probe. Sets the voltage level of the
+XDS110 power supply. A value of 0 leaves the supply off. Otherwise, the supply
+can be set to any value in the range 1800 to 3600 millivolts.
@end deffn
-@quotation Note
-This defines some driver-specific commands,
-which are not currently documented here.
-@end quotation
+@deffn {Command} {xds110 info}
+Displays information about the connected XDS110 debug probe (e.g. firmware
+version).
+@end deffn
+@end deffn
+
+@deffn {Interface Driver} {xlnx_pcie_xvc}
+This driver supports the Xilinx Virtual Cable (XVC) over PCI Express.
+It is commonly found in Xilinx based PCI Express designs. It allows debugging
+fabric based JTAG/SWD devices such as Cortex-M1/M3 microcontrollers. Access to this is
+exposed via extended capability registers in the PCI Express configuration space.
+
+For more information see Xilinx PG245 (Section on From_PCIE_to_JTAG mode).
+
+@deffn {Config Command} {xlnx_pcie_xvc config} device
+Specifies the PCI Express device via parameter @var{device} to use.
+
+The correct value for @var{device} can be obtained by looking at the output
+of lscpi -D (first column) for the corresponding device.
+
+The string will be of the format "DDDD:BB:SS.F" such as "0000:65:00.1".
-@deffn Command power [@option{on}|@option{off}]
-Turn power switch to target on/off.
-No arguments: print status.
+@end deffn
@end deffn
@deffn {Interface Driver} {bcm2835gpio}
peripherals' kernel drivers. The driver restores the previous
configuration on exit.
+GPIO numbers >= 32 can't be used for performance reasons. GPIO configuration is
+handled by the generic command @ref{adapter gpio, @command{adapter gpio}}.
+
See @file{interface/raspberrypi-native.cfg} for a sample config and
-pinout.
+@file{interface/raspberrypi-gpio-connector.cfg} for pinout.
+
+@deffn {Config Command} {bcm2835gpio speed_coeffs} @var{speed_coeff} @var{speed_offset}
+Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified,
+speed_coeff defaults to 113714, and speed_offset defaults to 28.
+@end deffn
+
+@deffn {Config Command} {bcm2835gpio peripheral_mem_dev} @var{device}
+Set the device path for access to the memory mapped GPIO control registers.
+Uses @file{/dev/gpiomem} by default, this is also the preferred option with
+respect to system security.
+If overridden to @file{/dev/mem}:
+@itemize @minus
+@item OpenOCD needs @code{cap_sys_rawio} or run as root to open @file{/dev/mem}.
+Please be aware of security issues imposed by running OpenOCD with
+elevated user rights and by @file{/dev/mem} itself.
+@item correct @command{peripheral_base} must be configured.
+@item GPIO 0-27 pads are set to the limited slew rate
+and drive strength is reduced to 4 mA (2 mA on RPi 4).
+@end itemize
+
+@end deffn
+
+@deffn {Config Command} {bcm2835gpio peripheral_base} @var{base}
+Set the peripheral base register address to access GPIOs.
+Ignored if @file{/dev/gpiomem} is used. For the RPi1, use
+0x20000000. For RPi2 and RPi3, use 0x3F000000. For RPi4, use 0xFE000000. A full
+list can be found in the
+@uref{https://www.raspberrypi.org/documentation/hardware/raspberrypi/peripheral_addresses.md, official guide}.
+@end deffn
@end deffn
@end deffn
+@deffn {Interface Driver} {am335xgpio} The AM335x SoC is present in BeagleBone
+Black and BeagleBone Green single-board computers which expose some of the GPIOs
+on the two expansion headers.
+
+For maximum performance the driver accesses memory-mapped GPIO peripheral
+registers directly. The memory mapping requires read and write permission to
+kernel memory; if /dev/gpiomem exists it will be used, otherwise /dev/mem will
+be used. The driver restores the GPIO state on exit.
+
+All four GPIO ports are available. GPIO configuration is handled by the generic
+command @ref{adapter gpio, @command{adapter gpio}}.
+
+@deffn {Config Command} {am335xgpio speed_coeffs} @var{speed_coeff} @var{speed_offset}
+Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified
+speed_coeff defaults to 600000 and speed_offset defaults to 575.
+@end deffn
+
+See @file{interface/beaglebone-swd-native.cfg} for a sample configuration file.
+
+@end deffn
+
+
+@deffn {Interface Driver} {linuxgpiod}
+Linux provides userspace access to GPIO through libgpiod since Linux kernel
+version v4.6. The driver emulates either JTAG or SWD transport through
+bitbanging. There are no driver-specific commands, all GPIO configuration is
+handled by the generic command @ref{adapter gpio, @command{adapter gpio}}. This
+driver supports the resistor pull options provided by the @command{adapter gpio}
+command but the underlying hardware may not be able to support them.
+
+See @file{interface/dln-2-gpiod.cfg} for a sample configuration file.
+@end deffn
+
+
+@deffn {Interface Driver} {sysfsgpio}
+Linux legacy userspace access to GPIO through sysfs is deprecated from Linux kernel version v5.3.
+Prefer using @b{linuxgpiod}, instead.
+
+See @file{interface/sysfsgpio-raspberrypi.cfg} for a sample config.
+@end deffn
+
+
@deffn {Interface Driver} {openjtag}
OpenJTAG compatible USB adapter.
This defines some driver-specific commands:
-@deffn {Config Command} {openjtag_variant} variant
+@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:
@end itemize
@end deffn
-@deffn {Config Command} {openjtag_device_desc} string
+@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
+
+@deffn {Config Command} {openjtag vid_pid} vid pid
+The USB vendor ID and product ID of the adapter. If not specified, default
+0x0403:0x6001 is used.
+This value is only used with the standard variant.
+@example
+openjtag vid_pid 0x403 0x6014
+@end example
+@end deffn
+@end deffn
+
+
+@deffn {Interface Driver} {vdebug}
+Cadence Virtual Debug Interface driver.
+
+@deffn {Config Command} {vdebug server} host:port
+Specifies the host and TCP port number where the vdebug server runs.
+@end deffn
+
+@deffn {Config Command} {vdebug batching} value
+Specifies the batching method for the vdebug request. Possible values are
+0 for no batching
+1 or wr to batch write transactions together (default)
+2 or rw to batch both read and write transactions
+@end deffn
+
+@deffn {Config Command} {vdebug polling} min max
+Takes two values, representing the polling interval in ms. Lower values mean faster
+debugger responsiveness, but lower emulation performance. The minimum should be
+around 10, maximum should not exceed 1000, which is the default gdb and keepalive
+timeout value.
+@end deffn
+
+@deffn {Config Command} {vdebug bfm_path} path clk_period
+Specifies the hierarchical path and input clk period of the vdebug BFM in the design.
+The hierarchical path uses Verilog notation top.inst.inst
+The clock period must include the unit, for instance 40ns.
+@end deffn
+
+@deffn {Config Command} {vdebug mem_path} path base size
+Specifies the hierarchical path to the design memory instance for backdoor access.
+Up to 4 memories can be specified. The hierarchical path uses Verilog notation.
+The base specifies start address in the design address space, size its size in bytes.
+Both values can use hexadecimal notation with prefix 0x.
+@end deffn
+@end deffn
+
+@deffn {Interface Driver} {jtag_dpi}
+SystemVerilog Direct Programming Interface (DPI) compatible driver for
+JTAG devices in emulation. The driver acts as a client for the SystemVerilog
+DPI server interface.
+
+@deffn {Config Command} {jtag_dpi set_port} port
+Specifies the TCP/IP port number of the SystemVerilog DPI server interface.
+@end deffn
+
+@deffn {Config Command} {jtag_dpi set_address} address
+Specifies the TCP/IP address of the SystemVerilog DPI server interface.
+@end deffn
+@end deffn
+
+
+@deffn {Interface Driver} {buspirate}
+
+This driver is for the Bus Pirate (see @url{http://dangerousprototypes.com/docs/Bus_Pirate}) and compatible devices.
+It uses a simple data protocol over a serial port connection.
+
+Most hardware development boards have a UART, a real serial port, or a virtual USB serial device, so this driver
+allows you to start building your own JTAG adapter without the complexity of a custom USB connection.
+
+@deffn {Config Command} {buspirate port} serial_port
+Specify the serial port's filename. For example:
+@example
+buspirate port /dev/ttyUSB0
+@end example
+@end deffn
+
+@deffn {Config Command} {buspirate speed} (normal|fast)
+Set the communication speed to 115k (normal) or 1M (fast). For example:
+@example
+buspirate speed normal
+@end example
+@end deffn
+
+@deffn {Config Command} {buspirate mode} (normal|open-drain)
+Set the Bus Pirate output mode.
+@itemize @minus
+@item In normal mode (push/pull), do not enable the pull-ups, and do not connect I/O header pin VPU to JTAG VREF.
+@item In open drain mode, you will then need to enable the pull-ups.
+@end itemize
+For example:
+@example
+buspirate mode normal
+@end example
+@end deffn
+
+@deffn {Config Command} {buspirate pullup} (0|1)
+Whether to connect (1) or not (0) the I/O header pin VPU (JTAG VREF)
+to the pull-up/pull-down resistors on MOSI (JTAG TDI), CLK (JTAG TCK), MISO (JTAG TDO) and CS (JTAG TMS).
+For example:
+@example
+buspirate pullup 0
+@end example
+@end deffn
+
+@deffn {Config Command} {buspirate vreg} (0|1)
+Whether to enable (1) or disable (0) the built-in voltage regulator,
+which can be used to supply power to a test circuit through
+I/O header pins +3V3 and +5V. For example:
+@example
+buspirate vreg 0
+@end example
+@end deffn
+
+@deffn {Command} {buspirate led} (0|1)
+Turns the Bus Pirate's LED on (1) or off (0). For example:
+@end deffn
+@example
+buspirate led 1
+@end example
+
+@end deffn
+
+@deffn {Interface Driver} {esp_usb_jtag}
+Espressif JTAG driver to communicate with ESP32-C3, ESP32-S3 chips and ESP USB Bridge board using OpenOCD.
+These chips have built-in JTAG circuitry and can be debugged without any additional hardware.
+Only an USB cable connected to the D+/D- pins is necessary.
+
+@deffn {Command} {espusbjtag tdo}
+Returns the current state of the TDO line
+@end deffn
+
+@deffn {Command} {espusbjtag setio} setio
+Manually set the status of the output lines with the order of (tdi tms tck trst srst)
+@example
+espusbjtag setio 0 1 0 1 0
+@end example
+@end deffn
+
+@deffn {Config Command} {espusbjtag vid_pid} vid_pid
+Set vendor ID and product ID for the ESP usb jtag driver
+@example
+espusbjtag vid_pid 0x303a 0x1001
+@end example
+@end deffn
+
+@deffn {Config Command} {espusbjtag caps_descriptor} caps_descriptor
+Set the jtag descriptor to read capabilities of ESP usb jtag driver
+@example
+espusbjtag caps_descriptor 0x2000
+@end example
+@end deffn
+
+@deffn {Config Command} {espusbjtag chip_id} chip_id
+Set chip id to transfer to the ESP USB bridge board
+@example
+espusbjtag chip_id 1
+@end example
+@end deffn
+
+@end deffn
+
+@deffn {Interface Driver} {dmem} Direct Memory access debug interface
+
+The Texas Instruments K3 SoC family provides memory access to DAP
+and coresight control registers. This allows control over the
+microcontrollers directly from one of the processors on the SOC
+itself.
+
+For maximum performance, the driver accesses the debug registers
+directly over the SoC memory map. The memory mapping requires read
+and write permission to kernel memory via "/dev/mem" and assumes that
+the system firewall configurations permit direct access to the debug
+memory space.
+
+@verbatim
++-----------+
+| OpenOCD | SoC mem map (/dev/mem)
+| on +--------------+
+| Cortex-A53| |
++-----------+ |
+ |
++-----------+ +-----v-----+
+|Cortex-M4F <--------+ |
++-----------+ | |
+ | DebugSS |
++-----------+ | |
+|Cortex-M4F <--------+ |
++-----------+ +-----------+
+@end verbatim
+
+NOTE: Firewalls are configurable in K3 SoC and depending on various types of
+device configuration, this function may be blocked out. Typical behavior
+observed in such cases is a firewall exception report on the security
+controller and armv8 processor reporting a system error.
+
+See @file{tcl/interface/ti_k3_am625-swd-native.cfg} for a sample configuration
+file.
+
+@deffn {Command} {dmem info}
+Print the DAPBUS dmem configuration.
+@end deffn
+
+@deffn {Config Command} {dmem device} device_path
+Set the DAPBUS memory access device (default: /dev/mem).
+@end deffn
+
+@deffn {Config Command} {dmem base_address} base_address
+Set the DAPBUS base address which is used to access CoreSight
+compliant Access Ports (APs) directly.
+@end deffn
+
+@deffn {Config Command} {dmem ap_address_offset} offset_address
+Set the address offset between Access Ports (APs).
+@end deffn
+
+@deffn {Config Command} {dmem max_aps} n
+Set the maximum number of valid access ports on the SoC.
+@end deffn
+
+@deffn {Config Command} {dmem emu_ap_list} n
+Set the list of Access Ports (APs) that need to be emulated. This
+emulation mode supports software translation of an AP request into an
+address mapped transaction that does not rely on physical AP hardware.
+This maybe needed if the AP is either denied access via memory map or
+protected using other SoC mechanisms.
+@end deffn
+
+@deffn {Config Command} {dmem emu_base_address_range} base_address address_window_size
+Set the emulated address and address window size. Both of these
+parameters must be aligned to page size.
+@end deffn
+
@end deffn
@section Transport Configuration
and the debug adapter you are using,
several transports may be available to
communicate with debug targets (or perhaps to program flash memory).
-@deffn Command {transport list}
+@deffn {Command} {transport list}
displays the names of the transports supported by this
version of OpenOCD.
@end deffn
-@deffn Command {transport select} @option{transport_name}
+@deffn {Command} {transport select} @option{transport_name}
Select which of the supported transports to use in this OpenOCD session.
When invoked with @option{transport_name}, attempts to select the named
Flash programming support is built on top of debug support.
JTAG transport is selected with the command @command{transport select
-jtag}. Unless your adapter uses @ref{hla_interface,the hla interface
-driver}, in which case the command is @command{transport select
-hla_jtag}.
+jtag}. Unless your adapter uses either @ref{hla_interface,the hla interface
+driver} (in which case the command is @command{transport select hla_jtag})
+or @ref{st_link_dap_interface,the st-link interface driver} (in which case
+the command is @command{transport select dapdirect_jtag}).
@subsection SWD Transport
@cindex SWD
(Some processors support both JTAG and SWD.)
SWD transport is selected with the command @command{transport select
-swd}. Unless your adapter uses @ref{hla_interface,the hla interface
-driver}, in which case the command is @command{transport select
-hla_swd}.
+swd}. Unless your adapter uses either @ref{hla_interface,the hla interface
+driver} (in which case the command is @command{transport select hla_swd})
+or @ref{st_link_dap_interface,the st-link interface driver} (in which case
+the command is @command{transport select dapdirect_swd}).
-@deffn Command {swd newdap} ...
+@deffn {Config Command} {swd newdap} ...
Declares a single DAP which uses SWD transport.
Parameters are currently the same as "jtag newtap" but this is
expected to change.
@end deffn
-@deffn Command {swd wcr trn prescale}
-Updates TRN (turnaround delay) and prescaling.fields of the
-Wire Control Register (WCR).
-No parameters: displays current settings.
-@end deffn
+
+@cindex SWD multi-drop
+The newer SWD devices (SW-DP v2 or SWJ-DP v2) support the multi-drop extension
+of SWD protocol: two or more devices can be connected to one SWD adapter.
+SWD transport works in multi-drop mode if @ref{dap_create,DAP} is configured
+with both @code{-dp-id} and @code{-instance-id} parameters regardless how many
+DAPs are created.
+
+Not all adapters and adapter drivers support SWD multi-drop. Only the following
+adapter drivers are SWD multi-drop capable:
+cmsis_dap (use an adapter with CMSIS-DAP version 2.0), ftdi, all bitbang based.
@subsection SPI Transport
@cindex SPI
which uses four wire signaling. Some processors use it as part of a
solution for flash programming.
+@anchor{swimtransport}
+@subsection SWIM Transport
+@cindex SWIM
+@cindex Single Wire Interface Module
+The Single Wire Interface Module (SWIM) is a low-pin-count debug protocol used
+by the STMicroelectronics MCU family STM8 and documented in the
+@uref{https://www.st.com/resource/en/user_manual/cd00173911.pdf, User Manual UM470}.
+
+SWIM does not support boundary scan testing nor multiple cores.
+
+The SWIM transport is selected with the command @command{transport select swim}.
+
+The concept of TAPs does not fit in the protocol since SWIM does not implement
+a scan chain. Nevertheless, the current SW model of OpenOCD requires defining a
+virtual SWIM TAP through the command @command{swim newtap basename tap_type}.
+The TAP definition must precede the target definition command
+@command{target create target_name stm8 -chain-position basename.tap_type}.
+
@anchor{jtagspeed}
@section JTAG Speed
JTAG clock setup is part of system setup.
may not be the fastest solution.
@b{NOTE:} Script writers should consider using @command{jtag_rclk}
-instead of @command{adapter_khz}, but only for (ARM) cores and boards
+instead of @command{adapter speed}, but only for (ARM) cores and boards
which support adaptive clocking.
-@deffn {Command} adapter_khz max_speed_kHz
+@deffn {Command} {adapter speed} max_speed_kHz
A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
JTAG interfaces usually support a limited number of
speeds. The speed actually used won't be faster
requirements that all reset pulses last for at least a
certain amount of time; and reset buttons commonly have
hardware debouncing.
-Use the @command{adapter_nsrst_delay} and @command{jtag_ntrst_delay}
+Use the @command{adapter srst delay} and @command{jtag_ntrst_delay}
commands to say when extra delays are needed.
@item @emph{Drive type} ... Reset lines often have a pullup
@section Commands for Handling Resets
-@deffn {Command} adapter_nsrst_assert_width milliseconds
+@deffn {Command} {adapter srst pulse_width} milliseconds
Minimum amount of time (in milliseconds) OpenOCD should wait
after asserting nSRST (active-low system reset) before
allowing it to be deasserted.
@end deffn
-@deffn {Command} adapter_nsrst_delay milliseconds
+@deffn {Command} {adapter srst delay} milliseconds
How long (in milliseconds) OpenOCD should wait after deasserting
nSRST (active-low system reset) before starting new JTAG operations.
When a board has a reset button connected to SRST line it will
probably have hardware debouncing, implying you should use this.
@end deffn
-@deffn {Command} jtag_ntrst_assert_width milliseconds
+@deffn {Command} {jtag_ntrst_assert_width} milliseconds
Minimum amount of time (in milliseconds) OpenOCD should wait
after asserting nTRST (active-low JTAG TAP reset) before
allowing it to be deasserted.
@end deffn
-@deffn {Command} jtag_ntrst_delay milliseconds
+@deffn {Command} {jtag_ntrst_delay} milliseconds
How long (in milliseconds) OpenOCD should wait after deasserting
nTRST (active-low JTAG TAP reset) before starting new JTAG operations.
@end deffn
-@anchor {reset_config}
-@deffn {Command} reset_config mode_flag ...
+@anchor{reset_config}
+@deffn {Command} {reset_config} mode_flag ...
This command displays or modifies the reset configuration
of your combination of JTAG board and target in target
configuration scripts.
or asserting both might trigger a stronger reset, which
needs special attention.
-Experiment with lower level operations, such as @command{jtag_reset}
+Experiment with lower level operations, such as
+@command{adapter assert}, @command{adapter deassert}
and the @command{jtag arp_*} operations shown here,
to find a sequence of operations that works.
@xref{JTAG Commands}.
may need the ability to reset only one target at time and
thus want to avoid using the board-wide SRST signal.
-@deffn {Overridable Procedure} init_reset mode
+@deffn {Overridable Procedure} {init_reset} mode
This is invoked near the beginning of the @command{reset} command,
usually to provide as much of a cold (power-up) reset as practical.
By default it is also invoked from @command{jtag_init} if
The default implementation just invokes @command{jtag arp_init-reset}.
Replacements will normally build on low level JTAG
-operations such as @command{jtag_reset}.
+operations such as @command{adapter assert} and @command{adapter deassert}.
Operations here must not address individual TAPs
(or their associated targets)
until the JTAG scan chain has first been verified to work.
(or @command{jtag arp_init-reset}).
@end deffn
-@deffn Command {jtag arp_init}
+@deffn {Command} {jtag arp_init}
This validates the scan chain using just the four
standard JTAG signals (TMS, TCK, TDI, TDO).
It starts by issuing a JTAG-only reset.
issued to all TAPs with handlers for that event.
@end deffn
-@deffn Command {jtag arp_init-reset}
+@deffn {Command} {jtag arp_init-reset}
This uses TRST and SRST to try resetting
everything on the JTAG scan chain
(and anything else connected to SRST).
instead of literals like @option{str912}, to support more than one chip
of each type. @xref{Config File Guidelines}.
-@deffn Command {jtag names}
+@deffn {Command} {jtag names}
Returns the names of all current TAPs in the scan chain.
Use @command{jtag cget} or @command{jtag tapisenabled}
to examine attributes and state of each TAP.
@end example
@end deffn
-@deffn Command {scan_chain}
+@deffn {Command} {scan_chain}
Displays the TAPs in the scan chain configuration,
and their status.
The set of TAPs listed by this command is fixed by
@section TAP Declaration Commands
-@c shouldn't this be(come) a {Config Command}?
-@deffn Command {jtag newtap} chipname tapname configparams...
+@deffn {Config Command} {jtag newtap} chipname tapname configparams...
Declares a new TAP with the dotted name @var{chipname}.@var{tapname},
and configured according to the various @var{configparams}.
JTAG-level ID for several largely-compatible chips, it may be more practical
to ignore the version field than to update config files to handle all of
the various chip IDs. The version field is defined as bit 28-31 of the IDCODE.
+@item @code{-ignore-bypass}
+@*Specify this to ignore the 'bypass' bit of the idcode. Some vendor put
+an invalid idcode regarding this bit. Specify this to ignore this bit and
+to not consider this tap in bypass mode.
@item @code{-ircapture} @var{NUMBER}
@*The bit pattern loaded by the TAP into the JTAG shift register
on entry to the @sc{ircapture} state, such as 0x01.
register during initial examination and when checking the sticky error bit.
This bit is normally checked after setting the CSYSPWRUPREQ bit, but some
devices do not set the ack bit until sometime later.
+@item @code{-ir-bypass} @var{NUMBER}
+@*Vendor specific bypass instruction, required by some hierarchical JTAG
+routers where the normal BYPASS instruction bypasses the whole router and
+a vendor specific bypass instruction is required to access child nodes.
@end itemize
@end deffn
@section Other TAP commands
-@deffn Command {jtag cget} dotted.name @option{-event} event_name
-@deffnx Command {jtag configure} dotted.name @option{-event} event_name handler
+@deffn {Command} {jtag cget} dotted.name @option{-idcode}
+Get the value of the IDCODE found in hardware.
+@end deffn
+
+@deffn {Command} {jtag cget} dotted.name @option{-event} event_name
+@deffnx {Command} {jtag configure} dotted.name @option{-event} event_name handler
At this writing this TAP attribute
-mechanism is used only for event handling.
+mechanism is limited and used mostly for event handling.
(It is not a direct analogue of the @code{cget}/@code{configure}
mechanism for debugger targets.)
See the next section for information about the available events.
Using brackets @{ @} would cause it to be evaluated later,
at runtime, when it might have a different value.
-@deffn Command {jtag tapdisable} dotted.name
+@deffn {Command} {jtag tapdisable} dotted.name
If necessary, disables the tap
by sending it a @option{tap-disable} event.
Returns the string "1" if the tap
and "0" if it is disabled.
@end deffn
-@deffn Command {jtag tapenable} dotted.name
+@deffn {Command} {jtag tapenable} dotted.name
If necessary, enables the tap
by sending it a @option{tap-enable} event.
Returns the string "1" if the tap
and "0" if it is disabled.
@end deffn
-@deffn Command {jtag tapisenabled} dotted.name
+@deffn {Command} {jtag tapisenabled} dotted.name
Returns the string "1" if the tap
specified by @var{dotted.name} is enabled,
and "0" if it is disabled.
The @command{dap} command group supports the following sub-commands:
-@deffn Command {dap create} dap_name @option{-chain-position} dotted.name configparams...
+@anchor{dap_create}
+@deffn {Command} {dap create} dap_name @option{-chain-position} dotted.name configparams...
Declare a DAP instance named @var{dap_name} linked to the JTAG tap
@var{dotted.name}. This also creates a new command (@command{dap_name})
which is used for various purposes including additional configuration.
A DAP may also provide optional @var{configparams}:
@itemize @bullet
+@item @code{-adiv5}
+Specify that it's an ADIv5 DAP. This is the default if not specified.
+@item @code{-adiv6}
+Specify that it's an ADIv6 DAP.
@item @code{-ignore-syspwrupack}
-@*Specify this to ignore the CSYSPWRUPACK bit in the ARM DAP DP CTRL/STAT
+Specify this to ignore the CSYSPWRUPACK bit in the ARM DAP DP CTRL/STAT
register during initial examination and when checking the sticky error bit.
This bit is normally checked after setting the CSYSPWRUPREQ bit, but some
devices do not set the ack bit until sometime later.
+
+@item @code{-dp-id} @var{number}
+@*Debug port identification number for SWD DPv2 multidrop.
+The @var{number} is written to bits 0..27 of DP TARGETSEL during DP selection.
+To find the id number of a single connected device read DP TARGETID:
+@code{device.dap dpreg 0x24}
+Use bits 0..27 of TARGETID.
+
+@item @code{-instance-id} @var{number}
+@*Instance identification number for SWD DPv2 multidrop.
+The @var{number} is written to bits 28..31 of DP TARGETSEL during DP selection.
+To find the instance number of a single connected device read DP DLPIDR:
+@code{device.dap dpreg 0x34}
+The instance number is in bits 28..31 of DLPIDR value.
@end itemize
@end deffn
-@deffn Command {dap names}
+@deffn {Command} {dap names}
This command returns a list of all registered DAP objects. It it useful mainly
for TCL scripting.
@end deffn
-@deffn Command {dap info} [num]
+@deffn {Command} {dap info} [@var{num}|@option{root}]
Displays the ROM table for MEM-AP @var{num},
defaulting to the currently selected AP of the currently selected target.
+On ADIv5 DAP @var{num} is the numeric index of the AP.
+On ADIv6 DAP @var{num} is the base address of the AP.
+With ADIv6 only, @option{root} specifies the root ROM table.
@end deffn
-@deffn Command {dap init}
+@deffn {Command} {dap init}
Initialize all registered DAPs. This command is used internally
during initialization. It can be issued at any time after the
initialization, too.
The following commands exist as subcommands of DAP instances:
-@deffn Command {$dap_name info} [num]
+@deffn {Command} {$dap_name info} [@var{num}|@option{root}]
Displays the ROM table for MEM-AP @var{num},
defaulting to the currently selected AP.
+On ADIv5 DAP @var{num} is the numeric index of the AP.
+On ADIv6 DAP @var{num} is the base address of the AP.
+With ADIv6 only, @option{root} specifies the root ROM table.
@end deffn
-@deffn Command {$dap_name apid} [num]
+@deffn {Command} {$dap_name apid} [num]
Displays ID register from AP @var{num}, defaulting to the currently selected AP.
+On ADIv5 DAP @var{num} is the numeric index of the AP.
+On ADIv6 DAP @var{num} is the base address of the AP.
@end deffn
@anchor{DAP subcommand apreg}
-@deffn Command {$dap_name apreg} ap_num reg [value]
+@deffn {Command} {$dap_name apreg} ap_num reg [value]
Displays content of a register @var{reg} from AP @var{ap_num}
or set a new value @var{value}.
+On ADIv5 DAP @var{ap_num} is the numeric index of the AP.
+On ADIv6 DAP @var{ap_num} is the base address of the AP.
@var{reg} is byte address of a word register, 0, 4, 8 ... 0xfc.
@end deffn
-@deffn Command {$dap_name apsel} [num]
+@deffn {Command} {$dap_name apsel} [num]
Select AP @var{num}, defaulting to 0.
+On ADIv5 DAP @var{num} is the numeric index of the AP.
+On ADIv6 DAP @var{num} is the base address of the AP.
@end deffn
-@deffn Command {$dap_name dpreg} reg [value]
+@deffn {Command} {$dap_name dpreg} reg [value]
Displays the content of DP register at address @var{reg}, or set it to a new
value @var{value}.
background activity by OpenOCD while you are operating at such low-level.
@end deffn
-@deffn Command {$dap_name baseaddr} [num]
+@deffn {Command} {$dap_name baseaddr} [num]
Displays debug base address from MEM-AP @var{num},
defaulting to the currently selected AP.
+On ADIv5 DAP @var{num} is the numeric index of the AP.
+On ADIv6 DAP @var{num} is the base address of the AP.
@end deffn
-@deffn Command {$dap_name memaccess} [value]
+@deffn {Command} {$dap_name memaccess} [value]
Displays the number of extra tck cycles in the JTAG idle to use for MEM-AP
memory bus access [0-255], giving additional time to respond to reads.
If @var{value} is defined, first assigns that.
@end deffn
-@deffn Command {$dap_name apcsw} [value [mask]]
+@deffn {Command} {$dap_name apcsw} [value [mask]]
Displays or changes CSW bit pattern for MEM-AP transfers.
At the begin of each memory access the CSW pattern is extended (bitwise or-ed)
and leaves the rest of the pattern intact. It configures memory access through
DCache on Cortex-M7.
@example
-set CSW_HPROT3_CACHEABLE [expr 1 << 27]
+set CSW_HPROT3_CACHEABLE [expr @{1 << 27@}]
samv.dap apcsw $CSW_HPROT3_CACHEABLE $CSW_HPROT3_CACHEABLE
@end example
Another example clears SPROT bit and leaves the rest of pattern intact:
@example
-set CSW_SPROT [expr 1 << 30]
+set CSW_SPROT [expr @{1 << 30@}]
samv.dap apcsw 0 $CSW_SPROT
@end example
@end example
@end deffn
-@deffn Command {$dap_name ti_be_32_quirks} [@option{enable}]
+@deffn {Config Command} {$dap_name ti_be_32_quirks} [@option{enable}]
Set/get quirks mode for TI TMS450/TMS570 processors
Disabled by default
@end deffn
+@deffn {Config Command} {$dap_name nu_npcx_quirks} [@option{enable}]
+Set/get quirks mode for Nuvoton NPCX/NPCD MCU families
+Disabled by default
+@end deffn
@node CPU Configuration
@chapter CPU Configuration
Several commands let you examine the list of targets:
-@deffn Command {target current}
+@deffn {Command} {target current}
Returns the name of the current target.
@end deffn
-@deffn Command {target names}
+@deffn {Command} {target names}
Lists the names of all current targets in the list.
@example
foreach t [target names] @{
@c yep, "target list" would have been better.
@c plus maybe "target setdefault".
-@deffn Command targets [name]
+@deffn {Command} {targets} [name]
@emph{Note: the name of this command is plural. Other target
command names are singular.}
since there's a command to list them.
@anchor{targettypes}
-@deffn Command {target types}
+@deffn {Command} {target types}
Lists all supported target types.
At this writing, the supported CPU types are:
@itemize @bullet
-@item @code{arm11} -- this is a generation of ARMv6 cores
-@item @code{arm720t} -- this is an ARMv4 core with an MMU
-@item @code{arm7tdmi} -- this is an ARMv4 core
-@item @code{arm920t} -- this is an ARMv4 core with an MMU
-@item @code{arm926ejs} -- this is an ARMv5 core with an MMU
-@item @code{arm966e} -- this is an ARMv5 core
-@item @code{arm9tdmi} -- this is an ARMv4 core
+@item @code{aarch64} -- this is an ARMv8-A core with an MMU.
+@item @code{arm11} -- this is a generation of ARMv6 cores.
+@item @code{arm720t} -- this is an ARMv4 core with an MMU.
+@item @code{arm7tdmi} -- this is an ARMv4 core.
+@item @code{arm920t} -- this is an ARMv4 core with an MMU.
+@item @code{arm926ejs} -- this is an ARMv5 core with an MMU.
+@item @code{arm946e} -- this is an ARMv5 core with an MMU.
+@item @code{arm966e} -- this is an ARMv5 core.
+@item @code{arm9tdmi} -- this is an ARMv4 core.
@item @code{avr} -- implements Atmel's 8-bit AVR instruction set.
(Support for this is preliminary and incomplete.)
-@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{avr32_ap7k} -- this an AVR32 core.
+@item @code{cortex_a} -- this is an ARMv7-A core with an MMU.
+@item @code{cortex_m} -- this is an ARMv7-M core, supporting only the
+compact Thumb2 instruction set. Supports also ARMv6-M and ARMv8-M cores
+@item @code{cortex_r4} -- this is an ARMv7-R core.
+@item @code{dragonite} -- resembles arm966e.
@item @code{dsp563xx} -- implements Freescale's 24-bit DSP.
(Support for this is still incomplete.)
+@item @code{dsp5680xx} -- implements Freescale's 5680x DSP.
@item @code{esirisc} -- this is an EnSilica eSi-RISC core.
The current implementation supports eSi-32xx cores.
-@item @code{fa526} -- resembles arm920 (w/o Thumb)
-@item @code{feroceon} -- resembles arm926
-@item @code{mips_m4k} -- a MIPS core
-@item @code{xscale} -- this is actually an architecture,
-not a CPU type. It is based on the ARMv5 architecture.
-@item @code{openrisc} -- this is an OpenRISC 1000 core.
-The current implementation supports three JTAG TAP cores:
+@item @code{esp32} -- this is an Espressif SoC with dual Xtensa cores.
+@item @code{esp32s2} -- this is an Espressif SoC with single Xtensa core.
+@item @code{esp32s3} -- this is an Espressif SoC with dual Xtensa cores.
+@item @code{fa526} -- resembles arm920 (w/o Thumb).
+@item @code{feroceon} -- resembles arm926.
+@item @code{hla_target} -- a Cortex-M alternative to work with HL adapters like ST-Link.
@item @code{ls1_sap} -- this is the SAP on NXP LS102x CPUs,
allowing access to physical memory addresses independently of CPU cores.
+@item @code{mem_ap} -- this is an ARM debug infrastructure Access Port without
+a CPU, through which bus read and write cycles can be generated; it may be
+useful for working with non-CPU hardware behind an AP or during development of
+support for new CPUs.
+It's possible to connect a GDB client to this target (the GDB port has to be
+specified, @xref{gdbportoverride,,option -gdb-port}.), and a fake ARM core will
+be emulated to comply to GDB remote protocol.
+@item @code{mips_m4k} -- a MIPS core.
+@item @code{mips_mips64} -- a MIPS64 core.
+@item @code{or1k} -- this is an OpenRISC 1000 core.
+The current implementation supports three JTAG TAP cores:
@itemize @minus
-@item @code{OpenCores TAP} (See: @url{http://opencores.org/project,jtag})
+@item @code{OpenCores TAP} (See: @url{http://opencores.org/project@comma{}jtag})
@item @code{Altera Virtual JTAG TAP} (See: @url{http://www.altera.com/literature/ug/ug_virtualjtag.pdf})
@item @code{Xilinx BSCAN_* virtual JTAG interface} (See: @url{http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_2/spartan6_hdl.pdf})
@end itemize
And two debug interfaces cores:
@itemize @minus
-@item @code{Advanced debug interface} (See: @url{http://opencores.org/project,adv_debug_sys})
-@item @code{SoC Debug Interface} (See: @url{http://opencores.org/project,dbg_interface})
+@item @code{Advanced debug interface}
+@*(See: @url{http://opencores.org/project@comma{}adv_debug_sys})
+@item @code{SoC Debug Interface}
+@*(See: @url{http://opencores.org/project@comma{}dbg_interface})
@end itemize
+@item @code{quark_d20xx} -- an Intel Quark D20xx core.
+@item @code{quark_x10xx} -- an Intel Quark X10xx core.
+@item @code{riscv} -- a RISC-V core.
+@item @code{stm8} -- implements an STM8 core.
+@item @code{testee} -- a dummy target for cases without a real CPU, e.g. CPLD.
+@item @code{xscale} -- this is actually an architecture,
+not a CPU type. It is based on the ARMv5 architecture.
+@item @code{xtensa} -- this is a generic Cadence/Tensilica Xtensa core.
@end itemize
@end deffn
in order to ``de-brick'' your board; or to load programs into
external DDR memory without having run the boot loader.
-@deffn Command {target create} target_name type configparams...
+@deffn {Config Command} {target create} target_name type configparams...
This command creates a GDB debug target that refers to a specific JTAG tap.
It enters that target into a list, and creates a new
command (@command{@var{target_name}}) which is used for various
@end itemize
@end deffn
-@deffn Command {$target_name configure} configparams...
+@deffn {Command} {$target_name configure} configparams...
The options accepted by this command may also be
specified as parameters to @command{target create}.
Their values can later be queried one at a time by
@anchor{rtostype}
@item @code{-rtos} @var{rtos_type} -- enable rtos support for target,
-@var{rtos_type} can be one of @option{auto}, @option{eCos},
+@var{rtos_type} can be one of @option{auto}, @option{none}, @option{eCos},
@option{ThreadX}, @option{FreeRTOS}, @option{linux}, @option{ChibiOS},
-@option{embKernel}, @option{mqx}, @option{uCOS-III}, @option{nuttx}
+@option{embKernel}, @option{mqx}, @option{uCOS-III}, @option{nuttx},
+@option{RIOT}, @option{Zephyr}, @option{rtkernel}
@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.
+@item @code{-ap-num} @var{ap_number} -- set DAP access port for target.
+On ADIv5 DAP @var{ap_number} is the numeric index of the DAP AP the target is connected to.
+On ADIv6 DAP @var{ap_number} is the base address 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.
Use this option to override, for this target only, the global parameter set with
command @command{gdb_port}.
@xref{gdb_port,,command gdb_port}.
+
+@item @code{-gdb-max-connections} @var{number} -- EXPERIMENTAL: set the maximum
+number of GDB connections that are allowed for the target. Default is 1.
+A negative value for @var{number} means unlimited connections.
+See @xref{gdbmeminspect,,Using GDB as a non-intrusive memory inspector}.
@end itemize
@end deffn
The commands supported by OpenOCD target objects are:
-@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}
-@deffnx Command {$target_name arp_waitstate}
+@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}
+@deffnx {Command} {$target_name arp_waitstate}
Internal OpenOCD scripts (most notably @file{startup.tcl})
use these to deal with specific reset cases.
They are not otherwise documented here.
@end deffn
-@deffn Command {$target_name array2mem} arrayname width address count
-@deffnx Command {$target_name mem2array} arrayname width address count
-These provide an efficient script-oriented interface to memory.
-The @code{array2mem} primitive writes bytes, halfwords, or words;
-while @code{mem2array} reads them.
-In both cases, the TCL side uses an array, and
-the target side uses raw memory.
+@deffn {Command} {$target_name set_reg} dict
+Set register values of the target.
+
+@itemize
+@item @var{dict} ... Tcl dictionary with pairs of register names and values.
+@end itemize
+
+For example, the following command sets the value 0 to the program counter (pc)
+register and 0x1000 to the stack pointer (sp) register:
+
+@example
+set_reg @{pc 0 sp 0x1000@}
+@end example
+@end deffn
+
+@deffn {Command} {$target_name get_reg} [-force] list
+Get register values from the target and return them as Tcl dictionary with pairs
+of register names and values.
+If option "-force" is set, the register values are read directly from the
+target, bypassing any caching.
+
+@itemize
+@item @var{list} ... List of register names
+@end itemize
+
+For example, the following command retrieves the values from the program
+counter (pc) and stack pointer (sp) register:
+
+@example
+get_reg @{pc sp@}
+@end example
+@end deffn
+
+@deffn {Command} {$target_name write_memory} address width data ['phys']
+This function provides an efficient way to write to the target memory from a Tcl
+script.
+
+@itemize
+@item @var{address} ... target memory address
+@item @var{width} ... memory access bit size, can be 8, 16, 32 or 64
+@item @var{data} ... Tcl list with the elements to write
+@item ['phys'] ... treat the memory address as physical instead of virtual address
+@end itemize
+
+For example, the following command writes two 32 bit words into the target
+memory at address 0x20000000:
+
+@example
+write_memory 0x20000000 32 @{0xdeadbeef 0x00230500@}
+@end example
+@end deffn
-The efficiency comes from enabling the use of
-bulk JTAG data transfer operations.
-The script orientation comes from working with data
-values that are packaged for use by TCL scripts;
-@command{mdw} type primitives only print data they retrieve,
-and neither store nor return those values.
+@deffn {Command} {$target_name read_memory} address width count ['phys']
+This function provides an efficient way to read the target memory from a Tcl
+script.
+A Tcl list containing the requested memory elements is returned by this function.
@itemize
-@item @var{arrayname} ... is the name of an array variable
-@item @var{width} ... is 8/16/32 - indicating the memory access size
-@item @var{address} ... is the target memory address
-@item @var{count} ... is the number of elements to process
+@item @var{address} ... target memory address
+@item @var{width} ... memory access bit size, can be 8, 16, 32 or 64
+@item @var{count} ... number of elements to read
+@item ['phys'] ... treat the memory address as physical instead of virtual address
@end itemize
+
+For example, the following command reads two 32 bit words from the target
+memory at address 0x20000000:
+
+@example
+read_memory 0x20000000 32 2
+@end example
@end deffn
-@deffn Command {$target_name cget} queryparm
+@deffn {Command} {$target_name cget} queryparm
Each configuration parameter accepted by
@command{$target_name configure}
can be individually queried, to return its current value.
@end deffn
@anchor{targetcurstate}
-@deffn Command {$target_name curstate}
+@deffn {Command} {$target_name curstate}
Displays the current target state:
@code{debug-running},
@code{halted},
(Also, @pxref{eventpolling,,Event Polling}.)
@end deffn
-@deffn Command {$target_name eventlist}
+@deffn {Command} {$target_name debug_reason}
+Displays the current debug reason:
+@code{debug-request},
+@code{breakpoint},
+@code{watchpoint},
+@code{watchpoint-and-breakpoint},
+@code{single-step},
+@code{target-not-halted},
+@code{program-exit},
+@code{exception-catch} or @code{undefined}.
+@end deffn
+
+@deffn {Command} {$target_name eventlist}
Displays a table listing all event handlers
currently associated with this target.
@xref{targetevents,,Target Events}.
@end deffn
-@deffn Command {$target_name invoke-event} event_name
+@deffn {Command} {$target_name invoke-event} event_name
Invokes the handler for the event named @var{event_name}.
(This is primarily intended for use by OpenOCD framework
code, for example by the reset code in @file{startup.tcl}.)
@end deffn
-@deffn Command {$target_name mdw} addr [count]
-@deffnx Command {$target_name mdh} addr [count]
-@deffnx Command {$target_name mdb} addr [count]
+@deffn {Command} {$target_name mdd} [phys] addr [count]
+@deffnx {Command} {$target_name mdw} [phys] addr [count]
+@deffnx {Command} {$target_name mdh} [phys] addr [count]
+@deffnx {Command} {$target_name mdb} [phys] addr [count]
Display contents of address @var{addr}, as
+64-bit doublewords (@command{mdd}),
32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}),
or 8-bit bytes (@command{mdb}).
+When the current target has an MMU which is present and active,
+@var{addr} is interpreted as a virtual address.
+Otherwise, or if the optional @var{phys} flag is specified,
+@var{addr} is interpreted as a physical address.
If @var{count} is specified, displays that many units.
-(If you want to manipulate the data instead of displaying it,
-see the @code{mem2array} primitives.)
+(If you want to process the data instead of displaying it,
+see the @code{read_memory} primitives.)
@end deffn
-@deffn Command {$target_name mww} addr word
-@deffnx Command {$target_name mwh} addr halfword
-@deffnx Command {$target_name mwb} addr byte
-Writes the specified @var{word} (32 bits),
-@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+@deffn {Command} {$target_name mwd} [phys] addr doubleword [count]
+@deffnx {Command} {$target_name mww} [phys] addr word [count]
+@deffnx {Command} {$target_name mwh} [phys] addr halfword [count]
+@deffnx {Command} {$target_name mwb} [phys] addr byte [count]
+Writes the specified @var{doubleword} (64 bits), @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) value,
at the specified address @var{addr}.
+When the current target has an MMU which is present and active,
+@var{addr} is interpreted as a virtual address.
+Otherwise, or if the optional @var{phys} flag is specified,
+@var{addr} is interpreted as a physical address.
+If @var{count} is specified, fills that many units of consecutive address.
@end deffn
@anchor{targetevents}
@* Before target examine is called.
@item @b{examine-end}
@* After target examine is called with no errors.
+@item @b{examine-fail}
+@* After target examine fails.
@item @b{gdb-attach}
@* When GDB connects. Issued before any GDB communication with the target
starts. GDB expects the target is halted during attachment.
before @command{reset-assert-pre} is called.
This is the most robust place to use @command{jtag_rclk}
-or @command{adapter_khz} to switch to a low JTAG clock rate,
+or @command{adapter speed} to switch to a low JTAG clock rate,
when reset disables PLLs needed to use a fast clock.
@item @b{resume-start}
@* Before any target is resumed
@* After all targets have resumed
@item @b{resumed}
@* Target has resumed
+@item @b{step-start}
+@* Before a target is single-stepped
+@item @b{step-end}
+@* After single-step has completed
@item @b{trace-config}
@* After target hardware trace configuration was changed
+@item @b{semihosting-user-cmd-0x100}
+@* The target made a semihosting call with user-defined operation number 0x100
+@item @b{semihosting-user-cmd-0x101}
+@* The target made a semihosting call with user-defined operation number 0x101
+@item @b{semihosting-user-cmd-0x102}
+@* The target made a semihosting call with user-defined operation number 0x102
+@item @b{semihosting-user-cmd-0x103}
+@* The target made a semihosting call with user-defined operation number 0x103
+@item @b{semihosting-user-cmd-0x104}
+@* The target made a semihosting call with user-defined operation number 0x104
+@item @b{semihosting-user-cmd-0x105}
+@* The target made a semihosting call with user-defined operation number 0x105
+@item @b{semihosting-user-cmd-0x106}
+@* The target made a semihosting call with user-defined operation number 0x106
+@item @b{semihosting-user-cmd-0x107}
+@* The target made a semihosting call with user-defined operation number 0x107
@end itemize
+@quotation Note
+OpenOCD events are not supposed to be preempt by another event, but this
+is not enforced in current code. Only the target event @b{resumed} is
+executed with polling disabled; this avoids polling to trigger the event
+@b{halted}, reversing the logical order of execution of their handlers.
+Future versions of OpenOCD will prevent the event preemption and will
+disable the schedule of polling during the event execution. Do not rely
+on polling in any event handler; this means, don't expect the status of
+a core to change during the execution of the handler. The event handler
+will have to enable polling or use @command{$target_name arp_poll} to
+check if the core has changed status.
+@end quotation
+
@node Flash Commands
@chapter Flash Commands
@end quotation
@end deffn
-@comment the REAL name for this command is "ocd_flash_banks"
@comment less confusing would be: "flash list" (like "nand list")
-@deffn Command {flash banks}
+@deffn {Command} {flash banks}
Prints a one-line summary of each device that was
declared using @command{flash bank}, numbered from zero.
Note that this is the @emph{plural} form;
the @emph{singular} form is a very different command.
@end deffn
-@deffn Command {flash list}
+@deffn {Command} {flash list}
Retrieves a list of associative arrays for each device that was
declared using @command{flash bank}, numbered from zero.
This returned list can be manipulated easily from within scripts.
@end deffn
-@deffn Command {flash probe} num
+@deffn {Command} {flash probe} num
Identify the flash, or validate the parameters of the configured flash. Operation
depends on the flash type.
The @var{num} parameter is a value shown by @command{flash banks}.
but most don't bother.
@end deffn
+@section Preparing a Target before Flash Programming
+
+The target device should be in well defined state before the flash programming
+begins.
+
+@emph{Always issue} @command{reset init} before @ref{flashprogrammingcommands,,Flash Programming Commands}.
+Do not issue another @command{reset} or @command{reset halt} or @command{resume}
+until the programming session is finished.
+
+If you use @ref{programmingusinggdb,,Programming using GDB},
+the target is prepared automatically in the event gdb-flash-erase-start
+
+The jimtcl script @command{program} calls @command{reset init} explicitly.
+
@section Erasing, Reading, Writing to Flash
@cindex flash erasing
@cindex flash reading
and AT91SAM7 on-chip flash.
@xref{flashprotect,,flash protect}.
-@deffn Command {flash erase_sector} num first last
+@deffn {Command} {flash erase_sector} num first last
Erase sectors in bank @var{num}, starting at sector @var{first}
up to and including @var{last}.
Sector numbering starts at 0.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {flash erase_address} [@option{pad}] [@option{unlock}] address length
+@deffn {Command} {flash erase_address} [@option{pad}] [@option{unlock}] address length
Erase sectors starting at @var{address} for @var{length} bytes.
Unless @option{pad} is specified, @math{address} must begin a
flash sector, and @math{address + length - 1} must end a sector.
before erase starts.
@end deffn
-@deffn Command {flash fillw} address word length
-@deffnx Command {flash fillh} address halfword length
-@deffnx Command {flash fillb} address byte length
-Fills flash memory with the specified @var{word} (32 bits),
+@deffn {Command} {flash filld} address double-word length
+@deffnx {Command} {flash fillw} address word length
+@deffnx {Command} {flash fillh} address halfword length
+@deffnx {Command} {flash fillb} address byte length
+Fills flash memory with the specified @var{double-word} (64 bits), @var{word} (32 bits),
@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
starting at @var{address} and continuing
for @var{length} units (word/halfword/byte).
@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 mdw} addr [count]
+@deffnx {Command} {flash mdh} addr [count]
+@deffnx {Command} {flash mdb} addr [count]
+Display contents of address @var{addr}, as
+32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}),
+or 8-bit bytes (@command{mdb}).
+If @var{count} is specified, displays that many units.
+Reads from flash using the flash driver, therefore it enables reading
+from a bank not mapped in target address space.
+The flash bank to use is inferred from the @var{address} of
+each block, and the specified length must stay within that bank.
+@end deffn
+
+@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. 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}. If @var{offset} is
omitted, start at the beginning of the flash bank. If @var{length} is omitted,
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 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
-@deffn Command {flash write_image} [erase] [unlock] filename [offset] [type]
+@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.
A relocation @var{offset} may be specified, in which case it is added
@end deffn
+@deffn {Command} {flash verify_image} filename [offset] [type]
+Verify the image @file{filename} to the current target's flash bank(s).
+Parameters follow the description of 'flash write_image'.
+In contrast to the 'verify_image' command, for banks with specific
+verify method, that one is used instead of the usual target's read
+memory methods. This is necessary for flash banks not readable by
+ordinary memory reads.
+This command gives only an overall good/bad result for each bank, not
+addresses of individual failed bytes as it's intended only as quick
+check for successful programming.
+@end deffn
+
@section Other Flash commands
@cindex flash protection
-@deffn Command {flash erase_check} num
+@deffn {Command} {flash erase_check} num
Check erase state of sectors in flash bank @var{num},
and display that status.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {flash info} num [sectors]
+@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.
@end deffn
@anchor{flashprotect}
-@deffn Command {flash protect} num first last (@option{on}|@option{off})
+@deffn {Command} {flash protect} num first last (@option{on}|@option{off})
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}.
See @command{flash info} for a list of protection blocks.
@end deffn
-@deffn Command {flash padded_value} num value
+@deffn {Command} {flash padded_value} num value
Sets the default value used for padding any image sections, This should
normally match the flash bank erased value. If not specified by this
command or the flash driver then it defaults to 0xff.
@end deffn
@anchor{program}
-@deffn Command {program} filename [verify] [reset] [exit] [offset]
+@deffn {Command} {program} filename [preverify] [verify] [reset] [exit] [offset]
This is a helper script that simplifies using OpenOCD as a standalone
programmer. The only required parameter is @option{filename}, the others are optional.
@xref{Flash Programming}.
and allows driver-specific options and behaviors.
Some drivers also activate driver-specific commands.
-@deffn {Flash Driver} virtual
+@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.
@subsection External Flash
-@deffn {Flash Driver} cfi
+@deffn {Flash Driver} {cfi}
@cindex Common Flash Interface
@cindex CFI
The ``Common Flash Interface'' (CFI) is the main standard for
@c "cfi part_id" disabled
@end deffn
-@deffn {Flash Driver} jtagspi
+@anchor{jtagspi}
+@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.
+SPI flash connected to them. To access this flash from the host, some FPGA
+device provides dedicated JTAG instructions, while other FPGA devices should
+be 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
+Since signalling 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
+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
@uref{https://github.com/m-labs/migen, migen} and a Xilinx toolchain to build.
+This mechanism with a proxy bitstream can also be used for FPGAs from Intel and
+Efinix. FPGAs from Lattice and Cologne Chip have dedicated JTAG instructions
+and procedure to connect the JTAG to the SPI signals and don't need a proxy
+bitstream. Support for these devices with dedicated procedure is provided by
+the pld drivers. For convenience the PLD drivers will provide the USERx code
+for FPGAs with a proxy bitstream. Currently the following PLD drivers are able
+to support jtagspi:
+@itemize
+@item Efinix: proxy-bitstream
+@item Gatemate: dedicated procedure
+@item Intel/Altera: proxy-bitstream
+@item Lattice: dedicated procedure supporting ECP2, ECP3, ECP5, Certus and Certus Pro devices
+@item AMD/Xilinx: proxy-bitstream
+@end itemize
+
+
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
functionality is available through the @command{flash write_bank},
@command{flash read_bank}, and @command{flash verify_bank} commands.
+According to device size, 1- to 4-byte addresses are sent. However, some
+flash chips additionally have to be switched to 4-byte addresses by an extra
+command, see below.
+
@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.
+@example
+target create $_TARGETNAME testee -chain-position $_CHIPNAME.tap
+set _USER1_INSTR_CODE 0x02
+flash bank $_FLASHNAME jtagspi 0x0 0 0 0 \
+ $_TARGETNAME $_USER1_INSTR_CODE
+@end example
+
+@item The option @option{-pld} @var{name} is used to have support from the
+PLD driver of pld device @var{name}. The name is the name of the pld device
+given during creation of the pld device.
+Pld device names are shown by the @command{pld devices} command.
+
+@example
+target create $_TARGETNAME testee -chain-position $_CHIPNAME.tap
+set _JTAGSPI_CHAIN_ID $_CHIPNAME.pld
+flash bank $_FLASHNAME jtagspi 0x0 0 0 0 \
+ $_TARGETNAME -pld $_JTAGSPI_CHAIN_ID
+@end example
@end itemize
+@deffn Command {jtagspi set} bank_id name total_size page_size read_cmd unused pprg_cmd mass_erase_cmd sector_size sector_erase_cmd
+Sets flash parameters: @var{name} human readable string, @var{total_size}
+size in bytes, @var{page_size} is write page size. @var{read_cmd} and @var{pprg_cmd}
+are commands for read and page program, respectively. @var{mass_erase_cmd},
+@var{sector_size} and @var{sector_erase_cmd} are optional.
+@example
+jtagspi set 0 w25q128 0x1000000 0x100 0x03 0 0x02 0xC7 0x10000 0xD8
+@end example
+@end deffn
+
+@deffn Command {jtagspi cmd} bank_id resp_num cmd_byte ...
+Sends command @var{cmd_byte} and at most 20 following bytes and reads
+@var{resp_num} bytes afterwards. E.g. for 'Enter 4-byte address mode'
@example
-target create $_TARGETNAME testee -chain-position $_CHIPNAME.fpga
-set _XILINX_USER1 0x02
-flash bank $_FLASHNAME spi 0x0 0 0 0 \
- $_TARGETNAME $_XILINX_USER1
+jtagspi cmd 0 0 0xB7
@end example
@end deffn
-@deffn {Flash Driver} xcf
+@deffn Command {jtagspi always_4byte} bank_id [ on | off ]
+Some devices use 4-byte addresses for all commands except the legacy 0x03 read
+regardless of device size. This command controls the corresponding hack.
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} {xcf}
@cindex Xilinx Platform flash driver
@cindex xcf
Xilinx FPGAs can be configured from specialized flash ICs named Platform Flash.
They must be properly configured for successful FPGA loading using
additional @var{xcf} driver command:
-@deffn Command {xcf ccb} <bank_id>
+@deffn {Command} {xcf ccb} <bank_id>
command accepts additional parameters:
@itemize
@item @var{external|internal} ... selects clock source.
dedicated sector.
@end deffn
-@deffn Command {xcf configure} <bank_id>
+@deffn {Command} {xcf configure} <bank_id>
Initiates FPGA loading procedure. Useful if your board has no "configure"
button.
@example
@end itemize
@end deffn
-@deffn {Flash Driver} lpcspifi
+@deffn {Flash Driver} {lpcspifi}
@cindex NXP SPI Flash Interface
@cindex SPIFI
@cindex lpcspifi
@end deffn
-@deffn {Flash Driver} stmsmi
+@deffn {Flash Driver} {stmsmi}
@cindex STMicroelectronics Serial Memory Interface
@cindex SMI
@cindex stmsmi
@end deffn
-@deffn {Flash Driver} mrvlqspi
+@deffn {Flash Driver} {stmqspi}
+@cindex STMicroelectronics QuadSPI/OctoSPI Interface
+@cindex QuadSPI
+@cindex OctoSPI
+@cindex stmqspi
+Some devices from STMicroelectronics include a proprietary ``QuadSPI Interface''
+(e.g. STM32F4, STM32F7, STM32L4) or ``OctoSPI Interface'' (e.g. STM32L4+)
+controller able to drive one or even two (dual mode) external SPI flash devices.
+The OctoSPI is a superset of QuadSPI, its presence is detected automatically.
+Currently only the regular command mode is supported, whereas the HyperFlash
+mode is not.
+
+QuadSPI/OctoSPI makes the flash contents directly accessible in the CPU address
+space; in case of dual mode both devices must be of the same type and are
+mapped in the same memory bank (even and odd addresses interleaved).
+CPU can directly read data, execute code (but not boot) from QuadSPI bank.
+
+The 'flash bank' command only requires the @var{base} parameter and the extra
+parameter @var{io_base} in order to identify the memory bank. Both are fixed
+by hardware, see datasheet or RM. All other parameters are ignored.
+
+The controller must be initialized after each reset and properly configured
+for memory-mapped read operation for the particular flash chip(s), for the full
+list of available register settings cf. the controller's RM. This setup is quite
+board specific (that's why booting from this memory is not possible). The
+flash driver infers all parameters from current controller register values when
+'flash probe @var{bank_id}' is executed.
+
+Normal OpenOCD commands like @command{mdw} can be used to display the flash content,
+but only after proper controller initialization as described above. However,
+due to a silicon bug in some devices, attempting to access the very last word
+should be avoided.
+
+It is possible to use two (even different) flash chips alternatingly, if individual
+bank chip selects are available. For some package variants, this is not the case
+due to limited pin count. To switch from one to another, adjust FSEL bit accordingly
+and re-issue 'flash probe bank_id'. Note that the bank base address will @emph{not}
+change, so the address spaces of both devices will overlap. In dual flash mode
+both chips must be identical regarding size and most other properties.
+
+Block or sector protection internal to the flash chip is not handled by this
+driver at all, but can be dealt with manually by the 'cmd' command, see below.
+The sector protection via 'flash protect' command etc. is completely internal to
+openocd, intended only to prevent accidental erase or overwrite and it does not
+persist across openocd invocations.
+
+OpenOCD contains a hardcoded list of flash devices with their properties,
+these are auto-detected. If a device is not included in this list, SFDP discovery
+is attempted. If this fails or gives inappropriate results, manual setting is
+required (see 'set' command).
+
+@example
+flash bank $_FLASHNAME stmqspi 0x90000000 0 0 0 \
+ $_TARGETNAME 0xA0001000
+flash bank $_FLASHNAME stmqspi 0x70000000 0 0 0 \
+ $_TARGETNAME 0xA0001400
+@end example
+
+There are three specific commands
+@deffn {Command} {stmqspi mass_erase} bank_id
+Clears sector protections and performs a mass erase. Works only if there is no
+chip specific write protection engaged.
+@end deffn
+
+@deffn {Command} {stmqspi set} bank_id name total_size page_size read_cmd fread_cmd pprg_cmd mass_erase_cmd sector_size sector_erase_cmd
+Set flash parameters: @var{name} human readable string, @var{total_size} size
+in bytes, @var{page_size} is write page size. @var{read_cmd}, @var{fread_cmd} and @var{pprg_cmd}
+are commands for reading and page programming. @var{fread_cmd} is used in DPI and QPI modes,
+@var{read_cmd} in normal SPI (single line) mode. @var{mass_erase_cmd}, @var{sector_size}
+and @var{sector_erase_cmd} are optional.
+
+This command is required if chip id is not hardcoded yet and e.g. for EEPROMs or FRAMs
+which don't support an id command.
+
+In dual mode parameters of both chips are set identically. The parameters refer to
+a single chip, so the whole bank gets twice the specified capacity etc.
+@end deffn
+
+@deffn {Command} {stmqspi cmd} bank_id resp_num cmd_byte ...
+If @var{resp_num} is zero, sends command @var{cmd_byte} and following data
+bytes. In dual mode command byte is sent to @emph{both} chips but data bytes are
+sent @emph{alternatingly} to chip 1 and 2, first to flash 1, second to flash 2, etc.,
+i.e. the total number of bytes (including cmd_byte) must be odd.
+
+If @var{resp_num} is not zero, cmd and at most four following data bytes are
+sent, in dual mode @emph{simultaneously} to both chips. Then @var{resp_num} bytes
+are read interleaved from both chips starting with chip 1. In this case
+@var{resp_num} must be even.
+
+Note the hardware dictated subtle difference of those two cases in dual-flash mode.
+
+To check basic communication settings, issue
+@example
+stmqspi cmd bank_id 0 0x04; stmqspi cmd bank_id 1 0x05
+stmqspi cmd bank_id 0 0x06; stmqspi cmd bank_id 1 0x05
+@end example
+for single flash mode or
+@example
+stmqspi cmd bank_id 0 0x04; stmqspi cmd bank_id 2 0x05
+stmqspi cmd bank_id 0 0x06; stmqspi cmd bank_id 2 0x05
+@end example
+for dual flash mode. This should return the status register contents.
+
+In 8-line mode, @var{cmd_byte} is sent twice - first time as given, second time
+complemented. Additionally, in 8-line mode only, some commands (e.g. Read Status)
+need a dummy address, e.g.
+@example
+stmqspi cmd bank_id 1 0x05 0x00 0x00 0x00 0x00
+@end example
+should return the status register contents.
+
+@end deffn
+
+@end deffn
+
+@deffn {Flash Driver} {mrvlqspi}
This driver supports QSPI flash controller of Marvell's Wireless
Microcontroller platform.
@end deffn
-@deffn {Flash Driver} ath79
+@deffn {Flash Driver} {ath79}
@cindex Atheros ath79 SPI driver
@cindex ath79
Members of ATH79 SoC family from Atheros include a SPI interface with 3
@example
flash bank $_FLASHNAME ath79 0xbf000000 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.
+# 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 0xbf000000 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 deffn
-@deffn {Flash Driver} fespi
+@deffn {Flash Driver} {fespi}
@cindex Freedom E SPI
@cindex fespi
@subsection Internal Flash (Microcontrollers)
-@deffn {Flash Driver} aduc702x
+@deffn {Flash Driver} {aduc702x}
The ADUC702x analog microcontrollers from Analog Devices
include internal flash and use ARM7TDMI cores.
The aduc702x flash driver works with models ADUC7019 through ADUC7028.
@end example
@end deffn
-@deffn {Flash Driver} ambiqmicro
+@deffn {Flash Driver} {ambiqmicro}
@cindex ambiqmicro
@cindex apollo
All members of the Apollo microcontroller family from
The @var{ambiqmicro} driver adds some additional commands:
-@deffn Command {ambiqmicro mass_erase} <bank>
+@deffn {Command} {ambiqmicro mass_erase} <bank>
Erase entire bank.
@end deffn
-@deffn Command {ambiqmicro page_erase} <bank> <first> <last>
+@deffn {Command} {ambiqmicro page_erase} <bank> <first> <last>
Erase device pages.
@end deffn
-@deffn Command {ambiqmicro program_otp} <bank> <offset> <count>
+@deffn {Command} {ambiqmicro program_otp} <bank> <offset> <count>
Program OTP is a one time operation to create write protected flash.
The user writes sectors to SRAM starting at 0x10000010.
Program OTP will write these sectors from SRAM to flash, and write protect
@end deffn
@end deffn
-@anchor{at91samd}
-@deffn {Flash Driver} at91samd
+@deffn {Flash Driver} {at91samd}
@cindex at91samd
All members of the ATSAM D2x, D1x, D0x, ATSAMR, ATSAML and ATSAMC microcontroller
families from Atmel include internal flash and use ARM's Cortex-M0+ core.
flash bank $_FLASHNAME at91samd 0x00000000 0 1 1 $_TARGETNAME
@end example
-@deffn Command {at91samd chip-erase}
+@deffn {Command} {at91samd chip-erase}
Issues a complete Flash erase via the Device Service Unit (DSU). This can be
used to erase a chip back to its factory state and does not require the
processor to be halted.
@end deffn
-@deffn Command {at91samd set-security}
+@deffn {Command} {at91samd set-security}
Secures the Flash via the Set Security Bit (SSB) command. This prevents access
to the Flash and can only be undone by using the chip-erase command which
erases the Flash contents and turns off the security bit. Warning: at this
@end example
@end deffn
-@deffn Command {at91samd eeprom}
+@deffn {Command} {at91samd eeprom}
Shows or sets the EEPROM emulation size configuration, stored in the User Row
of the Flash. When setting, the EEPROM size must be specified in bytes and it
must be one of the permitted sizes according to the datasheet. Settings are
@end example
@end deffn
-@deffn Command {at91samd bootloader}
+@deffn {Command} {at91samd bootloader}
Shows or sets the bootloader size configuration, stored in the User Row of the
Flash. This is called the BOOTPROT region. When setting, the bootloader size
must be specified in bytes and it must be one of the permitted sizes according
@end example
@end deffn
-@deffn Command {at91samd dsu_reset_deassert}
+@deffn {Command} {at91samd dsu_reset_deassert}
This command releases internal reset held by DSU
and prepares reset vector catch in case of reset halt.
-Command is used internally in event event reset-deassert-post.
+Command is used internally in event reset-deassert-post.
@end deffn
-@deffn Command {at91samd nvmuserrow}
+@deffn {Command} {at91samd nvmuserrow}
Writes or reads the entire 64 bit wide NVM user row register which is located at
0x804000. This register includes various fuses lock-bits and factory calibration
data. Reading the register is done by invoking this command without any
NVMUSERROW: 0xFFFFFC5DD8E0C788
# Write 0xFFFFFC5DD8E0C788 to user row
>at91samd nvmuserrow 0xFFFFFC5DD8E0C788
-# Write 0x12300 to user row but leave other bits and low byte unchanged
+# Write 0x12300 to user row but leave other bits and low
+# byte unchanged
>at91samd nvmuserrow 0x12345 0xFFF00
@end example
@end deffn
@end deffn
@anchor{at91sam3}
-@deffn {Flash Driver} at91sam3
+@deffn {Flash Driver} {at91sam3}
@cindex at91sam3
All members of the AT91SAM3 microcontroller family from
Atmel include internal flash and use ARM's Cortex-M3 core. The driver
The AT91SAM3 driver adds some additional commands:
-@deffn Command {at91sam3 gpnvm}
-@deffnx Command {at91sam3 gpnvm clear} number
-@deffnx Command {at91sam3 gpnvm set} number
-@deffnx Command {at91sam3 gpnvm show} [@option{all}|number]
+@deffn {Command} {at91sam3 gpnvm}
+@deffnx {Command} {at91sam3 gpnvm clear} number
+@deffnx {Command} {at91sam3 gpnvm set} number
+@deffnx {Command} {at91sam3 gpnvm show} [@option{all}|number]
With no parameters, @command{show} or @command{show all},
shows the status of all GPNVM bits.
With @command{show} @var{number}, displays that bit.
modifies that GPNVM bit.
@end deffn
-@deffn Command {at91sam3 info}
+@deffn {Command} {at91sam3 info}
This command attempts to display information about the AT91SAM3
chip. @emph{First} it read the @code{CHIPID_CIDR} [address 0x400e0740, see
Section 28.2.1, page 505 of the AT91SAM3U 29/may/2009 datasheet,
be 32768 Hz, see the command @command{at91sam3 slowclk}.
@end deffn
-@deffn Command {at91sam3 slowclk} [value]
+@deffn {Command} {at91sam3 slowclk} [value]
This command shows/sets the slow clock frequency used in the
@command{at91sam3 info} command calculations above.
@end deffn
@end deffn
-@deffn {Flash Driver} at91sam4
+@deffn {Flash Driver} {at91sam4}
@cindex at91sam4
All members of the AT91SAM4 microcontroller family from
Atmel include internal flash and use ARM's Cortex-M4 core.
This driver uses the same command names/syntax as @xref{at91sam3}.
@end deffn
-@deffn {Flash Driver} at91sam4l
+@deffn {Flash Driver} {at91sam4l}
@cindex at91sam4l
All members of the AT91SAM4L microcontroller family from
Atmel include internal flash and use ARM's Cortex-M4 core.
This driver uses the same command names/syntax as @xref{at91sam3}.
The AT91SAM4L driver adds some additional commands:
-@deffn Command {at91sam4l smap_reset_deassert}
+@deffn {Command} {at91sam4l smap_reset_deassert}
This command releases internal reset held by SMAP
and prepares reset vector catch in case of reset halt.
-Command is used internally in event event reset-deassert-post.
+Command is used internally in event reset-deassert-post.
@end deffn
@end deffn
@anchor{atsame5}
-@deffn {Flash Driver} atsame5
+@deffn {Flash Driver} {atsame5}
@cindex atsame5
All members of the SAM E54, E53, E51 and D51 microcontroller
families from Microchip (former Atmel) include internal flash
flash bank $_FLASHNAME atsame5 0x00000000 0 1 1 $_TARGETNAME
@end example
-@deffn Command {atsame5 bootloader}
+@deffn {Command} {atsame5 bootloader}
Shows or sets the bootloader size configuration, stored in the User Page of the
Flash. This is called the BOOTPROT region. When setting, the bootloader size
must be specified in bytes. The nearest bigger protection size is used.
@end example
@end deffn
-@deffn Command {atsame5 chip-erase}
+@deffn {Command} {atsame5 chip-erase}
Issues a complete Flash erase via the Device Service Unit (DSU). This can be
used to erase a chip back to its factory state and does not require the
processor to be halted.
@end deffn
-@deffn Command {atsame5 dsu_reset_deassert}
+@deffn {Command} {atsame5 dsu_reset_deassert}
This command releases internal reset held by DSU
and prepares reset vector catch in case of reset halt.
-Command is used internally in event event reset-deassert-post.
+Command is used internally in event reset-deassert-post.
@end deffn
-@deffn Command {atsame5 userpage}
+@deffn {Command} {atsame5 userpage}
Writes or reads the first 64 bits of NVM User Page which is located at
0x804000. This field includes various fuses.
Reading is done by invoking this command without any arguments.
USER PAGE: 0xAEECFF80FE9A9239
# Write
>atsame5 userpage 0xAEECFF80FE9A9239
-# Write 2 to SEESBLK and 4 to SEEPSZ fields but leave other bits unchanged
-# (setup SmartEEPROM of virtual size 8192 bytes)
+# Write 2 to SEESBLK and 4 to SEEPSZ fields but leave other
+# bits unchanged (setup SmartEEPROM of virtual size 8192
+# bytes)
>atsame5 userpage 0x4200000000 0x7f00000000
@end example
@end deffn
@end deffn
-@deffn {Flash Driver} atsamv
+@deffn {Flash Driver} {atsamv}
@cindex atsamv
All members of the ATSAMV7x, ATSAMS70, and ATSAME70 families from
Atmel include internal flash and use ARM's Cortex-M7 core.
This driver uses the same command names/syntax as @xref{at91sam3}.
+
+@example
+flash bank $_FLASHNAME atsamv 0x00400000 0 0 0 $_TARGETNAME
+@end example
+
+@deffn {Command} {atsamv gpnvm} [@option{show} [@option{all}|number]]
+@deffnx {Command} {atsamv gpnvm} (@option{clr}|@option{set}) number
+With no parameters, @option{show} or @option{show all},
+shows the status of all GPNVM bits.
+With @option{show} @var{number}, displays that bit.
+
+With @option{set} @var{number} or @option{clear} @var{number},
+modifies that GPNVM bit.
+@end deffn
+
@end deffn
-@deffn {Flash Driver} at91sam7
+@deffn {Flash Driver} {at91sam7}
All members of the AT91SAM7 microcontroller family from Atmel include
internal flash and use ARM7TDMI cores. The driver automatically
recognizes a number of these chips using the chip identification
plane (of up to 256KB), and it will be used automatically when you issue
@command{flash erase_sector} or @command{flash erase_address} commands.
-@deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
+@deffn {Command} {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
Set or clear a ``General Purpose Non-Volatile Memory'' (GPNVM)
bit for the processor. Each processor has a number of such bits,
used for controlling features such as brownout detection (so they
@end deffn
@end deffn
-@deffn {Flash Driver} avr
+@deffn {Flash Driver} {avr}
The AVR 8-bit microcontrollers from Atmel integrate flash memory.
@emph{The current implementation is incomplete.}
@comment - defines mass_erase ... pointless given flash_erase_address
@end deffn
-@deffn {Flash Driver} bluenrg-x
-STMicroelectronics BlueNRG-1 and BlueNRG-2 Bluetooth low energy wireless system-on-chip. They include ARM Cortex-M0 core and internal flash memory.
+@deffn {Flash Driver} {bluenrg-x}
+STMicroelectronics BlueNRG-1, BlueNRG-2 and BlueNRG-LP/LPS Bluetooth low energy wireless system-on-chip. They include ARM Cortex-M0/M0+ core and internal flash memory.
The driver automatically recognizes these chips using
the chip identification registers, and autoconfigures itself.
each single sector one by one.
@example
-flash erase_sector 0 0 79 # It will perform a mass erase on BlueNRG-1
-@end example
-
-@example
-flash erase_sector 0 0 127 # It will perform a mass erase on BlueNRG-2
+flash erase_sector 0 0 last # It will perform a mass erase
@end example
Triggering a mass erase is also useful when users want to disable readout protection.
@end deffn
-@deffn {Flash Driver} cc26xx
+@deffn {Flash Driver} {cc26xx}
All versions of the SimpleLink CC13xx and CC26xx microcontrollers from Texas
Instruments include internal flash. The cc26xx flash driver supports both the
CC13xx and CC26xx family of devices. The driver automatically recognizes the
@end example
@end deffn
-@deffn {Flash Driver} cc3220sf
+@deffn {Flash Driver} {cc3220sf}
The CC3220SF version of the SimpleLink CC32xx microcontrollers from Texas
Instruments includes 1MB of internal flash. The cc3220sf flash driver only
supports the internal flash. The serial flash on SimpleLink boards is
@end example
@end deffn
-@deffn {Flash Driver} efm32
-All members of the EFM32 microcontroller family from Energy Micro include
-internal flash and use ARM Cortex-M3 cores. The driver automatically recognizes
-a number of these chips using the chip identification register, and
+@deffn {Flash Driver} {efm32}
+All members of the EFM32/EFR32 microcontroller family from Energy Micro (now Silicon Labs)
+include internal flash and use Arm Cortex-M3 or Cortex-M4 cores. The driver automatically
+recognizes a number of these chips using the chip identification register, and
autoconfigures itself.
@example
flash bank $_FLASHNAME efm32 0 0 0 0 $_TARGETNAME
@end example
+It supports writing to the user data page, as well as the portion of the lockbits page
+past 512 bytes on chips with larger page sizes. The latter is used by the SiLabs
+bootloader/AppLoader system for encryption keys. Setting protection on these pages is
+currently not supported.
+@example
+flash bank userdata.flash efm32 0x0FE00000 0 0 0 $_TARGETNAME
+flash bank lockbits.flash efm32 0x0FE04000 0 0 0 $_TARGETNAME
+@end example
+
A special feature of efm32 controllers is that it is possible to completely disable the
debug interface by writing the correct values to the 'Debug Lock Word'. OpenOCD supports
this via the following command:
supported.}
@end deffn
-@deffn {Flash Driver} esirisc
+@deffn {Flash Driver} {eneispif}
+All versions of the KB1200 microcontrollers from ENE include internal
+flash. The eneispif flash driver supports the KB1200 family of devices. The driver
+automatically recognizes the specific version's flash parameters and
+autoconfigures itself. The flash bank starts at address 0x60000000. An optional additional
+parameter sets the address of eneispif controller, with the default address is 0x50101000.
+
+@example
+
+flash bank $_FLASHNAME eneispif 0x60000000 0 0 0 $_TARGETNAME \
+ 0x50101000
+
+# Address defaults to 0x50101000
+flash bank $_FLASHNAME eneispif 0x60000000 0 0 0 $_TARGETNAME
+
+@end example
+@end deffn
+
+@deffn {Flash Driver} {esirisc}
Members of the eSi-RISC family may optionally include internal flash programmed
via the eSi-TSMC Flash interface. Additional parameters are required to
configure the driver: @option{cfg_address} is the base address of the
$_TARGETNAME cfg_address clock_hz wait_states
@end example
-@deffn Command {esirisc flash mass_erase} bank_id
+@deffn {Command} {esirisc flash mass_erase} bank_id
Erase all pages in data memory for the bank identified by @option{bank_id}.
@end deffn
-@deffn Command {esirisc flash ref_erase} bank_id
+@deffn {Command} {esirisc flash ref_erase} bank_id
Erase the reference cell for the bank identified by @option{bank_id}. @emph{This
is an uncommon operation.}
@end deffn
@end deffn
-@deffn {Flash Driver} fm3
+@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
@end example
@end deffn
-@deffn {Flash Driver} fm4
+@deffn {Flash Driver} {fm4}
All members of the FM4 microcontroller family from Spansion (formerly Fujitsu)
include internal flash and use ARM Cortex-M4 cores.
The @var{fm4} driver uses a @var{family} parameter to select the
nor is Chip Erase (only Sector Erase is implemented).}
@end deffn
-@deffn {Flash Driver} kinetis
+@deffn {Flash Driver} {kinetis}
@cindex kinetis
-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
+Several microcontrollers from NXP (former Freescale), including
+Kx, KLx, KVx and KE1x members of the Kinetis family,
+and S32K11x/S32K14x microcontrollers, include
+internal flash and use ARM Cortex-M0+ or M4 cores.
+Kinetis and S32K1 families use incompatible
+identification registers, so the driver assumes Kinetis and requires
+a driver option to indicate S32K1 is to be used.
+Within the familiy, 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 and KEAx 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.
+@item -s32k select S32K11x/S32K14x microcontroller flash support.
+
+@item -sim-base @var{addr} ... base of System Integration Module where chip identification resides. Driver tries 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}
+@deffn {Config 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]
+@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.
@emph{BEWARE: Incorrect flash configuration may permanently lock the device!}
@end deffn
-@deffn Command {kinetis fopt} [num]
+@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.
+@deffn {Command} {kinetis mdm check_security}
+Checks status of device security lock. Used internally in examine-end
+and examine-fail event.
@end deffn
-@deffn Command {kinetis mdm halt}
+@deffn {Command} {kinetis mdm halt}
Issues a halt via the MDM-AP. This command can be used to break a watchdog reset
loop when connecting to an unsecured target.
@end deffn
-@deffn Command {kinetis mdm mass_erase}
+@deffn {Command} {kinetis mdm mass_erase}
Issues a complete flash erase via the MDM-AP. This can be used to erase a chip
back to its factory state, removing security. It does not require the processor
to be halted, however the target will remain in a halted state after this
command completes.
@end deffn
-@deffn Command {kinetis nvm_partition}
+@deffn {Command} {kinetis nvm_partition}
For FlexNVM devices only (KxxDX and KxxFX).
+Not supported (yet) on S32K1 devices.
Command shows or sets data flash or EEPROM backup size in kilobytes,
sets two EEPROM blocks sizes in bytes and enables/disables loading
of EEPROM contents to FlexRAM during reset.
@end example
@end deffn
-@deffn Command {kinetis mdm reset}
+@deffn {Command} {kinetis mdm reset}
Issues a reset via the MDM-AP. This causes the MCU to output a low pulse on the
RESET pin, which can be used to reset other hardware on board.
@end deffn
-@deffn Command {kinetis disable_wdog}
+@deffn {Command} {kinetis disable_wdog}
For Kx devices only (KLx has different COP watchdog, it is not supported).
Command disables watchdog timer.
@end deffn
@end deffn
-@deffn {Flash Driver} kinetis_ke
+@deffn {Flash Driver} {kinetis_ke}
@cindex kinetis_ke
KE0x and KEAx members of the Kinetis microcontroller family from NXP include
internal flash and use ARM Cortex-M0+. The driver automatically recognizes
flash bank $_FLASHNAME kinetis_ke 0 0 0 0 $_TARGETNAME
@end example
-@deffn Command {kinetis_ke mdm check_security}
+@deffn {Command} {kinetis_ke mdm check_security}
Checks status of device security lock. Used internally in examine-end event.
@end deffn
-@deffn Command {kinetis_ke mdm mass_erase}
+@deffn {Command} {kinetis_ke mdm mass_erase}
Issues a complete Flash erase via the MDM-AP.
This can be used to erase a chip back to its factory state.
Command removes security lock from a device (use of SRST highly recommended).
It does not require the processor to be halted.
@end deffn
-@deffn Command {kinetis_ke disable_wdog}
+@deffn {Command} {kinetis_ke disable_wdog}
Command disables watchdog timer.
@end deffn
@end deffn
-@deffn {Flash Driver} lpc2000
+@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
the LPC800, LPC1500, LPC1700, LPC1800, LPC2000, LPC4000, LPC54100,
@end deffn
@end deffn
-@deffn {Flash Driver} lpc288x
+@deffn {Flash Driver} {lpc288x}
The LPC2888 microcontroller from NXP needs slightly different flash
support from its lpc2000 siblings.
The @var{lpc288x} driver defines one mandatory parameter,
@end example
@end deffn
-@deffn {Flash Driver} lpc2900
+@deffn {Flash Driver} {lpc2900}
This driver supports the LPC29xx ARM968E based microcontroller family
from NXP.
the @var{bank} parameter is the bank number as obtained by the
@code{flash banks} command.
-@deffn Command {lpc2900 signature} bank
+@deffn {Command} {lpc2900 signature} bank
Calculates a 128-bit hash value, the @emph{signature}, from the whole flash
content. This is a hardware feature of the flash block, hence the calculation is
very fast. You may use this to verify the content of a programmed device against
@end example
@end deffn
-@deffn Command {lpc2900 read_custom} bank filename
+@deffn {Command} {lpc2900 read_custom} bank filename
Reads the 912 bytes of customer information from the flash index sector, and
saves it to a file in binary format.
Example:
commands need to be preceded by a successful call to the @code{password}
command:
-@deffn Command {lpc2900 password} bank password
+@deffn {Command} {lpc2900 password} bank password
You need to use this command right before each of the following commands:
@code{lpc2900 write_custom}, @code{lpc2900 secure_sector},
@code{lpc2900 secure_jtag}.
@end example
@end deffn
-@deffn Command {lpc2900 write_custom} bank filename type
+@deffn {Command} {lpc2900 write_custom} bank filename type
Writes the content of the file into the customer info space of the flash index
sector. The filetype can be specified with the @var{type} field. Possible values
for @var{type} are: @var{bin} (binary), @var{ihex} (Intel hex format),
@end example
@end deffn
-@deffn Command {lpc2900 secure_sector} bank first last
+@deffn {Command} {lpc2900 secure_sector} bank first last
Secures the sector range from @var{first} to @var{last} (including) against
further program and erase operations. The sector security will be effective
after the next power cycle.
@end example
@end deffn
-@deffn Command {lpc2900 secure_jtag} bank
+@deffn {Command} {lpc2900 secure_jtag} bank
Irreversibly disable the JTAG port. The new JTAG security setting will be
effective after the next power cycle.
@quotation Attention
@end deffn
@end deffn
-@deffn {Flash Driver} mdr
+@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.
@end example
@end deffn
-@deffn {Flash Driver} msp432
+@deffn {Flash Driver} {msp432}
All versions of the SimpleLink MSP432 microcontrollers from Texas
Instruments include internal flash. The msp432 flash driver automatically
recognizes the specific version's flash parameters and autoconfigures itself.
-Main program flash (starting at address 0) is flash bank 0. Information flash
-region on MSP432P4 versions (starting at address 0x200000) is flash bank 1.
+Main program flash starts at address 0. The information flash region on
+MSP432P4 versions starts at address 0x200000.
@example
flash bank $_FLASHNAME msp432 0 0 0 0 $_TARGETNAME
@end example
-@deffn Command {msp432 mass_erase} [main|all]
+@deffn {Command} {msp432 mass_erase} bank_id [main|all]
Performs a complete erase of flash. By default, @command{mass_erase} will erase
only the main program flash.
flash, the user must first use the @command{bsl} command.
@end deffn
-@deffn Command {msp432 bsl} [unlock|lock]
+@deffn {Command} {msp432 bsl} bank_id [unlock|lock]
On MSP432P4 versions, @command{bsl} unlocks and locks the bootstrap loader (BSL)
region in information flash so that flash commands can erase or write the BSL.
Leave the BSL locked to prevent accidentally corrupting the bootstrap loader.
@end deffn
@end deffn
-@deffn {Flash Driver} niietcm4
+@deffn {Flash Driver} {niietcm4}
This drivers handles the integrated NOR flash on NIIET Cortex-M4
based controllers. Flash size and sector layout are auto-configured by the driver.
Main flash memory is called "Bootflash" and has main region and info region.
Some niietcm4-specific commands are defined:
-@deffn Command {niietcm4 uflash_read_byte} bank ('main'|'info') address
+@deffn {Command} {niietcm4 uflash_read_byte} bank ('main'|'info') address
Read byte from main or info userflash region.
@end deffn
-@deffn Command {niietcm4 uflash_write_byte} bank ('main'|'info') address value
+@deffn {Command} {niietcm4 uflash_write_byte} bank ('main'|'info') address value
Write byte to main or info userflash region.
@end deffn
-@deffn Command {niietcm4 uflash_full_erase} bank
+@deffn {Command} {niietcm4 uflash_full_erase} bank
Erase all userflash including info region.
@end deffn
-@deffn Command {niietcm4 uflash_erase} bank ('main'|'info') first_sector last_sector
+@deffn {Command} {niietcm4 uflash_erase} bank ('main'|'info') first_sector last_sector
Erase sectors of main or info userflash region, starting at sector first up to and including last.
@end deffn
-@deffn Command {niietcm4 uflash_protect_check} bank ('main'|'info')
+@deffn {Command} {niietcm4 uflash_protect_check} bank ('main'|'info')
Check sectors protect.
@end deffn
-@deffn Command {niietcm4 uflash_protect} bank ('main'|'info') first_sector last_sector ('on'|'off')
+@deffn {Command} {niietcm4 uflash_protect} bank ('main'|'info') first_sector last_sector ('on'|'off')
Protect sectors of main or info userflash region, starting at sector first up to and including last.
@end deffn
-@deffn Command {niietcm4 bflash_info_remap} bank ('on'|'off')
+@deffn {Command} {niietcm4 bflash_info_remap} bank ('on'|'off')
Enable remapping bootflash info region to 0x00000000 (or 0x40000000 if external memory boot used).
@end deffn
-@deffn Command {niietcm4 extmem_cfg} bank ('gpioa'|'gpiob'|'gpioc'|'gpiod'|'gpioe'|'gpiof'|'gpiog'|'gpioh') pin_num ('func1'|'func3')
+@deffn {Command} {niietcm4 extmem_cfg} bank ('gpioa'|'gpiob'|'gpioc'|'gpiod'|'gpioe'|'gpiof'|'gpiog'|'gpioh') pin_num ('func1'|'func3')
Configure external memory interface for boot.
@end deffn
-@deffn Command {niietcm4 service_mode_erase} bank
+@deffn {Command} {niietcm4 service_mode_erase} bank
Perform emergency erase of all flash (bootflash and userflash).
@end deffn
-@deffn Command {niietcm4 driver_info} bank
+@deffn {Command} {niietcm4 driver_info} bank
Show information about flash driver.
@end deffn
@end deffn
-@deffn {Flash Driver} nrf5
+@deffn {Flash Driver} {npcx}
+All versions of the NPCX microcontroller families from Nuvoton include internal
+flash. The NPCX flash driver supports the NPCX family of devices. The driver
+automatically recognizes the specific version's flash parameters and
+autoconfigures itself. The flash bank starts at address 0x64000000. An optional additional
+parameter sets the FIU version for the bank, with the default FIU is @var{npcx.fiu}.
+
+@example
+
+flash bank $_FLASHNAME npcx 0x64000000 0 0 0 $_TARGETNAME npcx_v2.fiu
+
+# FIU defaults to npcx.fiu
+flash bank $_FLASHNAME npcx 0x64000000 0 0 0 $_TARGETNAME
+
+@end example
+@end deffn
+
+@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.
+include internal flash and use ARM Cortex-M0 core. nRF52 family powered
+by ARM Cortex-M4 or M4F core is supported too. nRF52832 is fully supported
+including BPROT flash protection scheme. nRF52833 and nRF52840 devices are
+supported with the exception of security extensions (flash access control list
+- ACL).
@example
flash bank $_FLASHNAME nrf5 0 0x00000000 0 0 $_TARGETNAME
Some nrf5-specific commands are defined:
-@deffn Command {nrf5 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
@end deffn
-@deffn {Flash Driver} ocl
+@deffn {Flash Driver} {ocl}
This driver is an implementation of the ``on chip flash loader''
protocol proposed by Pavel Chromy.
@end example
@end deffn
-@deffn {Flash Driver} pic32mx
+@deffn {Flash Driver} {pic32mx}
The PIC32MX microcontrollers are based on the MIPS 4K cores,
and integrate flash memory.
@comment - lock, unlock ... pointless given protect on/off (yes?)
@comment - pgm_word ... shouldn't bank be deduced from address??
Some pic32mx-specific commands are defined:
-@deffn Command {pic32mx pgm_word} address value bank
+@deffn {Command} {pic32mx pgm_word} address value bank
Programs the specified 32-bit @var{value} at the given @var{address}
in the specified chip @var{bank}.
@end deffn
-@deffn Command {pic32mx unlock} bank
+@deffn {Command} {pic32mx unlock} bank
Unlock and erase specified chip @var{bank}.
This will remove any Code Protection.
@end deffn
@end deffn
-@deffn {Flash Driver} psoc4
+@deffn {Flash Driver} {psoc4}
All members of the PSoC 41xx/42xx microcontroller family from Cypress
include internal flash and use ARM Cortex-M0 cores.
The driver automatically recognizes a number of these chips using
@end example
psoc4-specific commands
-@deffn Command {psoc4 flash_autoerase} num (on|off)
+@deffn {Command} {psoc4 flash_autoerase} num (on|off)
Enables or disables autoerase mode for a flash bank.
If flash_autoerase is off, use mass_erase before flash programming.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {psoc4 mass_erase} num
+@deffn {Command} {psoc4 mass_erase} num
Erases the contents of the flash memory, protection and security lock.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@end deffn
-@deffn {Flash Driver} psoc5lp
+@deffn {Flash Driver} {psoc5lp}
All members of the PSoC 5LP microcontroller family from Cypress
include internal program flash and use ARM Cortex-M3 cores.
The driver probes for a number of these chips and autoconfigures itself,
Commands defined in the @var{psoc5lp} driver:
-@deffn Command {psoc5lp mass_erase}
+@deffn {Command} {psoc5lp mass_erase}
Erases all flash data and ECC/configuration bytes, all flash protection rows,
and all row latches in all flash arrays on the device.
@end deffn
@end deffn
-@deffn {Flash Driver} psoc5lp_eeprom
+@deffn {Flash Driver} {psoc5lp_eeprom}
All members of the PSoC 5LP microcontroller family from Cypress
include internal EEPROM and use ARM Cortex-M3 cores.
The driver probes for a number of these chips and autoconfigures itself,
apart from the base address.
@example
-flash bank $_CHIPNAME.eeprom psoc5lp_eeprom 0x40008000 0 0 0 $_TARGETNAME
+flash bank $_CHIPNAME.eeprom psoc5lp_eeprom 0x40008000 0 0 0 \
+ $_TARGETNAME
@end example
@end deffn
-@deffn {Flash Driver} psoc5lp_nvl
+@deffn {Flash Driver} {psoc5lp_nvl}
All members of the PSoC 5LP microcontroller family from Cypress
include internal Nonvolatile Latches and use ARM Cortex-M3 cores.
The driver probes for a number of these chips and autoconfigures itself.
@end quotation
@end deffn
-@deffn {Flash Driver} psoc6
+@deffn {Flash Driver} {psoc6}
Supports PSoC6 (CY8C6xxx) family of Cypress microcontrollers.
PSoC6 is a dual-core device with CM0+ and CM4 cores. Both cores share
the same Flash/RAM/MMIO address space.
PSoC6 is equipped with NOR Flash so erased Flash reads as 0x00.
@example
-flash bank main_flash_cm0 psoc6 0x10000000 0 0 0 $@{TARGET@}.cm0
-flash bank work_flash_cm0 psoc6 0x14000000 0 0 0 $@{TARGET@}.cm0
-flash bank super_flash_user_cm0 psoc6 0x16000800 0 0 0 $@{TARGET@}.cm0
-flash bank super_flash_nar_cm0 psoc6 0x16001A00 0 0 0 $@{TARGET@}.cm0
-flash bank super_flash_key_cm0 psoc6 0x16005A00 0 0 0 $@{TARGET@}.cm0
-flash bank super_flash_toc2_cm0 psoc6 0x16007C00 0 0 0 $@{TARGET@}.cm0
-
-flash bank main_flash_cm4 psoc6 0x10000000 0 0 0 $@{TARGET@}.cm4
-flash bank work_flash_cm4 psoc6 0x14000000 0 0 0 $@{TARGET@}.cm4
-flash bank super_flash_user_cm4 psoc6 0x16000800 0 0 0 $@{TARGET@}.cm4
-flash bank super_flash_nar_cm4 psoc6 0x16001A00 0 0 0 $@{TARGET@}.cm4
-flash bank super_flash_key_cm4 psoc6 0x16005A00 0 0 0 $@{TARGET@}.cm4
-flash bank super_flash_toc2_cm4 psoc6 0x16007C00 0 0 0 $@{TARGET@}.cm4
+flash bank main_flash_cm0 psoc6 0x10000000 0 0 0 \
+ $@{TARGET@}.cm0
+flash bank work_flash_cm0 psoc6 0x14000000 0 0 0 \
+ $@{TARGET@}.cm0
+flash bank super_flash_user_cm0 psoc6 0x16000800 0 0 0 \
+ $@{TARGET@}.cm0
+flash bank super_flash_nar_cm0 psoc6 0x16001A00 0 0 0 \
+ $@{TARGET@}.cm0
+flash bank super_flash_key_cm0 psoc6 0x16005A00 0 0 0 \
+ $@{TARGET@}.cm0
+flash bank super_flash_toc2_cm0 psoc6 0x16007C00 0 0 0 \
+ $@{TARGET@}.cm0
+
+flash bank main_flash_cm4 psoc6 0x10000000 0 0 0 \
+ $@{TARGET@}.cm4
+flash bank work_flash_cm4 psoc6 0x14000000 0 0 0 \
+ $@{TARGET@}.cm4
+flash bank super_flash_user_cm4 psoc6 0x16000800 0 0 0 \
+ $@{TARGET@}.cm4
+flash bank super_flash_nar_cm4 psoc6 0x16001A00 0 0 0 \
+ $@{TARGET@}.cm4
+flash bank super_flash_key_cm4 psoc6 0x16005A00 0 0 0 \
+ $@{TARGET@}.cm4
+flash bank super_flash_toc2_cm4 psoc6 0x16007C00 0 0 0 \
+ $@{TARGET@}.cm4
@end example
psoc6-specific commands
-@deffn Command {psoc6 reset_halt}
+@deffn {Command} {psoc6 reset_halt}
Command can be used to simulate broken Vector Catch from gdbinit or tcl scripts.
When invoked for CM0+ target, it will set break point at application entry point
and issue SYSRESETREQ. This will reset both cores and all peripherals. CM0+ will
instead of SYSRESETREQ to avoid unwanted reset of CM0+;
@end deffn
-@deffn Command {psoc6 mass_erase} num
+@deffn {Command} {psoc6 mass_erase} num
Erases the contents given flash bank. The @var{num} parameter is a value shown
by @command{flash banks}.
Note: only Main and Work flash regions support Erase operation.
@end deffn
@end deffn
-@deffn {Flash Driver} sim3x
+@deffn {Flash Driver} {qn908x}
+The NXP QN908x microcontrollers feature a Cortex-M4F with integrated Bluetooth
+LE 5 support and an internal flash of up to 512 KiB. These chips only support
+the SWD interface.
+
+The @var{qn908x} driver uses the internal "Flash Memory Controller" block via
+SWD to erase, program and read the internal flash. This driver does not
+support the ISP (In-System Programming) mode which is an alternate way to
+program the flash via UART, SPI or USB.
+
+The internal flash is 512 KiB in size in all released chips and it starts at
+the address 0x01000000, although it can be mapped to address 0 and it is
+aliased to other addresses. This driver only recognizes the bank starting at
+address 0x01000000.
+
+The internal bootloader stored in ROM is in charge of loading and verifying
+the image from flash, or enter ISP mode. The programmed image must start at
+the beginning of the flash and contain a valid header and a matching CRC32
+checksum. Additionally, the image header contains a "Code Read Protection"
+(CRP) word which indicates whether SWD access is enabled, as well as whether
+ISP mode is enabled. Therefore, it is possible to program an image that
+disables SWD and ISP making it impossible to program another image in the
+future through these interfaces, or even debug the current image. While this is
+a valid use case for production deployments where the chips are locked down, by
+default this driver doesn't allow such images that disable the SWD interface.
+To program such images see the @command{qn908x allow_brick} command.
+
+Apart from the CRP field which is located in the image header, the last page
+of the flash memory contains a "Flash lock and protect" descriptor which allows
+to individually protect each 2 KiB page, as well as disabling SWD access to the
+flash and RAM. If this access is disabled it is not possible to read, erase or
+program individual pages from the SWD interface or even access the read-only
+"Flash information page" with information about the bootloader version and
+flash size. However when this protection is in place, it is still possible to
+mass erase the whole chip and then program a new image, for which you can use
+the @command{qn908x mass_erase}.
+
+Example:
+@example
+flash bank $FLASHNAME qn908x 0x01000000 0 0 0 $TARGETNAME calc_checksum
+@end example
+
+Parameters:
+@itemize
+@item @option{calc_checksum} optional parameter to compute the required
+checksum of the first bytes in the vector table.
+@quotation Note
+If the checksum in the header of your image is invalid and you don't provide the
+@option{calc_checksum} option the boot ROM will not boot your image and it may
+render the flash inaccessible. On the other hand, if you use this option to
+compute the checksum keep in mind that @command{verify_image} will fail on
+those four bytes of the checksum since those bytes in the flash will have the
+updated checksum.
+@end quotation
+@end itemize
+
+@deffn {Command} {qn908x allow_brick}
+Allow the qn908x driver to program images with a "Code Read Protection" byte
+that disables the SWD access. Programming such image will cause OpenOCD to
+not be able to reach the target over SWD anymore after the new image is
+programmed and its configuration takes effect, e.g. after a reboot. After
+executing @command{qn908x allow_brick} these images will be allowed to be
+programmed when writing to the flash.
+@end deffn
+
+@deffn {Command} {qn908x disable_wdog}
+Disable the watchdog timer (WDT) by resetting its CTRL field. The WDT starts
+enabled after a @command{reset halt} and it doesn't run while the target is
+halted. However, the verification process in this driver uses the generic
+Cortex-M verification process which executes a payload in RAM and thus
+requires the watchdog to be disabled before running @command{verify_image}
+after a reset halt or any other condition where the watchdog is running.
+Note that this is not done automatically and you must run this command in
+those scenarios.
+@end deffn
+
+@deffn {Command} {qn908x mass_erase}
+Erases the complete flash using the mass_erase method. Mass erase is only
+allowed if enabled in the Lock Status Register 8 (LOCK_STAT_8) which is read
+from the last sector of the flash on boot. However, this mass_erase lock
+protection can be bypassed and this command does so automatically.
+
+In the same LOCK_STAT_8 the flash and RAM access from SWD can be disabled by
+setting two bits in this register. After a mass_erase, all the bits of the
+flash would be set, making it the default to restrict SWD access to the flash
+and RAM regions. This new after erase LOCK_STAT_8 value only takes effect after
+being read from flash on the next reboot for example. After a mass_erase the
+LOCK_STAT_8 register is changed by the hardware to allow access to flash and
+RAM regardless of the value on flash, but only right after a mass_erase and
+until the next boot. Therefore it is possible to perform a mass_erase, program
+a new image, verify it and then reboot to a valid image that's locked from the
+SWD access.
+
+The @command{qn908x mass_erase} command clears the bits that would be loaded
+from the flash into LOCK_STAT_8 after erasing the whole chip to allow SWD
+access for debugging or re-flashing an image without a mass_erase by default.
+If the image being programmed also programs the last page of the flash with its
+own settings, this mass_erase behavior will interfere with that write since a
+new erase of at least the last page would need to be performed before writing
+to it again. For this reason the optional @option{keep_lock} argument can be
+used to leave the flash and RAM lock set. For development environments, the
+default behavior is desired.
+
+The mass erase locking mechanism is independent from the individual page
+locking bits, so it is possible that you can't erase a given page that is
+locked and you can't unprotect that page because the locking bits are also
+locked, but can still mass erase the whole flash.
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} {rp2040}
+Supports RP2040 "Raspberry Pi Pico" microcontroller.
+RP2040 is a dual-core device with two CM0+ cores. Both cores share the same
+Flash/RAM/MMIO address space. Non-volatile storage is achieved with an
+external QSPI flash; a Boot ROM provides helper functions.
+
+@example
+flash bank $_FLASHNAME rp2040_flash $_FLASHBASE $_FLASHSIZE 1 32 $_TARGETNAME
+@end example
+@end deffn
+
+@deffn {Flash Driver} {rsl10}
+Supports Onsemi RSL10 microcontroller flash memory. Uses functions
+stored in ROM to control flash memory interface.
+
+@example
+flash bank $_FLASHNAME rsl10 $_FLASHBASE $_FLASHSIZE 0 0 $_TARGETNAME
+@end example
+
+@deffn {Command} {rsl10 lock} key1 key2 key3 key4
+Writes @var{key1 key2 key3 key4} words to @var{0x81044 0x81048 0x8104c
+0x8050}. Locks debug port by writing @var{0x4C6F634B} to @var{0x81040}.
+
+To unlock use the @command{rsl10 unlock key1 key2 key3 key4} command.
+@end deffn
+
+@deffn {Command} {rsl10 unlock} key1 key2 key3 key4
+Unlocks debug port, by writing @var{key1 key2 key3 key4} words to
+registers through DAP, and clears @var{0x81040} address in flash to 0x1.
+@end deffn
+
+@deffn {Command} {rsl10 mass_erase}
+Erases all unprotected flash sectors.
+@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.
There are 2 commands defined in the @var{sim3x} driver:
-@deffn Command {sim3x mass_erase}
+@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}
+@deffn {Command} {sim3x lock}
Lock the flash. To unlock use the @command{sim3x mass_erase} command.
@end deffn
@end deffn
-@deffn {Flash Driver} stellaris
+@deffn {Flash Driver} {stellaris}
All members of the Stellaris LM3Sxxx, LM4x and Tiva C microcontroller
families from Texas Instruments include internal flash. The driver
automatically recognizes a number of these chips using the chip
flash bank $_FLASHNAME stellaris 0 0 0 0 $_TARGETNAME
@end example
-@deffn Command {stellaris recover}
+@deffn {Command} {stellaris recover}
Performs the @emph{Recovering a "Locked" Device} procedure to restore
the flash and its associated nonvolatile registers to their factory
default values (erased). This is the only way to remove flash
@end deffn
@end deffn
-@deffn {Flash Driver} stm32f1x
-All members of the STM32F0, STM32F1 and STM32F3 microcontroller families
-from STMicroelectronics include internal flash and use ARM Cortex-M0/M3/M4 cores.
-The driver automatically recognizes a number of these chips using
-the chip identification register, and autoconfigures itself.
+@deffn {Flash Driver} {stm32f1x}
+This driver supports the STM32F0, STM32F1 and STM32F3 microcontroller series from STMicroelectronics.
+The driver is also compatible with the GD32F1, GD32VF103 (RISC-V core), GD32F3 and GD32E23 microcontroller series from GigaDevice.
+The driver also supports the APM32F0 and APM32F1 series from Geehy Semiconductor.
+The driver automatically recognizes a number of these chips using the chip identification register, and autoconfigures itself.
@example
flash bank $_FLASHNAME stm32f1x 0 0 0 0 $_TARGETNAME
Some stm32f1x-specific commands are defined:
-@deffn Command {stm32f1x lock} num
+@deffn {Command} {stm32f1x lock} num
Locks the entire stm32 device against reading.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32f1x unlock} num
+@deffn {Command} {stm32f1x unlock} num
Unlocks the entire stm32 device for reading. This command will cause
a mass erase of the entire stm32 device if previously locked.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32f1x mass_erase} num
+@deffn {Command} {stm32f1x mass_erase} num
Mass erases the entire stm32 device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32f1x options_read} num
+@deffn {Command} {stm32f1x options_read} num
Reads and displays active stm32 option bytes loaded during POR
or upon executing the @command{stm32f1x options_load} command.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32f1x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP}) (@option{USEROPT} user_data)
+@deffn {Command} {stm32f1x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP}) (@option{USEROPT} user_data)
Writes the stm32 option byte with the specified values.
The @var{num} parameter is a value shown by @command{flash banks}.
The @var{user_data} parameter is content of higher 16 bits of the option byte register (Data0 and Data1 as one 16bit number).
@end deffn
-@deffn Command {stm32f1x options_load} num
+@deffn {Command} {stm32f1x options_load} num
Generates a special kind of reset to re-load the stm32 option bytes written
by the @command{stm32f1x options_write} or @command{flash protect} commands
without having to power cycle the target. Not applicable to stm32f1x devices.
@end deffn
@end deffn
-@deffn {Flash Driver} stm32f2x
+@deffn {Flash Driver} {stm32f2x}
All members of the STM32F2, STM32F4 and STM32F7 microcontroller families from STMicroelectronics
include internal flash and use ARM Cortex-M3/M4/M7 cores.
+The driver also works for the APM32F4 series from Geehy Semiconductor.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
flash bank $_FLASHNAME stm32f2x 0x1FFF7800 0 0 0 $_TARGETNAME
@end example
-@deffn Command {stm32f2x otp } num (@option{enable}|@option{disable}|@option{show})
+@deffn {Command} {stm32f2x otp} num (@option{enable}|@option{disable}|@option{show})
Enables or disables OTP write commands for bank @var{num}.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
Some stm32f2x-specific commands are defined:
-@deffn Command {stm32f2x lock} num
+@deffn {Command} {stm32f2x lock} num
Locks the entire stm32 device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32f2x unlock} num
+@deffn {Command} {stm32f2x unlock} num
Unlocks the entire stm32 device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32f2x mass_erase} num
+@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
+@deffn {Command} {stm32f2x options_read} num
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
+@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}, @var{user_options} a
@var{boot_addr1} two halfwords (of FLASH_OPTCR1).
@end deffn
-@deffn Command {stm32f2x optcr2_write} num optcr2
+@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
+@deffn {Flash Driver} {stm32h7x}
All members of the STM32H7 microcontroller families from STMicroelectronics
include internal flash and use ARM Cortex-M7 core.
The driver automatically recognizes a number of these chips using
Some stm32h7x-specific commands are defined:
-@deffn Command {stm32h7x lock} num
+@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
+@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
+@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
+
+@deffn {Command} {stm32h7x option_read} num reg_offset
+Reads an option byte register from the stm32h7x device.
+The @var{num} parameter is a value shown by @command{flash banks}, @var{reg_offset}
+is the register offset of the option byte to read from the used bank registers' base.
+For example: in STM32H74x/H75x the bank 1 registers' base is 0x52002000 and 0x52002100 for bank 2.
+
+Example usage:
+@example
+# read OPTSR_CUR
+stm32h7x option_read 0 0x1c
+# read WPSN_CUR1R
+stm32h7x option_read 0 0x38
+# read WPSN_CUR2R
+stm32h7x option_read 1 0x38
+@end example
+@end deffn
+
+@deffn {Command} {stm32h7x option_write} num reg_offset value [reg_mask]
+Writes an option byte register of the stm32h7x device.
+The @var{num} parameter is a value shown by @command{flash banks}, @var{reg_offset}
+is the register offset of the option byte to write from the used bank register base,
+and @var{reg_mask} is the mask to apply when writing the register (only bits with a '1'
+will be touched).
+
+Example usage:
+@example
+# swap bank 1 and bank 2 in dual bank devices
+# by setting SWAP_BANK_OPT bit in OPTSR_PRG
+stm32h7x option_write 0 0x20 0x8000000 0x8000000
+@end example
+@end deffn
@end deffn
-@deffn {Flash Driver} stm32lx
-All members of the STM32L microcontroller families from STMicroelectronics
+@deffn {Flash Driver} {stm32lx}
+All members of the STM32L0 and STM32L1 microcontroller families from STMicroelectronics
include internal flash and use ARM Cortex-M3 and Cortex-M0+ cores.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
Some stm32lx-specific commands are defined:
-@deffn Command {stm32lx lock} num
+@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
+@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
+@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
Level is 2 which can't be unlocked at all).
@end deffn
@end deffn
-@deffn {Flash Driver} stm32l4x
-All members of the STM32L4 microcontroller families from STMicroelectronics
-include internal flash and use ARM Cortex-M4 cores.
+@deffn {Flash Driver} {stm32l4x}
+All members of the STM32 G0, G4, L4, L4+, L5, U5, WB and WL
+microcontroller families from STMicroelectronics include internal flash
+and use ARM Cortex-M0+, M4 and M33 cores.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
flash bank $_FLASHNAME stm32l4x 0 0 0 0 $_TARGETNAME
@end example
+If you use OTP (One-Time Programmable) memory define it as a second bank
+as per the following example.
+@example
+flash bank $_FLASHNAME stm32l4x 0x1FFF7000 0 0 0 $_TARGETNAME
+@end example
+
+@deffn {Command} {stm32l4x otp} num (@option{enable}|@option{disable}|@option{show})
+Enables or disables OTP write commands for bank @var{num}.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
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 flash driver. However, specifying a wrong value might lead to a completely
+wrong flash layout, so this feature must be used carefully.
@example
flash bank $_FLASHNAME stm32l4x 0x08000000 0x40000 0 0 $_TARGETNAME
Some stm32l4x-specific commands are defined:
-@deffn Command {stm32l4x lock} num
+@deffn {Command} {stm32l4x lock} num
Locks the entire stm32 device.
The @var{num} parameter is a value shown by @command{flash banks}.
+
+@emph{Note:} To apply the protection change immediately, use @command{stm32l4x option_load}.
@end deffn
-@deffn Command {stm32l4x unlock} num
+@deffn {Command} {stm32l4x unlock} num
Unlocks the entire stm32 device.
The @var{num} parameter is a value shown by @command{flash banks}.
+
+@emph{Note:} To apply the protection change immediately, use @command{stm32l4x option_load}.
@end deffn
-@deffn Command {stm32l4x mass_erase} num
+@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
-@deffn Command {stm32l4x option_read} num reg_offset
+@deffn {Command} {stm32l4x option_read} num reg_offset
Reads an option byte register from the stm32l4x device.
The @var{num} parameter is a value shown by @command{flash banks}, @var{reg_offset}
is the register offset of the Option byte to read.
For example to read the FLASH_OPTR register:
@example
stm32l4x option_read 0 0x20
-# Option Register: <0x40022020> = 0xffeff8aa
+# Option Register (for STM32L4x): <0x40022020> = 0xffeff8aa
+# Option Register (for STM32WBx): <0x58004020> = ...
+# The correct flash base address will be used automatically
@end example
The above example will read out the FLASH_OPTR register which contains the RDP
option byte, Watchdog configuration, BOR level etc.
@end deffn
-@deffn Command {stm32l4x option_write} num reg_offset reg_mask
+@deffn {Command} {stm32l4x option_write} num reg_offset reg_mask
Write an option byte register of the stm32l4x device.
The @var{num} parameter is a value shown by @command{flash banks}, @var{reg_offset}
is the register offset of the Option byte to write, and @var{reg_mask} is the mask
to apply when writing the register (only bits with a '1' will be touched).
+@emph{Note:} To apply the option bytes change immediately, use @command{stm32l4x option_load}.
+
For example to write the WRP1AR option bytes:
@example
stm32l4x option_write 0 0x28 0x00FF0000 0x00FF00FF
This will effectively write protect all sectors in flash bank 1.
@end deffn
-@deffn Command {stm32l4x option_load} num
-Forces a re-load of the option byte registers. Will cause a reset of the device.
+@deffn {Command} {stm32l4x wrp_info} num [device_bank]
+List the protected areas using WRP.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@var{device_bank} parameter is optional, possible values 'bank1' or 'bank2',
+if not specified, the command will display the whole flash protected areas.
+
+@b{Note:} @var{device_bank} is different from banks created using @code{flash bank}.
+Devices supported in this flash driver, can have main flash memory organized
+in single or dual-banks mode.
+Thus the usage of @var{device_bank} is meaningful only in dual-bank mode, to get
+write protected areas in a specific @var{device_bank}
+
+@end deffn
+
+@deffn {Command} {stm32l4x option_load} num
+Forces a re-load of the option byte registers. Will cause a system reset of the device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
+
+@deffn Command {stm32l4x trustzone} num [@option{enable} | @option{disable}]
+Enables or disables Global TrustZone Security, using the TZEN option bit.
+If neither @option{enabled} nor @option{disable} are specified, the command will display
+the TrustZone status.
+@emph{Note:} This command works only with devices with TrustZone, eg. STM32L5.
+@emph{Note:} This command will perform an OBL_Launch after modifying the TZEN.
+@end deffn
@end deffn
-@deffn {Flash Driver} str7x
+@deffn {Flash Driver} {str7x}
All members of the STR7 microcontroller family from STMicroelectronics
include internal flash and use ARM7TDMI cores.
The @var{str7x} driver defines one mandatory parameter, @var{variant},
0x40000000 0x00040000 0 0 $_TARGETNAME STR71x
@end example
-@deffn Command {str7x disable_jtag} bank
+@deffn {Command} {str7x disable_jtag} bank
Activate the Debug/Readout protection mechanism
for the specified flash bank.
@end deffn
@end deffn
-@deffn {Flash Driver} str9x
+@deffn {Flash Driver} {str9x}
Most members of the STR9 microcontroller family from STMicroelectronics
include internal flash and use ARM966E cores.
The str9 needs the flash controller to be configured using
str9x flash_config 0 4 2 0 0x80000
@end example
-@deffn Command {str9x flash_config} num bbsr nbbsr bbadr nbbadr
+@deffn {Command} {str9x flash_config} num bbsr nbbsr bbadr nbbadr
Configures the str9 flash controller.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn {Flash Driver} str9xpec
+@deffn {Flash Driver} {str9xpec}
@cindex str9xpec
Only use this driver for locking/unlocking the device or configuring the option bytes.
@example
# assert srst, we do not want core running
# while accessing str9xpec flash driver
-jtag_reset 0 1
+adapter assert srst
# turn off target polling
poll off
# disable str9 core
Several str9xpec-specific commands are defined:
-@deffn Command {str9xpec disable_turbo} num
+@deffn {Command} {str9xpec disable_turbo} num
Restore the str9 into JTAG chain.
@end deffn
-@deffn Command {str9xpec enable_turbo} num
+@deffn {Command} {str9xpec enable_turbo} num
Enable turbo mode, will simply remove the str9 from the chain and talk
directly to the embedded flash controller.
@end deffn
-@deffn Command {str9xpec lock} num
+@deffn {Command} {str9xpec lock} num
Lock str9 device. The str9 will only respond to an unlock command that will
erase the device.
@end deffn
-@deffn Command {str9xpec part_id} num
+@deffn {Command} {str9xpec part_id} num
Prints the part identifier for bank @var{num}.
@end deffn
-@deffn Command {str9xpec options_cmap} num (@option{bank0}|@option{bank1})
+@deffn {Command} {str9xpec options_cmap} num (@option{bank0}|@option{bank1})
Configure str9 boot bank.
@end deffn
-@deffn Command {str9xpec options_lvdsel} num (@option{vdd}|@option{vdd_vddq})
+@deffn {Command} {str9xpec options_lvdsel} num (@option{vdd}|@option{vdd_vddq})
Configure str9 lvd source.
@end deffn
-@deffn Command {str9xpec options_lvdthd} num (@option{2.4v}|@option{2.7v})
+@deffn {Command} {str9xpec options_lvdthd} num (@option{2.4v}|@option{2.7v})
Configure str9 lvd threshold.
@end deffn
-@deffn Command {str9xpec options_lvdwarn} bank (@option{vdd}|@option{vdd_vddq})
+@deffn {Command} {str9xpec options_lvdwarn} bank (@option{vdd}|@option{vdd_vddq})
Configure str9 lvd reset warning source.
@end deffn
-@deffn Command {str9xpec options_read} num
+@deffn {Command} {str9xpec options_read} num
Read str9 option bytes.
@end deffn
-@deffn Command {str9xpec options_write} num
+@deffn {Command} {str9xpec options_write} num
Write str9 option bytes.
@end deffn
-@deffn Command {str9xpec unlock} num
+@deffn {Command} {str9xpec unlock} num
unlock str9 device.
@end deffn
@end deffn
-@deffn {Flash Driver} tms470
+@deffn {Flash Driver} {swm050}
+@cindex swm050
+All members of the swm050 microcontroller family from Foshan Synwit Tech.
+
+@example
+flash bank $_FLASHNAME swm050 0x0 0x2000 0 0 $_TARGETNAME
+@end example
+
+One swm050-specific command is defined:
+
+@deffn {Command} {swm050 mass_erase} bank_id
+Erases the entire flash bank.
+@end deffn
+
+@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
+@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
+@deffn {Command} {tms470 osc_megahertz} clock_mhz
Reports the clock speed, which is used to calculate timings.
@end deffn
-@deffn Command {tms470 plldis} (0|1)
+@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} w600
+@deffn {Flash Driver} {w600}
W60x series Wi-Fi SoC from WinnerMicro
are designed with ARM Cortex-M3 and have 1M Byte QFLASH inside.
The @var{w600} driver uses the @var{target} parameter to select the
@end example
@end deffn
-@deffn {Flash Driver} xmc1xxx
+@deffn {Flash Driver} {xmc1xxx}
All members of the XMC1xxx microcontroller family from Infineon.
This driver does not require the chip and bus width to be specified.
@end deffn
-@deffn {Flash Driver} xmc4xxx
+@deffn {Flash Driver} {xmc4xxx}
All members of the XMC4xxx microcontroller family from Infineon.
This driver does not require the chip and bus width to be specified.
Some xmc4xxx-specific commands are defined:
-@deffn Command {xmc4xxx flash_password} bank_id passwd1 passwd2
+@deffn {Command} {xmc4xxx flash_password} bank_id passwd1 passwd2
Saves flash protection passwords which are used to lock the user flash
@end deffn
-@deffn Command {xmc4xxx flash_unprotect} bank_id user_level[0-1]
+@deffn {Command} {xmc4xxx flash_unprotect} bank_id user_level[0-1]
Removes Flash write protection from the selected user bank
@end deffn
@end itemize
@end deffn
-@deffn Command {nand list}
+@deffn {Command} {nand list}
Prints a summary of each device declared
using @command{nand device}, numbered from zero.
Note that un-probed devices show no details.
@end example
@end deffn
-@deffn Command {nand probe} num
+@deffn {Command} {nand probe} num
Probes the specified device to determine key characteristics
like its page and block sizes, and how many blocks it has.
The @var{num} parameter is the value shown by @command{nand list}.
@subsection Erasing, Reading, Writing to NAND Flash
-@deffn Command {nand dump} num filename offset length [oob_option]
+@deffn {Command} {nand dump} num filename offset length [oob_option]
@cindex NAND reading
Reads binary data from the NAND device and writes it to the file,
starting at the specified offset.
@end itemize
@end deffn
-@deffn Command {nand erase} num [offset length]
+@deffn {Command} {nand erase} num [offset length]
@cindex NAND erasing
@cindex NAND programming
Erases blocks on the specified NAND device, starting at the
will still report that the block ``is'' bad.
@end deffn
-@deffn Command {nand write} num filename offset [option...]
+@deffn {Command} {nand write} num filename offset [option...]
@cindex NAND writing
@cindex NAND programming
Writes binary data from the file into the specified NAND device,
@end itemize
@end deffn
-@deffn Command {nand verify} num filename offset [option...]
+@deffn {Command} {nand verify} num filename offset [option...]
@cindex NAND verification
@cindex NAND programming
Verify the binary data in the file has been programmed to the
@subsection Other NAND commands
@cindex NAND other commands
-@deffn Command {nand check_bad_blocks} num [offset length]
+@deffn {Command} {nand check_bad_blocks} num [offset length]
Checks for manufacturer bad block markers on the specified NAND
device. If no parameters are provided, checks the whole
device; otherwise, starts at the specified @var{offset} and
driver will not try to apply hardware ECC.
@end deffn
-@deffn Command {nand info} num
+@deffn {Command} {nand info} num
The @var{num} parameter is the value shown by @command{nand list}.
This prints the one-line summary from "nand list", plus for
devices which have been probed this also prints any known
status for each block.
@end deffn
-@deffn Command {nand raw_access} num (@option{enable}|@option{disable})
+@deffn {Command} {nand raw_access} num (@option{enable}|@option{disable})
Sets or clears an flag affecting how page I/O is done.
The @var{num} parameter is the value shown by @command{nand list}.
driver-specific options and behaviors.
Some controllers also activate controller-specific commands.
-@deffn {NAND Driver} at91sam9
+@deffn {NAND Driver} {at91sam9}
This driver handles the NAND controllers found on AT91SAM9 family chips from
Atmel. It takes two extra parameters: address of the NAND chip;
address of the ECC controller.
disabled by using the @command{nand raw_access} command. There are four
additional commands that are needed to fully configure the AT91SAM9 NAND
controller. Two are optional; most boards use the same wiring for ALE/CLE:
-@deffn Command {at91sam9 cle} num addr_line
+@deffn {Config Command} {at91sam9 cle} num addr_line
Configure the address line used for latching commands. The @var{num}
parameter is the value shown by @command{nand list}.
@end deffn
-@deffn Command {at91sam9 ale} num addr_line
+@deffn {Config Command} {at91sam9 ale} num addr_line
Configure the address line used for latching addresses. The @var{num}
parameter is the value shown by @command{nand list}.
@end deffn
For the next two commands, it is assumed that the pins have already been
properly configured for input or output.
-@deffn Command {at91sam9 rdy_busy} num pio_base_addr pin
+@deffn {Config Command} {at91sam9 rdy_busy} num pio_base_addr pin
Configure the RDY/nBUSY input from the NAND device. The @var{num}
parameter is the value shown by @command{nand list}. @var{pio_base_addr}
is the base address of the PIO controller and @var{pin} is the pin number.
@end deffn
-@deffn Command {at91sam9 ce} num pio_base_addr pin
+@deffn {Config Command} {at91sam9 ce} num pio_base_addr pin
Configure the chip enable input to the NAND device. The @var{num}
parameter is the value shown by @command{nand list}. @var{pio_base_addr}
is the base address of the PIO controller and @var{pin} is the pin number.
@end deffn
@end deffn
-@deffn {NAND Driver} davinci
+@deffn {NAND Driver} {davinci}
This driver handles the NAND controllers found on DaVinci family
chips from Texas Instruments.
It takes three extra parameters:
the @command{nand raw_access} command.
@end deffn
-@deffn {NAND Driver} lpc3180
+@deffn {NAND Driver} {lpc3180}
These controllers require an extra @command{nand device}
parameter: the clock rate used by the controller.
-@deffn Command {lpc3180 select} num [mlc|slc]
+@deffn {Command} {lpc3180 select} num [mlc|slc]
Configures use of the MLC or SLC controller mode.
MLC implies use of hardware ECC.
The @var{num} parameter is the value shown by @command{nand list}.
@end deffn
@comment current lpc3180 code won't issue 5-byte address cycles
-@deffn {NAND Driver} mx3
+@deffn {NAND Driver} {mx3}
This driver handles the NAND controller in i.MX31. The mxc driver
should work for this chip as well.
@end deffn
-@deffn {NAND Driver} mxc
+@deffn {NAND Driver} {mxc}
This driver handles the NAND controller found in Freescale i.MX
chips. It has support for v1 (i.MX27 and i.MX31) and v2 (i.MX35).
The driver takes 3 extra arguments, chip (@option{mx27},
@example
nand device mx35.nand mxc imx35.cpu mx35 hwecc biswap
@end example
-@deffn Command {mxc biswap} bank_num [enable|disable]
+@deffn {Command} {mxc biswap} bank_num [enable|disable]
Turns on/off bad block information swapping from main area,
without parameter query status.
@end deffn
@end deffn
-@deffn {NAND Driver} orion
+@deffn {NAND Driver} {orion}
These controllers require an extra @command{nand device}
parameter: the address of the controller.
@example
change any behavior.
@end deffn
-@deffn {NAND Driver} s3c2410
-@deffnx {NAND Driver} s3c2412
-@deffnx {NAND Driver} s3c2440
-@deffnx {NAND Driver} s3c2443
-@deffnx {NAND Driver} s3c6400
+@deffn {NAND Driver} {s3c2410}
+@deffnx {NAND Driver} {s3c2412}
+@deffnx {NAND Driver} {s3c2440}
+@deffnx {NAND Driver} {s3c2443}
+@deffnx {NAND Driver} {s3c6400}
These S3C family controllers don't have any special
@command{nand device} options, and don't define any
specialized commands.
change any behavior.
@end deffn
-@section mFlash
+@node Flash Programming
+@chapter Flash Programming
+
+OpenOCD implements numerous ways to program the target flash, whether internal or external.
+Programming can be achieved by either using @ref{programmingusinggdb,,Programming using GDB},
+or using the commands given in @ref{flashprogrammingcommands,,Flash Programming Commands}.
-@subsection mFlash Configuration
-@cindex mFlash Configuration
+@*To simplify using the flash commands directly a jimtcl script is available that handles the programming and verify stage.
+OpenOCD will program/verify/reset the target and optionally shutdown.
-@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.
+The script is executed as follows and by default the following actions will be performed.
+@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 If the @option{preverify} parameter is given, the target is "verified" first and only flashed if this fails.
+@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
-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 achieved by either using GDB @ref{programmingusinggdb,,Programming using GDB},
-or using the commands given in @ref{flashprogrammingcommands,,Flash Programming Commands}.
-
-@*To simplify using the flash commands 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 performed.
-@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}.
+An example of usage is given below. @xref{program}.
@example
# program and verify using elf/hex/s19. verify and reset
As it does for JTAG TAPs, debug targets, and flash chips (both NOR and NAND),
OpenOCD maintains a list of PLDs available for use in various commands.
-Also, each such PLD requires a driver.
+Also, each such PLD requires a driver. PLD drivers may also be needed to program
+SPI flash connected to the FPGA to store the bitstream (@xref{jtagspi} for details).
-They are referenced by the number shown by the @command{pld devices} command,
-and new PLDs are defined by @command{pld device driver_name}.
+They are referenced by the name which was given when the pld was created or
+the number shown by the @command{pld devices} command.
+New PLDs are defined by @command{pld create pld_name driver_name -chain-position tap_name [driver_options]}.
-@deffn {Config Command} {pld device} driver_name tap_name [driver_options]
-Defines a new PLD device, supported by driver @var{driver_name},
-using the TAP named @var{tap_name}.
-The driver may make use of any @var{driver_options} to configure its
-behavior.
+@deffn {Config Command} {pld create} pld_name driver_name -chain-position tap_name [driver_options]
+Creates a new PLD device, supported by driver @var{driver_name},
+assigning @var{pld_name} for further reference.
+@code{-chain-position} @var{tap_name} names the TAP
+used to access this target.
+The driver may make use of any @var{driver_options} to configure its behavior.
@end deffn
@deffn {Command} {pld devices}
-Lists the PLDs and their numbers.
+List the known PLDs with their name.
@end deffn
-@deffn {Command} {pld load} num filename
-Loads the file @file{filename} into the PLD identified by @var{num}.
+@deffn {Command} {pld load} pld_name filename
+Loads the file @file{filename} into the PLD identified by @var{pld_name}.
The file format must be inferred by the driver.
@end deffn
definition command, and may also define commands usable only with
that particular type of PLD.
-@deffn {FPGA Driver} virtex2 [no_jstart]
+@deffn {FPGA Driver} {virtex2} [@option{-no_jstart}]
Virtex-II is a family of FPGAs sold by Xilinx.
+This driver can also be used to load Series3, Series6, Series7 and Zynq 7000 devices.
It supports the IEEE 1532 standard for In-System Configuration (ISC).
-If @var{no_jstart} is non-zero, the JSTART instruction is not used after
+If @var{-no_jstart} is given, 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
+@example
+openocd -f board/digilent_zedboard.cfg -c "init" \
+ -c "pld load 0 zedboard_bitstream.bit"
+@end example
+
+
+@deffn {Command} {virtex2 read_stat} pld_name
Reads and displays the Virtex-II status register (STAT)
-for FPGA @var{num}.
+for FPGA @var{pld_name}.
+@end deffn
+
+@deffn {Command} {virtex2 set_instr_codes} pld_name cfg_out cfg_in jprogb jstart jshutdown [user1 [user2 [user3 [user4]]]]
+Change values for boundary scan instructions. Default are values for Virtex 2, devices Virtex 4/5/6 and
+SSI devices are using different values.
+@var{pld_name} is the name of the pld device.
+@var{cfg_out} is the value used to select CFG_OUT instruction.
+@var{cfg_in} is the value used to select CFG_IN instruction.
+@var{jprogb} is the value used to select JPROGRAM instruction.
+@var{jstart} is the value used to select JSTART instruction.
+@var{jshutdown} is the value used to select JSHUTDOWN instruction.
+@var{user1} to @var{user4} are the intruction used to select the user registers USER1 to USER4.
+@end deffn
+
+@deffn {Command} {virtex2 set_user_codes} pld_name user1 [user2 [user3 [user4]]]
+Change values for boundary scan instructions selecting the registers USER1 to USER4.
+Description of the arguments can be found at command @command{virtex2 set_instr_codes}.
+@end deffn
+
+@deffn {Command} {virtex2 refresh} pld_name
+Load the bitstream from external memory for FPGA @var{pld_name}. A.k.a. program.
+@end deffn
+@end deffn
+
+
+
+@deffn {FPGA Driver} {lattice} [@option{-family} <name>]
+The FGPA families ECP2, ECP3, ECP5, Certus and CertusPro by Lattice are supported.
+This driver can be used to load the bitstream into the FPGA or read the status register and read/write the usercode register.
+
+For the option @option{-family} @var{name} is one of @var{ecp2 ecp3 ecp5 certus}. This is needed when the JTAG ID of the device is not known by openocd (newer NX devices).
+
+@deffn {Command} {lattice read_status} pld_name
+Reads and displays the status register
+for FPGA @var{pld_name}.
+@end deffn
+
+@deffn {Command} {lattice read_user} pld_name
+Reads and displays the user register
+for FPGA @var{pld_name}.
+@end deffn
+
+@deffn {Command} {lattice write_user} pld_name val
+Writes the user register.
+for FPGA @var{pld_name} with value @var{val}.
@end deffn
+
+@deffn {Command} {lattice set_preload} pld_name length
+Set the length of the register for the preload. This is needed when the JTAG ID of the device is not known by openocd (newer NX devices).
+The load command for the FPGA @var{pld_name} will use a length for the preload of @var{length}.
+@end deffn
+
+@deffn {Command} {lattice refresh} pld_name
+Load the bitstream from external memory for FPGA @var{pld_name}. A.k.a program.
+@end deffn
+@end deffn
+
+
+@deffn {FPGA Driver} {efinix} [@option{-family} <name>]
+Both families (Trion and Titanium) sold by Efinix are supported as both use the same protocol for In-System Configuration.
+This driver can be used to load the bitstream into the FPGA.
+For the option @option{-family} @var{name} is one of @var{trion|titanium}.
+@end deffn
+
+
+@deffn {FPGA Driver} {intel} [@option{-family} <name>]
+This driver can be used to load the bitstream into Intel (former Altera) FPGAs.
+The families Cyclone III, Cyclone IV, Cyclone V, Cyclone 10, Arria II are supported.
+@c Arria V and Arria 10, MAX II, MAX V, MAX10)
+
+For the option @option{-family} @var{name} is one of @var{cycloneiii cycloneiv cyclonev cyclone10 arriaii}.
+This is needed when the JTAG ID of the device is ambiguous (same ID is used for chips in different families).
+
+As input file format the driver supports a '.rbf' (raw bitstream file) file. The '.rbf' file can be generated
+from a '.sof' file with @verb{|quartus_cpf -c blinker.sof blinker.rbf|}
+
+Creates a new PLD device, an FPGA of the Cyclone III family, using the TAP named @verb{|cycloneiii.tap|}:
+@example
+pld create cycloneiii.pld intel -chain-position cycloneiii.tap -family cycloneiii
+@end example
+
+@deffn {Command} {intel set_bscan} pld_name len
+Set boundary scan register length of FPGA @var{pld_name} to @var{len}. This is needed because the
+length can vary between chips with the same JTAG ID.
@end deffn
+@deffn {Command} {intel set_check_pos} pld_name pos
+Selects the position @var{pos} in the boundary-scan register. The bit at this
+position is checked after loading the bitstream and must be '1', which is the case when no error occurred.
+With a value of -1 for @var{pos} the check will be omitted.
+@end deffn
+@end deffn
+
+
+@deffn {FPGA Driver} {gowin}
+This driver can be used to load the bitstream into FPGAs from Gowin.
+It is possible to program the SRAM. Programming the flash is not supported.
+The files @verb{|.fs|} and @verb{|.bin|} generated by Gowin FPGA Designer are supported.
+
+@deffn {Command} {gowin read_status} pld_name
+Reads and displays the status register
+for FPGA @var{pld_name}.
+@end deffn
+
+@deffn {Command} {gowin read_user} pld_name
+Reads and displays the user register
+for FPGA @var{pld_name}.
+@end deffn
+
+@deffn {Command} {gowin refresh} pld_name
+Load the bitstream from external memory for
+FPGA @var{pld_name}. A.k.a. reload.
+@end deffn
+@end deffn
+
+
+@deffn {FPGA Driver} {gatemate}
+This driver can be used to load the bitstream into GateMate FPGAs form CologneChip.
+The files @verb{|.bit|} and @verb{|.cfg|} both generated by p_r tool from CologneChip are supported.
+@end deffn
+
+
@node General Commands
@chapter General Commands
@cindex commands
@item @b{Machine Interface}
The Tcl interface's intent is to be a machine interface. The default Tcl
-port is 5555.
+port is 6666.
@end itemize
@section Server Commands
-@deffn {Command} exit
+@deffn {Command} {exit}
Exits the current telnet session.
@end deffn
-@deffn {Command} help [string]
+@deffn {Command} {help} [string]
With no parameters, prints help text for all commands.
Otherwise, prints each helptext containing @var{string}.
Not every command provides helptext.
which are only available after the configuration stage has completed.
@end deffn
-@deffn Command sleep msec [@option{busy}]
+@deffn {Command} {usage} [string]
+With no parameters, prints usage text for all commands. Otherwise,
+prints all usage text of which command, help text, and usage text
+containing @var{string}.
+Not every command provides helptext.
+@end deffn
+
+@deffn {Command} {sleep} msec [@option{busy}]
Wait for at least @var{msec} milliseconds before resuming.
If @option{busy} is passed, busy-wait instead of sleeping.
(This option is strongly discouraged.)
(@command{script} command and @command{target_name} configuration).
@end deffn
-@deffn Command shutdown [@option{error}]
+@deffn {Command} {shutdown} [@option{error}]
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.
-Like any TCL commands, also @command{shutdown} can be redefined, e.g.:
+If user types CTRL-C or kills OpenOCD, the command @command{shutdown}
+will be automatically executed to cause OpenOCD to exit.
+
+It is possible to specify, in the TCL list @var{pre_shutdown_commands} , a
+set of commands to be automatically executed before @command{shutdown} , e.g.:
@example
-# redefine shutdown
-rename shutdown original_shutdown
-proc shutdown @{@} @{
- puts "This is my implementation of shutdown"
- # my own stuff before exit OpenOCD
- original_shutdown
-@}
+lappend pre_shutdown_commands @{echo "Goodbye, my friend ..."@}
+lappend pre_shutdown_commands @{echo "see you soon !"@}
@end example
-If user types CTRL-C or kills OpenOCD, either the command @command{shutdown}
-or its replacement will be automatically executed before OpenOCD exits.
+The commands in the list will be executed (in the same order they occupy
+in the list) before OpenOCD exits. If one of the commands in the list
+fails, then the remaining commands are not executed anymore while OpenOCD
+will proceed to quit.
@end deffn
@anchor{debuglevel}
-@deffn Command debug_level [n]
+@deffn {Command} {debug_level} [n]
@cindex message level
Display debug level.
If @var{n} (from 0..4) is provided, then set it to that level.
@xref{Running}.
@end deffn
-@deffn Command echo [-n] message
+@deffn {Command} {echo} [-n] message
Logs a message at "user" priority.
-Output @var{message} to stdout.
Option "-n" suppresses trailing newline.
@example
echo "Downloading kernel -- please wait"
@end example
@end deffn
-@deffn Command log_output [filename]
-Redirect logging to @var{filename};
-the initial log output channel is stderr.
+@deffn {Command} {log_output} [filename | 'default']
+Redirect logging to @var{filename}. If used without an argument or
+@var{filename} is set to 'default' log output channel is set to
+stderr.
@end deffn
-@deffn Command add_script_search_dir [directory]
+@deffn {Command} {add_script_search_dir} [directory]
Add @var{directory} to the file/script search path.
@end deffn
-@deffn Command bindto [@var{name}]
+@deffn {Config Command} {bindto} [@var{name}]
Specify hostname or IPv4 address on which to listen for incoming
TCP/IP connections. By default, OpenOCD will listen on the loopback
interface only. If your network environment is safe, @code{bindto
by using @command{targets} command with the name of the
target which should become current.
-@deffn Command reg [(number|name) [(value|'force')]]
+@deffn {Command} {reg} [(number|name) [(value|'force')]]
Access a single register by @var{number} or by its @var{name}.
The target must generally be halted before access to CPU core
registers is allowed. Depending on the hardware, some other
@end example
@end deffn
-@deffn Command halt [ms]
-@deffnx Command wait_halt [ms]
+@deffn {Command} {set_reg} dict
+Set register values of the target.
+
+@itemize
+@item @var{dict} ... Tcl dictionary with pairs of register names and values.
+@end itemize
+
+For example, the following command sets the value 0 to the program counter (pc)
+register and 0x1000 to the stack pointer (sp) register:
+
+@example
+set_reg @{pc 0 sp 0x1000@}
+@end example
+@end deffn
+
+@deffn {Command} {get_reg} [-force] list
+Get register values from the target and return them as Tcl dictionary with pairs
+of register names and values.
+If option "-force" is set, the register values are read directly from the
+target, bypassing any caching.
+
+@itemize
+@item @var{list} ... List of register names
+@end itemize
+
+For example, the following command retrieves the values from the program
+counter (pc) and stack pointer (sp) register:
+
+@example
+get_reg @{pc sp@}
+@end example
+@end deffn
+
+@deffn {Command} {write_memory} address width data ['phys']
+This function provides an efficient way to write to the target memory from a Tcl
+script.
+
+@itemize
+@item @var{address} ... target memory address
+@item @var{width} ... memory access bit size, can be 8, 16, 32 or 64
+@item @var{data} ... Tcl list with the elements to write
+@item ['phys'] ... treat the memory address as physical instead of virtual address
+@end itemize
+
+For example, the following command writes two 32 bit words into the target
+memory at address 0x20000000:
+
+@example
+write_memory 0x20000000 32 @{0xdeadbeef 0x00230500@}
+@end example
+@end deffn
+
+@deffn {Command} {read_memory} address width count ['phys']
+This function provides an efficient way to read the target memory from a Tcl
+script.
+A Tcl list containing the requested memory elements is returned by this function.
+
+@itemize
+@item @var{address} ... target memory address
+@item @var{width} ... memory access bit size, can be 8, 16, 32 or 64
+@item @var{count} ... number of elements to read
+@item ['phys'] ... treat the memory address as physical instead of virtual address
+@end itemize
+
+For example, the following command reads two 32 bit words from the target
+memory at address 0x20000000:
+
+@example
+read_memory 0x20000000 32 2
+@end example
+@end deffn
+
+@deffn {Command} {halt} [ms]
+@deffnx {Command} {wait_halt} [ms]
The @command{halt} command first sends a halt request to the target,
which @command{wait_halt} doesn't.
Otherwise these behave the same: wait up to @var{ms} milliseconds,
@end deffn
-@deffn Command resume [address]
+@deffn {Command} {resume} [address]
Resume the target at its current code position,
or the optional @var{address} if it is provided.
-OpenOCD will wait 5 seconds for the target to resume.
@end deffn
-@deffn Command step [address]
+@deffn {Command} {step} [address]
Single-step the target at its current code position,
or the optional @var{address} if it is provided.
@end deffn
@anchor{resetcommand}
-@deffn Command reset
-@deffnx Command {reset run}
-@deffnx Command {reset halt}
-@deffnx Command {reset init}
+@deffn {Command} {reset}
+@deffnx {Command} {reset run}
+@deffnx {Command} {reset halt}
+@deffnx {Command} {reset init}
Perform as hard a reset as possible, using SRST if possible.
@emph{All defined targets will be reset, and target
events will fire during the reset sequence.}
@end itemize
@end deffn
-@deffn Command soft_reset_halt
+@deffn {Command} {soft_reset_halt}
Requesting target halt and executing a soft reset. This is often used
when a target cannot be reset and halted. The target, after reset is
released begins to execute code. OpenOCD attempts to stop the CPU and
state.
@end deffn
-@section I/O Utilities
-
-These commands are available when
-OpenOCD is built with @option{--enable-ioutil}.
-They are mainly useful on embedded targets,
-notably the ZY1000.
-Hosts with operating systems have complementary tools.
-
-@emph{Note:} there are several more such commands.
-
-@deffn Command append_file filename [string]*
-Appends the @var{string} parameters to
-the text file @file{filename}.
-Each string except the last one is followed by one space.
-The last string is followed by a newline.
-@end deffn
-
-@deffn Command cat filename
-Reads and displays the text file @file{filename}.
-@end deffn
-
-@deffn Command cp src_filename dest_filename
-Copies contents from the file @file{src_filename}
-into @file{dest_filename}.
-@end deffn
-
-@deffn Command ip
-@emph{No description provided.}
-@end deffn
-
-@deffn Command ls
-@emph{No description provided.}
-@end deffn
-
-@deffn Command mac
-@emph{No description provided.}
-@end deffn
-
-@deffn Command meminfo
-Display available RAM memory on OpenOCD host.
-Used in OpenOCD regression testing scripts.
-@end deffn
-
-@deffn Command peek
-@emph{No description provided.}
-@end deffn
-
-@deffn Command poke
-@emph{No description provided.}
-@end deffn
+@deffn {Command} {adapter assert} [signal [assert|deassert signal]]
+@deffnx {Command} {adapter deassert} [signal [assert|deassert signal]]
+Set values of reset signals.
+Without parameters returns current status of the signals.
+The @var{signal} parameter values may be
+@option{srst}, indicating that srst signal is to be asserted or deasserted,
+@option{trst}, indicating that trst signal is to be asserted or deasserted.
-@deffn Command rm filename
-@c "rm" has both normal and Jim-level versions??
-Unlinks the file @file{filename}.
-@end deffn
+The @command{reset_config} command should already have been used
+to configure how the board and the adapter treat these two
+signals, and to say if either signal is even present.
+@xref{Reset Configuration}.
+Trying to assert a signal that is not present triggers an error.
+If a signal is present on the adapter and not specified in the command,
+the signal will not be modified.
-@deffn Command trunc filename
-Removes all data in the file @file{filename}.
+@quotation Note
+TRST is specially handled.
+It actually signifies JTAG's @sc{reset} state.
+So if the board doesn't support the optional TRST signal,
+or it doesn't support it along with the specified SRST value,
+JTAG reset is triggered with TMS and TCK signals
+instead of the TRST signal.
+And no matter how that JTAG reset is triggered, once
+the scan chain enters @sc{reset} with TRST inactive,
+TAP @code{post-reset} events are delivered to all TAPs
+with handlers for that event.
+@end quotation
@end deffn
@anchor{memoryaccess}
about what TAP is the current target, or about MMU configuration.
@end enumerate
-@deffn Command mdw [phys] addr [count]
-@deffnx Command mdh [phys] addr [count]
-@deffnx Command mdb [phys] addr [count]
+@deffn {Command} {mdd} [phys] addr [count]
+@deffnx {Command} {mdw} [phys] addr [count]
+@deffnx {Command} {mdh} [phys] addr [count]
+@deffnx {Command} {mdb} [phys] addr [count]
Display contents of address @var{addr}, as
+64-bit doublewords (@command{mdd}),
32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}),
or 8-bit bytes (@command{mdb}).
When the current target has an MMU which is present and active,
Otherwise, or if the optional @var{phys} flag is specified,
@var{addr} is interpreted as a physical address.
If @var{count} is specified, displays that many units.
-(If you want to manipulate the data instead of displaying it,
-see the @code{mem2array} primitives.)
+(If you want to process the data instead of displaying it,
+see the @code{read_memory} primitives.)
@end deffn
-@deffn Command mww [phys] addr word
-@deffnx Command mwh [phys] addr halfword
-@deffnx Command mwb [phys] addr byte
-Writes the specified @var{word} (32 bits),
+@deffn {Command} {mwd} [phys] addr doubleword [count]
+@deffnx {Command} {mww} [phys] addr word [count]
+@deffnx {Command} {mwh} [phys] addr halfword [count]
+@deffnx {Command} {mwb} [phys] addr byte [count]
+Writes the specified @var{doubleword} (64 bits), @var{word} (32 bits),
@var{halfword} (16 bits), or @var{byte} (8-bit) value,
at the specified address @var{addr}.
When the current target has an MMU which is present and active,
@var{addr} is interpreted as a virtual address.
Otherwise, or if the optional @var{phys} flag is specified,
@var{addr} is interpreted as a physical address.
+If @var{count} is specified, fills that many units of consecutive address.
@end deffn
@anchor{imageaccess}
@cindex image loading
@cindex image dumping
-@deffn Command {dump_image} filename address size
+@deffn {Command} {dump_image} filename address size
Dump @var{size} bytes of target memory starting at @var{address} to the
binary file named @var{filename}.
@end deffn
-@deffn Command {fast_load}
+@deffn {Command} {fast_load}
Loads an image stored in memory by @command{fast_load_image} to the
current target. Must be preceded by fast_load_image.
@end deffn
-@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}|@option{s19}]
+@deffn {Command} {fast_load_image} filename [address [@option{bin}|@option{ihex}|@option{elf}|@option{s19} [@option{min_addr} [@option{max_length}]]]]]]
Normally you should be using @command{load_image} or GDB load. However, for
testing purposes or when I/O overhead is significant(OpenOCD running on an embedded
host), storing the image in memory and uploading the image to the target
separately.
@end deffn
-@deffn Command {load_image} filename address [[@option{bin}|@option{ihex}|@option{elf}|@option{s19}] @option{min_addr} @option{max_length}]
-Load image from file @var{filename} to target memory offset by @var{address} from its load address.
+@deffn {Command} {load_image} filename [address [@option{bin}|@option{ihex}|@option{elf}|@option{s19} [@option{min_addr} [@option{max_length}]]]]
+Load image from file @var{filename} to target memory.
+If an @var{address} is specified, it is used as an offset to the file format
+defined addressing (e.g. @option{bin} file is loaded at that address).
The file format may optionally be specified
(@option{bin}, @option{ihex}, @option{elf}, or @option{s19}).
In addition the following arguments may be specified:
proc load_image_bin @{fname foffset address length @} @{
# Load data from fname filename at foffset offset to
# target at address. Load at most length bytes.
- load_image $fname [expr $address - $foffset] bin \
+ load_image $fname [expr @{$address - $foffset@}] bin \
$address $length
@}
@end example
@end deffn
-@deffn Command {test_image} filename [address [@option{bin}|@option{ihex}|@option{elf}]]
+@deffn {Command} {test_image} filename [address [@option{bin}|@option{ihex}|@option{elf}]]
Displays image section sizes and addresses
as if @var{filename} were loaded into target memory
starting at @var{address} (defaults to zero).
(@option{bin}, @option{ihex}, or @option{elf})
@end deffn
-@deffn Command {verify_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
-Verify @var{filename} against target memory starting at @var{address}.
+@deffn {Command} {verify_image} filename [address [@option{bin}|@option{ihex}|@option{elf}]]
+Verify @var{filename} against target memory.
+If an @var{address} is specified, it is used as an offset to the file format
+defined addressing (e.g. @option{bin} file is compared against memory starting
+at that address).
The file format may optionally be specified
(@option{bin}, @option{ihex}, or @option{elf})
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}.
+@deffn {Command} {verify_image_checksum} filename [address [@option{bin}|@option{ihex}|@option{elf}]]
+Verify @var{filename} against target memory.
+If an @var{address} is specified, it is used as an offset to the file format
+defined addressing (e.g. @option{bin} file is compared against memory starting
+at that address).
The file format may optionally be specified
(@option{bin}, @option{ihex}, or @option{elf})
This perform a comparison using a CRC checksum only
watchpoints.
In addition, CPUs almost always support software breakpoints.
-@deffn Command {bp} [address len [@option{hw}]]
+@deffn {Command} {bp} [address len [@option{hw}]]
With no parameters, lists all active breakpoints.
Else sets a breakpoint on code execution starting
at @var{address} for @var{length} bytes.
for similar mechanisms that do not consume hardware breakpoints.)
@end deffn
-@deffn Command {rbp} address
-Remove the breakpoint at @var{address}.
+@deffn {Command} {rbp} @option{all} | address
+Remove the breakpoint at @var{address} or all breakpoints.
@end deffn
-@deffn Command {rwp} address
-Remove data watchpoint on @var{address}
+@deffn {Command} {rwp} @option{all} | address
+Remove data watchpoint on @var{address} or all watchpoints.
@end deffn
-@deffn Command {wp} [address len [(@option{r}|@option{w}|@option{a}) [value [mask]]]]
+@deffn {Command} {wp} [address length [(@option{r}|@option{w}|@option{a}) [value [mask]]]]
With no parameters, lists all active watchpoints.
Else sets a data watchpoint on data from @var{address} for @var{length} bytes.
The watch point is an "access" watchpoint unless
using @var{mask} to mark ``don't care'' fields.
@end deffn
+
+@section Real Time Transfer (RTT)
+
+Real Time Transfer (RTT) is an interface specified by SEGGER based on basic
+memory reads and writes to transfer data bidirectionally between target and host.
+The specification is independent of the target architecture.
+Every target that supports so called "background memory access", which means
+that the target memory can be accessed by the debugger while the target is
+running, can be used.
+This interface is especially of interest for targets without
+Serial Wire Output (SWO), such as ARM Cortex-M0, or where semihosting is not
+applicable because of real-time constraints.
+
+@quotation Note
+The current implementation supports only single target devices.
+@end quotation
+
+The data transfer between host and target device is organized through
+unidirectional up/down-channels for target-to-host and host-to-target
+communication, respectively.
+
+@quotation Note
+The current implementation does not respect channel buffer flags.
+They are used to determine what happens when writing to a full buffer, for
+example.
+@end quotation
+
+Channels are exposed via raw TCP/IP connections. One or more RTT servers can be
+assigned to each channel to make them accessible to an unlimited number
+of TCP/IP connections.
+
+@deffn {Command} {rtt setup} address size ID
+Configure RTT for the currently selected target.
+Once RTT is started, OpenOCD searches for a control block with the
+identifier @var{ID} starting at the memory address @var{address} within the next
+@var{size} bytes.
+@end deffn
+
+@deffn {Command} {rtt start}
+Start RTT.
+If the control block location is not known, OpenOCD starts searching for it.
+@end deffn
+
+@deffn {Command} {rtt stop}
+Stop RTT.
+@end deffn
+
+@deffn {Command} {rtt polling_interval} [interval]
+Display the polling interval.
+If @var{interval} is provided, set the polling interval.
+The polling interval determines (in milliseconds) how often the up-channels are
+checked for new data.
+@end deffn
+
+@deffn {Command} {rtt channels}
+Display a list of all channels and their properties.
+@end deffn
+
+@deffn {Command} {rtt channellist}
+Return a list of all channels and their properties as Tcl list.
+The list can be manipulated easily from within scripts.
+@end deffn
+
+@deffn {Command} {rtt server start} port channel [message]
+Start a TCP server on @var{port} for the channel @var{channel}. When
+@var{message} is not empty, it will be sent to a client when it connects.
+@end deffn
+
+@deffn {Command} {rtt server stop} port
+Stop the TCP sever with port @var{port}.
+@end deffn
+
+The following example shows how to setup RTT using the SEGGER RTT implementation
+on the target device.
+
+@example
+resume
+
+rtt setup 0x20000000 2048 "SEGGER RTT"
+rtt start
+
+rtt server start 9090 0
+@end example
+
+In this example, OpenOCD searches the control block with the ID "SEGGER RTT"
+starting at 0x20000000 for 2048 bytes. The RTT channel 0 is exposed through the
+TCP/IP port 9090.
+
+
@section Misc Commands
@cindex profiling
-@deffn Command {profile} seconds filename [start end]
+@deffn {Command} {profile} seconds filename [start end]
Profiling samples the CPU's program counter as quickly as possible,
which is useful for non-intrusive stochastic profiling.
-Saves up to 10000 samples in @file{filename} using ``gmon.out''
+Saves up to 1000000 samples in @file{filename} using ``gmon.out''
format. Optional @option{start} and @option{end} parameters allow to
limit the address range.
@end deffn
-@deffn Command {version}
-Displays a string identifying the version of this OpenOCD server.
+@deffn {Command} {version} [git]
+Returns a string identifying the version of this OpenOCD server.
+With option @option{git}, it returns the git version obtained at compile time
+through ``git describe''.
@end deffn
-@deffn Command {virt2phys} virtual_address
+@deffn {Command} {virt2phys} virtual_address
Requests the current target to map the specified @var{virtual_address}
to its corresponding physical address, and displays the result.
@end deffn
+@deffn {Command} {add_help_text} 'command_name' 'help-string'
+Add or replace help text on the given @var{command_name}.
+@end deffn
+
+@deffn {Command} {add_usage_text} 'command_name' 'help-string'
+Add or replace usage text on the given @var{command_name}.
+@end deffn
+
@node Architecture and Core Commands
@chapter Architecture and Core Commands
@cindex Architecture Specific Commands
@end quotation
@end deffn
-@deffn Command {etm info}
+@deffn {Command} {etm info}
Displays information about the current target's ETM.
This includes resource counts from the @code{ETM_CONFIG} register,
as well as silicon capabilities (except on rather old modules).
from the @code{ETM_SYS_CONFIG} register.
@end deffn
-@deffn Command {etm status}
+@deffn {Command} {etm status}
Displays status of the current target's ETM and trace port driver:
is the ETM idle, or is it collecting data?
Did trace data overflow?
Was it triggered?
@end deffn
-@deffn Command {etm tracemode} [type context_id_bits cycle_accurate branch_output]
+@deffn {Command} {etm tracemode} [type context_id_bits cycle_accurate branch_output]
Displays what data that ETM will collect.
If arguments are provided, first configures that data.
When the configuration changes, tracing is stopped
@itemize
@item @var{type} ... describing how data accesses are traced,
-when they pass any ViewData filtering that that was set up.
+when they pass any ViewData filtering that was set up.
The value is one of
@option{none} (save nothing),
@option{data} (save data),
@end itemize
@end deffn
-@deffn Command {etm trigger_debug} (@option{enable}|@option{disable})
+@deffn {Command} {etm trigger_debug} (@option{enable}|@option{disable})
Displays whether ETM triggering debug entry (like a breakpoint) is
enabled or disabled, after optionally modifying that configuration.
The default behaviour is @option{disable}.
At this writing, September 2009, there are no Tcl utility
procedures to help set up any common tracing scenarios.
-@deffn Command {etm analyze}
+@deffn {Command} {etm analyze}
Reads trace data into memory, if it wasn't already present.
Decodes and prints the data that was collected.
@end deffn
-@deffn Command {etm dump} filename
+@deffn {Command} {etm dump} filename
Stores the captured trace data in @file{filename}.
@end deffn
-@deffn Command {etm image} filename [base_address] [type]
+@deffn {Command} {etm image} filename [base_address] [type]
Opens an image file.
@end deffn
-@deffn Command {etm load} filename
+@deffn {Command} {etm load} filename
Loads captured trace data from @file{filename}.
@end deffn
-@deffn Command {etm start}
+@deffn {Command} {etm start}
Starts trace data collection.
@end deffn
-@deffn Command {etm stop}
+@deffn {Command} {etm stop}
Stops trace data collection.
@end deffn
To use an ETM trace port it must be associated with a driver.
-@deffn {Trace Port Driver} dummy
+@deffn {Trace Port Driver} {dummy}
Use the @option{dummy} driver if you are configuring an ETM that's
not connected to anything (on-chip ETB or off-chip trace connector).
@emph{This driver lets OpenOCD talk to the ETM, but it does not expose
@end deffn
@end deffn
-@deffn {Trace Port Driver} etb
+@deffn {Trace Port Driver} {etb}
Use the @option{etb} driver if you are configuring an ETM
to use on-chip ETB memory.
@deffn {Config Command} {etb config} target etb_tap
Associates the ETM for @var{target} with the ETB at @var{etb_tap}.
You can see the ETB registers using the @command{reg} command.
@end deffn
-@deffn Command {etb trigger_percent} [percent]
+@deffn {Command} {etb trigger_percent} [percent]
This displays, or optionally changes, ETB behavior after the
ETM's configured @emph{trigger} event fires.
It controls how much more trace data is saved after the (single)
@end deffn
-@deffn {Trace Port Driver} oocd_trace
-This driver isn't available unless OpenOCD was explicitly configured
-with the @option{--enable-oocd_trace} option. You probably don't want
-to configure it unless you've built the appropriate prototype hardware;
-it's @emph{proof-of-concept} software.
-
-Use the @option{oocd_trace} driver if you are configuring an ETM that's
-connected to an off-chip trace connector.
-
-@deffn {Config Command} {oocd_trace config} target tty
-Associates the ETM for @var{target} with a trace driver which
-collects data through the serial port @var{tty}.
-@end deffn
-
-@deffn Command {oocd_trace resync}
-Re-synchronizes with the capture clock.
-@end deffn
-
-@deffn Command {oocd_trace status}
-Reports whether the capture clock is locked or not.
-@end deffn
-@end deffn
-
@anchor{armcrosstrigger}
@section ARM Cross-Trigger Interface
@cindex CTI
CTI instance attached to it. OpenOCD has limited support for CTI using
the @emph{cti} group of commands.
-@deffn Command {cti create} cti_name @option{-dap} dap_name @option{-ap-num} apn @option{-ctibase} base_address
+@deffn {Command} {cti create} cti_name @option{-dap} dap_name @option{-ap-num} apn @option{-baseaddr} base_address
Creates a CTI instance @var{cti_name} on the DAP instance @var{dap_name} on MEM-AP
-@var{apn}. The @var{base_address} must match the base address of the CTI
+@var{apn}.
+On ADIv5 DAP @var{apn} is the numeric index of the DAP AP the CTI is connected to.
+On ADIv6 DAP @var{apn} is the base address of the DAP AP the CTI is connected to.
+The @var{base_address} must match the base address of the CTI
on the respective MEM-AP. All arguments are mandatory. This creates a
new command @command{$cti_name} which is used for various purposes
including additional configuration.
@end deffn
-@deffn Command {$cti_name enable} @option{on|off}
+@deffn {Command} {$cti_name enable} @option{on|off}
Enable (@option{on}) or disable (@option{off}) the CTI.
@end deffn
-@deffn Command {$cti_name dump}
+@deffn {Command} {$cti_name dump}
Displays a register dump of the CTI.
@end deffn
-@deffn Command {$cti_name write } @var{reg_name} @var{value}
+@deffn {Command} {$cti_name write} @var{reg_name} @var{value}
Write @var{value} to the CTI register with the symbolic name @var{reg_name}.
@end deffn
-@deffn Command {$cti_name read} @var{reg_name}
+@deffn {Command} {$cti_name read} @var{reg_name}
Print the value read from the CTI register with the symbolic name @var{reg_name}.
@end deffn
-@deffn Command {$cti_name testmode} @option{on|off}
+@deffn {Command} {$cti_name ack} @var{event}
+Acknowledge a CTI @var{event}.
+@end deffn
+
+@deffn {Command} {$cti_name channel} @var{channel_number} @var{operation}
+Perform a specific channel operation, the possible operations are:
+gate, ungate, set, clear and pulse
+@end deffn
+
+@deffn {Command} {$cti_name testmode} @option{on|off}
Enable (@option{on}) or disable (@option{off}) the integration test mode
of the CTI.
@end deffn
-@deffn Command {cti names}
+@deffn {Command} {cti names}
Prints a list of names of all CTI objects created. This command is mainly
useful in TCL scripting.
@end deffn
They are available in addition to other core-specific
commands that may be available.
-@deffn Command {arm core_state} [@option{arm}|@option{thumb}]
+@deffn {Command} {arm core_state} [@option{arm}|@option{thumb}]
Displays the core_state, optionally changing it to process
either @option{arm} or @option{thumb} instructions.
The target may later be resumed in the currently set core_state.
that is not currently supported in OpenOCD.)
@end deffn
-@deffn Command {arm disassemble} address [count [@option{thumb}]]
+@deffn {Command} {arm disassemble} address [count [@option{thumb}]]
@cindex disassemble
Disassembles @var{count} instructions starting at @var{address}.
If @var{count} is not specified, a single instruction is disassembled.
ThumbEE disassembly currently has no explicit support.
@end deffn
-@deffn Command {arm mcr} pX op1 CRn CRm op2 value
+@deffn {Command} {arm mcr} pX op1 CRn CRm op2 value
Write @var{value} to a coprocessor @var{pX} register
passing parameters @var{CRn},
@var{CRm}, opcodes @var{opc1} and @var{opc2},
an ARM register.)
@end deffn
-@deffn Command {arm mrc} pX coproc op1 CRn CRm op2
+@deffn {Command} {arm mrc} pX coproc op1 CRn CRm op2
Read a coprocessor @var{pX} register passing parameters @var{CRn},
@var{CRm}, opcodes @var{opc1} and @var{opc2},
and the MRC instruction.
an ARM register.)
@end deffn
-@deffn Command {arm reg}
+@deffn {Command} {arm reg}
Display a table of all banked core registers, fetching the current value from every
core mode if necessary.
@end deffn
-@deffn Command {arm semihosting} [@option{enable}|@option{disable}]
+@deffn {Command} {arm semihosting} [@option{enable}|@option{disable}]
@cindex ARM semihosting
Display status of semihosting, after optionally changing that status.
Supervisor Call vector by OpenOCD.
@end deffn
-@deffn Command {arm semihosting_cmdline} [@option{enable}|@option{disable}]
+@deffn {Command} {arm semihosting_redirect} (@option{disable} | @option{tcp} <port> [@option{debug}|@option{stdio}|@option{all}])
+@cindex ARM semihosting
+Redirect semihosting messages to a specified TCP port.
+
+This command redirects debug (READC, WRITEC and WRITE0) and stdio (READ, WRITE)
+semihosting operations to the specified TCP port.
+The command allows to select which type of operations to redirect (debug, stdio, all (default)).
+
+Note: for stdio operations, only I/O from/to ':tt' file descriptors are redirected.
+@end deffn
+
+@deffn {Command} {arm semihosting_cmdline} [@option{enable}|@option{disable}]
@cindex ARM semihosting
Set the command line to be passed to the debugger.
programs look at argv[0]), argv0 is ignored and can be any string.
@end deffn
-@deffn Command {arm semihosting_fileio} [@option{enable}|@option{disable}]
+@deffn {Command} {arm semihosting_fileio} [@option{enable}|@option{disable}]
@cindex ARM semihosting
Display status of semihosting fileio, after optionally changing that
status.
debugger.
@end deffn
-@deffn Command {arm semihosting_resexit} [@option{enable}|@option{disable}]
+@deffn {Command} {arm semihosting_resexit} [@option{enable}|@option{disable}]
@cindex ARM semihosting
Enable resumable SEMIHOSTING_SYS_EXIT.
this option (default: disabled).
@end deffn
+@deffn {Command} {arm semihosting_read_user_param}
+@cindex ARM semihosting
+Read parameter of the semihosting call from the target. Usable in
+semihosting-user-cmd-0x10* event handlers, returning a string.
+
+When the target makes semihosting call with operation number from range 0x100-
+0x107, an optional string parameter can be passed to the server. This parameter
+is valid during the run of the event handlers and is accessible with this
+command.
+@end deffn
+
+@deffn {Command} {arm semihosting_basedir} [dir]
+@cindex ARM semihosting
+Set the base directory for semihosting I/O, either an absolute path or a path relative to OpenOCD working directory.
+Use "." for the current directory.
+@end deffn
+
@section ARMv4 and ARMv5 Architecture
@cindex ARMv4
@cindex ARMv5
They are available in addition to the ARM commands,
and any other core-specific commands that may be available.
-@deffn Command {arm7_9 dbgrq} [@option{enable}|@option{disable}]
+@deffn {Command} {arm7_9 dbgrq} [@option{enable}|@option{disable}]
Displays the value of the flag controlling use of the
-the EmbeddedIce DBGRQ signal to force entry into debug mode,
+EmbeddedIce DBGRQ signal to force entry into debug mode,
instead of breakpoints.
If a boolean parameter is provided, first assigns that flag.
including ARM9TDMI, ARM920T, and ARM926EJ-S.
@end deffn
-@deffn Command {arm7_9 dcc_downloads} [@option{enable}|@option{disable}]
+@deffn {Command} {arm7_9 dcc_downloads} [@option{enable}|@option{disable}]
@cindex DCC
Displays the value of the flag controlling use of the debug communications
channel (DCC) to write larger (>128 byte) amounts of memory.
with OpenOCD rev. 60, and requires a few bytes of working area.
@end deffn
-@deffn Command {arm7_9 fast_memory_access} [@option{enable}|@option{disable}]
+@deffn {Command} {arm7_9 fast_memory_access} [@option{enable}|@option{disable}]
Displays the value of the flag controlling use of memory writes and reads
that don't check completion of the operation.
If a boolean parameter is provided, first assigns that flag.
speeds, like the 32kHz startup clock of an AT91RM9200.
@end deffn
-@subsection ARM720T specific commands
-@cindex ARM720T
-
-These commands are available to ARM720T based CPUs,
-which are implementations of the ARMv4T architecture
-based on the ARM7TDMI-S integer core.
-They are available in addition to the ARM and ARM7/ARM9 commands.
-
-@deffn Command {arm720t cp15} opcode [value]
-@emph{DEPRECATED -- avoid using this.
-Use the @command{arm mrc} or @command{arm mcr} commands instead.}
-
-Display cp15 register returned by the ARM instruction @var{opcode};
-else if a @var{value} is provided, that value is written to that register.
-The @var{opcode} should be the value of either an MRC or MCR instruction.
-@end deffn
-
@subsection ARM9 specific commands
@cindex ARM9
@c versions have different rules about when they commit writes.
@anchor{arm9vectorcatch}
-@deffn Command {arm9 vector_catch} [@option{all}|@option{none}|list]
+@deffn {Command} {arm9 vector_catch} [@option{all}|@option{none}|list]
@cindex vector_catch
Vector Catch hardware provides a sort of dedicated breakpoint
for hardware events such as reset, interrupt, and abort.
They are available in addition to the ARM, ARM7/ARM9,
and ARM9 commands.
-@deffn Command {arm920t cache_info}
+@deffn {Command} {arm920t cache_info}
Print information about the caches found. This allows to see whether your target
is an ARM920T (2x16kByte cache) or ARM922T (2x8kByte cache).
@end deffn
-@deffn Command {arm920t cp15} regnum [value]
+@deffn {Command} {arm920t cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
This uses "physical access" and the register number is as
(Not all registers can be written.)
@end deffn
-@deffn Command {arm920t cp15i} opcode [value [address]]
-@emph{DEPRECATED -- avoid using this.
-Use the @command{arm mrc} or @command{arm mcr} commands instead.}
-
-Interpreted access using ARM instruction @var{opcode}, which should
-be the value of either an MRC or MCR instruction
-(as shown tables 9-11, 9-12, and 9-13 in the ARM920T TRM).
-If no @var{value} is provided, the result is displayed.
-Else if that value is written using the specified @var{address},
-or using zero if no other address is provided.
-@end deffn
-
-@deffn Command {arm920t read_cache} filename
+@deffn {Command} {arm920t read_cache} filename
Dump the content of ICache and DCache to a file named @file{filename}.
@end deffn
-@deffn Command {arm920t read_mmu} filename
+@deffn {Command} {arm920t read_mmu} filename
Dump the content of the ITLB and DTLB to a file named @file{filename}.
@end deffn
The Feroceon cores also support these commands, although
they are not built from ARM926ej-s designs.
-@deffn Command {arm926ejs cache_info}
+@deffn {Command} {arm926ejs cache_info}
Print information about the caches found.
@end deffn
They are available in addition to the ARM, ARM7/ARM9,
and ARM9 commands.
-@deffn Command {arm966e cp15} regnum [value]
+@deffn {Command} {arm966e cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
The six bit @var{regnum} values are bits 37..32 from table 7-2 of the
These commands are available to XScale based CPUs,
which are implementations of the ARMv5TE architecture.
-@deffn Command {xscale analyze_trace}
+@deffn {Command} {xscale analyze_trace}
Displays the contents of the trace buffer.
@end deffn
-@deffn Command {xscale cache_clean_address} address
+@deffn {Command} {xscale cache_clean_address} address
Changes the address used when cleaning the data cache.
@end deffn
-@deffn Command {xscale cache_info}
+@deffn {Command} {xscale cache_info}
Displays information about the CPU caches.
@end deffn
-@deffn Command {xscale cp15} regnum [value]
+@deffn {Command} {xscale cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
@end deffn
-@deffn Command {xscale debug_handler} target address
+@deffn {Command} {xscale debug_handler} target address
Changes the address used for the specified target's debug handler.
@end deffn
-@deffn Command {xscale dcache} [@option{enable}|@option{disable}]
+@deffn {Command} {xscale dcache} [@option{enable}|@option{disable}]
Enables or disable the CPU's data cache.
@end deffn
-@deffn Command {xscale dump_trace} filename
+@deffn {Command} {xscale dump_trace} filename
Dumps the raw contents of the trace buffer to @file{filename}.
@end deffn
-@deffn Command {xscale icache} [@option{enable}|@option{disable}]
+@deffn {Command} {xscale icache} [@option{enable}|@option{disable}]
Enables or disable the CPU's instruction cache.
@end deffn
-@deffn Command {xscale mmu} [@option{enable}|@option{disable}]
+@deffn {Command} {xscale mmu} [@option{enable}|@option{disable}]
Enables or disable the CPU's memory management unit.
@end deffn
-@deffn Command {xscale trace_buffer} [@option{enable}|@option{disable} [@option{fill} [n] | @option{wrap}]]
+@deffn {Command} {xscale trace_buffer} [@option{enable}|@option{disable} [@option{fill} [n] | @option{wrap}]]
Displays the trace buffer status, after optionally
enabling or disabling the trace buffer
and modifying how it is emptied.
@end deffn
-@deffn Command {xscale trace_image} filename [offset [type]]
+@deffn {Command} {xscale trace_image} filename [offset [type]]
Opens a trace image from @file{filename}, optionally rebasing
its segment addresses by @var{offset}.
The image @var{type} may be one of
@end deffn
@anchor{xscalevectorcatch}
-@deffn Command {xscale vector_catch} [mask]
+@deffn {Command} {xscale vector_catch} [mask]
@cindex vector_catch
Display a bitmask showing the hardware vectors to catch.
If the optional parameter is provided, first set the bitmask to that value.
@end example
@end deffn
-@deffn Command {xscale vector_table} [(@option{low}|@option{high}) index value]
+@deffn {Command} {xscale vector_table} [(@option{low}|@option{high}) index value]
@cindex vector_table
Set an entry in the mini-IC vector table. There are two tables: one for
@subsection ARM11 specific commands
@cindex ARM11
-@deffn Command {arm11 memwrite burst} [@option{enable}|@option{disable}]
+@deffn {Command} {arm11 memwrite burst} [@option{enable}|@option{disable}]
Displays the value of the memwrite burst-enable flag,
which is enabled by default.
If a boolean parameter is provided, first assigns that flag.
This is usually safe, because JTAG runs much slower than the CPU.
@end deffn
-@deffn Command {arm11 memwrite error_fatal} [@option{enable}|@option{disable}]
+@deffn {Command} {arm11 memwrite error_fatal} [@option{enable}|@option{disable}]
Displays the value of the memwrite error_fatal flag,
which is enabled by default.
If a boolean parameter is provided, first assigns that flag.
When set, certain memory write errors cause earlier transfer termination.
@end deffn
-@deffn Command {arm11 step_irq_enable} [@option{enable}|@option{disable}]
+@deffn {Command} {arm11 step_irq_enable} [@option{enable}|@option{disable}]
Displays the value of the flag controlling whether
IRQs are enabled during single stepping;
they are disabled by default.
If a boolean parameter is provided, first assigns that.
@end deffn
-@deffn Command {arm11 vcr} [value]
+@deffn {Command} {arm11 vcr} [value]
@cindex vector_catch
Displays the value of the @emph{Vector Catch Register (VCR)},
coprocessor 14 register 7.
@subsection ARMv7-A specific commands
@cindex Cortex-A
-@deffn Command {cortex_a cache_info}
+@deffn {Command} {cortex_a cache_info}
display information about target caches
@end deffn
-@deffn Command {cortex_a dacrfixup [@option{on}|@option{off}]}
+@deffn {Command} {cortex_a dacrfixup} [@option{on}|@option{off}]
Work around issues with software breakpoints when the program text is
mapped read-only by the operating system. This option sets the CP15 DACR
to "all-manager" to bypass MMU permission checks on memory access.
Defaults to 'off'.
@end deffn
-@deffn Command {cortex_a dbginit}
+@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
+@deffn {Command} {cortex_a smp} [on|off]
+Display/set the current SMP mode
@end deffn
-@deffn Command {cortex_a smp_on}
-Enable SMP mode
-@end deffn
-
-@deffn Command {cortex_a smp_gdb} [core_id]
+@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}]
+@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]
+@deffn {Command} {cache_config l2x} [base way]
configure l2x cache
@end deffn
-@deffn Command {cortex_a mmu dump} [@option{0}|@option{1}|@option{addr} address [@option{num_entries}]]
+@deffn {Command} {cortex_a mmu dump} [@option{0}|@option{1}|@option{addr} address [@option{num_entries}]]
Dump the MMU translation table from TTB0 or TTB1 register, or from physical
memory location @var{address}. When dumping the table from @var{address}, print at most
@var{num_entries} page table entries. @var{num_entries} is optional, if omitted, the maximum
@subsection ARMv7-R specific commands
@cindex Cortex-R
-@deffn Command {cortex_r dbginit}
+@deffn {Command} {cortex_r4 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}]
+@deffn {Command} {cortex_r4 maskisr} [@option{on}|@option{off}]
Selects whether interrupts will be processed when single stepping
@end deffn
-@subsection ARMv7-M specific commands
+@subsection ARM CoreSight TPIU and SWO specific commands
@cindex tracing
@cindex SWO
@cindex SWV
@cindex TPIU
-@cindex ITM
-@cindex ETM
-
-@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}]))
-ARMv7-M architecture provides several modules to generate debugging
+ARM CoreSight provides several modules to generate debugging
information internally (ITM, DWT and ETM). Their output is directed
-through TPIU to be captured externally either on an SWO pin (this
+through TPIU or SWO modules to be captured externally either on an SWO pin (this
configuration is called SWV) or on a synchronous parallel trace port.
-This command configures the TPIU module of the target and, if internal
-capture mode is selected, starts to capture trace output by using the
-debugger adapter features.
+ARM CoreSight provides independent HW blocks named TPIU and SWO each with its
+own functionality. Embedded in Cortex-M3 and M4, ARM provides an optional HW
+block that includes both TPIU and SWO functionalities and is again named TPIU,
+which causes quite some confusion.
+The registers map of all the TPIU and SWO implementations allows using a single
+driver that detects at runtime the features available.
-Some targets require additional actions to be performed in the
-@b{trace-config} handler for trace port to be activated.
+The @command{tpiu} is used for either TPIU or SWO.
+A convenient alias @command{swo} is available to help distinguish, in scripts,
+the commands for SWO from the commands for TPIU.
-Command options:
-@itemize @minus
-@item @option{disable} disable TPIU handling;
-@item @option{external} configure TPIU to let user capture trace
-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
-coding;
-@item @option{uart} use asynchronous SWO mode with NRZ (same as
-regular UART 8N1) coding;
-@item @var{formatter_enable} is @option{on} or @option{off} to enable
-or disable TPIU formatter which needs to be used when both ITM and ETM
-data is to be output via SWO;
-@item @var{TRACECLKIN_freq} this should be specified to match target's
-current TRACECLKIN frequency (usually the same as HCLK);
-@item @var{trace_freq} trace port frequency. Can be omitted in
-internal mode to let the adapter driver select the maximum supported
-rate automatically.
+@deffn {Command} {swo} ...
+Alias of @command{tpiu ...}. Can be used in scripts to distinguish the commands
+for SWO from the commands for TPIU.
+@end deffn
+
+@deffn {Command} {tpiu create} tpiu_name configparams...
+Creates a TPIU or a SWO object. The two commands are equivalent.
+Add the object in a list and add new commands (@command{@var{tpiu_name}})
+which are used for various purposes including additional configuration.
+
+@itemize @bullet
+@item @var{tpiu_name} -- the name of the TPIU or SWO object.
+This name is also used to create the object's command, referred to here
+as @command{$tpiu_name}, and in other places where the TPIU or SWO needs to be identified.
+@item @var{configparams} -- all parameters accepted by @command{$tpiu_name configure} are permitted.
+
+You @emph{must} set here the AP and MEM_AP base_address through @code{-dap @var{dap_name}},
+@code{-ap-num @var{ap_number}} and @code{-baseaddr @var{base_address}}.
+@end itemize
+@end deffn
+
+@deffn {Command} {tpiu names}
+Lists all the TPIU or SWO objects created so far. The two commands are equivalent.
+@end deffn
+
+@deffn {Command} {tpiu init}
+Initialize all registered TPIU and SWO. The two commands are equivalent.
+These commands are used internally during initialization. They can be issued
+at any time after the initialization, too.
+@end deffn
+
+@deffn {Command} {$tpiu_name cget} queryparm
+Each configuration parameter accepted by @command{$tpiu_name configure} can be
+individually queried, to return its current value.
+The @var{queryparm} is a parameter name accepted by that command, such as @code{-dap}.
+@end deffn
+
+@deffn {Command} {$tpiu_name configure} configparams...
+The options accepted by this command may also be specified as parameters
+to @command{tpiu create}. Their values can later be queried one at a time by
+using the @command{$tpiu_name cget} command.
+
+@itemize @bullet
+@item @code{-dap} @var{dap_name} -- names the DAP used to access this
+TPIU. @xref{dapdeclaration,,DAP declaration}, on how to create and manage DAP instances.
+
+@item @code{-ap-num} @var{ap_number} -- sets DAP access port for TPIU.
+On ADIv5 DAP @var{ap_number} is the numeric index of the DAP AP the TPIU is connected to.
+On ADIv6 DAP @var{ap_number} is the base address of the DAP AP the TPIU is connected to.
+
+@item @code{-baseaddr} @var{base_address} -- sets the TPIU @var{base_address} where
+to access the TPIU in the DAP AP memory space.
+
+@item @code{-protocol} (@option{sync}|@option{uart}|@option{manchester}) -- sets the
+protocol used for trace data:
+@itemize @minus
+@item @option{sync} -- synchronous parallel trace output mode, using @var{port_width}
+ data bits (default);
+@item @option{uart} -- use asynchronous SWO mode with NRZ (same as regular UART 8N1) coding;
+@item @option{manchester} -- use asynchronous SWO mode with Manchester coding.
+@end itemize
+
+@item @code{-event} @var{event_name} @var{event_body} -- assigns an event handler,
+a TCL string which is evaluated when the event is triggered. The events
+@code{pre-enable}, @code{post-enable}, @code{pre-disable} and @code{post-disable}
+are defined for TPIU/SWO.
+A typical use case for the event @code{pre-enable} is to enable the trace clock
+of the TPIU.
+
+@item @code{-output} (@option{external}|@option{:}@var{port}|@var{filename}|@option{-}) -- specifies
+the destination of the trace data:
+@itemize @minus
+@item @option{external} -- configure TPIU/SWO to let user capture trace
+output externally, either with an additional UART or with a logic analyzer (default);
+@item @option{-} -- configure TPIU/SWO and debug adapter to gather trace data
+and forward it to @command{tcl_trace} command;
+@item @option{:}@var{port} -- configure TPIU/SWO and debug adapter to gather
+trace data, open a TCP server at port @var{port} and send the trace data to
+each connected client;
+@item @var{filename} -- configure TPIU/SWO and debug adapter to
+gather trace data and append it to @var{filename}, which can be
+either a regular file or a named pipe.
@end itemize
+@item @code{-traceclk} @var{TRACECLKIN_freq} -- mandatory parameter.
+Specifies the frequency in Hz of the trace clock. For the TPIU embedded in
+Cortex-M3 or M4, this is usually the same frequency as HCLK. For protocol
+@option{sync} this is twice the frequency of the pin data rate.
+
+@item @code{-pin-freq} @var{trace_freq} -- specifies the expected data rate
+in Hz of the SWO pin. Parameter used only on protocols @option{uart} and
+@option{manchester}. Can be omitted to let the adapter driver select the
+maximum supported rate automatically.
+
+@item @code{-port-width} @var{port_width} -- sets to @var{port_width} the width
+of the synchronous parallel port used for trace output. Parameter used only on
+protocol @option{sync}. If not specified, default value is @var{1}.
+
+@item @code{-formatter} (@option{0}|@option{1}) -- specifies if the formatter
+should be enabled. Parameter used only on protocol @option{sync}. If not specified,
+default value is @var{0}.
+@end itemize
+@end deffn
+
+@deffn {Command} {$tpiu_name enable}
+Uses the parameters specified by the previous @command{$tpiu_name configure}
+to configure and enable the TPIU or the SWO.
+If required, the adapter is also configured and enabled to receive the trace
+data.
+This command can be used before @command{init}, but it will take effect only
+after the @command{init}.
+@end deffn
+
+@deffn {Command} {$tpiu_name disable}
+Disable the TPIU or the SWO, terminating the receiving of the trace data.
+@end deffn
+
+
+
Example usage:
@enumerate
@item STM32L152 board is programmed with an application that configures
@item OpenOCD invocation line:
@example
openocd -f interface/stlink.cfg \
- -c "transport select hla_swd" \
- -f target/stm32l1.cfg \
- -c "tpiu config external uart off 24000000 12000000"
+-c "transport select hla_swd" \
+-f target/stm32l1.cfg \
+-c "stm32l1.tpiu configure -protocol uart" \
+-c "stm32l1.tpiu configure -traceclk 24000000 -pin-freq 12000000" \
+-c "stm32l1.tpiu enable"
@end example
@end enumerate
-@end deffn
-@deffn Command {itm port} @var{port} (@option{0}|@option{1}|@option{on}|@option{off})
+@subsection ARMv7-M specific commands
+@cindex tracing
+@cindex SWO
+@cindex SWV
+@cindex ITM
+@cindex ETM
+
+@deffn {Command} {itm port} @var{port} (@option{0}|@option{1}|@option{on}|@option{off})
Enable or disable trace output for ITM stimulus @var{port} (counting
from 0). Port 0 is enabled on target creation automatically.
@end deffn
-@deffn Command {itm ports} (@option{0}|@option{1}|@option{on}|@option{off})
+@deffn {Command} {itm ports} (@option{0}|@option{1}|@option{on}|@option{off})
Enable or disable trace output for all ITM stimulus ports.
@end deffn
@subsection Cortex-M specific commands
@cindex Cortex-M
-@deffn Command {cortex_m maskisr} (@option{auto}|@option{on}|@option{off})
+@deffn {Command} {cortex_m maskisr} (@option{auto}|@option{on}|@option{off}|@option{steponly})
Control masking (disabling) interrupts during target step/resume.
The @option{auto} option handles interrupts during stepping in a way that they
are enabled again. If the interrupt handlers don't complete within 500ms,
the step command leaves with the core running.
+The @option{steponly} option disables interrupts during single-stepping but
+enables them during normal execution. This can be used as a partial workaround
+for 702596 erratum in Cortex-M7 r0p1. See "Cortex-M7 (AT610) and Cortex-M7 with
+FPU (AT611) Software Developer Errata Notice" from ARM for further details.
+
Note that a free hardware (FPB) breakpoint is required for the @option{auto}
option. If no breakpoint is available at the time of the step, then the step
is taken with interrupts enabled, i.e. the same way the @option{off} option
Default is @option{auto}.
@end deffn
-@deffn Command {cortex_m vector_catch} [@option{all}|@option{none}|list]
+@deffn {Command} {cortex_m vector_catch} [@option{all}|@option{none}|list]
@cindex vector_catch
Vector Catch hardware provides dedicated breakpoints
for certain hardware events.
This finishes by listing the current vector catch configuration.
@end deffn
-@deffn Command {cortex_m reset_config} (@option{sysresetreq}|@option{vectreset})
+@deffn {Command} {cortex_m reset_config} (@option{sysresetreq}|@option{vectreset})
Control reset handling if hardware srst is not fitted
@xref{reset_config,,reset_config}.
@cindex ARMv8-A
@cindex aarch64
-@deffn Command {aarch64 cache_info}
+@deffn {Command} {aarch64 cache_info}
Display information about target caches
@end deffn
-@deffn Command {aarch64 dbginit}
+@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
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
+@deffn {Command} {aarch64 disassemble} address [count]
+@cindex disassemble
+Disassembles @var{count} instructions starting at @var{address}.
+If @var{count} is not specified, a single instruction is disassembled.
+@end deffn
+
+@deffn {Command} {aarch64 smp} [on|off]
+Display, enable or disable SMP handling mode. 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
-@deffn Command {aarch64 maskisr} [@option{on}|@option{off}]
+@deffn {Command} {aarch64 maskisr} [@option{on}|@option{off}]
Selects whether interrupts will be processed when single stepping. The default configuration is
@option{on}.
@end deffn
+@deffn {Command} {$target_name catch_exc} [@option{off}|@option{sec_el1}|@option{sec_el3}|@option{nsec_el1}|@option{nsec_el2}]+
+Cause @command{$target_name} to halt when an exception is taken. Any combination of
+Secure (sec) EL1/EL3 or Non-Secure (nsec) EL1/EL2 is valid. The target
+@command{$target_name} will halt before taking the exception. In order to resume
+the target, the exception catch must be disabled again with @command{$target_name catch_exc off}.
+Issuing the command without options prints the current configuration.
+@end deffn
+
+@deffn {Command} {$target_name pauth} [@option{off}|@option{on}]
+Enable or disable pointer authentication features.
+When pointer authentication is used on ARM cores, GDB asks GDB servers for an 8-bytes mask to remove signature bits added by pointer authentication.
+If this feature is enabled, OpenOCD provides GDB with an 8-bytes mask.
+Pointer authentication feature is broken until gdb 12.1, going to be fixed.
+Consider using a newer version of gdb if you want to enable pauth feature.
+The default configuration is @option{off}.
+@end deffn
+
+
@section EnSilica eSi-RISC Architecture
eSi-RISC is a highly configurable microprocessor architecture for embedded systems
@subsection eSi-RISC Configuration
-@deffn Command {esirisc cache_arch} (@option{harvard}|@option{von_neumann})
+@deffn {Command} {esirisc cache_arch} (@option{harvard}|@option{von_neumann})
Configure the caching architecture. Targets with the @code{UNIFIED_ADDRESS_SPACE}
option disabled employ a Harvard architecture. By default, @option{von_neumann} is assumed.
@end deffn
-@deffn Command {esirisc hwdc} (@option{all}|@option{none}|mask ...)
+@deffn {Command} {esirisc hwdc} (@option{all}|@option{none}|mask ...)
Configure hardware debug control. The HWDC register controls which exceptions return
control back to the debugger. Possible masks are @option{all}, @option{none},
@option{reset}, @option{interrupt}, @option{syscall}, @option{error}, and @option{debug}.
@subsection eSi-RISC Operation
-@deffn Command {esirisc flush_caches}
+@deffn {Command} {esirisc flush_caches}
Flush instruction and data caches. This command requires that the target is halted
when the command is issued and configured with an instruction or data cache.
@end deffn
software operation on the CPU.
@end quotation
-@deffn Command {esirisc trace buffer} address size [@option{wrap}]
+@deffn {Command} {esirisc trace buffer} address size [@option{wrap}]
Configure trace buffer using the provided address and size. If the @option{wrap}
option is specified, trace collection will continue once the end of the buffer
is reached. By default, wrap is disabled.
@end deffn
-@deffn Command {esirisc trace fifo} address
+@deffn {Command} {esirisc trace fifo} address
Configure trace FIFO using the provided address.
@end deffn
-@deffn Command {esirisc trace flow_control} (@option{enable}|@option{disable})
+@deffn {Command} {esirisc trace flow_control} (@option{enable}|@option{disable})
Enable or disable stalling the CPU to collect trace data. By default, flow
control is disabled.
@end deffn
-@deffn Command {esirisc trace format} (@option{full}|@option{branch}|@option{icache}) pc_bits
+@deffn {Command} {esirisc trace format} (@option{full}|@option{branch}|@option{icache}) pc_bits
Configure trace format and number of PC bits to be captured. @option{pc_bits}
must be within 1 and 31 as the LSB is not collected. If external tooling is used
to analyze collected trace data, these values must match.
@end itemize
@end deffn
-@deffn Command {esirisc trace trigger start} (@option{condition}) [start_data start_mask]
+@deffn {Command} {esirisc trace trigger start} (@option{condition}) [start_data start_mask]
Configure trigger start condition using the provided start data and mask. A
brief description of each condition is provided below; for more detail on how
these values are used, see the eSi-RISC Architecture Manual.
@end itemize
@end deffn
-@deffn Command {esirisc trace trigger stop} (@option{condition}) [stop_data stop_mask]
+@deffn {Command} {esirisc trace trigger stop} (@option{condition}) [stop_data stop_mask]
Configure trigger stop condition using the provided stop data and mask. A brief
description of each condition is provided below; for more detail on how these
values are used, see the eSi-RISC Architecture Manual.
@end itemize
@end deffn
-@deffn Command {esirisc trace trigger delay} (@option{trigger}) [cycles]
+@deffn {Command} {esirisc trace trigger delay} (@option{trigger}) [cycles]
Configure trigger start/stop delay in clock cycles.
Supported triggers:
@subsection eSi-Trace Operation
-@deffn Command {esirisc trace init}
+@deffn {Command} {esirisc trace init}
Initialize trace collection. This command must be called any time the
-configuration changes. If an trace buffer has been configured, the contents will
+configuration changes. If a trace buffer has been configured, the contents will
be overwritten when trace collection starts.
@end deffn
-@deffn Command {esirisc trace info}
+@deffn {Command} {esirisc trace info}
Display trace configuration.
@end deffn
-@deffn Command {esirisc trace status}
+@deffn {Command} {esirisc trace status}
Display trace collection status.
@end deffn
-@deffn Command {esirisc trace start}
+@deffn {Command} {esirisc trace start}
Start manual trace collection.
@end deffn
-@deffn Command {esirisc trace stop}
+@deffn {Command} {esirisc trace stop}
Stop manual trace collection.
@end deffn
-@deffn Command {esirisc trace analyze} [address size]
+@deffn {Command} {esirisc trace analyze} [address size]
Analyze collected trace data. This command may only be used if a trace buffer
has been configured. If a trace FIFO has been configured, trace data must be
copied to an in-memory buffer identified by the @option{address} and
@option{size} options using DMA.
@end deffn
-@deffn Command {esirisc trace dump} [address size] @file{filename}
+@deffn {Command} {esirisc trace dump} [address size] @file{filename}
Dump collected trace data to file. This command may only be used if a trace
buffer has been configured. If a trace FIFO has been configured, trace data must
be copied to an in-memory buffer identified by the @option{address} and
@option{size} options using DMA.
@end deffn
-@deffn Command {$target_name catch_exc} [@option{off}|@option{sec_el1}|@option{sec_el3}|@option{nsec_el1}|@option{nsec_el2}]+
-Cause @command{$target_name} to halt when an exception is taken. Any combination of
-Secure (sec) EL1/EL3 or Non-Secure (nsec) EL1/EL2 is valid. The target
-@command{$target_name} will halt before taking the exception. In order to resume
-the target, the exception catch must be disabled again with @command{$target_name catch_exc off}.
-Issuing the command without options prints the current configuration.
-@end deffn
-
@section Intel Architecture
Intel Quark X10xx is the first product in the Quark family of SoCs. It is an IA-32
The three main address spaces for x86 are memory, I/O and configuration space.
These commands allow a user to read and write to the 64Kbyte I/O address space.
-@deffn Command {x86_32 idw} address
+@deffn {Command} {x86_32 idw} address
Display the contents of a 32-bit I/O port from address range 0x0000 - 0xffff.
@end deffn
-@deffn Command {x86_32 idh} address
+@deffn {Command} {x86_32 idh} address
Display the contents of a 16-bit I/O port from address range 0x0000 - 0xffff.
@end deffn
-@deffn Command {x86_32 idb} address
+@deffn {Command} {x86_32 idb} address
Display the contents of a 8-bit I/O port from address range 0x0000 - 0xffff.
@end deffn
-@deffn Command {x86_32 iww} address
+@deffn {Command} {x86_32 iww} address
Write the contents of a 32-bit I/O port to address range 0x0000 - 0xffff.
@end deffn
-@deffn Command {x86_32 iwh} address
+@deffn {Command} {x86_32 iwh} address
Write the contents of a 16-bit I/O port to address range 0x0000 - 0xffff.
@end deffn
-@deffn Command {x86_32 iwb} address
+@deffn {Command} {x86_32 iwb} address
Write the contents of a 8-bit I/O port to address range 0x0000 - 0xffff.
@end deffn
configured with any of the TAP / Debug Unit available.
@subsection TAP and Debug Unit selection commands
-@deffn Command {tap_select} (@option{vjtag}|@option{mohor}|@option{xilinx_bscan})
+@deffn {Command} {tap_select} (@option{vjtag}|@option{mohor}|@option{xilinx_bscan})
Select between the Altera Virtual JTAG , Xilinx Virtual JTAG and Mohor TAP.
@end deffn
-@deffn Command {du_select} (@option{adv}|@option{mohor}) [option]
+@deffn {Command} {du_select} (@option{adv}|@option{mohor}) [option]
Select between the Advanced Debug Interface and the classic one.
An option can be passed as a second argument to the debug unit.
@end deffn
@subsection Registers commands
-@deffn Command {addreg} [name] [address] [feature] [reg_group]
+@deffn {Command} {addreg} [name] [address] [feature] [reg_group]
Add a new register in the cpu register list. This register will be
included in the generated target descriptor file.
addreg rtest 0x1234 org.gnu.gdb.or1k.group0 system
@end example
+@end deffn
+
+@section MIPS Architecture
+@cindex microMIPS
+@cindex MIPS32
+@cindex MIPS64
+
+@uref{http://mips.com/, MIPS} is a simple, streamlined, highly scalable RISC
+architecture. The architecture is evolving over time, from MIPS I~V to
+MIPS release 1~6 iterations, the architecture is now able to handle various tasks
+with different ASEs, including SIMD(MSA), DSP, VZ, MT and more.
+MIPS32 supports 32-bit programs while MIPS64 can support both 32-bit and 64-bit programs.
+@subsection MIPS Terminology
+
+The term ASE means Application-Specific Extension, ASEs provide features that
+improve the efficiency and performance of certain workloads, such as
+digital signal processing(DSP), Virtualization(VZ), Multi-Threading(MT),
+SIMD(MSA) and more.
+
+MIPS Cores use Coprocessors(CPx) to configure their behaviour or to let software
+know the capabilities of current CPU, the main Coprocessor is CP0, containing 32
+registers with a maximum select number of 7.
+
+@subsection MIPS FPU & Vector Registers
+
+MIPS processors does not all comes with FPU co-processor, and when it does, the FPU
+appears as Coprocessor 1 whereas the Coprocessor 0 is for the main processor.
+
+Most of MIPS FPUs are 64 bits, IEEE 754 standard, and they provides both 32-bit
+single precision and 64-bit double precision calculations. Fixed point format
+calculations are also provided with both 32 and 64-bit modes.
+
+The MIPS SIMD Architecture(MSA) operates on 32 128-bit wide vector registers.
+If both MSA and the scalar floating-point unit (FPU) are present, the 128-bit MSA
+vector registers extend and share the 64-bit FPU registers. MSA and FPU can not be
+both present, unless the FPU has 64-bit floating-point register.
+
+@subsection MIPS Configuration Commands
+
+@deffn {Command} {mips32 cpuinfo}
+Displays detailed information about current CPU core. This includes core type,
+vendor, instruction set, cache size, and other relevant details.
+@end deffn
+
+@deffn {Config Command} {mips32 scan_delay} [nanoseconds]
+Display or set scan delay in nano seconds. A value below 2_000_000 will set the
+scan delay into legacy mode.
@end deffn
-@deffn Command {readgroup} (@option{group})
-Display all registers in @emph{group}.
-@emph{group} can be "system",
- "dmmu", "immu", "dcache", "icache", "mac", "debug", "perf", "power", "pic",
- "timer" or any new group created with addreg command.
+@deffn {Config Command} {mips32 cp0} [[reg_name|regnum select] [value]]
+Displays or sets coprocessor 0 register by register number and select or their name.
+This command shows all available cp0 register if no arguments are provided.
+
+For common MIPS Coprocessor 0 registers, you can find the definitions of them
+on MIPS Privileged Resource Architecture Documents(MIPS Document MD00090).
+
+For core specific cp0 registers, you can find the definitions of them on Core
+Specific Software User's Manual(SUM), for example, MIPS M5150 Software User Manual
+(MD00980).
+@end deffn
+
+@deffn {Command} {mips32 ejtag_reg}
+Reads EJTAG Registers for inspection.
+
+EJTAG Register Specification could be found in MIPS Document MD00047F, for
+core specific EJTAG Register definition, please check Core Specific SUM manual.
+@end deffn
+
+@deffn {Command} {mips32 dsp} [[register_name] [value]]
+Displays all DSP registers' contents or get/set value by register name. Will display
+an error if current CPU does not support DSP.
@end deffn
@section RISC-V Architecture
another hart, or may be a separate core. RISC-V treats those the same, and
OpenOCD exposes each hart as a separate core.
+@subsection Vector Registers
+
+For harts that implement the vector extension, OpenOCD provides access to the
+relevant CSRs, as well as the vector registers (v0-v31). The size of each
+vector register is dependent on the value of vlenb. RISC-V allows each vector
+register to be divided into selected-width elements, and this division can be
+changed at run-time. Because OpenOCD cannot update register definitions at
+run-time, it exposes each vector register to gdb as a union of fields of
+vectors so that users can easily access individual bytes, shorts, words,
+longs, and quads inside each vector register. It is left to gdb or
+higher-level debuggers to present this data in a more intuitive format.
+
+In the XML register description, the vector registers (when vlenb=16) look as
+follows:
+
+@example
+<feature name="org.gnu.gdb.riscv.vector">
+<vector id="bytes" type="uint8" count="16"/>
+<vector id="shorts" type="uint16" count="8"/>
+<vector id="words" type="uint32" count="4"/>
+<vector id="longs" type="uint64" count="2"/>
+<vector id="quads" type="uint128" count="1"/>
+<union id="riscv_vector">
+<field name="b" type="bytes"/>
+<field name="s" type="shorts"/>
+<field name="w" type="words"/>
+<field name="l" type="longs"/>
+<field name="q" type="quads"/>
+</union>
+<reg name="v0" bitsize="128" regnum="4162" save-restore="no"
+ type="riscv_vector" group="vector"/>
+...
+<reg name="v31" bitsize="128" regnum="4193" save-restore="no"
+ type="riscv_vector" group="vector"/>
+</feature>
+@end example
+
@subsection RISC-V Debug Configuration Commands
-@deffn Command {riscv expose_csrs} n0[-m0][,n1[-m1]]...
-Configure a list of inclusive ranges for CSRs to expose in addition to the
-standard ones. This must be executed before `init`.
+@deffn {Config Command} {riscv expose_csrs} n[-m|=name] [...]
+Configure which CSRs to expose in addition to the standard ones. The CSRs to expose
+can be specified as individual register numbers or register ranges (inclusive). For the
+individually listed CSRs, a human-readable name can optionally be set using the @code{n=name}
+syntax, which will get @code{csr_} prepended to it. If no name is provided, the register will be
+named @code{csr<n>}.
By default OpenOCD attempts to expose only CSRs that are mentioned in a spec,
and then only if the corresponding extension appears to be implemented. This
-command can be used if OpenOCD gets this wrong, or a target implements custom
+command can be used if OpenOCD gets this wrong, or if the target implements custom
CSRs.
+
+@example
+# Expose a single RISC-V CSR number 128 under the name "csr128":
+$_TARGETNAME expose_csrs 128
+
+# Expose multiple RISC-V CSRs 128..132 under names "csr128" through "csr132":
+$_TARGETNAME expose_csrs 128-132
+
+# Expose a single RISC-V CSR number 1996 under custom name "csr_myregister":
+$_TARGETNAME expose_csrs 1996=myregister
+@end example
@end deffn
-@deffn Command {riscv expose_custom} n0[-m0][,n1[-m1]]...
+@deffn {Config Command} {riscv expose_custom} n[-m|=name] [...]
The RISC-V Debug Specification allows targets to expose custom registers
through abstract commands. (See Section 3.5.1.1 in that document.) This command
-configures a list of inclusive ranges of those registers to expose. Number 0
-indicates the first custom register, whose abstract command number is 0xc000.
-This command must be executed before `init`.
+configures individual registers or register ranges (inclusive) that shall be exposed.
+Number 0 indicates the first custom register, whose abstract command number is 0xc000.
+For individually listed registers, a human-readable name can be optionally provided
+using the @code{n=name} syntax, which will get @code{custom_} prepended to it. If no
+name is provided, the register will be named @code{custom<n>}.
+
+@example
+# Expose one RISC-V custom register with number 0xc010 (0xc000 + 16)
+# under the name "custom16":
+$_TARGETNAME expose_custom 16
+
+# Expose a range of RISC-V custom registers with numbers 0xc010 .. 0xc018
+# (0xc000+16 .. 0xc000+24) under the names "custom16" through "custom24":
+$_TARGETNAME expose_custom 16-24
+
+# Expose one RISC-V custom register with number 0xc020 (0xc000 + 32) under
+# user-defined name "custom_myregister":
+$_TARGETNAME expose_custom 32=myregister
+@end example
+@end deffn
+
+@deffn {Command} {riscv info}
+Displays some information OpenOCD detected about the target.
@end deffn
-@deffn Command {riscv set_command_timeout_sec} [seconds]
+@deffn {Command} {riscv reset_delays} [wait]
+OpenOCD learns how many Run-Test/Idle cycles are required between scans to avoid
+encountering the target being busy. This command resets those learned values
+after `wait` scans. It's only useful for testing OpenOCD itself.
+@end deffn
+
+@deffn {Command} {riscv set_command_timeout_sec} [seconds]
Set the wall-clock timeout (in seconds) for individual commands. The default
should work fine for all but the slowest targets (eg. simulators).
@end deffn
-@deffn Command {riscv set_reset_timeout_sec} [seconds]
+@deffn {Command} {riscv set_reset_timeout_sec} [seconds]
Set the maximum time to wait for a hart to come out of reset after reset is
deasserted.
@end deffn
-@deffn Command {riscv set_scratch_ram} none|[address]
-Set the address of 16 bytes of scratch RAM the debugger can use, or 'none'.
-This is used to access 64-bit floating point registers on 32-bit targets.
+@deffn {Command} {riscv set_mem_access} method1 [method2] [method3]
+Specify which RISC-V memory access method(s) shall be used, and in which order
+of priority. At least one method must be specified.
+
+Available methods are:
+@itemize
+@item @code{progbuf} - Use RISC-V Debug Program Buffer to access memory.
+@item @code{sysbus} - Access memory via RISC-V Debug System Bus interface.
+@item @code{abstract} - Access memory via RISC-V Debug abstract commands.
+@end itemize
+
+By default, all memory access methods are enabled in the following order:
+@code{progbuf sysbus abstract}.
+
+This command can be used to change the memory access methods if the default
+behavior is not suitable for a particular target.
+@end deffn
+
+@deffn {Command} {riscv set_enable_virtual} on|off
+When on, memory accesses are performed on physical or virtual memory depending
+on the current system configuration. When off (default), all memory accessses are performed
+on physical memory.
@end deffn
-@deffn Command {riscv set_prefer_sba} on|off
-When on, prefer to use System Bus Access to access memory. When off, prefer to
-use the Program Buffer to access memory.
+@deffn {Command} {riscv set_enable_virt2phys} on|off
+When on (default), memory accesses are performed on physical or virtual memory
+depending on the current satp configuration. When off, all memory accessses are
+performed on physical memory.
@end deffn
-@deffn Command {riscv set_ir} (@option{idcode}|@option{dtmcs}|@option{dmi}) [value]
+@deffn {Command} {riscv resume_order} normal|reversed
+Some software assumes all harts are executing nearly continuously. Such
+software may be sensitive to the order that harts are resumed in. On harts
+that don't support hasel, this option allows the user to choose the order the
+harts are resumed in. If you are using this option, it's probably masking a
+race condition problem in your code.
+
+Normal order is from lowest hart index to highest. This is the default
+behavior. Reversed order is from highest hart index to lowest.
+@end deffn
+
+@deffn {Command} {riscv set_ir} (@option{idcode}|@option{dtmcs}|@option{dmi}) [value]
Set the IR value for the specified JTAG register. This is useful, for
example, when using the existing JTAG interface on a Xilinx FPGA by
way of BSCANE2 primitives that only permit a limited selection of IR
and DBUS registers, respectively.
@end deffn
+@deffn {Command} {riscv use_bscan_tunnel} value
+Enable or disable use of a BSCAN tunnel to reach DM. Supply the width of
+the DM transport TAP's instruction register to enable. Supply a value of 0 to disable.
+@end deffn
+
+@deffn {Command} {riscv set_ebreakm} on|off
+Control dcsr.ebreakm. When on (default), M-mode ebreak instructions trap to
+OpenOCD. When off, they generate a breakpoint exception handled internally.
+@end deffn
+
+@deffn {Command} {riscv set_ebreaks} on|off
+Control dcsr.ebreaks. When on (default), S-mode ebreak instructions trap to
+OpenOCD. When off, they generate a breakpoint exception handled internally.
+@end deffn
+
+@deffn {Command} {riscv set_ebreaku} on|off
+Control dcsr.ebreaku. When on (default), U-mode ebreak instructions trap to
+OpenOCD. When off, they generate a breakpoint exception handled internally.
+@end deffn
+
@subsection RISC-V Authentication Commands
The following commands can be used to authenticate to a RISC-V system. Eg. a
trivial challenge-response protocol could be implemented as follows in a
configuration file, immediately following @command{init}:
@example
-set challenge [ocd_riscv authdata_read]
-riscv authdata_write [expr $challenge + 1]
+set challenge [riscv authdata_read]
+riscv authdata_write [expr @{$challenge + 1@}]
@end example
-@deffn Command {riscv authdata_read}
-Return the 32-bit value read from authdata. Note that to get read value back in
-a TCL script, it needs to be invoked as @command{ocd_riscv authdata_read}.
+@deffn {Command} {riscv authdata_read}
+Return the 32-bit value read from authdata.
@end deffn
-@deffn Command {riscv authdata_write} value
+@deffn {Command} {riscv authdata_write} value
Write the 32-bit value to authdata.
@end deffn
The following commands allow direct access to the Debug Module Interface, which
can be used to interact with custom debug features.
-@deffn Command {riscv dmi_read}
-Perform a 32-bit DMI read at address, returning the value. Note that to get
-read value back in a TCL script, it needs to be invoked as @command{ocd_riscv
-dmi_read}.
+@deffn {Command} {riscv dmi_read} address
+Perform a 32-bit DMI read at address, returning the value.
@end deffn
-@deffn Command {riscv dmi_write} address value
+@deffn {Command} {riscv dmi_write} address value
Perform a 32-bit DMI write of value at address.
@end deffn
+@section ARC Architecture
+@cindex ARC
+
+Synopsys DesignWare ARC Processors are a family of 32-bit CPUs that SoC
+designers can optimize for a wide range of uses, from deeply embedded to
+high-performance host applications in a variety of market segments. See more
+at: @url{http://www.synopsys.com/IP/ProcessorIP/ARCProcessors/Pages/default.aspx}.
+OpenOCD currently supports ARC EM processors.
+There is a set ARC-specific OpenOCD commands that allow low-level
+access to the core and provide necessary support for ARC extensibility and
+configurability capabilities. ARC processors has much more configuration
+capabilities than most of the other processors and in addition there is an
+extension interface that allows SoC designers to add custom registers and
+instructions. For the OpenOCD that mostly means that set of core and AUX
+registers in target will vary and is not fixed for a particular processor
+model. To enable extensibility several TCL commands are provided that allow to
+describe those optional registers in OpenOCD configuration files. Moreover
+those commands allow for a dynamic target features discovery.
+
+
+@subsection General ARC commands
+
+@deffn {Config Command} {arc add-reg} configparams
+
+Add a new register to processor target. By default newly created register is
+marked as not existing. @var{configparams} must have following required
+arguments:
+
+@itemize @bullet
+
+@item @code{-name} name
+@*Name of a register.
+
+@item @code{-num} number
+@*Architectural register number: core register number or AUX register number.
+
+@item @code{-feature} XML_feature
+@*Name of GDB XML target description feature.
+
+@end itemize
+
+@var{configparams} may have following optional arguments:
+
+@itemize @bullet
+
+@item @code{-gdbnum} number
+@*GDB register number. It is recommended to not assign GDB register number
+manually, because there would be a risk that two register will have same
+number. When register GDB number is not set with this option, then register
+will get a previous register number + 1. This option is required only for those
+registers that must be at particular address expected by GDB.
+
+@item @code{-core}
+@*This option specifies that register is a core registers. If not - this is an
+AUX register. AUX registers and core registers reside in different address
+spaces.
+
+@item @code{-bcr}
+@*This options specifies that register is a BCR register. BCR means Build
+Configuration Registers - this is a special type of AUX registers that are read
+only and non-volatile, that is - they never change their value. Therefore OpenOCD
+never invalidates values of those registers in internal caches. Because BCR is a
+type of AUX registers, this option cannot be used with @code{-core}.
+
+@item @code{-type} type_name
+@*Name of type of this register. This can be either one of the basic GDB types,
+or a custom types described with @command{arc add-reg-type-[flags|struct]}.
+
+@item @code{-g}
+@* If specified then this is a "general" register. General registers are always
+read by OpenOCD on context save (when core has just been halted) and is always
+transferred to GDB client in a response to g-packet. Contrary to this,
+non-general registers are read and sent to GDB client on-demand. In general it
+is not recommended to apply this option to custom registers.
+
+@end itemize
+
+@end deffn
+
+@deffn {Config Command} {arc add-reg-type-flags} -name name flags...
+Adds new register type of ``flags'' class. ``Flags'' types can contain only
+one-bit fields. Each flag definition looks like @code{-flag name bit-position}.
+@end deffn
+
+@anchor{add-reg-type-struct}
+@deffn {Config Command} {arc add-reg-type-struct} -name name structs...
+Adds new register type of ``struct'' class. ``Struct'' types can contain either
+bit-fields or fields of other types, however at the moment only bit fields are
+supported. Structure bit field definition looks like @code{-bitfield name
+startbit endbit}.
+@end deffn
+
+@deffn {Command} {arc get-reg-field} reg-name field-name
+Returns value of bit-field in a register. Register must be ``struct'' register
+type, @xref{add-reg-type-struct}. command definition.
+@end deffn
+
+@deffn {Command} {arc set-reg-exists} reg-names...
+Specify that some register exists. Any amount of names can be passed
+as an argument for a single command invocation.
+@end deffn
+
+@subsection ARC JTAG commands
+
+@deffn {Command} {arc jtag set-aux-reg} regnum value
+This command writes value to AUX register via its number. This command access
+register in target directly via JTAG, bypassing any OpenOCD internal caches,
+therefore it is unsafe to use if that register can be operated by other means.
+
+@end deffn
+
+@deffn {Command} {arc jtag set-core-reg} regnum value
+This command is similar to @command{arc jtag set-aux-reg} but is for core
+registers.
+@end deffn
+
+@deffn {Command} {arc jtag get-aux-reg} regnum
+This command returns the value storded in AUX register via its number. This commands access
+register in target directly via JTAG, bypassing any OpenOCD internal caches,
+therefore it is unsafe to use if that register can be operated by other means.
+
+@end deffn
+
+@deffn {Command} {arc jtag get-core-reg} regnum
+This command is similar to @command{arc jtag get-aux-reg} but is for core
+registers.
+@end deffn
+
+@section STM8 Architecture
+@uref{http://st.com/stm8/, STM8} is a 8-bit microcontroller platform from
+STMicroelectronics, based on a proprietary 8-bit core architecture.
+
+OpenOCD supports debugging STM8 through the STMicroelectronics debug
+protocol SWIM, @pxref{swimtransport,,SWIM}.
+
+@section Xtensa Architecture
+
+Xtensa is a highly-customizable, user-extensible microprocessor and DSP
+architecture for complex embedded systems provided by Cadence Design
+Systems, Inc. See the
+@uref{https://www.cadence.com/en_US/home/tools/ip/tensilica-ip.html, Tensilica IP}
+website for additional information and documentation.
+
+OpenOCD supports generic Xtensa processor implementations which can be customized by
+providing a core-specific configuration file which describes every enabled
+Xtensa architecture option, e.g. number of address registers, exceptions, reduced
+size instructions support, memory banks configuration etc. OpenOCD also supports SMP
+configurations for Xtensa processors with any number of cores and allows configuring
+their debug interconnect (termed "break/stall networks"), which control how debug
+signals are distributed among cores. Xtensa "break networks" are compatible with
+ARM's Cross Trigger Interface (CTI). OpenOCD implements both generic Xtensa targets
+as well as several Espressif Xtensa-based chips from the
+@uref{https://www.espressif.com/en/products/socs, ESP32 family}.
+
+OCD sessions for Xtensa processor and DSP targets are accessed via the Xtensa
+Debug Module (XDM), which provides external connectivity either through a
+traditional JTAG interface or an ARM DAP interface. If used, the DAP interface
+can control Xtensa targets through JTAG or SWD probes.
+
+@subsection Xtensa Core Configuration
+
+Due to the high level of configurability in Xtensa cores, the Xtensa target
+configuration comprises two categories:
+
+@enumerate
+@item Base Xtensa support common to all core configurations, and
+@item Core-specific support as configured for individual cores.
+@end enumerate
+
+All common Xtensa support is built into the OpenOCD Xtensa target layer and
+is enabled through a combination of TCL scripts: the target-specific
+@file{target/xtensa.cfg} and a board-specific @file{board/xtensa-*.cfg},
+similar to other target architectures.
+
+Importantly, core-specific configuration information must be provided by
+the user, and takes the form of an @file{xtensa-core-XXX.cfg} TCL script that
+defines the core's configurable features through a series of Xtensa
+configuration commands (detailed below).
+
+This core-specific @file{xtensa-core-XXX.cfg} file is typically either:
+
+@itemize @bullet
+@item Located within the Xtensa core configuration build as
+@file{src/config/xtensa-core-openocd.cfg}, or
+@item Generated by running the command @code{xt-gdb --dump-oocd-config}
+from the Xtensa processor tool-chain's command-line tools.
+@end itemize
+
+NOTE: @file{xtensa-core-XXX.cfg} must match the target Xtensa hardware
+connected to OpenOCD.
+
+Some example Xtensa configurations are bundled with OpenOCD for reference:
+@enumerate
+@item Cadence Palladium VDebug emulation target. The user can combine their
+@file{xtensa-core-XXX.cfg} with the provided
+@file{board/xtensa-palladium-vdebug.cfg} to debug an emulated Xtensa RTL design.
+@item NXP MIMXRT685-EVK evaluation kit. The relevant configuration files are:
+@itemize @bullet
+@item @file{board/xtensa-rt685-ext.cfg}
+@item @file{target/xtensa-core-nxp_rt600.cfg}
+@end itemize
+Additional information is available by searching for "i.MX RT600 Evaluation Kit"
+on @url{https://www.nxp.com}.
+@end enumerate
+
+@subsection Xtensa Configuration Commands
+
+@deffn {Config Command} {xtensa xtdef} (@option{LX}|@option{NX})
+Configure the Xtensa target architecture. Currently, Xtensa support is limited
+to LX6, LX7, and NX cores.
+@end deffn
+
+@deffn {Config Command} {xtensa xtopt} option value
+Configure Xtensa target options that are relevant to the debug subsystem.
+@var{option} is one of: @option{arnum}, @option{windowed},
+@option{cpenable}, @option{exceptions}, @option{intnum}, @option{hipriints},
+@option{excmlevel}, @option{intlevels}, @option{debuglevel},
+@option{ibreaknum}, or @option{dbreaknum}. @var{value} is an integer with
+the exact range determined by each particular option.
+
+NOTE: Some options are specific to Xtensa LX or Xtensa NX architecture, while
+others may be common to both but have different valid ranges.
+@end deffn
+
+@deffn {Config Command} {xtensa xtmem} (@option{iram}|@option{dram}|@option{sram}|@option{irom}|@option{drom}|@option{srom}) baseaddr bytes
+Configure Xtensa target memory. Memory type determines access rights,
+where RAMs are read/write while ROMs are read-only. @var{baseaddr} and
+@var{bytes} are both integers, typically hexadecimal and decimal, respectively.
+
+NOTE: Some Xtensa memory types, such as system RAM/ROM or MMIO/device regions,
+can be added or modified after the Xtensa core has been generated. Additional
+@code{xtensa xtmem} definitions should be manually added to xtensa-core-XXX.cfg
+to keep OpenOCD's target address map consistent with the Xtensa configuration.
+@end deffn
+
+@deffn {Config Command} {xtensa xtmem} (@option{icache}|@option{dcache}) linebytes cachebytes ways [writeback]
+Configure Xtensa processor cache. All parameters are required except for
+the optional @option{writeback} parameter; all are integers.
+@end deffn
+
+@deffn {Config Command} {xtensa xtmpu} numfgseg minsegsz lockable execonly
+Configure an Xtensa Memory Protection Unit (MPU). MPUs can restrict access
+and/or control cacheability of specific address ranges, but are lighter-weight
+than a full traditional MMU. All parameters are required; all are integers.
+@end deffn
+
+@deffn {Config Command} {xtensa xtmmu} numirefillentries numdrefillentries
+(Xtensa-LX only) Configure an Xtensa Memory Management Unit (MMU). Both
+parameters are required; both are integers.
+@end deffn
+
+@deffn {Config Command} {xtensa xtregs} numregs
+Configure the total number of registers for the Xtensa core. Configuration
+logic expects to subsequently process this number of @code{xtensa xtreg}
+definitions. @var{numregs} is an integer.
+@end deffn
+
+@deffn {Config Command} {xtensa xtregfmt} (@option{sparse}|@option{contiguous}) [general]
+Configure the type of register map used by GDB to access the Xtensa core.
+Generic Xtensa tools (e.g. xt-gdb) require @option{sparse} mapping (default) while
+Espressif tools expect @option{contiguous} mapping. Contiguous mapping takes an
+additional, optional integer parameter @option{numgregs}, which specifies the number
+of general registers used in handling g/G packets.
+@end deffn
+
+@deffn {Config Command} {xtensa xtreg} name offset
+Configure an Xtensa core register. All core registers are 32 bits wide,
+while TIE and user registers may have variable widths. @var{name} is a
+character string identifier while @var{offset} is a hexadecimal integer.
+@end deffn
+
+@subsection Xtensa Operation Commands
+
+@deffn {Command} {xtensa maskisr} (@option{on}|@option{off})
+(Xtensa-LX only) Mask or unmask Xtensa interrupts during instruction step.
+When masked, an interrupt that occurs during a step operation is handled and
+its ISR is executed, with the user's debug session returning after potentially
+executing many instructions. When unmasked, a triggered interrupt will result
+in execution progressing the requested number of instructions into the relevant
+vector/ISR code.
+@end deffn
+
+@deffn {Command} {xtensa set_permissive} (0|1)
+By default accessing memory beyond defined regions is forbidden. This commnd controls memory access address check.
+When set to (1), skips access controls and address range check before read/write memory.
+@end deffn
+
+@deffn {Command} {xtensa smpbreak} [none|breakinout|runstall] | [BreakIn] [BreakOut] [RunStallIn] [DebugModeOut]
+Configures debug signals connection ("break network") for currently selected core.
+@itemize @bullet
+@item @code{none} - Core's "break/stall network" is disconnected. Core is not affected by any debug
+signal from other cores.
+@item @code{breakinout} - Core's "break network" is fully connected (break inputs and outputs are enabled).
+Core will receive debug break signals from other cores and send such signals to them. For example when another core
+is stopped due to breakpoint hit this core will be stopped too and vice versa.
+@item @code{runstall} - Core's "stall network" is fully connected (stall inputs and outputs are enabled).
+This feature is not well implemented and tested yet.
+@item @code{BreakIn} - Core's "break-in" signal is enabled.
+Core will receive debug break signals from other cores. For example when another core is
+stopped due to breakpoint hit this core will be stopped too.
+@item @code{BreakOut} - Core's "break-out" signal is enabled.
+Core will send debug break signal to other cores. For example when this core is
+stopped due to breakpoint hit other cores with enabled break-in signals will be stopped too.
+@item @code{RunStallIn} - Core's "runstall-in" signal is enabled.
+This feature is not well implemented and tested yet.
+@item @code{DebugModeOut} - Core's "debugmode-out" signal is enabled.
+This feature is not well implemented and tested yet.
+@end itemize
+@end deffn
+
+@deffn {Command} {xtensa exe} <ascii-encoded hexadecimal instruction bytes>
+Execute one arbitrary instruction provided as an ascii string. The string represents an integer
+number of instruction bytes, thus its length must be even. The instruction can be of any width
+that is valid for the Xtensa core configuration.
+@end deffn
+
+@deffn {Command} {xtensa dm} (address) [value]
+Read or write Xtensa Debug Module (DM) registers. @var{address} is required for both reads
+and writes and is a 4-byte-aligned value typically between 0 and 0x3ffc. @var{value} is specified
+only for write accesses.
+@end deffn
+
+@subsection Xtensa Performance Monitor Configuration
+
+@deffn {Command} {xtensa perfmon_enable} <counter_id> <select> [mask] [kernelcnt] [tracelevel]
+Enable and start performance counter.
+@itemize @bullet
+@item @code{counter_id} - Counter ID (0-1).
+@item @code{select} - Selects performance metric to be counted by the counter,
+e.g. 0 - CPU cycles, 2 - retired instructions.
+@item @code{mask} - Selects input subsets to be counted (counter will
+increment only once even if more than one condition corresponding to a mask bit occurs).
+@item @code{kernelcnt} - 0 - count events with "CINTLEVEL <= tracelevel",
+1 - count events with "CINTLEVEL > tracelevel".
+@item @code{tracelevel} - Compares this value to "CINTLEVEL" when deciding
+whether to count.
+@end itemize
+@end deffn
+
+@deffn {Command} {xtensa perfmon_dump} (counter_id)
+Dump performance counter value. If no argument specified, dumps all counters.
+@end deffn
+
+@subsection Xtensa Trace Configuration
+
+@deffn {Command} {xtensa tracestart} [pc <pcval>/[<maskbitcount>]] [after <n> [ins|words]]
+Set up and start a HW trace. Optionally set PC address range to trigger tracing stop when reached during program execution.
+This command also allows to specify the amount of data to capture after stop trigger activation.
+@itemize @bullet
+@item @code{pcval} - PC value which will trigger trace data collection stop.
+@item @code{maskbitcount} - PC value mask.
+@item @code{n} - Maximum number of instructions/words to capture after trace stop trigger.
+@end itemize
+@end deffn
+
+@deffn {Command} {xtensa tracestop}
+Stop current trace as started by the tracestart command.
+@end deffn
+
+@deffn {Command} {xtensa tracedump} <outfile>
+Dump trace memory to a file.
+@end deffn
+
+@section Espressif Specific Commands
+
+@deffn {Command} {esp apptrace} (start <destination> [<poll_period> [<trace_size> [<stop_tmo> [<wait4halt> [<skip_size>]]]]])
+Starts
+@uref{https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html#application-level-tracing-library, application level tracing}.
+Data will be stored to specified destination. Available destinations are:
+@itemize @bullet
+@item @code{file://<outfile>} - Save trace logs into file.
+@item @code{tcp://<host>:<port>} - Send trace logs to tcp port on specified host. OpenOCD will act as a tcp client.
+@item @code{con:} - Print trace logs to the stdout.
+@end itemize
+Other parameters will be same for each destination.
+@itemize @bullet
+@item @code{poll_period} - trace data polling period in ms.
+@item @code{trace_size} - maximum trace data size.
+Tracing will be stopped automatically when that amount is reached.
+Use "-1" to disable the limitation.
+@item @code{stop_tmo} - Data reception timeout in ms.
+Tracing will be stopped automatically when no data is received within that period.
+@item @code{wait4halt} - if non-zero then wait for target to be halted before tracing start.
+@item @code{skip_size} - amount of tracing data to be skipped before writing it to destination.
+@end itemize
+@end deffn
+
+@deffn {Command} {esp apptrace} (stop)
+Stops tracing started with above command.
+@end deffn
+
+@deffn {Command} {esp apptrace} (status)
+Requests ongoing tracing status.
+@end deffn
+
+@deffn {Command} {esp apptrace} (dump file://<outfile>)
+Dumps tracing data from target buffer. It can be useful to dump the latest data
+buffered on target for post-mortem analysis. For example when target starts tracing automatically
+w/o OpenOCD command and keeps only the latest data window which fit into the buffer.
+@uref{https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html#application-level-tracing-library, application level tracing}.
+Data will be stored to specified destination.
+@end deffn
+
+@deffn {Command} {esp sysview} (start file://<outfile1> [file://<outfile2>] [<poll_period> [<trace_size> [<stop_tmo> [<wait4halt> [<skip_size>]]]]])
+Starts @uref{https://www.segger.com/products/development-tools/systemview/, SEGGER SystemView}
+compatible tracing. Data will be stored to specified destination.
+For dual-core chips traces from every core will be saved to separate files.
+Resulting files can be open in "SEGGER SystemView" application.
+@url{https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html#openocd-systemview-tracing-command-options}
+The meaning of the arguments is identical to @command{esp apptrace start}.
+@end deffn
+
+@deffn {Command} {esp sysview} (stop)
+Stops SystremView compatible tracing started with above command.
+@url{https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html#openocd-systemview-tracing-command-options}
+@end deffn
+
+@deffn {Command} {esp sysview} (status)
+Requests ongoing SystremView compatible tracing status.
+@url{https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html#openocd-systemview-tracing-command-options}
+@end deffn
+
+@deffn {Command} {esp sysview_mcore} (start file://<outfile> [<poll_period> [<trace_size> [<stop_tmo> [<wait4halt> [<skip_size>]]]]])
+This command is identical to @command{esp sysview start}, but uses Espressif multi-core extension to
+@uref{https://www.segger.com/products/development-tools/systemview/, SEGGER SystemView} data format.
+Data will be stored to specified destination. Tracing data from all cores are saved in the same file.
+The meaning of the arguments is identical to @command{esp sysview start}.
+@end deffn
+
+@deffn {Command} {esp sysview_mcore} (stop)
+Stops Espressif multi-core SystremView tracing started with above command.
+@end deffn
+
+@deffn {Command} {esp sysview_mcore} (status)
+Requests ongoing Espressif multi-core SystremView tracing status.
+@end deffn
+
@anchor{softwaredebugmessagesandtracing}
@section Software Debug Messages and Tracing
@cindex Linux-ARM DCC support
Other software, such as the U-Boot boot loader, sometimes
does the same thing.
-@deffn Command {target_request debugmsgs} [@option{enable}|@option{disable}|@option{charmsg}]
+@deffn {Command} {target_request debugmsgs} [@option{enable}|@option{disable}|@option{charmsg}]
Displays current handling of target DCC message requests.
These messages may be sent to the debugger while the target is running.
The optional @option{enable} and @option{charmsg} parameters
otherwise the libdcc format is used.
@end deffn
-@deffn Command {trace history} [@option{clear}|count]
+@deffn {Command} {trace history} [@option{clear}|count]
With no parameter, displays all the trace points that have triggered
in the order they triggered.
With the parameter @option{clear}, erases all current trace history records.
history records.
@end deffn
-@deffn Command {trace point} [@option{clear}|identifier]
+@deffn {Command} {trace point} [@option{clear}|identifier]
With no parameter, displays all trace point identifiers and how many times
they have been triggered.
With the parameter @option{clear}, erases all current trace point counters.
In a debug session that doesn't use JTAG for its transport protocol,
these commands are not available.
-@deffn Command {drscan} tap [numbits value]+ [@option{-endstate} tap_state]
+@deffn {Command} {drscan} tap [numbits value]+ [@option{-endstate} tap_state]
Loads the data register of @var{tap} with a series of bit fields
that specify the entire register.
Each field is @var{numbits} bits long with
@end quotation
@end deffn
-@deffn Command {flush_count}
+@deffn {Command} {flush_count}
Returns the number of times the JTAG queue has been flushed.
This may be used for performance tuning.
instead of batching them into larger operations.
@end deffn
-@deffn Command {irscan} [tap instruction]+ [@option{-endstate} tap_state]
+@deffn {Command} {irscan} [tap instruction]+ [@option{-endstate} tap_state]
For each @var{tap} listed, loads the instruction register
with its associated numeric @var{instruction}.
(The number of bits in that instruction may be displayed
@end quotation
@end deffn
-@deffn Command {jtag_reset} trst srst
-Set values of reset signals.
-The @var{trst} and @var{srst} parameter values may be
-@option{0}, indicating that reset is inactive (pulled or driven high),
-or @option{1}, indicating it is active (pulled or driven low).
-The @command{reset_config} command should already have been used
-to configure how the board and JTAG adapter treat these two
-signals, and to say if either signal is even present.
-@xref{Reset Configuration}.
-
-Note that TRST is specially handled.
-It actually signifies JTAG's @sc{reset} state.
-So if the board doesn't support the optional TRST signal,
-or it doesn't support it along with the specified SRST value,
-JTAG reset is triggered with TMS and TCK signals
-instead of the TRST signal.
-And no matter how that JTAG reset is triggered, once
-the scan chain enters @sc{reset} with TRST inactive,
-TAP @code{post-reset} events are delivered to all TAPs
-with handlers for that event.
-@end deffn
-
-@deffn Command {pathmove} start_state [next_state ...]
+@deffn {Command} {pathmove} start_state [next_state ...]
Start by moving to @var{start_state}, which
must be one of the @emph{stable} states.
Unless it is the only state given, this will often be the
The final state must also be stable.
@end deffn
-@deffn Command {runtest} @var{num_cycles}
+@deffn {Command} {runtest} @var{num_cycles}
Move to the @sc{run/idle} state, and execute at least
@var{num_cycles} of the JTAG clock (TCK).
Instructions often need some time
@c tms_sequence (short|long)
@c ... temporary, debug-only, other than USBprog bug workaround...
-@deffn Command {verify_ircapture} (@option{enable}|@option{disable})
+@deffn {Command} {verify_ircapture} (@option{enable}|@option{disable})
Verify values captured during @sc{ircapture} and returned
during IR scans. Default is enabled, but this can be
overridden by @command{verify_jtag}.
This flag is ignored when validating JTAG chain configuration.
@end deffn
-@deffn Command {verify_jtag} (@option{enable}|@option{disable})
+@deffn {Command} {verify_jtag} (@option{enable}|@option{disable})
Enables verification of DR and IR scans, to help detect
programming errors. For IR scans, @command{verify_ircapture}
must also be enabled.
In a debug session using JTAG for its transport protocol,
OpenOCD supports running such test files.
-@deffn Command {svf} @file{filename} [@option{-tap @var{tapname}}] [@option{[-]quiet}] @
- [@option{[-]nil}] [@option{[-]progress}] [@option{[-]ignore_error}]
+@deffn {Command} {svf} @file{filename} [@option{-tap @var{tapname}}] [@option{-quiet}] @
+ [@option{-nil}] [@option{-progress}] [@option{-ignore_error}] @
+ [@option{-noreset}] [@option{-addcycles @var{cyclecount}}]
This issues a JTAG reset (Test-Logic-Reset) and then
runs the SVF script from @file{filename}.
specified by the SVF file with HIR, TIR, HDR and TDR commands;
instead, calculate them automatically according to the current JTAG
chain configuration, targeting @var{tapname};
-@item @option{[-]quiet} do not log every command before execution;
-@item @option{[-]nil} ``dry run'', i.e., do not perform any operations
+@item @option{-quiet} do not log every command before execution;
+@item @option{-nil} ``dry run'', i.e., do not perform any operations
on the real interface;
-@item @option{[-]progress} enable progress indication;
-@item @option{[-]ignore_error} continue execution despite TDO check
+@item @option{-progress} enable progress indication;
+@item @option{-ignore_error} continue execution despite TDO check
errors.
+@item @option{-noreset} omit JTAG reset (Test-Logic-Reset) before executing
+content of the SVF file;
+@item @option{-addcycles @var{cyclecount}} inject @var{cyclecount} number of
+additional TCLK cycles after each SDR scan instruction;
@end itemize
@end deffn
Not all XSVF commands are supported.
@end quotation
-@deffn Command {xsvf} (tapname|@option{plain}) filename [@option{virt2}] [@option{quiet}]
+@deffn {Command} {xsvf} (tapname|@option{plain}) filename [@option{virt2}] [@option{quiet}]
This issues a JTAG reset (Test-Logic-Reset) and then
runs the XSVF script from @file{filename}.
When a @var{tapname} is specified, the commands are directed at
probably will not be usable with other XSVF tools.
+@section IPDBG: JTAG-Host server
+@cindex IPDBG JTAG-Host server
+@cindex IPDBG
+
+IPDBG is a set of tools to debug IP-Cores. It comprises, among others, a logic analyzer and an arbitrary
+waveform generator. These are synthesize-able hardware descriptions of
+logic circuits in addition to software for control, visualization and further analysis.
+In a session using JTAG for its transport protocol, OpenOCD supports the function
+of a JTAG-Host. The JTAG-Host is needed to connect the circuit over JTAG to the
+control-software. The JTAG-Hub is the circuit which transfers the data from JTAG to the
+different tools connected to the Hub. Hub implementations for most major FPGA vendors/families
+are provided. For more details see @url{http://ipdbg.org}.
+
+@deffn {Command} {ipdbg create-hub} @var{hub_name} @option{-tap @var{tapname}} @option{-ir @var{ir_value} [@var{dr_length}]} [@option{-vir [@var{vir_value} [@var{length} [@var{instr_code}]]]}]
+@deffnx {Command} {ipdbg create-hub} @var{hub_name} @option{-pld @var{pld_name} [@var{user}]} [@option{-vir [@var{vir_value} [@var{length} [@var{instr_code}]]]}]
+Creates a IPDBG JTAG Hub. The created hub is later used to start, stop and configure IPDBG JTAG Host servers.
+The first argument @var{hub_name} is the name of the created hub. It can be used later as a reference.
+
+The pld drivers are able to provide the tap and ir_value for the IPDBG JTAG-Host server. This will be used with the second variant with option @option{-pld}.
+
+Command options:
+@itemize @bullet
+@item @var{hub_name} the name of the IPDBG hub.
+This name is also used to create the object's command, referred to here
+as @command{$hub_name}, and in other places where the Hub needs to be identified.
+
+@item @option{-tap @var{tapname}} targeting the TAP @var{tapname}.
+
+@item @option{-ir @var{ir_value}} states that the JTAG hub is
+reachable with dr-scans while the JTAG instruction register has the value @var{ir_value}. Also known as @verb{|USERx|} instructions.
+The optional @var{dr_length} is the length of the dr.
+Current JTAG-Hub implementation only supports dr_length=13, which is also the default value.
+
+@item @option{-vir [@var{vir_value} [@var{length} [@var{instr_code}]]]} To support more Hubs than USER registers in a single FPGA it is possible to
+use a mechanism known as virtual-ir where the user data-register is reachable if there is a specific value in a second dr.
+This second dr is called vir (virtual ir). With this parameter given, the IPDBG satisfies this condition prior an
+access to the IPDBG-Hub. The value shifted into the vir is given by the first parameter @var{vir_value} (default: 0x11). The second
+parameter @var{length} is the length of the vir data register (default: 5). With the @var{instr_code} (default: 0x00e) parameter the ir value to
+shift data through vir can be configured.
+
+@item @option{-pld @var{pld_name} [@var{user}]} The defined driver for the pld @var{pld_name} is used to get the tap and user instruction.
+The pld devices names can be shown by the command @command{pld devices}. With [@var{user}] one can select a different @verb{|USERx|}-Instruction.
+If the IPDBG JTAG-Hub is used without modification the default value of 1 which selects the first @verb{|USERx|} instruction is adequate.
+The @verb{|USERx|} instructions are vendor specific and don't change between families of the same vendor.
+So if there's a pld driver for your vendor it should work with your FPGA even when the driver is not compatible with your device for the remaining features.
+If your device/vendor is not supported you have to use the first variant.
+
+@end itemize
+
+@end deffn
+
+@deffn {Command} {$hub_name ipdbg start} @option{-tool @var{number}} @option{-port @var{number}}
+Starts a IPDBG JTAG-Host server. The remaining arguments can be specified in any order.
+
+Command options:
+@itemize @bullet
+@item @option{-port @var{number}} tcp port number where the JTAG-Host will listen. The default is 4242 which is used when the option is not given.
+@item @option{-tool @var{number}} number of the tool/feature. These corresponds to the ports "data_(up/down)_(0..6)" at the JtagHub. The default is 1 which is used when the option is not given.
+@end itemize
+@end deffn
+
+@deffn {Command} {$hub_name ipdbg stop} @option{-tool @var{number}}
+Stops a IPDBG JTAG-Host server.
+Command options:
+@itemize @bullet
+@item @option{-tool @var{number}} number of the tool/feature. These corresponds to the ports "data_(up/down)_(0..6)" at the JtagHub. The default is 1 which is used when the option is not given.
+@end itemize
+@end deffn
+
+Examples:
+@example
+ipdbg create-hub xc6s.ipdbghub -tap xc6s.tap -hub 0x02
+xc6s.ipdbghub ipdbg start -port 4242 -tool 4
+@end example
+Creates a IPDBG Hub and starts a server listening on tcp-port 4242 which connects to tool 4.
+The connection is through the TAP of a Xilinx Spartan 6 on USER1 instruction (tested with a papillion pro board).
+
+@example
+ipdbg create-hub max10m50.ipdbghub -tap max10m50.tap -hub 0x00C -vir
+max10m50.ipdbghub ipdbg start -tool 1 -port 60000
+@end example
+Starts a server listening on tcp-port 60000 which connects to tool 1 (data_up_1/data_down_1).
+The connection is through the TAP of a Intel MAX10 virtual jtag component (sld_instance_index is 0; sld_ir_width is smaller than 5).
+
+@example
+ipdbg create-hub xc7.ipdbghub -pld xc7.pld
+xc7.ipdbghub ipdbg start -port 5555 -tool 0
+@end example
+Starts a server listening on tcp-port 5555 which connects to tool 0 (data_up_0/data_down_0).
+The TAP and ir value used to reach the JTAG Hub is given by the pld driver.
+
+@deffn {Command} {$hub_name queuing} @option{-size @var{size}}
+Configure the queuing between IPDBG JTAG-Host and Hub.
+The maximum possible queue size is 1024 which is also the default.
+
+@itemize @bullet
+@item @option{-size @var{size}} max number of transfers in the queue.
+@end itemize
+@end deffn
+
+@example
+bitbang.ibdbghub queuing -size 32
+@end example
+Send a maximum of 32 transfers to the queue before executing them.
+
+
@node Utility Commands
@chapter Utility Commands
@cindex Utility Commands
to get access to the following facilities:
-@deffn Command {memTestDataBus} address
+@deffn {Command} {memTestDataBus} address
Test the data bus wiring in a memory region by performing a walking
1's test at a fixed address within that region.
@end deffn
-@deffn Command {memTestAddressBus} baseaddress size
+@deffn {Command} {memTestAddressBus} baseaddress size
Perform a walking 1's test on the relevant bits of the address and
check for aliasing. This test will find single-bit address failures
such as stuck-high, stuck-low, and shorted pins.
@end deffn
-@deffn Command {memTestDevice} baseaddress size
+@deffn {Command} {memTestDevice} baseaddress size
Test the integrity of a physical memory device by performing an
increment/decrement test over the entire region. In the process every
storage bit in the device is tested as zero and as one.
@end deffn
-@deffn Command {runAllMemTests} baseaddress size
+@deffn {Command} {runAllMemTests} baseaddress size
Run all of the above tests over a specified memory region.
@end deffn
openocd -f tools/firmware-recovery.tcl -c firmware_help
@end example
-@node TFTP
-@chapter TFTP
-@cindex TFTP
-If OpenOCD runs on an embedded host (as ZY1000 does), then TFTP can
-be used to access files on PCs (either the developer's PC or some other PC).
-
-The way this works on the ZY1000 is to prefix a filename by
-"/tftp/ip/" and append the TFTP path on the TFTP
-server (tftpd). For example,
-
-@example
-load_image /tftp/10.0.0.96/c:\temp\abc.elf
-@end example
-
-will load c:\temp\abc.elf from the developer pc (10.0.0.96) into memory as
-if the file was hosted on the embedded host.
-
-In order to achieve decent performance, you must choose a TFTP server
-that supports a packet size bigger than the default packet size (512 bytes). There
-are numerous TFTP servers out there (free and commercial) and you will have to do
-a bit of googling to find something that fits your requirements.
-
@node GDB and OpenOCD
@chapter GDB and OpenOCD
@cindex GDB
@item
A socket (TCP/IP) connection is typically started as follows:
@example
-target remote localhost:3333
+target extended-remote localhost:3333
@end example
This would cause GDB to connect to the gdbserver on the local pc using port 3333.
-It is also possible to use the GDB extended remote protocol as follows:
+The extended remote protocol is a super-set of the remote protocol and should
+be the preferred choice. More details are available in GDB documentation
+@url{https://sourceware.org/gdb/onlinedocs/gdb/Connecting.html}
+
+To speed-up typing, any GDB command can be abbreviated, including the extended
+remote command above that becomes:
@example
-target extended-remote localhost:3333
+tar ext :3333
+@end example
+
+@b{Note:} If any backward compatibility issue requires using the old remote
+protocol in place of the extended remote one, the former protocol is still
+available through the command:
+@example
+target remote localhost:3333
@end example
+
@item
A pipe connection is typically started as follows:
@example
-target remote | openocd -c "gdb_port pipe; log_output openocd.log"
+target extended-remote | \
+ openocd -c "gdb_port pipe; log_output openocd.log"
@end example
This would cause GDB to run OpenOCD and communicate using pipes (stdin/stdout).
Using this method has the advantage of GDB starting/stopping OpenOCD for the debug
@example
$ arm-none-eabi-gdb example.elf
-(gdb) target remote localhost:3333
+(gdb) target extended-remote localhost:3333
Remote debugging using localhost:3333
...
(gdb) monitor reset halt
If you switched gdb_memory_map off, you may want to setup GDB memory map
manually or issue @command{set mem inaccessible-by-default off}
-Now you can issue GDB command @command{target remote ...} and inspect memory
+Now you can issue GDB command @command{target extended-remote ...} and inspect memory
of a running target. Do not use GDB commands @command{continue},
@command{step} or @command{next} as they synchronize GDB with your target
and GDB would require stopping the target to get the prompt back.
Do not use this mode under an IDE like Eclipse as it caches values of
-previously shown varibles.
+previously shown variables.
+
+It's also possible to connect more than one GDB to the same target by the
+target's configuration option @code{-gdb-max-connections}. This allows, for
+example, one GDB to run a script that continuously polls a set of variables
+while other GDB can be used interactively. Be extremely careful in this case,
+because the two GDB can easily get out-of-sync.
@section RTOS Support
@cindex RTOS Support
@item @option{mqx}
@item @option{uCOS-III}
@item @option{nuttx}
+@item @option{RIOT}
@item @option{hwthread} (This is not an actual RTOS. @xref{usingopenocdsmpwithgdb,,Using OpenOCD SMP with GDB}.)
+@item @option{Zephyr}
+@item @option{rtkernel}
@end itemize
+At any time, it's possible to drop the selected RTOS using:
+@example
+$_TARGETNAME configure -rtos none
+@end example
+
Before an RTOS can be detected, it must export certain symbols; otherwise, it cannot
be used by OpenOCD. Below is a list of the required symbols for each supported RTOS.
@item ThreadX symbols
_tx_thread_current_ptr, _tx_thread_created_ptr, _tx_thread_created_count.
@item FreeRTOS symbols
-@c The following is taken from recent texinfo to provide compatibility
-@c with ancient versions that do not support @raggedright
-@tex
-\begingroup
-\rightskip0pt plus2em \spaceskip.3333em \xspaceskip.5em\relax
+@raggedright
pxCurrentTCB, pxReadyTasksLists, xDelayedTaskList1, xDelayedTaskList2,
pxDelayedTaskList, pxOverflowDelayedTaskList, xPendingReadyList,
-uxCurrentNumberOfTasks, uxTopUsedPriority.
-\par
-\endgroup
-@end tex
+uxCurrentNumberOfTasks, uxTopUsedPriority, xSchedulerRunning.
+@end raggedright
@item linux symbols
init_task.
@item ChibiOS symbols
@item mqx symbols
_mqx_kernel_data, MQX_init_struct.
@item uC/OS-III symbols
-OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty
+OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty.
@item nuttx symbols
-g_readytorun, g_tasklisttable
+g_readytorun, g_tasklisttable.
+@item RIOT symbols
+@raggedright
+sched_threads, sched_num_threads, sched_active_pid, max_threads,
+_tcb_name_offset.
+@end raggedright
+@item Zephyr symbols
+_kernel, _kernel_openocd_offsets, _kernel_openocd_size_t_size
+@item rtkernel symbols
+Multiple struct offsets.
@end table
For most RTOS supported the above symbols will be exported by default. However for
-some, eg. FreeRTOS and uC/OS-III, extra steps must be taken.
+some, eg. FreeRTOS, uC/OS-III and Zephyr, extra steps must be taken.
+
+Zephyr must be compiled with the DEBUG_THREAD_INFO option. This will generate some symbols
+with information needed in order to build the list of threads.
-These RTOSes may require additional OpenOCD-specific file to be linked
+FreeRTOS and uC/OS-III RTOSes may require additional OpenOCD-specific file to be linked
along with the project:
@table @code
while other cores are free-running or remain halted, depending on the
scheduler-locking mode configured in GDB.
-@section Legacy SMP core switching support
-@quotation Note
-This method is deprecated in favor of the @emph{hwthread} pseudo RTOS.
-@end quotation
-
-For SMP support following GDB serial protocol packet have been defined :
-@itemize @bullet
-@item j - smp status request
-@item J - smp set request
-@end itemize
-
-OpenOCD implements :
-@itemize @bullet
-@item @option{jc} packet for reading core id displayed by
-GDB connection. Reply is @option{XXXXXXXX} (8 hex digits giving core id) or
- @option{E01} for target not smp.
-@item @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue
-(core id -1 is reserved for returning to normal resume mode). Reply @option{E01}
-for target not smp or @option{OK} on success.
-@end itemize
-
-Handling of this packet within GDB can be done :
-@itemize @bullet
-@item by the creation of an internal variable (i.e @option{_core}) by mean
-of function allocate_computed_value allowing following GDB command.
-@example
-set $_core 1
-#Jc01 packet is sent
-print $_core
-#jc packet is sent and result is affected in $
-@end example
-
-@item by the usage of GDB maintenance command as described in following example (2 cpus in SMP with
-core id 0 and 1 @pxref{definecputargetsworkinginsmp,,Define CPU targets working in SMP}).
-
-@example
-# toggle0 : force display of coreid 0
-define toggle0
-maint packet Jc0
-continue
-main packet Jc-1
-end
-# toggle1 : force display of coreid 1
-define toggle1
-maint packet Jc1
-continue
-main packet Jc-1
-end
-@end example
-@end itemize
-
@node Tcl Scripting API
@chapter Tcl Scripting API
@cindex Tcl Scripting API
@section Internal low-level Commands
-By "low-level," we mean commands that a human would typically not
+By "low-level", we mean commands that a human would typically not
invoke directly.
-Some low-level commands need to be prefixed with "ocd_"; e.g.
-@command{ocd_flash_banks}
-is the low-level API upon which @command{flash banks} is implemented.
-
-@itemize @bullet
-@item @b{mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
-
-Read memory and return as a Tcl array for script processing
-@item @b{array2mem} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
-
-Convert a Tcl array to memory locations and write the values
-@item @b{ocd_flash_banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...]
+@itemize
+@item @b{flash banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...]
Return information about the flash banks
@item @b{capture} <@var{command}>
Run <@var{command}> and return full log output that was produced during
-its execution. Example:
+its execution together with the command output. Example:
@example
> capture "reset init"
@file{startup.tcl} "unknown" proc will translate this into a Tcl proc
called "flash_banks".
-@section OpenOCD specific Global Variables
-
-Real Tcl has ::tcl_platform(), and platform::identify, and many other
-variables. JimTCL, as implemented in OpenOCD creates $ocd_HOSTOS which
-holds one of the following values:
-
-@itemize @bullet
-@item @b{cygwin} Running under Cygwin
-@item @b{darwin} Darwin (Mac-OS) is the underlying operating system.
-@item @b{freebsd} Running under FreeBSD
-@item @b{openbsd} Running under OpenBSD
-@item @b{netbsd} Running under NetBSD
-@item @b{linux} Linux is the underlying operating system
-@item @b{mingw32} Running under MingW32
-@item @b{winxx} Built using Microsoft Visual Studio
-@item @b{ecos} Running under eCos
-@item @b{other} Unknown, none of the above.
-@end itemize
-
-Note: 'winxx' was chosen because today (March-2009) no distinction is made between Win32 and Win64.
-
-@quotation Note
-We should add support for a variable like Tcl variable
-@code{tcl_platform(platform)}, it should be called
-@code{jim_platform} (because it
-is jim, not real tcl).
-@end quotation
-
@section Tcl RPC server
@cindex RPC
value (it will be terminated with @code{0x1a} as well). This can be
repeated as many times as desired without reopening the connection.
-Remember that most of the OpenOCD commands need to be prefixed with
-@code{ocd_} to get the results back. Sometimes you might also need the
+It is not needed anymore to prefix the OpenOCD commands with
+@code{ocd_} to get the results back. But sometimes you might need the
@command{capture} command.
See @file{contrib/rpc_examples/} for specific client implementations.
type target_reset mode [reset-mode]
@end verbatim
-@deffn {Command} tcl_notifications [on/off]
+@deffn {Command} {tcl_notifications} [on/off]
Toggle output of target notifications to the current Tcl RPC server.
Only available from the Tcl RPC server.
Defaults to off.
type target_trace data [trace-data-hex-encoded]
@end verbatim
-@deffn {Command} tcl_trace [on/off]
+@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.
@example
# Example: 1.234MHz
-adapter_khz 1234
+adapter speed 1234
@end example
remember to pop them off when the ISR is done.
@b{Also note:} If you have a multi-threaded operating system, they
-often do not @b{in the intrest of saving memory} waste these few
+often do not @b{in the interest of saving memory} waste these few
bytes. Painful...
"Warning: arm7_9_common.c:679 arm7_9_assert_reset(): srst resets test logic, too".
This warning doesn't indicate any serious problem, as long as you don't want to
-debug your core right out of reset. Your .cfg file specified @option{jtag_reset
+debug your core right out of reset. Your .cfg file specified @option{reset_config
trst_and_srst srst_pulls_trst} to tell OpenOCD that either your board,
your debugger or your target uC (e.g. LPC2000) can't assert the two reset signals
independently. With this setup, it's not possible to halt the core right out of
When the command ``proc'' is parsed (which creates a procedure
function) it gets 3 parameters on the command line. @b{1} the name of
the proc (function), @b{2} the list of parameters, and @b{3} the body
-of the function. Not the choice of words: LIST and BODY. The PROC
+of the function. Note the choice of words: LIST and BODY. The PROC
command stores these items in a table somewhere so it can be found by
``LookupCommand()''
@example
set x 6
set y 7
- puts [format "The answer: %d" [expr $x * $y]]
+ puts [format "The answer: %d" [expr @{$x * $y@}]]
@end example
@enumerate
@item The SET command creates 2 variables, X and Y.
@b{Dynamic variable creation}
@example
# Dynamically create a bunch of variables.
-for @{ set x 0 @} @{ $x < 32 @} @{ set x [expr $x + 1]@} @{
+for @{ set x 0 @} @{ $x < 32 @} @{ set x [expr @{$x + 1@}]@} @{
# Create var name
set vn [format "BIT%d" $x]
# Make it a global
global $vn
# Set it.
- set $vn [expr (1 << $x)]
+ set $vn [expr @{1 << $x@}]
@}
@end example
@b{Dynamic proc/command creation}
@}
@end example
+@node License
+@appendix The GNU Free Documentation License.
@include fdl.texi
@node OpenOCD Concept Index
Code Review / openocd.git / blobdiff