X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=f678621ee00decfbfc313c2ec3e670cc37c410fa;hp=be9e5ac085f8e832348334b509f76ab741348b8f;hb=2053120ba10d68339c61cd2b247bde01bda41ab7;hpb=62cea61237033b1821d68b1d4d09fd381ddb5d52 diff --git a/doc/openocd.texi b/doc/openocd.texi index be9e5ac085..f678621ee0 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -4646,8 +4646,12 @@ There can only be one DAP for each JTAG tap in the system. A DAP may also provide optional @var{configparams}: @itemize @bullet +@item @code{-adiv5} +Specify that it's an ADIv5 DAP. This is the default if not specified. +@item @code{-adiv6} +Specify that it's an ADIv6 DAP. @item @code{-ignore-syspwrupack} -@*Specify this to ignore the CSYSPWRUPACK bit in the ARM DAP DP CTRL/STAT +Specify this to ignore the CSYSPWRUPACK bit in the ARM DAP DP CTRL/STAT register during initial examination and when checking the sticky error bit. This bit is normally checked after setting the CSYSPWRUPREQ bit, but some devices do not set the ack bit until sometime later. @@ -4673,9 +4677,12 @@ This command returns a list of all registered DAP objects. It it useful mainly for TCL scripting. @end deffn -@deffn {Command} {dap info} [num] +@deffn {Command} {dap info} [@var{num}|@option{root}] Displays the ROM table for MEM-AP @var{num}, defaulting to the currently selected AP of the currently selected target. +On ADIv5 DAP @var{num} is the numeric index of the AP. +On ADIv6 DAP @var{num} is the base address of the AP. +With ADIv6 only, @option{root} specifies the root ROM table. @end deffn @deffn {Command} {dap init} @@ -4686,24 +4693,33 @@ initialization, too. The following commands exist as subcommands of DAP instances: -@deffn {Command} {$dap_name info} [num] +@deffn {Command} {$dap_name info} [@var{num}|@option{root}] Displays the ROM table for MEM-AP @var{num}, defaulting to the currently selected AP. +On ADIv5 DAP @var{num} is the numeric index of the AP. +On ADIv6 DAP @var{num} is the base address of the AP. +With ADIv6 only, @option{root} specifies the root ROM table. @end deffn @deffn {Command} {$dap_name apid} [num] Displays ID register from AP @var{num}, defaulting to the currently selected AP. +On ADIv5 DAP @var{num} is the numeric index of the AP. +On ADIv6 DAP @var{num} is the base address of the AP. @end deffn @anchor{DAP subcommand apreg} @deffn {Command} {$dap_name apreg} ap_num reg [value] Displays content of a register @var{reg} from AP @var{ap_num} or set a new value @var{value}. +On ADIv5 DAP @var{ap_num} is the numeric index of the AP. +On ADIv6 DAP @var{ap_num} is the base address of the AP. @var{reg} is byte address of a word register, 0, 4, 8 ... 0xfc. @end deffn @deffn {Command} {$dap_name apsel} [num] Select AP @var{num}, defaulting to 0. +On ADIv5 DAP @var{num} is the numeric index of the AP. +On ADIv6 DAP @var{num} is the base address of the AP. @end deffn @deffn {Command} {$dap_name dpreg} reg [value] @@ -4721,6 +4737,8 @@ background activity by OpenOCD while you are operating at such low-level. @deffn {Command} {$dap_name baseaddr} [num] Displays debug base address from MEM-AP @var{num}, defaulting to the currently selected AP. +On ADIv5 DAP @var{num} is the numeric index of the AP. +On ADIv6 DAP @var{num} is the base address of the AP. @end deffn @deffn {Command} {$dap_name memaccess} [value] @@ -4895,6 +4913,9 @@ compact Thumb2 instruction set. Supports also ARMv6-M and ARMv8-M cores @item @code{dsp5680xx} -- implements Freescale's 5680x DSP. @item @code{esirisc} -- this is an EnSilica eSi-RISC core. The current implementation supports eSi-32xx cores. +@item @code{esp32} -- this is an Espressif SoC with dual Xtensa cores. +@item @code{esp32s2} -- this is an Espressif SoC with single Xtensa core. +@item @code{esp32s3} -- this is an Espressif SoC with dual Xtensa cores. @item @code{fa526} -- resembles arm920 (w/o Thumb). @item @code{feroceon} -- resembles arm926. @item @code{hla_target} -- a Cortex-M alternative to work with HL adapters like ST-Link. @@ -5093,8 +5114,9 @@ The value should normally correspond to a static mapping for the scan and after a reset. A manual call to arp_examine is required to access the target for debugging. -@item @code{-ap-num} @var{ap_number} -- set DAP access port for target, -@var{ap_number} is the numeric index of the DAP AP the target is connected to. +@item @code{-ap-num} @var{ap_number} -- set DAP access port for target. +On ADIv5 DAP @var{ap_number} is the numeric index of the DAP AP the target is connected to. +On ADIv6 DAP @var{ap_number} is the base address of the DAP AP the target is connected to. Use this option with systems where multiple, independent cores are connected to separate access ports of the same DAP. @@ -9444,7 +9466,10 @@ the @emph{cti} group of commands. @deffn {Command} {cti create} cti_name @option{-dap} dap_name @option{-ap-num} apn @option{-baseaddr} base_address Creates a CTI instance @var{cti_name} on the DAP instance @var{dap_name} on MEM-AP -@var{apn}. The @var{base_address} must match the base address of the CTI +@var{apn}. +On ADIv5 DAP @var{apn} is the numeric index of the DAP AP the CTI is connected to. +On ADIv6 DAP @var{apn} is the base address of the DAP AP the CTI is connected to. +The @var{base_address} must match the base address of the CTI on the respective MEM-AP. All arguments are mandatory. This creates a new command @command{$cti_name} which is used for various purposes including additional configuration. @@ -9624,6 +9649,12 @@ is valid during the run of the event handlers and is accessible with this command. @end deffn +@deffn {Command} {arm semihosting_basedir} [dir] +@cindex ARM semihosting +Set the base directory for semihosting I/O, either an absolute path or a path relative to OpenOCD working directory. +Use "." for the current directory. +@end deffn + @section ARMv4 and ARMv5 Architecture @cindex ARMv4 @cindex ARMv5 @@ -10103,8 +10134,9 @@ using the @command{$tpiu_name cget} command. @item @code{-dap} @var{dap_name} -- names the DAP used to access this TPIU. @xref{dapdeclaration,,DAP declaration}, on how to create and manage DAP instances. -@item @code{-ap-num} @var{ap_number} -- sets DAP access port for TPIU, -@var{ap_number} is the numeric index of the DAP AP the TPIU is connected to. +@item @code{-ap-num} @var{ap_number} -- sets DAP access port for TPIU. +On ADIv5 DAP @var{ap_number} is the numeric index of the DAP AP the TPIU is connected to. +On ADIv6 DAP @var{ap_number} is the base address of the DAP AP the TPIU is connected to. @item @code{-baseaddr} @var{base_address} -- sets the TPIU @var{base_address} where to access the TPIU in the DAP AP memory space. @@ -10950,6 +10982,94 @@ STMicroelectronics, based on a proprietary 8-bit core architecture. OpenOCD supports debugging STM8 through the STMicroelectronics debug protocol SWIM, @pxref{swimtransport,,SWIM}. +@section Xtensa Architecture +Xtensa processors are based on a modular, highly flexible 32-bit RISC architecture +that can easily scale from a tiny, cache-less controller or task engine to a high-performance +SIMD/VLIW DSP provided by Cadence. +@url{https://www.cadence.com/en_US/home/tools/ip/tensilica-ip/tensilica-xtensa-controllers-and-extensible-processors.html}. + +OpenOCD supports generic Xtensa processors implementation which can be customized by +simply providing vendor-specific core configuration which controls every configurable +Xtensa architecture option, e.g. number of address registers, exceptions, reduced +size instructions support, memory banks configuration etc. Also OpenOCD supports SMP +configurations for Xtensa processors with any number of cores and allows to configure +their debug signals interconnection (so-called "break/stall networks") which control how +debug signals are distributed among cores. Xtensa "break networks" are compatible with +ARM's Cross Trigger Interface (CTI). For debugging code on Xtensa chips OpenOCD +uses JTAG protocol. Currently OpenOCD implements several Epsressif Xtensa-based chips of +@uref{https://www.espressif.com/en/products/socs, ESP32 family}. + +@subsection General Xtensa Commands + +@deffn {Command} {xtensa set_permissive} (0|1) +By default accessing memory beyond defined regions is forbidden. This commnd controls memory access address check. +When set to (1), skips access controls and address range check before read/write memory. +@end deffn + +@deffn {Command} {xtensa maskisr} (on|off) +Selects whether interrupts will be disabled during stepping over single instruction. The default configuration is (off). +@end deffn + +@deffn {Command} {xtensa smpbreak} [none|breakinout|runstall] | [BreakIn] [BreakOut] [RunStallIn] [DebugModeOut] +Configures debug signals connection ("break network") for currently selected core. +@itemize @bullet +@item @code{none} - Core's "break/stall network" is disconnected. Core is not affected by any debug +signal from other cores. +@item @code{breakinout} - Core's "break network" is fully connected (break inputs and outputs are enabled). +Core will receive debug break signals from other cores and send such signals to them. For example when another core +is stopped due to breakpoint hit this core will be stopped too and vice versa. +@item @code{runstall} - Core's "stall network" is fully connected (stall inputs and outputs are enabled). +This feature is not well implemented and tested yet. +@item @code{BreakIn} - Core's "break-in" signal is enabled. +Core will receive debug break signals from other cores. For example when another core is +stopped due to breakpoint hit this core will be stopped too. +@item @code{BreakOut} - Core's "break-out" signal is enabled. +Core will send debug break signal to other cores. For example when this core is +stopped due to breakpoint hit other cores with enabled break-in signals will be stopped too. +@item @code{RunStallIn} - Core's "runstall-in" signal is enabled. +This feature is not well implemented and tested yet. +@item @code{DebugModeOut} - Core's "debugmode-out" signal is enabled. +This feature is not well implemented and tested yet. +@end itemize +@end deffn + +@deffn {Command} {xtensa perfmon_enable}