if you have a new kind of hardware interface
and need to provide a driver for it.
+@deffn {Command} {find} 'filename'
+Prints full path to @var{filename} according to OpenOCD search rules.
+@end deffn
+
+@deffn {Command} {ocd_find} 'filename'
+Prints full path to @var{filename} according to OpenOCD search rules. This
+is a low level function used by the @command{find}. Usually you want
+to use @command{find}, instead.
+@end deffn
+
@section Board Config Files
@cindex config file, board
@cindex board config file
After it leaves this stage, configuration commands may no
longer be issued.
+@deffn {Command} {command mode} [command_name]
+Returns the command modes allowed by a command: 'any', 'config', or
+'exec'. If no command is specified, returns the current command
+mode. Returns 'unknown' if an unknown command is given. Command can be
+multiple tokens. (command valid any time)
+
+In this document, the modes are described as stages, 'config' and
+'exec' mode correspond configuration stage and run stage. 'any' means
+the command can be executed in either
+stages. @xref{configurationstage,,Configuration Stage}, and
+@xref{enteringtherunstage,,Entering the Run Stage}.
+@end deffn
+
@anchor{enteringtherunstage}
@section Entering the Run Stage
OpenOCD executes the command for you after processing all
configuration files and/or command line options.
-@b{NOTE:} This command normally occurs at or near the end of your
+@b{NOTE:} This command normally occurs near the end of your
openocd.cfg file to force OpenOCD to ``initialize'' and make the
targets ready. For example: If your openocd.cfg file needs to
read/write memory on your target, @command{init} must occur before
the memory read/write commands. This includes @command{nand probe}.
+
+@command{init} calls the following internal OpenOCD commands to initialize
+corresponding subsystems:
+@deffn {Config Command} {target init}
+@deffnx {Command} {transport init}
+@deffnx {Command} {dap init}
+@deffnx {Config Command} {flash init}
+@deffnx {Config Command} {nand init}
+@deffnx {Config Command} {pld init}
+@deffnx {Command} {tpiu init}
+@end deffn
+@end deffn
+
+@deffn {Config Command} {noinit}
+Prevent OpenOCD from implicit @command{init} call at the end of startup.
+Allows issuing configuration commands over telnet or Tcl connection.
+When you are done with configuration use @command{init} to enter
+the run stage.
@end deffn
@deffn {Overridable Procedure} {jtag_init}
Specifies the @var{serial_string} of the adapter to use.
If this command is not specified, serial strings are not checked.
Only the following adapter drivers use the serial string from this command:
-cmsis_dap, ft232r, ftdi, kitprog, presto, vsllink.
-The following adapters have their own command to specify the serial string:
-hla, jlink, st-link, xds110.
+aice (aice_usb), arm-jtag-ew, cmsis_dap, ft232r, ftdi, hla (stlink, ti-icdi), jlink, kitprog, opendus,
+openjtag, osbdm, presto, rlink, st-link, usb_blaster (ublast2), usbprog, vsllink, xds110.
@end deffn
@section Interface Drivers
@deffn {Command} {cmsis-dap info}
Display various device information, like hardware version, firmware version, current bus status.
@end deffn
+
+@deffn {Command} {cmsis-dap cmd} number number ...
+Execute an arbitrary CMSIS-DAP command. Use for adapter testing or for handling
+of an adapter vendor specific command from a Tcl script.
+
+Take given numbers as bytes, assemble a CMSIS-DAP protocol command packet
+from them and send it to the adapter. The first 4 bytes of the adapter response
+are logged.
+See @url{https://arm-software.github.io/CMSIS_5/DAP/html/group__DAP__Commands__gr.html}
+@end deffn
@end deffn
@deffn {Interface Driver} {dummy}
selection via USB address is not always unambiguous. It is recommended to use
the serial number instead, if possible.
-As a configuration command, it can be used only before 'init'.
-@end deffn
-@deffn {Config 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.
-
As a configuration command, it can be used only before 'init'.
@end deffn
@end deffn
Currently Not Supported.
@end deffn
-@deffn {Config Command} {hla_serial} serial
-Specifies the serial number of the adapter.
-@end deffn
-
@deffn {Config Command} {hla_layout} (@option{stlink}|@option{icdi}|@option{nulink})
Specifies the adapter layout to use.
@end deffn
@emph{Note:} ST-Link TCP server does not support the SWIM transport.
@end deffn
-@deffn {Config Command} {st-link serial} serial
-Specifies the serial number of the adapter.
-@end deffn
-
@deffn {Config Command} {st-link vid_pid} [vid pid]+
Pairs of vendor IDs and product IDs of the device.
@end deffn
debug probe with the added capability to supply power to the target board. The
following commands are supported by the XDS110 driver:
-@deffn {Config Command} {xds110 serial} serial_string
-Specifies the serial number of which XDS110 probe to use. Otherwise, the first
-XDS110 found will be used.
-@end deffn
-
@deffn {Config Command} {xds110 supply} voltage_in_millivolts
Available only on the XDS110 stand-alone probe. Sets the voltage level of the
XDS110 power supply. A value of 0 leaves the supply off. Otherwise, the supply
expected to change.
@end deffn
+@cindex SWD multi-drop
+The newer SWD devices (SW-DP v2 or SWJ-DP v2) support the multi-drop extension
+of SWD protocol: two or more devices can be connected to one SWD adapter.
+SWD transport works in multi-drop mode if @ref{dap_create,DAP} is configured
+with both @code{-dp-id} and @code{-instance-id} parameters regardless how many
+DAPs are created.
+
+Not all adapters and adapter drivers support SWD multi-drop. Only the following
+adapter drivers are SWD multi-drop capable:
+cmsis_dap (use an adapter with CMSIS-DAP version 2.0), ftdi, all bitbang based.
+
@subsection SPI Transport
@cindex SPI
@cindex Serial Peripheral Interface
The @command{dap} command group supports the following sub-commands:
+@anchor{dap_create}
@deffn {Command} {dap create} dap_name @option{-chain-position} dotted.name configparams...
Declare a DAP instance named @var{dap_name} linked to the JTAG tap
@var{dotted.name}. This also creates a new command (@command{dap_name})
All members of the ATSAMV7x, ATSAMS70, and ATSAME70 families from
Atmel include internal flash and use ARM's Cortex-M7 core.
This driver uses the same command names/syntax as @xref{at91sam3}.
+
+@example
+flash bank $_FLASHNAME atsamv 0x00400000 0 0 0 $_TARGETNAME
+@end example
+
+@deffn {Command} {atsamv gpnvm} [@option{show} [@option{all}|number]]
+@deffnx {Command} {atsamv gpnvm} (@option{clr}|@option{set}) number
+With no parameters, @option{show} or @option{show all},
+shows the status of all GPNVM bits.
+With @option{show} @var{number}, displays that bit.
+
+With @option{set} @var{number} or @option{clear} @var{number},
+modifies that GPNVM bit.
+@end deffn
+
@end deffn
@deffn {Flash Driver} {at91sam7}
@deffn {Flash Driver} {nrf5}
All members of the nRF51 microcontroller families from Nordic Semiconductor
-include internal flash and use ARM Cortex-M0 core.
-Also, the nRF52832 microcontroller from Nordic Semiconductor, which include
-internal flash and use an ARM Cortex-M4F core.
+include internal flash and use ARM Cortex-M0 core. nRF52 family powered
+by ARM Cortex-M4 or M4F core is supported too. nRF52832 is fully supported
+including BPROT flash protection scheme. nRF52833 and nRF52840 devices are
+supported with the exception of security extensions (flash access control list
+- ACL).
@example
flash bank $_FLASHNAME nrf5 0 0x00000000 0 0 $_TARGETNAME
which are only available after the configuration stage has completed.
@end deffn
+@deffn {Command} {usage} [string]
+With no parameters, prints usage text for all commands. Otherwise,
+prints all usage text of which command, help text, and usage text
+containing @var{string}.
+Not every command provides helptext.
+@end deffn
+
@deffn {Command} {sleep} msec [@option{busy}]
Wait for at least @var{msec} milliseconds before resuming.
If @option{busy} is passed, busy-wait instead of sleeping.
to its corresponding physical address, and displays the result.
@end deffn
+@deffn {Command} {add_help_text} 'command_name' 'help-string'
+Add or replace help text on the given @var{command_name}.
+@end deffn
+
+@deffn {Command} {add_usage_text} 'command_name' 'help-string'
+Add or replace usage text on the given @var{command_name}.
+@end deffn
+
@node Architecture and Core Commands
@chapter Architecture and Core Commands
@cindex Architecture Specific Commands
another hart, or may be a separate core. RISC-V treats those the same, and
OpenOCD exposes each hart as a separate core.
+@subsection Vector Registers
+
+For harts that implement the vector extension, OpenOCD provides access to the
+relevant CSRs, as well as the vector registers (v0-v31). The size of each
+vector register is dependent on the value of vlenb. RISC-V allows each vector
+register to be divided into selected-width elements, and this division can be
+changed at run-time. Because OpenOCD cannot update register definitions at
+run-time, it exposes each vector register to gdb as a union of fields of
+vectors so that users can easily access individual bytes, shorts, words,
+longs, and quads inside each vector register. It is left to gdb or
+higher-level debuggers to present this data in a more intuitive format.
+
+In the XML register description, the vector registers (when vlenb=16) look as
+follows:
+
+@example
+<feature name="org.gnu.gdb.riscv.vector">
+<vector id="bytes" type="uint8" count="16"/>
+<vector id="shorts" type="uint16" count="8"/>
+<vector id="words" type="uint32" count="4"/>
+<vector id="longs" type="uint64" count="2"/>
+<vector id="quads" type="uint128" count="1"/>
+<union id="riscv_vector">
+<field name="b" type="bytes"/>
+<field name="s" type="shorts"/>
+<field name="w" type="words"/>
+<field name="l" type="longs"/>
+<field name="q" type="quads"/>
+</union>
+<reg name="v0" bitsize="128" regnum="4162" save-restore="no"
+ type="riscv_vector" group="vector"/>
+...
+<reg name="v31" bitsize="128" regnum="4193" save-restore="no"
+ type="riscv_vector" group="vector"/>
+</feature>
+@end example
+
@subsection RISC-V Debug Configuration Commands
-@deffn {Command} {riscv expose_csrs} n0[-m0][,n1[-m1]]...
-Configure a list of inclusive ranges for CSRs to expose in addition to the
-standard ones. This must be executed before `init`.
+@deffn {Config Command} {riscv expose_csrs} n[-m|=name] [...]
+Configure which CSRs to expose in addition to the standard ones. The CSRs to expose
+can be specified as individual register numbers or register ranges (inclusive). For the
+individually listed CSRs, a human-readable name can optionally be set using the @code{n=name}
+syntax, which will get @code{csr_} prepended to it. If no name is provided, the register will be
+named @code{csr<n>}.
By default OpenOCD attempts to expose only CSRs that are mentioned in a spec,
and then only if the corresponding extension appears to be implemented. This
-command can be used if OpenOCD gets this wrong, or a target implements custom
+command can be used if OpenOCD gets this wrong, or if the target implements custom
CSRs.
+
+@example
+# Expose a single RISC-V CSR number 128 under the name "csr128":
+$_TARGETNAME expose_csrs 128
+
+# Expose multiple RISC-V CSRs 128..132 under names "csr128" through "csr132":
+$_TARGETNAME expose_csrs 128-132
+
+# Expose a single RISC-V CSR number 1996 under custom name "csr_myregister":
+$_TARGETNAME expose_csrs 1996=myregister
+@end example
@end deffn
-@deffn {Command} {riscv expose_custom} n0[-m0][,n1[-m1]]...
+@deffn {Config Command} {riscv expose_custom} n[-m|=name] [...]
The RISC-V Debug Specification allows targets to expose custom registers
through abstract commands. (See Section 3.5.1.1 in that document.) This command
-configures a list of inclusive ranges of those registers to expose. Number 0
-indicates the first custom register, whose abstract command number is 0xc000.
-This command must be executed before `init`.
+configures individual registers or register ranges (inclusive) that shall be exposed.
+Number 0 indicates the first custom register, whose abstract command number is 0xc000.
+For individually listed registers, a human-readable name can be optionally provided
+using the @code{n=name} syntax, which will get @code{custom_} prepended to it. If no
+name is provided, the register will be named @code{custom<n>}.
+
+@example
+# Expose one RISC-V custom register with number 0xc010 (0xc000 + 16)
+# under the name "custom16":
+$_TARGETNAME expose_custom 16
+
+# Expose a range of RISC-V custom registers with numbers 0xc010 .. 0xc018
+# (0xc000+16 .. 0xc000+24) under the names "custom16" through "custom24":
+$_TARGETNAME expose_custom 16-24
+
+# Expose one RISC-V custom register with number 0xc020 (0xc000 + 32) under
+# user-defined name "custom_myregister":
+$_TARGETNAME expose_custom 32=myregister
+@end example
@end deffn
@deffn {Command} {riscv set_command_timeout_sec} [seconds]
deasserted.
@end deffn
-@deffn {Command} {riscv set_prefer_sba} on|off
-When on, prefer to use System Bus Access to access memory. When off (default),
-prefer to use the Program Buffer to access memory.
+@deffn {Command} {riscv set_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_mem_access} method1 [method2] [method3]
+Specify which RISC-V memory access method(s) shall be used, and in which order
+of priority. At least one method must be specified.
+
+Available methods are:
+@itemize
+@item @code{progbuf} - Use RISC-V Debug Program Buffer to access memory.
+@item @code{sysbus} - Access memory via RISC-V Debug System Bus interface.
+@item @code{abstract} - Access memory via RISC-V Debug abstract commands.
+@end itemize
+
+By default, all memory access methods are enabled in the following order:
+@code{progbuf sysbus abstract}.
+
+This command can be used to change the memory access methods if the default
+behavior is not suitable for a particular target.
@end deffn
@deffn {Command} {riscv set_enable_virtual} on|off
projects / fw / openocd / blobdiff