diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/openocd.texi | 278 |
1 files changed, 256 insertions, 22 deletions
diff --git a/doc/openocd.texi b/doc/openocd.texi index 38c8970..27a2601 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -2672,6 +2672,35 @@ minimal impact on the target system. Avoid floating inputs, conflicting outputs and initially asserted reset signals. @end deffn +@deffn {Command} {ftdi oscan1_mode} on|off +Enable or disable OScan1 mode. This mode is intended for use with an adapter, +such as the ARM-JTAG-SWD by Olimex, that sits in between the FTDI chip and the +target. The cJTAG prococol is composed of two wires: TCKC (clock) and TMSC (data). +TMSC is a bidirectional signal which is time-multiplexed alternating TDI, TMS and +TDO. The multiplexing is achieved by a tri-state buffer which puts TMSC in Hi-Z +when the device is supposed to take the control of the line (TDO phase). + +The ARM-JTAG-SWD adapter uses standard TRST and TMS signals to control TMSC +direction. TRST is used by the adapter as selector for the multiplexers which set +the JTAG probe in 2-wire mode. Whatever signal is used for this purpose, it must +be defined with the name JTAG_SEL using @command{ftdi layout_signal}. JTAG_SEL is +set to 0 during OScan1 initialization. + +Some JTAG probes like the Digilent JTAG-HS2, support cJTAG by using a +separate pin to control when TMS is driven onto TMSC. You can use such +probes by defining the signal TMSC_EN using +@command{ftdi layout_signal TMSC_EN -data <mask>}. +@end deffn + +@deffn {Command} {ftdi jscan3_mode} on|off +Enable or disable JScan3 mode. This mode uses the classic 4-wire JTAG protocol +in chips whose JTAG port is only compliant with the cJTAG standard (IEEE 1149.7). + +Since cJTAG needs a 2-wire escape sequence to select the operating mode, +a cJTAG adapter like ARM-JTAG-SWD by Olimex is still required. This means +that a cJTAG probe configuration script must be used too. +@end deffn + @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 @@ -11077,11 +11106,9 @@ core specific EJTAG Register definition, please check Core Specific SUM manual. @section RISC-V Architecture @uref{http://riscv.org/, RISC-V} is a free and open ISA. OpenOCD supports JTAG -debug of RV32 and RV64 cores in heterogeneous multicore systems of up to 32 -harts. (It's possible to increase this limit to 1024 by changing -RISCV_MAX_HARTS in riscv.h.) OpenOCD primarily supports 0.13 of the RISC-V -Debug Specification, but there is also support for legacy targets that -implement version 0.11. +debug of RV32 and RV64 cores in heterogeneous multicore systems of up to 2^20 +harts. OpenOCD primarily supports 0.13 of the RISC-V Debug Specification, +but there is also support for legacy targets that implement version 0.11. @subsection RISC-V Terminology @@ -11128,6 +11155,13 @@ follows: @subsection RISC-V Debug Configuration Commands +@deffn {Command} {riscv dump_sample_buf} [base64] +Dump and clear the contents of the sample buffer. Which samples are collected +is configured with @code{riscv memory_sample}. If the optional base64 +argument is passed, the raw buffer is dumped in base64 format, so that +external tools can gather the data efficiently. +@end deffn + @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 @@ -11142,13 +11176,13 @@ CSRs. @example # Expose a single RISC-V CSR number 128 under the name "csr128": -$_TARGETNAME expose_csrs 128 +riscv expose_csrs 128 # Expose multiple RISC-V CSRs 128..132 under names "csr128" through "csr132": -$_TARGETNAME expose_csrs 128-132 +riscv expose_csrs 128-132 # Expose a single RISC-V CSR number 1996 under custom name "csr_myregister": -$_TARGETNAME expose_csrs 1996=myregister +riscv expose_csrs 1996=myregister @end example @end deffn @@ -11176,8 +11210,43 @@ $_TARGETNAME expose_custom 32=myregister @end example @end deffn +@deffn {Config Command} {riscv hide_csrs} n[-m] [,n1[-m1]] [...] +The RISC-V Specification defines many CSRs, and we may want to avoid showing +each CSR to the user, as they may not be relevant to the task at hand. For +example, we may choose not to show trigger or PMU registers for simple +debugging scenarios. This command allows to mark individual registers or +register ranges (inclusive) as "hidden". Such hidden registers won't be +displayed in GDB or @code{reg} command output. + +@example + +# Hide range of RISC-V CSRs +# CSR_TSELECT - 1952 and CSR_TDATA1 - 1953 +$_TARGETNAME riscv hide_csrs 1952-1953 + +@end example +@end deffn + +@deffn {Command} {riscv memory_sample} bucket address|clear [size=4] +Configure OpenOCD to frequently read size bytes at the given addresses. +Execute the command with no arguments to see the current configuration. Use +clear to stop using a given bucket. + +OpenOCD will allocate a 1MB sample buffer, and when it fills up no more +samples will be collected until it is emptied with @code{riscv +dump_sample_buf}. +@end deffn + +@deffn {Command} {riscv repeat_read} count address [size=4] +Quickly read count words of the given size from address. This can be useful +to read out a buffer that's memory-mapped to be accessed through a single +address, or to sample a changing value in a memory-mapped device. +@end deffn + @deffn {Command} {riscv info} -Displays some information OpenOCD detected about the target. +Displays some information OpenOCD detected about the target. Output's format +allows to use it directly with TCL's `array set` function. In case obtaining an +info point failed, the corresponding value is displayed as "unavailable". @end deffn @deffn {Command} {riscv reset_delays} [wait] @@ -11248,26 +11317,80 @@ When utilizing version 0.11 of the RISC-V Debug Specification, and DBUS registers, respectively. @end deffn +@deffn {Command} {riscv smp} [on|off] +Display, enable or disable SMP handling mode. This command is needed only if +user wants to temporary @b{disable} SMP handling for an existing SMP group +(see @code{aarch64 smp} for additional information). To define an SMP +group the command @code{target smp} should be used. +@end deffn + +@deffn {Command} {riscv smp_gdb} [core_id] +Display/set the current core displayed in GDB. This is needed only if +@code{riscv smp} was used. +@end deffn + @deffn {Command} {riscv use_bscan_tunnel} value -Enable or disable use of a BSCAN tunnel to reach DM. Supply the width of -the DM transport TAP's instruction register to enable. Supply a value of 0 to disable. +Enable or disable use of a BSCAN tunnel to reach the Debug Module. Supply the +width of the DM transport TAP's instruction register to enable. Supply a +value of 0 to disable. + +This BSCAN tunnel interface is specific to SiFive IP. Anybody may implement +it, but currently there is no good documentation on it. In a nutshell, this +feature scans USER4 into a Xilinx TAP to select the tunnel device (assuming +hardware is present and it is hooked up to the Xilinx USER4 IR) and +encapsulates a tunneled scan directive into a DR scan into the Xilinx TAP. A +tunneled DR scan consists of: +@enumerate +@item 1 bit that selects IR when 0, or DR when 1 +@item 7 bits that encode the width of the desired tunneled scan +@item A width+1 stream of bits for the tunneled TDI. The plus one is because there is a one-clock skew between TDI of Xilinx chain and TDO from tunneled chain. +@item 3 bits of zero that the tunnel uses to go back to idle state. +@end enumerate + +@end deffn + +@deffn {Command} {riscv set_bscan_tunnel_ir} value +Allows the use_bscan_tunnel feature to target non Xilinx device by +specifying the JTAG TAP IR used to access the bscan tunnel. @end deffn -@deffn {Command} {riscv set_ebreakm} on|off +@deffn {Command} {riscv set_maskisr} [@option{off}|@option{steponly}] +Selects whether interrupts will be disabled when single stepping. The default configuration is @option{off}. +This feature is only useful on hardware that always steps into interrupts and doesn't support dcsr.stepie=0. +Keep in mind, disabling the option does not guarantee that single stepping will go into interrupt handlers. +To make that happen, dcsr.stepie would have to be written to 1 as well. +@end deffn + +@deffn {Command} {riscv set_ebreakm} [on|off] Control dcsr.ebreakm. When on (default), M-mode ebreak instructions trap to OpenOCD. When off, they generate a breakpoint exception handled internally. @end deffn -@deffn {Command} {riscv set_ebreaks} on|off +@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 +The commands below can be used to prevent OpenOCD from using certain RISC-V trigger features. +For example in cases when there are known issues in the target hardware. + +@deffn {Command} {riscv set_enable_eq_match_trigger} [on|off] +When on (default), allow OpenOCD to use exact-match triggers in watchpoints. +@end deffn + +@deffn {Command} {riscv set_enable_napot_trigger} [on|off] +When on (default), allow OpenOCD to use NAPOT trigger in watchpoints. +@end deffn + +@deffn {Command} {riscv set_enable_ge_lt_trigger} [on|off] +When on (default), allow OpenOCD to use a pair of chained less-than & greater-than triggers in watchpoints. +@end deffn + @subsection RISC-V Authentication Commands The following commands can be used to authenticate to a RISC-V system. Eg. a @@ -11278,27 +11401,130 @@ set challenge [riscv authdata_read] riscv authdata_write [expr @{$challenge + 1@}] @end example -@deffn {Command} {riscv authdata_read} -Return the 32-bit value read from authdata. +@deffn {Command} {riscv authdata_read} [index=0] +Return the 32-bit value read from authdata or authdata0 (index=0), or +authdata1 (index=1). @end deffn -@deffn {Command} {riscv authdata_write} value -Write the 32-bit value to authdata. +@deffn {Command} {riscv authdata_write} [index=0] value +Write the 32-bit value to authdata or authdata0 (index=0), or authdata1 +(index=1). @end deffn @subsection RISC-V DMI Commands -The following commands allow direct access to the Debug Module Interface, which -can be used to interact with custom debug features. +The following commands allow for direct low-level access to the registers +of the Debug Module (DM). They can be useful to access custom features in the DM. + +@deffn {Command} {riscv dm_read} reg_address +Perform a 32-bit read from the register indicated by reg_address from the DM of the +current target. +@end deffn + +@deffn {Command} {riscv dm_write} reg_address value +Write the 32-bit value to the register indicated by reg_address from the DM of the +current target. +@end deffn + +The following commands allow for direct low-level access to the Debug Module +Interface (DMI). They can be useful to access any device that resides on the DMI. @deffn {Command} {riscv dmi_read} address -Perform a 32-bit DMI read at address, returning the value. +Perform a 32-bit read from the given DMI address, returning the value. @end deffn @deffn {Command} {riscv dmi_write} address value -Perform a 32-bit DMI write of value at address. +Perform a 32-bit write to the given DMI address. +@end deffn + +@subsection RISC-V Trigger Commands + +The RISC-V Debug Specification defines several optional trigger types that don't +map cleanly onto OpenOCD's notion of hardware breakpoints. For the types that +the target supports, these commands let you +set those triggers directly. (It's also possible to do so by writing the +appropriate CSRs.) + +@deffn {Command} {riscv etrigger set} [@option{m}] [@option{s}] [@option{u}] [@option{vs}] [@option{vu}] exception_codes +Set an exception trigger (type 5) on the current target, which halts the target when it +fires. @option{m}, @option{s}, @option{u}, @option{vs}, and @option{vu} control +which execution modes the trigger fires in. @var{exception_codes} is a bit +field, where each bit corresponds to an exception code in mcause (defined in the +RISC-V Privileged Spec). The etrigger will fire on the exceptions whose bits are +set in @var{exception_codes}. + +For details on this trigger type, see the RISC-V Debug Specification. +@end deffn + +@deffn {Command} {riscv etrigger clear} +Clear the type 5 trigger that was set using @command{riscv etrigger set}. +@end deffn + +@deffn {Command} {riscv icount set} [@option{m}] [@option{s}] [@option{u}] [@option{vs}] [@option{vu}] [@option{pending}] count +Set an instruction count +trigger (type 3) on the current target, which halts the target when it fires. +@option{m}, @option{s}, @option{u}, @option{vs}, and @option{vu} control which +execution modes the trigger fires in. If [@option{pending}] is passed then the +pending bit is set, which is unlikely to be useful unless you're debugging the +hardware implementation of this trigger. +@var{count} sets the number of instructions to execute before the trigger is +taken. + +For details on this trigger type, see the RISC-V Debug Specification. +@end deffn + +@deffn {Command} {riscv icount clear} +Clear the type 3 trigger that was set using @command{riscv icount set}. +@end deffn + +@deffn {Command} {riscv itrigger set} [@option{m}] [@option{s}] [@option{u}] [@option{vs}] [@option{vu}] [@option{nmi}] mie_bits +Set an interrupt trigger (type 4) on the current target, which halts the target when it +fires. @option{m}, @option{s}, @option{u}, @option{vs}, and @option{vu} control +which execution modes the trigger fires in. If [@option{nmi}] is passed then +the trigger will fire on non-maskable interrupts in those modes. @var{mie_bits} +controls which interrupts the trigger fires on, using the same bit assignments +as in the mie CSR (defined in the RISC-V Privileged Spec). + +For details on this trigger type, see the RISC-V Debug Specification. +@end deffn + +@deffn {Command} {riscv itrigger clear} +Clear the type 4 trigger that was set using @command{riscv itrigger set}. +@end deffn + +@subsection RISC-V Program Buffer Commands + +Program Buffer is an optional feature of RISC-V targets - it is a mechanism that debuggers +can use to execute sequences of arbitrary instructions (small programs) on the target. +For details on the Program Buffer, please refer to the RISC-V Debug Specification. + +@deffn {Command} {riscv exec_progbuf} inst1 [inst2 [... inst16]] +Execute the given sequence of instructions on the target using the Program Buffer. +The command can only be used on halted targets. + +The instructions @var{inst1} .. @var{inst16} shall be specified in their binary form +(as 32-bit integers). In case a pair of compressed (16-bit) instructions is used, +the first instruction should be placed to the lower 16-bits of the 32-bit value. +The terminating @var{ebreak} instruction needs not be specified - it is added +automatically if needed. @end deffn +Examples: + +@example +# Execute 32-bit instructions "fence rw,rw" (0x0330000f) +# and "fence.i" (0x0000100f) using the Program Buffer, +# in this order: + +riscv exec_progbuf 0x0330000f 0x0000100f + +# Execute 16-bit instructions "c.addi s0,s0,1" (0x0405) +# and "c.add s1,s1,s0" (0x94a2) using the Program Buffer, +# in this order: + +riscv exec_progbuf 0x94a20405 +@end example + @section ARC Architecture @cindex ARC @@ -12554,6 +12780,14 @@ contrib/rtos-helpers/FreeRTOS-openocd.c contrib/rtos-helpers/uCOS-III-openocd.c @end table +@section RTOS Commands +@cindex RTOS Commands + +@deffn {Config Command} {freertos_ticktype_size} (2|4|8) +Pass the size (in bytes) of FreeRTOS TickType_t to OpenOCD. To make sure the +calculation of offsets and sizes is correct. Defaults to 4. +@end deffn + @anchor{usingopenocdsmpwithgdb} @section Using OpenOCD SMP with GDB @cindex SMP |