@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.
@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.
@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 current version
+supports only JTAG as a transport, but other virtual transports, like DAP are planned.
+
@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
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
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 {Overridable Procedure} jtag_init
+@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}
This is invoked at server startup to verify that it can talk
to the scan chain (list of TAPs) which has been configured.
use the command line @option{-pipe} option.
@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
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
target.
@end deffn
-@deffn Command {adapter list}
+@deffn {Command} {adapter list}
List the debug adapter drivers that have been built into
the running copy of OpenOCD.
@end deffn
-@deffn Command {adapter 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
-@deffn Command {adapter name}
+@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>]...]
+@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
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:
+aice (aice_usb), arm-jtag-ew, cmsis_dap, 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
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 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.
-@end deffn
-
@deffn {Config Command} {cmsis_dap_backend} [@option{auto}|@option{usb_bulk}|@option{hid}]
Specifies how to communicate with the adapter:
@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 command @ref{adapter_usb_location,,adapter usb location} 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:
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
For example, to connect remotely via TCP to the host foobar you might have
@example
adapter driver remote_bitbang
-remote_bitbang_port 3335
-remote_bitbang_host foobar
+remote_bitbang port 3335
+remote_bitbang host foobar
@end example
To connect to another process running locally via UNIX sockets with socket
@example
adapter driver remote_bitbang
-remote_bitbang_port 0
-remote_bitbang_host mysocket
+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 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
-@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.
-
As a configuration command, it can be used only before 'init'.
@end deffn
@end deffn
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 speed} configuration.
To measure the toggling time with a logic analyzer or a digital storage
oscilloscope, follow the procedure below:
@example
-> parport_toggling_time 1000
+> parport toggling_time 1000
> adapter speed 500
@end example
This sets the maximum JTAG clock speed of the hardware, but
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 speed}
command given in OpenOCD scripts and event handlers.
@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
@example
adapter driver parport
-parport_port 0x278
-parport_cable wiggler
+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}
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}|@option{nulink})
Specifies the adapter layout to use.
@end deffn
@emph{Note:} ST-Link TCP server does not support the SWIM transport.
@end deffn
-@deffn {Config Command} {st-link serial} serial
-Specifies the serial number of the adapter.
-@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}
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 serial} serial_string
-Specifies the serial number of which XDS110 probe to use. Otherwise, the first
-XDS110 found will be used.
-@end deffn
-
@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
For more information see Xilinx PG245 (Section on From_PCIE_to_JTAG mode).
-@deffn {Config Command} {xlnx_pcie_xvc_config} device
+@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
peripherals' kernel drivers. The driver restores the previous
configuration on exit.
+GPIO numbers >= 32 can't be used for performance reasons.
+
See @file{interface/raspberrypi-native.cfg} for a sample config and
pinout.
+@deffn {Config Command} {bcm2835gpio jtag_nums} @var{tck} @var{tms} @var{tdi} @var{tdo}
+Set JTAG transport GPIO numbers for TCK, TMS, TDI, and TDO (in that order).
+Must be specified to enable JTAG transport. These pins can also be specified
+individually.
+@end deffn
+
+@deffn {Config Command} {bcm2835gpio tck_num} @var{tck}
+Set TCK GPIO number. Must be specified to enable JTAG transport. Can also be
+specified using the configuration command @command{bcm2835gpio jtag_nums}.
+@end deffn
+
+@deffn {Config Command} {bcm2835gpio tms_num} @var{tms}
+Set TMS GPIO number. Must be specified to enable JTAG transport. Can also be
+specified using the configuration command @command{bcm2835gpio jtag_nums}.
+@end deffn
+
+@deffn {Config Command} {bcm2835gpio tdo_num} @var{tdo}
+Set TDO GPIO number. Must be specified to enable JTAG transport. Can also be
+specified using the configuration command @command{bcm2835gpio jtag_nums}.
+@end deffn
+
+@deffn {Config Command} {bcm2835gpio tdi_num} @var{tdi}
+Set TDI GPIO number. Must be specified to enable JTAG transport. Can also be
+specified using the configuration command @command{bcm2835gpio jtag_nums}.
+@end deffn
+
+@deffn {Config Command} {bcm2835gpio swd_nums} @var{swclk} @var{swdio}
+Set SWD transport GPIO numbers for SWCLK and SWDIO (in that order). Must be
+specified to enable SWD transport. These pins can also be specified individually.
+@end deffn
+
+@deffn {Config Command} {bcm2835gpio swclk_num} @var{swclk}
+Set SWCLK GPIO number. Must be specified to enable SWD transport. Can also be
+specified using the configuration command @command{bcm2835gpio swd_nums}.
+@end deffn
+
+@deffn {Config Command} {bcm2835gpio swdio_num} @var{swdio}
+Set SWDIO GPIO number. Must be specified to enable SWD transport. Can also be
+specified using the configuration command @command{bcm2835gpio swd_nums}.
+@end deffn
+
+@deffn {Config Command} {bcm2835gpio swdio_dir_num} @var{swdio} @var{dir}
+Set SWDIO direction control pin GPIO number. If specified, this pin can be used
+to control the direction of an external buffer on the SWDIO pin (set=output
+mode, clear=input mode). If not specified, this feature is disabled.
+@end deffn
+
+@deffn {Config Command} {bcm2835gpio srst_num} @var{srst}
+Set SRST GPIO number. Must be specified to enable SRST.
+@end deffn
+
+@deffn {Config Command} {bcm2835gpio trst_num} @var{trst}
+Set TRST GPIO number. Must be specified to enable TRST.
+@end deffn
+
+@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_base} @var{base}
+Set the peripheral base register address to access GPIOs. 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
@deffn {Interface Driver} {imx_gpio}
@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. GPIOs numbered 0 to 31 are mapped to GPIO port
+0, GPIO numbers 32 to 63 are mapped to GPIO port 1 and so on.
+
+See @file{interface/beaglebone-swd-native.cfg} for a sample configuration file.
+
+@deffn {Config Command} {am335xgpio jtag_nums} @var{tck} @var{tms} @var{tdi} @var{tdo}
+Set JTAG transport GPIO numbers for TCK, TMS, TDI, and TDO (in that order).
+Must be specified to enable JTAG transport. These pins can also be specified
+individually.
+@end deffn
+
+@deffn {Config Command} {am335xgpio tck_num} @var{tck}
+Set TCK GPIO number. Must be specified to enable JTAG transport. Can also be
+specified using the configuration command @command{am335xgpio jtag_nums}.
+@end deffn
+
+@deffn {Config Command} {am335xgpio tms_num} @var{tms}
+Set TMS GPIO number. Must be specified to enable JTAG transport. Can also be
+specified using the configuration command @command{am335xgpio jtag_nums}.
+@end deffn
+
+@deffn {Config Command} {am335xgpio tdo_num} @var{tdo}
+Set TDO GPIO number. Must be specified to enable JTAG transport. Can also be
+specified using the configuration command @command{am335xgpio jtag_nums}.
+@end deffn
+
+@deffn {Config Command} {am335xgpio tdi_num} @var{tdi}
+Set TDI GPIO number. Must be specified to enable JTAG transport. Can also be
+specified using the configuration command @command{am335xgpio jtag_nums}.
+@end deffn
+
+@deffn {Config Command} {am335xgpio swd_nums} @var{swclk} @var{swdio}
+Set SWD transport GPIO numbers for SWCLK and SWDIO (in that order). Must be
+specified to enable SWD transport. These pins can also be specified individually.
+@end deffn
+
+@deffn {Config Command} {am335xgpio swclk_num} @var{swclk}
+Set SWCLK GPIO number. Must be specified to enable SWD transport. Can also be
+specified using the configuration command @command{am335xgpio swd_nums}.
+@end deffn
+
+@deffn {Config Command} {am335xgpio swdio_num} @var{swdio}
+Set SWDIO GPIO number. Must be specified to enable SWD transport. Can also be
+specified using the configuration command @command{am335xgpio swd_nums}.
+@end deffn
+
+@deffn {Config Command} {am335xgpio swdio_dir_num} @var{swdio_dir}
+Set SWDIO direction control pin GPIO number. If specified, this pin can be used
+to control the direction of an external buffer on the SWDIO pin. The direction
+control state can be set with the command @command{am335xgpio
+swdio_dir_output_state}. If not specified this feature is disabled.
+@end deffn
+
+@deffn {Config Command} {am335xgpio swdio_dir_output_state} @var{output_state}
+Set the state required for an external SWDIO buffer to be an output. Valid
+values are @option{on} (default) and @option{off}.
+@end deffn
+
+@deffn {Config Command} {am335xgpio srst_num} @var{srst}
+Set SRST GPIO number. Must be specified to enable SRST.
+@end deffn
+
+@deffn {Config Command} {am335xgpio trst_num} @var{trst}
+Set TRST GPIO number. Must be specified to enable TRST.
+@end deffn
+
+@deffn {Config Command} {am335xgpio led_num} @var{led}
+Set activity LED GPIO number. If not specified an activity LED is not enabled.
+@end deffn
+
+@deffn {Config Command} {am335xgpio led_on_state} @var{on_state}
+Set required logic level for the LED to be on. Valid values are @option{on}
+(default) and @option{off}.
+@end deffn
+
+@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
+
+@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 and SWD transport through bitbanging.
+The driver emulates either JTAG or SWD transport through bitbanging.
See @file{interface/dln-2-gpiod.cfg} for a sample config.
+
+@deffn {Config Command} {linuxgpiod gpiochip} @var{chip}
+Set the GPIO chip number for all GPIOs used by linuxgpiod. If GPIOs use
+different GPIO chips then the individual GPIO configuration commands (i.e., not
+@command{linuxgpiod jtag_nums} or @command{linuxgpiod swd_nums}) can be used to
+set chip numbers independently for each GPIO.
+@end deffn
+
+@deffn {Config Command} {linuxgpiod jtag_nums} @var{tck} @var{tms} @var{tdi} @var{tdo}
+Set JTAG transport GPIO numbers for TCK, TMS, TDI, and TDO (in that order). Must
+be specified to enable JTAG transport. These pins can also be specified
+individually.
+@end deffn
+
+@deffn {Config Command} {linuxgpiod tck_num} [@var{chip}] @var{tck}
+Set TCK GPIO number, and optionally TCK chip number. Must be specified to enable
+JTAG transport. Can also be specified using the configuration command
+@command{linuxgpiod jtag_nums}.
+@end deffn
+
+@deffn {Config Command} {linuxgpiod tms_num} [@var{chip}] @var{tms}
+Set TMS GPIO number, and optionally TMS chip number. Must be specified to enable
+JTAG transport. Can also be specified using the configuration command
+@command{linuxgpiod jtag_nums}.
+@end deffn
+
+@deffn {Config Command} {linuxgpiod tdo_num} [@var{chip}] @var{tdo}
+Set TDO GPIO number, and optionally TDO chip number. Must be specified to enable
+JTAG transport. Can also be specified using the configuration command
+@command{linuxgpiod jtag_nums}.
+@end deffn
+
+@deffn {Config Command} {linuxgpiod tdi_num} [@var{chip}] @var{tdi}
+Set TDI GPIO number, and optionally TDI chip number. Must be specified to enable
+JTAG transport. Can also be specified using the configuration command
+@command{linuxgpiod jtag_nums}.
+@end deffn
+
+@deffn {Config Command} {linuxgpiod trst_num} [@var{chip}] @var{trst}
+Set TRST GPIO number, and optionally TRST chip number. Must be specified to
+enable TRST.
+@end deffn
+
+@deffn {Config Command} {linuxgpiod swd_nums} @var{swclk} @var{swdio}
+Set SWD transport GPIO numbers for SWCLK and SWDIO (in that order). Must be
+specified to enable SWD transport. These pins can also be specified
+individually.
+@end deffn
+
+@deffn {Config Command} {linuxgpiod swclk_num} [@var{chip}] @var{swclk}
+Set SWCLK GPIO number, and optionally SWCLK chip number. Must be specified to
+enable SWD transport. Can also be specified using the configuration command
+@command{linuxgpiod swd_nums}.
+@end deffn
+
+@deffn {Config Command} {linuxgpiod swdio_num} [@var{chip}] @var{swdio}
+Set SWDIO GPIO number, and optionally SWDIO chip number. Must be specified to
+enable SWD transport. Can also be specified using the configuration command
+@command{linuxgpiod swd_nums}.
+@end deffn
+
+@deffn {Config Command} {linuxgpiod swdio_dir_num} [@var{chip}] @var{swdio_dir}
+Set SWDIO direction control GPIO number, and optionally SWDIO direction control
+chip number. If specified, this GPIO can be used to control the direction of an
+external buffer connected to the SWDIO GPIO (set=output mode, clear=input mode).
+@end deffn
+
+@deffn {Config Command} {linuxgpiod srst_num} [@var{chip}] @var{srst}
+Set SRST GPIO number, and optionally SRST chip number. Must be specified to
+enable SRST.
+@end deffn
+
+@deffn {Config Command} {linuxgpiod led_num} [@var{chip}] @var{led}
+Set activity LED GPIO number, and optionally activity LED chip number. If not
+specified an activity LED is not enabled.
+@end deffn
+
@end deffn
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
@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
+@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
+@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
+
+
@section Transport Configuration
@cindex Transport
As noted earlier, depending on the version of OpenOCD you use,
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
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
instead of @command{adapter speed}, but only for (ARM) cores and boards
which support adaptive clocking.
-@deffn {Command} adapter speed 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
@section Commands for Handling Resets
-@deffn {Command} adapter srst pulse_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 srst 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 ...
+@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.
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
(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.
@section Other TAP commands
-@deffn Command {jtag cget} dotted.name @option{-idcode}
+@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
+@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 limited and used mostly for event handling.
(It is not a direct analogue of the @code{cget}/@code{configure}
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
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:
@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{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.
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
+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{nds32_v2} -- this is an Andes NDS32 v2 core.
-@item @code{nds32_v3} -- this is an Andes NDS32 v3 core.
-@item @code{nds32_v3m} -- this is an Andes NDS32 v3m core.
+@item @code{nds32_v2} -- this is an Andes NDS32 v2 core (deprecated; would be removed in v0.13.0).
+@item @code{nds32_v3} -- this is an Andes NDS32 v3 core (deprecated; would be removed in v0.13.0).
+@item @code{nds32_v3m} -- this is an Andes NDS32 v3m core (deprecated; would be removed in v0.13.0).
@item @code{or1k} -- this is an OpenRISC 1000 core.
The current implementation supports three JTAG TAP cores:
@itemize @minus
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
@var{rtos_type} can be one of @option{auto}, @option{eCos},
@option{ThreadX}, @option{FreeRTOS}, @option{linux}, @option{ChibiOS},
@option{embKernel}, @option{mqx}, @option{uCOS-III}, @option{nuttx},
-@option{RIOT}
+@option{RIOT}, @option{Zephyr}
@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.
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.
-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.
+@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{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{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
+
+@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{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 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 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]
+@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}),
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 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]
+@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}.
@* 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
@end deffn
@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}.
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 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
+@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
@end deffn
@comment no current checks for errors if fill blocks touch multiple banks!
-@deffn Command {flash mdw} addr [count]
-@deffnx Command {flash mdh} addr [count]
-@deffnx Command {flash mdb} addr [count]
+@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}).
each block, and the specified length must stay within that bank.
@end deffn
-@deffn Command {flash write_bank} num filename [offset]
+@deffn {Command} {flash write_bank} num filename [offset]
Write the binary @file{filename} to flash bank @var{num},
starting at @var{offset} bytes from the beginning of the bank. 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]
+@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
@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 [preverify] [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
+@deffn {Flash Driver} {jtagspi}
@cindex Generic JTAG2SPI driver
@cindex SPI
@cindex jtagspi
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
flash bank $_FLASHNAME spi 0x0 0 0 0 \
$_TARGETNAME $_XILINX_USER1
@end example
+
+@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
+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} stmqspi
+@deffn {Flash Driver} {stmqspi}
@cindex STMicroelectronics QuadSPI/OctoSPI Interface
@cindex QuadSPI
@cindex OctoSPI
'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 decribed above. However,
+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.
@end example
There are three specific commands
-@deffn Command {stmqspi mass_erase} bank_id
+@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
+@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,
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 ...
+@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.,
@end deffn
-@deffn {Flash Driver} mrvlqspi
+@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
@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
@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 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
@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 reset-deassert-post.
@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 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.
@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, BlueNRG-2 and BlueNRG-LP Bluetooth low energy wireless system-on-chip. They include ARM Cortex-M0/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.
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} {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
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}
+@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).
Command shows or sets data flash or EEPROM backup size in kilobytes,
sets two EEPROM blocks sizes in bytes and enables/disables loading
@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.
flash bank $_FLASHNAME msp432 0 0 0 0 $_TARGETNAME
@end example
-@deffn Command {msp432 mass_erase} bank_id [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} bank_id [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.
+
+@example
+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
code.
@end deffn
-@deffn Command {nrf5 info}
+@deffn {Command} {nrf5 info}
Decodes and shows information from FICR and UICR registers.
@end deffn
@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,
@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.
@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} {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} {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
+@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.
+from STMicroelectronics and all members of the GD32F1x0, GD32F3x0 and GD32E23x microcontroller
+families from GigaDevice include internal flash and use ARM Cortex-M0/M3/M4/M23 cores.
+The driver also works with GD32VF103 powered by RISC-V core.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
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 automatically recognizes a number of these chips using
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
+@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.
@end example
@end deffn
-@deffn Command {stm32h7x option_write} num reg_offset value [reg_mask]
+@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,
@end deffn
@end deffn
-@deffn {Flash Driver} stm32lx
+@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
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 STM32 G0, G4, L4, L4+, L5, WB and WL
+@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
flash bank $_FLASHNAME stm32l4x 0x1FFF7000 0 0 0 $_TARGETNAME
@end example
-@deffn Command {stm32l4x otp} num (@option{enable}|@option{disable}|@option{show})
+@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
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.
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 wrp_info} num [device_bank]
+@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',
@end deffn
-@deffn Command {stm32l4x option_load} num
+@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.
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} swm050
+@deffn {Flash Driver} {swm050}
@cindex swm050
All members of the swm050 microcontroller family from Foshan Synwit Tech.
One swm050-specific command is defined:
-@deffn Command {swm050 mass_erase} bank_id
+@deffn {Command} {swm050 mass_erase} bank_id
Erases the entire flash bank.
@end deffn
@end deffn
-@deffn {Flash Driver} tms470
+@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.
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} [no_jstart]
Virtex-II is a family of FPGAs sold by Xilinx.
It supports the IEEE 1532 standard for In-System Configuration (ISC).
@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 | "default"]
+@deffn {Command} {log_output} [filename | "default"]
Redirect logging to @var{filename} or set it back to default output;
the default log output channel is 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
-@deffn Command {adapter assert} [signal [assert|deassert signal]]
-@deffnx Command {adapter deassert} [signal [assert|deassert signal]]
+@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
about what TAP is the current target, or about MMU configuration.
@end enumerate
-@deffn Command mdd [phys] addr [count]
-@deffnx 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}),
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 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]
+@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}.
@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}]
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}]
+@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.
The file format may optionally be specified
(@option{bin}, @option{ihex}, @option{elf}, or @option{s19}).
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}]
+@deffn {Command} {verify_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
Verify @var{filename} against target memory starting at @var{address}.
The file format may optionally be specified
(@option{bin}, @option{ihex}, or @option{elf})
This 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}]
+@deffn {Command} {verify_image_checksum} filename address [@option{bin}|@option{ihex}|@option{elf}]
Verify @var{filename} against target memory starting at @var{address}.
The file format may optionally be specified
(@option{bin}, @option{ihex}, or @option{elf})
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} @option{all} | address
+@deffn {Command} {rbp} @option{all} | address
Remove the breakpoint at @var{address} or all breakpoints.
@end deffn
-@deffn Command {rwp} address
+@deffn {Command} {rwp} address
Remove data watchpoint on @var{address}
@end deffn
-@deffn Command {wp} [address len [(@option{r}|@option{w}|@option{a}) [value [mask]]]]
+@deffn {Command} {wp} [address len [(@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
assigned to each channel to make them accessible to an unlimited number
of TCP/IP connections.
-@deffn Command {rtt setup} address size ID
+@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}
+@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}
+@deffn {Command} {rtt stop}
Stop RTT.
@end deffn
-@deffn Command {rtt polling_interval [interval]}
+@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}
+@deffn {Command} {rtt channels}
Display a list of all channels and their properties.
@end deffn
-@deffn Command {rtt channellist}
+@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
+@deffn {Command} {rtt server start} port channel
Start a TCP server on @var{port} for the channel @var{channel}.
@end deffn
-@deffn Command {rtt server stop} port
+@deffn {Command} {rtt server stop} port
Stop the TCP sever with port @var{port}.
@end deffn
@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''
limit the address range.
@end deffn
-@deffn Command {version}
+@deffn {Command} {version}
Displays a string identifying the version of this OpenOCD server.
@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
@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)
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{-baseaddr} 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 ack} @var{event}
+@deffn {Command} {$cti_name ack} @var{event}
Acknowledge a CTI @var{event}.
@end deffn
-@deffn Command {$cti_name channel} @var{channel_number} @var{operation}
+@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}
+@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
EmbeddedIce DBGRQ signal to force entry into debug mode,
instead of breakpoints.
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.
@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 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} [on|off]
+@deffn {Command} {cortex_a smp} [on|off]
Display/set the current 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
A convenient alias @command{swo} is available to help distinguish, in scripts,
the commands for SWO from the commands for TPIU.
-@deffn Command {swo} ...
+@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...
+@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.
@end itemize
@end deffn
-@deffn Command {tpiu names}
+@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}
+@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
+@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...
+@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.
@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,
-@var{ap_number} is the numeric index of the DAP AP the TPIU is connected to.
+@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.
@end itemize
@end deffn
-@deffn Command {$tpiu_name enable}
+@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
after the @command{init}.
@end deffn
-@deffn Command {$tpiu_name disable}
+@deffn {Command} {$tpiu_name disable}
Disable the TPIU or the SWO, terminating the receiving of the trace data.
@end deffn
@cindex ITM
@cindex ETM
-@deffn Command {itm port} @var{port} (@option{0}|@option{1}|@option{on}|@option{off})
+@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}|@option{steponly})
+@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
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 disassemble} address [count]
+@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]
+@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}]+
+@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
@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 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
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
-@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.
@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 set_command_timeout_sec} [seconds]
+@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]
+@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.
@end deffn
-@deffn Command {riscv set_prefer_sba} on|off
-When on, prefer to use System Bus Access to access memory. When off (default),
-prefer to use the Program Buffer to access memory.
+@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
+@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_enable_virt2phys} on|off
+@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 resume_order} normal|reversed
+@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
behavior. Reversed order is from highest hart index to lowest.
@end deffn
-@deffn Command {riscv set_ir} (@option{idcode}|@option{dtmcs}|@option{dmi}) [value]
+@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
+@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
+@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
+@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
+@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
configuration file, immediately following @command{init}:
@example
set challenge [riscv authdata_read]
-riscv authdata_write [expr $challenge + 1]
+riscv authdata_write [expr @{$challenge + 1@}]
@end example
-@deffn Command {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} address
+@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
@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.
+type, @xref{add-reg-type-struct}. command definition.
@end deffn
@deffn {Command} {arc set-reg-exists} reg-names...
OpenOCD supports debugging STM8 through the STMicroelectronics debug
protocol SWIM, @pxref{swimtransport,,SWIM}.
+@section Xtensa Architecture
+Xtensa processors are based on a modular, highly flexible 32-bit RISC architecture
+that can easily scale from a tiny, cache-less controller or task engine to a high-performance
+SIMD/VLIW DSP provided by Cadence.
+@url{https://www.cadence.com/en_US/home/tools/ip/tensilica-ip/tensilica-xtensa-controllers-and-extensible-processors.html}.
+
+OpenOCD supports generic Xtensa processors implementation which can be customized by
+simply providing vendor-specific core configuration which controls every configurable
+Xtensa architecture option, e.g. number of address registers, exceptions, reduced
+size instructions support, memory banks configuration etc. Also OpenOCD supports SMP
+configurations for Xtensa processors with any number of cores and allows to configure
+their debug signals interconnection (so-called "break/stall networks") which control how
+debug signals are distributed among cores. Xtensa "break networks" are compatible with
+ARM's Cross Trigger Interface (CTI). For debugging code on Xtensa chips OpenOCD
+uses JTAG protocol. Currently OpenOCD implements several Epsressif Xtensa-based chips of
+@uref{https://www.espressif.com/en/products/socs, ESP32 family}.
+
+@subsection General Xtensa Commands
+
+@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 maskisr} (on|off)
+Selects whether interrupts will be disabled during stepping over single instruction. The default configuration is (off).
+@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 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
+
+@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
+
@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 {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}] @
+@deffn {Command} {svf} @file{filename} [@option{-tap @var{tapname}}] [@option{[-]quiet}] @
[@option{[-]nil}] [@option{[-]progress}] [@option{[-]ignore_error}]
This issues a JTAG reset (Test-Logic-Reset) and then
runs the SVF script from @file{filename}.
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. For more details see @url{http://ipdbg.org}.
+
+@deffn {Command} {ipdbg} [@option{-start|-stop}] @option{-tap @var{tapname}} @option{-hub @var{ir_value} [@var{dr_length}]} [@option{-port @var{number}}] [@option{-tool @var{number}}] [@option{-vir [@var{vir_value} [@var{length} [@var{instr_code}]]]}]
+Starts or stops a IPDBG JTAG-Host server. Arguments can be specified in any order.
+
+Command options:
+@itemize @bullet
+@item @option{-start|-stop} starts or stops a IPDBG JTAG-Host server (default: start).
+@item @option{-tap @var{tapname}} targeting the TAP @var{tapname}.
+@item @option{-hub @var{ir_value}} states that the JTAG hub is
+reachable with dr-scans while the JTAG instruction register has the value @var{ir_value}.
+@item @option{-port @var{number}} tcp port number where the JTAG-Host is listening.
+@item @option{-tool @var{number}} number of the tool/feature. These corresponds to the ports "data_(up/down)_(0..6)" at the JtagHub.
+@item @option{-vir [@var{vir_value} [@var{length} [@var{instr_code}]]]} On some devices, the user data-register is only 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.
+@end itemize
+@end deffn
+
+Examples:
+@example
+ipdbg -start -tap xc6s.tap -hub 0x02 -port 4242 -tool 4
+@end example
+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 -start -tap 10m50.tap -hub 0x00C -vir -port 60000 -tool 1
+@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).
+
@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
@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}
@end itemize
Before an RTOS can be detected, it must export certain symbols; otherwise, it cannot
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
@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.
-These RTOSes may require additional OpenOCD-specific file to be linked
+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.
+
+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.
-@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
+@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
@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
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.
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...
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}
Code Review / openocd.git / blobdiff