@cindex dongles
@cindex FTDI
@cindex wiggler
-@cindex zy1000
@cindex printer port
@cindex USB Adapter
@cindex RTCK
an adapter .... [snip]
In the OpenOCD case, this generally refers to @b{a small adapter} that
-attaches to your computer via USB or the parallel port. One
-exception is the Ultimate Solutions ZY1000, packaged as a small box you
-attach via an ethernet cable. The ZY1000 has the advantage that it does not
-require any drivers to be installed on the developer PC. It also has
-a built in web interface. It supports RTCK/RCLK or adaptive clocking
-and has a built-in relay to power cycle targets remotely.
+attaches to your computer via USB or the parallel port.
@section Choosing a Dongle
RTCK support (also known as ``adaptive clocking'')?
@end enumerate
-@section Stand-alone JTAG Probe
-
-The ZY1000 from Ultimate Solutions is technically not a dongle but a
-stand-alone JTAG probe that, unlike most dongles, doesn't require any drivers
-running on the developer's host computer.
-Once installed on a network using DHCP or a static IP assignment, users can
-access the ZY1000 probe locally or remotely from any host with access to the
-IP address assigned to the probe.
-The ZY1000 provides an intuitive web interface with direct access to the
-OpenOCD debugger.
-Users may also run a GDBSERVER directly on the ZY1000 to take full advantage
-of GCC & GDB to debug any distribution of embedded Linux or NetBSD running on
-the target.
-The ZY1000 supports RTCK & RCLK or adaptive clocking and has a built-in relay
-to power cycle the target remotely.
-
-For more information, visit:
-
-@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/210-zylin-zy1000-main}
-
@section USB FT2232 Based
There are many USB JTAG dongles on the market, many of them based
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,
the memory read/write commands. This includes @command{nand probe}.
@end deffn
-@deffn {Overridable Procedure} jtag_init
+@deffn {Overridable Procedure} {jtag_init}
This is invoked at server startup to verify that it can talk
to the scan chain (list of TAPs) which has been configured.
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
When using "pipe", also use log_output to redirect the log
output to a file so as not to flood the stdin/out pipes.
-The -p/--pipe option is deprecated and a warning is printed
-as it is equivalent to passing in -c "gdb_port pipe; log_output openocd.log".
-
Any other string is interpreted as named pipe to listen to.
Output pipe is the same name as input pipe, but with 'o' appended,
e.g. /var/gdb, /var/gdbo.
cause initialization to fail with "Unknown remote qXfer reply: OK".
@end deffn
-@deffn {Command} tcl_port [number]
+@deffn {Config Command} {tcl_port} [number]
Specify or query the port used for a simplified RPC
connection that can be used by clients to issue TCL commands and get the
output from the Tcl engine.
When specified as "disabled", this service is not activated.
@end deffn
-@deffn {Command} telnet_port [number]
+@deffn {Config Command} {telnet_port} [number]
Specify or query the
port on which to listen for incoming telnet connections.
This port is intended for interaction with one human through TCL commands.
@xref{targetevents,,Target Events}, about configuring target-specific event handling.
@anchor{gdbbreakpointoverride}
-@deffn {Command} gdb_breakpoint_override [@option{hard}|@option{soft}|@option{disable}]
+@deffn {Command} {gdb_breakpoint_override} [@option{hard}|@option{soft}|@option{disable}]
Force breakpoint type for gdb @command{break} commands.
This option supports GDB GUIs which don't
distinguish hard versus soft breakpoints, if the default OpenOCD and
@end deffn
@anchor{gdbflashprogram}
-@deffn {Config Command} gdb_flash_program (@option{enable}|@option{disable})
+@deffn {Config Command} {gdb_flash_program} (@option{enable}|@option{disable})
Set to @option{enable} to cause OpenOCD to program the flash memory when a
vFlash packet is received.
The default behaviour is @option{enable}.
@end deffn
-@deffn {Config Command} gdb_memory_map (@option{enable}|@option{disable})
+@deffn {Config Command} {gdb_memory_map} (@option{enable}|@option{disable})
Set to @option{enable} to cause OpenOCD to send the memory configuration to GDB when
requested. GDB will then know when to set hardware breakpoints, and program flash
using the GDB load command. @command{gdb_flash_program enable} must also be enabled
@xref{gdbflashprogram,,gdb_flash_program}.
@end deffn
-@deffn {Config Command} gdb_report_data_abort (@option{enable}|@option{disable})
+@deffn {Config Command} {gdb_report_data_abort} (@option{enable}|@option{disable})
Specifies whether data aborts cause an error to be reported
by GDB memory read packets.
The default behaviour is @option{disable};
use @option{enable} see these errors reported.
@end deffn
-@deffn {Config Command} gdb_report_register_access_error (@option{enable}|@option{disable})
+@deffn {Config Command} {gdb_report_register_access_error} (@option{enable}|@option{disable})
Specifies whether register accesses requested by GDB register read/write
packets report errors or not.
The default behaviour is @option{disable};
use @option{enable} see these errors reported.
@end deffn
-@deffn {Config Command} gdb_target_description (@option{enable}|@option{disable})
+@deffn {Config Command} {gdb_target_description} (@option{enable}|@option{disable})
Set to @option{enable} to cause OpenOCD to send the target descriptions to gdb via qXfer:features:read packet.
The default behaviour is @option{enable}.
@end deffn
-@deffn {Command} gdb_save_tdesc
+@deffn {Command} {gdb_save_tdesc}
Saves the target description file to the local file system.
The file name is @i{target_name}.xml.
There is a command to manage and monitor that polling,
which is normally done in the background.
-@deffn Command poll [@option{on}|@option{off}]
+@deffn {Command} {poll} [@option{on}|@option{off}]
Poll the current target for its current state.
(Also, @pxref{targetcurstate,,target curstate}.)
If that target is in debug mode, architecture
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
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
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
Selects the channel of the FTDI device to use for MPSSE operations. Most
adapters use the default, channel 0, but there are exceptions.
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
@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
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
As a configuration command, it can be used only before 'init'.
@end deffn
-@deffn {Config} {jlink serial} <serial number>
+@deffn {Config Command} {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.
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.
@end deffn
@end deffn
-@deffn {Interface Driver} {ZY1000}
-This is the Zylin ZY1000 JTAG debugger.
-@end deffn
-
-@quotation Note
-This defines some driver-specific commands,
-which are not currently documented here.
-@end quotation
-
-@deffn Command power [@option{on}|@option{off}]
-Turn power switch to target on/off.
-No arguments: print status.
-@end deffn
-
@deffn {Interface Driver} {bcm2835gpio}
This SoC is present in Raspberry Pi which is a cheap single-board computer
exposing some GPIOs on its expansion header.
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}
+@deffn {Command} {swd wcr trn prescale}
Updates TRN (turnaround delay) and prescaling.fields of the
Wire Control Register (WCR).
No parameters: displays current settings.
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}.
@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...
+@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.
@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} [num]
Displays the ROM table for MEM-AP @var{num},
defaulting to the currently selected AP of the currently selected target.
@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} [num]
Displays the ROM table for MEM-AP @var{num},
defaulting to the currently selected AP.
@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.
@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}.
@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.
@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.
@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)
@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{hla_target} -- a Cortex-M alternative to work with HL adapters like ST-Link.
@item @code{ls1_sap} -- this is the SAP on NXP LS102x CPUs,
allowing access to physical memory addresses independently of CPU cores.
-@item @code{mem_ap} -- this is an ARM debug infrastructure Access Port without a CPU, through which bus read and write cycles can be generated; it may be useful for working with non-CPU hardware behind an AP or during development of support for new CPUs.
+@item @code{mem_ap} -- this is an ARM debug infrastructure Access Port without
+a CPU, through which bus read and write cycles can be generated; it may be
+useful for working with non-CPU hardware behind an AP or during development of
+support for new CPUs.
+It's possible to connect a GDB client to this target (the GDB port has to be
+specified, @xref{gdbportoverride,,option -gdb-port}.), and a fake ARM core will
+be emulated to comply to GDB remote protocol.
@item @code{mips_m4k} -- a MIPS core.
@item @code{mips_mips64} -- a MIPS64 core.
@item @code{nds32_v2} -- this is an Andes NDS32 v2 core.
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
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
+@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.
@end itemize
@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}),
see the @code{mem2array} 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}.
@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
@end example
@end deffn
-@deffn {Flash Driver} xcf
+@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
@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}.
@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
+@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.
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
+@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
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} {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
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 and GD32F3x0 microcontroller
+families from GigaDevice include internal flash and use ARM Cortex-M0/M3/M4 cores.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
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
+@deffn {Flash Driver} {stm32l4x}
All members of the STM32 G0, G4, L4, L4+, L5, WB and WL
microcontroller families from STMicroelectronics include internal flash
and use ARM Cortex-M0+, M4 and M33 cores.
flash bank $_FLASHNAME stm32l4x 0 0 0 0 $_TARGETNAME
@end example
+If you use OTP (One-Time Programmable) memory define it as a second bank
+as per the following example.
+@example
+flash bank $_FLASHNAME stm32l4x 0x1FFF7000 0 0 0 $_TARGETNAME
+@end example
+
+@deffn {Command} {stm32l4x otp} num (@option{enable}|@option{disable}|@option{show})
+Enables or disables OTP write commands for bank @var{num}.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
Note that some devices have been found that have a flash size register that contains
an invalid value, to workaround this issue you can override the probed value used by
the flash driver. However, specifying a wrong value might lead to a completely
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}.
@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}.
@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
This will effectively write protect all sectors in flash bank 1.
@end deffn
-@deffn Command {stm32l4x option_load} num
+@deffn {Command} {stm32l4x wrp_info} num [device_bank]
+List the protected areas using WRP.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@var{device_bank} parameter is optional, possible values 'bank1' or 'bank2',
+if not specified, the command will display the whole flash protected areas.
+
+@b{Note:} @var{device_bank} is different from banks created using @code{flash bank}.
+Devices supported in this flash driver, can have main flash memory organized
+in single or dual-banks mode.
+Thus the usage of @var{device_bank} is meaningful only in dual-bank mode, to get
+write protected areas in a specific @var{device_bank}
+
+@end deffn
+
+@deffn {Command} {stm32l4x option_load} num
Forces a re-load of the option byte registers. Will cause a system reset of the device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@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_mhz} 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} {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.
@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.
@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} {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
@end quotation
@end deffn
-@section I/O Utilities
-
-These commands are available when
-OpenOCD is built with @option{--enable-ioutil}.
-They are mainly useful on embedded targets,
-notably the ZY1000.
-Hosts with operating systems have complementary tools.
-
-@emph{Note:} there are several more such commands.
-
-@deffn Command append_file filename [string]*
-Appends the @var{string} parameters to
-the text file @file{filename}.
-Each string except the last one is followed by one space.
-The last string is followed by a newline.
-@end deffn
-
-@deffn Command cat filename
-Reads and displays the text file @file{filename}.
-@end deffn
-
-@deffn Command cp src_filename dest_filename
-Copies contents from the file @file{src_filename}
-into @file{dest_filename}.
-@end deffn
-
-@deffn Command ip
-@emph{No description provided.}
-@end deffn
-
-@deffn Command ls
-@emph{No description provided.}
-@end deffn
-
-@deffn Command mac
-@emph{No description provided.}
-@end deffn
-
-@deffn Command meminfo
-Display available RAM memory on OpenOCD host.
-Used in OpenOCD regression testing scripts.
-@end deffn
-
-@deffn Command peek
-@emph{No description provided.}
-@end deffn
-
-@deffn Command poke
-@emph{No description provided.}
-@end deffn
-
-@deffn Command rm filename
-@c "rm" has both normal and Jim-level versions??
-Unlinks the file @file{filename}.
-@end deffn
-
-@deffn Command trunc filename
-Removes all data in the file @file{filename}.
-@end deffn
-
@anchor{memoryaccess}
@section Memory access commands
@cindex memory access
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}),
see the @code{mem2array} 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}).
@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
@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)
@end deffn
-@deffn {Trace Port Driver} oocd_trace
-This driver isn't available unless OpenOCD was explicitly configured
-with the @option{--enable-oocd_trace} option. You probably don't want
-to configure it unless you've built the appropriate prototype hardware;
-it's @emph{proof-of-concept} software.
-
-Use the @option{oocd_trace} driver if you are configuring an ETM that's
-connected to an off-chip trace connector.
-
-@deffn {Config Command} {oocd_trace config} target tty
-Associates the ETM for @var{target} with a trace driver which
-collects data through the serial port @var{tty}.
-@end deffn
-
-@deffn Command {oocd_trace resync}
-Re-synchronizes with the capture clock.
-@end deffn
-
-@deffn Command {oocd_trace status}
-Reports whether the capture clock is locked or not.
-@end deffn
-@end deffn
-
@anchor{armcrosstrigger}
@section ARM Cross-Trigger Interface
@cindex CTI
CTI instance attached to it. OpenOCD has limited support for CTI using
the @emph{cti} group of commands.
-@deffn Command {cti create} cti_name @option{-dap} dap_name @option{-ap-num} apn @option{-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
on the respective MEM-AP. All arguments are mandatory. This creates a
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_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.
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 cp15i} opcode [value [address]]
-@emph{DEPRECATED -- avoid using this.
-Use the @command{arm mrc} or @command{arm mcr} commands instead.}
-
-Interpreted access using ARM instruction @var{opcode}, which should
-be the value of either an MRC or MCR instruction
-(as shown tables 9-11, 9-12, and 9-13 in the ARM920T TRM).
-If no @var{value} is provided, the result is displayed.
-Else if that value is written using the specified @var{address},
-or using zero if no other address is provided.
-@end deffn
-
-@deffn Command {arm920t read_cache} filename
+@deffn {Command} {arm920t read_cache} filename
Dump the content of ICache and DCache to a file named @file{filename}.
@end deffn
-@deffn Command {arm920t read_mmu} filename
+@deffn {Command} {arm920t read_mmu} filename
Dump the content of the ITLB and DTLB to a file named @file{filename}.
@end deffn
The Feroceon cores also support these commands, although
they are not built from ARM926ej-s designs.
-@deffn Command {arm926ejs cache_info}
+@deffn {Command} {arm926ejs cache_info}
Print information about the caches found.
@end deffn
They are available in addition to the ARM, ARM7/ARM9,
and ARM9 commands.
-@deffn Command {arm966e cp15} regnum [value]
+@deffn {Command} {arm966e cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
The six bit @var{regnum} values are bits 37..32 from table 7-2 of the
These commands are available to XScale based CPUs,
which are implementations of the ARMv5TE architecture.
-@deffn Command {xscale analyze_trace}
+@deffn {Command} {xscale analyze_trace}
Displays the contents of the trace buffer.
@end deffn
-@deffn Command {xscale cache_clean_address} address
+@deffn {Command} {xscale cache_clean_address} address
Changes the address used when cleaning the data cache.
@end deffn
-@deffn Command {xscale cache_info}
+@deffn {Command} {xscale cache_info}
Displays information about the CPU caches.
@end deffn
-@deffn Command {xscale cp15} regnum [value]
+@deffn {Command} {xscale cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
@end deffn
-@deffn Command {xscale debug_handler} target address
+@deffn {Command} {xscale debug_handler} target address
Changes the address used for the specified target's debug handler.
@end deffn
-@deffn Command {xscale dcache} [@option{enable}|@option{disable}]
+@deffn {Command} {xscale dcache} [@option{enable}|@option{disable}]
Enables or disable the CPU's data cache.
@end deffn
-@deffn Command {xscale dump_trace} filename
+@deffn {Command} {xscale dump_trace} filename
Dumps the raw contents of the trace buffer to @file{filename}.
@end deffn
-@deffn Command {xscale icache} [@option{enable}|@option{disable}]
+@deffn {Command} {xscale icache} [@option{enable}|@option{disable}]
Enables or disable the CPU's instruction cache.
@end deffn
-@deffn Command {xscale mmu} [@option{enable}|@option{disable}]
+@deffn {Command} {xscale mmu} [@option{enable}|@option{disable}]
Enables or disable the CPU's memory management unit.
@end deffn
-@deffn Command {xscale trace_buffer} [@option{enable}|@option{disable} [@option{fill} [n] | @option{wrap}]]
+@deffn {Command} {xscale trace_buffer} [@option{enable}|@option{disable} [@option{fill} [n] | @option{wrap}]]
Displays the trace buffer status, after optionally
enabling or disabling the trace buffer
and modifying how it is emptied.
@end deffn
-@deffn Command {xscale trace_image} filename [offset [type]]
+@deffn {Command} {xscale trace_image} filename [offset [type]]
Opens a trace image from @file{filename}, optionally rebasing
its segment addresses by @var{offset}.
The image @var{type} may be one of
@end deffn
@anchor{xscalevectorcatch}
-@deffn Command {xscale vector_catch} [mask]
+@deffn {Command} {xscale vector_catch} [mask]
@cindex vector_catch
Display a bitmask showing the hardware vectors to catch.
If the optional parameter is provided, first set the bitmask to that value.
@end example
@end deffn
-@deffn Command {xscale vector_table} [(@option{low}|@option{high}) index value]
+@deffn {Command} {xscale vector_table} [(@option{low}|@option{high}) index value]
@cindex vector_table
Set an entry in the mini-IC vector table. There are two tables: one for
@subsection ARM11 specific commands
@cindex ARM11
-@deffn Command {arm11 memwrite burst} [@option{enable}|@option{disable}]
+@deffn {Command} {arm11 memwrite burst} [@option{enable}|@option{disable}]
Displays the value of the memwrite burst-enable flag,
which is enabled by default.
If a boolean parameter is provided, first assigns that flag.
This is usually safe, because JTAG runs much slower than the CPU.
@end deffn
-@deffn Command {arm11 memwrite error_fatal} [@option{enable}|@option{disable}]
+@deffn {Command} {arm11 memwrite error_fatal} [@option{enable}|@option{disable}]
Displays the value of the memwrite error_fatal flag,
which is enabled by default.
If a boolean parameter is provided, first assigns that flag.
When set, certain memory write errors cause earlier transfer termination.
@end deffn
-@deffn Command {arm11 step_irq_enable} [@option{enable}|@option{disable}]
+@deffn {Command} {arm11 step_irq_enable} [@option{enable}|@option{disable}]
Displays the value of the flag controlling whether
IRQs are enabled during single stepping;
they are disabled by default.
If a boolean parameter is provided, first assigns that.
@end deffn
-@deffn Command {arm11 vcr} [value]
+@deffn {Command} {arm11 vcr} [value]
@cindex vector_catch
Displays the value of the @emph{Vector Catch Register (VCR)},
coprocessor 14 register 7.
@subsection ARMv7-A specific commands
@cindex Cortex-A
-@deffn Command {cortex_a cache_info}
+@deffn {Command} {cortex_a cache_info}
display information about target caches
@end deffn
-@deffn Command {cortex_a dacrfixup [@option{on}|@option{off}]}
+@deffn {Command} {cortex_a dacrfixup [@option{on}|@option{off}]}
Work around issues with software breakpoints when the program text is
mapped read-only by the operating system. This option sets the CP15 DACR
to "all-manager" to bypass MMU permission checks on memory access.
Defaults to 'off'.
@end deffn
-@deffn Command {cortex_a dbginit}
+@deffn {Command} {cortex_a dbginit}
Initialize core debug
Enables debug by unlocking the Software Lock and clearing sticky powerdown indications
@end deffn
-@deffn Command {cortex_a smp} [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_r 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_r 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.
@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.
@end deffn
-@deffn Command {readgroup} (@option{group})
+@deffn {Command} {readgroup} (@option{group})
Display all registers in @emph{group}.
@emph{group} can be "system",
@subsection RISC-V Debug Configuration Commands
-@deffn Command {riscv expose_csrs} n0[-m0][,n1[-m1]]...
+@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`.
CSRs.
@end deffn
-@deffn Command {riscv expose_custom} n0[-m0][,n1[-m1]]...
+@deffn {Command} {riscv expose_custom} n0[-m0][,n1[-m1]]...
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
This command must be executed before `init`.
@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
+@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.
@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
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...
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
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
@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.
@}
@end example
+@node License
+@appendix The GNU Free Documentation License.
@include fdl.texi
@node OpenOCD Concept Index