X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=8e50585389723627e21999bc3f85b96e60335180;hb=d27d66bc1bdbef0cbfe43d88597576e173317c01;hp=c76fc076c5e53788ab4a68f5ee6fb44215788c76;hpb=271e5416af975b52d4cd0e2ced65a4cbda9d041f;p=fw%2Fopenocd diff --git a/doc/openocd.texi b/doc/openocd.texi index c76fc076c..8e5058538 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -1359,6 +1359,16 @@ Read the OpenOCD source code (and Developer's Guide) 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 @@ -2040,6 +2050,19 @@ may access or activate TAPs. 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 @@ -2075,11 +2098,29 @@ If this command does not appear in any startup/configuration file 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} @@ -2371,9 +2412,8 @@ This command is only available if your libusb1 is at least version 1.0.16. 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 @@ -2448,6 +2488,16 @@ interface string or for user class interface. @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} @@ -2848,12 +2898,6 @@ to the host. If not specified, USB addresses are not considered. Device selection via USB address is not always unambiguous. It is recommended to use the serial number instead, if possible. -As a configuration command, it can be used only before 'init'. -@end deffn -@deffn {Config Command} {jlink serial} -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 @@ -3046,10 +3090,6 @@ version reported is V2.J21.S4. 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 @@ -3098,10 +3138,6 @@ ST-LINK server software module}. @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 @@ -3141,11 +3177,6 @@ LaunchPad evaluation boards. The XDS110 is also available as a stand-alone USB debug probe with the added capability to supply power to the target board. The following commands are supported by the XDS110 driver: -@deffn {Config Command} {xds110 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 @@ -3453,6 +3484,17 @@ Parameters are currently the same as "jtag newtap" but this is 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 @@ -4366,6 +4408,7 @@ instead of "@option{-chain-position} @var{dotted.name}" when the target is creat 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}) @@ -6192,6 +6235,21 @@ USER PAGE: 0xAEECFF80FE9A9239 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} @@ -6822,9 +6880,11 @@ flash bank $_FLASHNAME npcx 0x64000000 0 0 0 $_TARGETNAME @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 @@ -8231,6 +8291,13 @@ In most cases, no such restriction is listed; this indicates commands 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. @@ -8720,6 +8787,14 @@ Requests the current target to map the specified @var{virtual_address} to its corresponding physical address, and displays the result. @end deffn +@deffn {Command} {add_help_text} 'command_name' 'help-string' +Add or replace help text on the given @var{command_name}. +@end deffn + +@deffn {Command} {add_usage_text} 'command_name' 'help-string' +Add or replace usage text on the given @var{command_name}. +@end deffn + @node Architecture and Core Commands @chapter Architecture and Core Commands @cindex Architecture Specific Commands @@ -10137,24 +10212,91 @@ A @emph{hart} is a hardware thread. A hart may share resources (eg. FPU) with 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 + + + + + + + + + + + + + + +... + + +@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}. 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}. + +@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] @@ -10167,9 +10309,27 @@ Set the maximum time to wait for a hart to come out of reset after reset is 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