of the Open On-Chip Debugger (OpenOCD).
@itemize @bullet
-@item Copyright @copyright{} 2008 The OpenOCD Project
+@item Copyright @copyright{} 2008-2022 The OpenOCD Project
@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
@item Copyright @copyright{} 2008-2010 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
@item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com}
@item @b{imx_gpio}
@* A NXP i.MX-based board (e.g. Wandboard) using the GPIO pins (should work on any i.MX processor).
+@item @b{am335xgpio}
+@* A Texas Instruments AM335x-based board (e.g. BeagleBone Black) using the GPIO pins of the expansion headers.
+
@item @b{jtag_vpi}
@* A JTAG driver acting as a client for the JTAG VPI server interface.
@* Link: @url{http://github.com/fjullien/jtag_vpi}
@item @b{vdebug}
@* A driver for Cadence virtual Debug Interface to emulated or simulated targets.
It implements a client connecting to the vdebug server, which in turn communicates
-with the emulated or simulated RTL model through a transactor. The current version
-supports only JTAG as a transport, but other virtual transports, like DAP are planned.
+with the emulated or simulated RTL model through a transactor. The driver supports
+JTAG and DAP-level transports.
@item @b{jtag_dpi}
@* A JTAG driver acting as a client for the SystemVerilog Direct Programming
@* A bitbang JTAG driver using Linux legacy sysfs GPIO.
This is deprecated from Linux v5.3; prefer using @b{linuxgpiod}.
+@item @b{esp_usb_jtag}
+@* A JTAG driver to communicate with builtin debug modules of Espressif ESP32-C3 and ESP32-S3 chips using OpenOCD.
+
@end itemize
@node About Jim-Tcl
@deffnx {Config Command} {pld init}
@deffnx {Command} {tpiu init}
@end deffn
+
+At last, @command{init} executes all the commands that are specified in
+the TCL list @var{post_init_commands}. The commands are executed in the
+same order they occupy in the list. If one of the commands fails, then
+the error is propagated and OpenOCD fails too.
+@example
+lappend post_init_commands @{echo "OpenOCD successfully initialized."@}
+lappend post_init_commands @{echo "Have fun with OpenOCD !"@}
+@end example
@end deffn
@deffn {Config Command} {noinit}
the hardware can support.
@end deffn
+@anchor{adapter gpio}
+@deffn {Config Command} {adapter gpio [ @
+ @option{tdo} | @option{tdi} | @option{tms} | @option{tck} | @option{trst} | @
+ @option{swdio} | @option{swdio_dir} | @option{swclk} | @option{srst} | @
+ @option{led} @
+ [ @
+ gpio_number | @option{-chip} chip_number | @
+ @option{-active-high} | @option{-active-low} | @
+ @option{-push-pull} | @option{-open-drain} | @option{-open-source} | @
+ @option{-pull-none} | @option{-pull-up} | @option{-pull-down} | @
+ @option{-init-inactive} | @option{-init-active} | @option{-init-input} @
+ ] ]}
+Define the GPIO mapping that the adapter will use. The following signals can be
+defined:
+
+@itemize @minus
+@item @option{tdo}, @option{tdi}, @option{tms}, @option{tck}, @option{trst}:
+JTAG transport signals
+@item @option{swdio}, @option{swclk}: SWD transport signals
+@item @option{swdio_dir}: optional swdio buffer control signal
+@item @option{srst}: system reset signal
+@item @option{led}: optional activity led
+
+@end itemize
+
+Some adapters require that the GPIO chip number is set in addition to the GPIO
+number. The configuration options enable signals to be defined as active-high or
+active-low. The output drive mode can be set to push-pull, open-drain or
+open-source. Most adapters will have to emulate open-drain or open-source drive
+modes by switching between an input and output. Input and output signals can be
+instructed to use a pull-up or pull-down resistor, assuming it is supported by
+the adaptor driver and hardware. The initial state of outputs may also be set,
+"active" state means 1 for active-high outputs and 0 for active-low outputs.
+Bidirectional signals may also be initialized as an input. If the swdio signal
+is buffered the buffer direction can be controlled with the swdio_dir signal;
+the active state means that the buffer should be set as an output with respect
+to the adapter. The command options are cumulative with later commands able to
+override settings defined by earlier ones. The two commands @command{gpio led 7
+-active-high} and @command{gpio led -chip 1 -active-low} sent sequentially are
+equivalent to issuing the single command @command{gpio led 7 -chip 1
+-active-low}. It is not permissible to set the drive mode or initial state for
+signals which are inputs. The drive mode for the srst and trst signals must be
+set with the @command{adapter reset_config} command. It is not permissible to
+set the initial state of swdio_dir as it is derived from the initial state of
+swdio. The command @command{adapter gpio} prints the current configuration for
+all GPIOs while the command @command{adapter gpio gpio_name} prints the current
+configuration for gpio_name. Not all adapters support this generic GPIO mapping,
+some require their own commands to define the GPIOs used. Adapters that support
+the generic mapping may not support all of the listed options.
+@end deffn
@deffn {Command} {adapter name}
Returns the name of the debug adapter driver being used.
peripherals' kernel drivers. The driver restores the previous
configuration on exit.
-GPIO numbers >= 32 can't be used for performance reasons.
+GPIO numbers >= 32 can't be used for performance reasons. GPIO configuration is
+handled by the generic command @ref{adapter gpio, @command{adapter gpio}}.
See @file{interface/raspberrypi-native.cfg} for a sample config and
pinout.
-@deffn {Config Command} {bcm2835gpio jtag_nums} @var{tck} @var{tms} @var{tdi} @var{tdo}
-Set JTAG transport GPIO numbers for TCK, TMS, TDI, and TDO (in that order).
-Must be specified to enable JTAG transport. These pins can also be specified
-individually.
-@end deffn
-
-@deffn {Config Command} {bcm2835gpio tck_num} @var{tck}
-Set TCK GPIO number. Must be specified to enable JTAG transport. Can also be
-specified using the configuration command @command{bcm2835gpio jtag_nums}.
-@end deffn
-
-@deffn {Config Command} {bcm2835gpio tms_num} @var{tms}
-Set TMS GPIO number. Must be specified to enable JTAG transport. Can also be
-specified using the configuration command @command{bcm2835gpio jtag_nums}.
-@end deffn
-
-@deffn {Config Command} {bcm2835gpio tdo_num} @var{tdo}
-Set TDO GPIO number. Must be specified to enable JTAG transport. Can also be
-specified using the configuration command @command{bcm2835gpio jtag_nums}.
-@end deffn
-
-@deffn {Config Command} {bcm2835gpio tdi_num} @var{tdi}
-Set TDI GPIO number. Must be specified to enable JTAG transport. Can also be
-specified using the configuration command @command{bcm2835gpio jtag_nums}.
-@end deffn
-
-@deffn {Config Command} {bcm2835gpio swd_nums} @var{swclk} @var{swdio}
-Set SWD transport GPIO numbers for SWCLK and SWDIO (in that order). Must be
-specified to enable SWD transport. These pins can also be specified individually.
-@end deffn
-
-@deffn {Config Command} {bcm2835gpio swclk_num} @var{swclk}
-Set SWCLK GPIO number. Must be specified to enable SWD transport. Can also be
-specified using the configuration command @command{bcm2835gpio swd_nums}.
-@end deffn
-
-@deffn {Config Command} {bcm2835gpio swdio_num} @var{swdio}
-Set SWDIO GPIO number. Must be specified to enable SWD transport. Can also be
-specified using the configuration command @command{bcm2835gpio swd_nums}.
-@end deffn
-
-@deffn {Config Command} {bcm2835gpio swdio_dir_num} @var{swdio} @var{dir}
-Set SWDIO direction control pin GPIO number. If specified, this pin can be used
-to control the direction of an external buffer on the SWDIO pin (set=output
-mode, clear=input mode). If not specified, this feature is disabled.
-@end deffn
-
-@deffn {Config Command} {bcm2835gpio srst_num} @var{srst}
-Set SRST GPIO number. Must be specified to enable SRST.
-@end deffn
-
-@deffn {Config Command} {bcm2835gpio trst_num} @var{trst}
-Set TRST GPIO number. Must be specified to enable TRST.
-@end deffn
-
@deffn {Config Command} {bcm2835gpio speed_coeffs} @var{speed_coeff} @var{speed_offset}
Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified,
speed_coeff defaults to 113714, and speed_offset defaults to 28.
@end deffn
+@deffn {Interface Driver} {am335xgpio} The AM335x SoC is present in BeagleBone
+Black and BeagleBone Green single-board computers which expose some of the GPIOs
+on the two expansion headers.
+
+For maximum performance the driver accesses memory-mapped GPIO peripheral
+registers directly. The memory mapping requires read and write permission to
+kernel memory; if /dev/gpiomem exists it will be used, otherwise /dev/mem will
+be used. The driver restores the GPIO state on exit.
+
+All four GPIO ports are available. GPIO configuration is handled by the generic
+command @ref{adapter gpio, @command{adapter gpio}}.
+
+@deffn {Config Command} {am335xgpio speed_coeffs} @var{speed_coeff} @var{speed_offset}
+Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified
+speed_coeff defaults to 600000 and speed_offset defaults to 575.
+@end deffn
+
+See @file{interface/beaglebone-swd-native.cfg} for a sample configuration file.
+
+@end deffn
+
+
@deffn {Interface Driver} {linuxgpiod}
-Linux provides userspace access to GPIO through libgpiod since Linux kernel version v4.6.
-The driver emulates either JTAG and SWD transport through bitbanging.
+Linux provides userspace access to GPIO through libgpiod since Linux kernel
+version v4.6. The driver emulates either JTAG or SWD transport through
+bitbanging. There are no driver-specific commands, all GPIO configuration is
+handled by the generic command @ref{adapter gpio, @command{adapter gpio}}. This
+driver supports the resistor pull options provided by the @command{adapter gpio}
+command but the underlying hardware may not be able to support them.
-See @file{interface/dln-2-gpiod.cfg} for a sample config.
+See @file{interface/dln-2-gpiod.cfg} for a sample configuration file.
@end deffn
@end deffn
+@deffn {Interface Driver} {esp_usb_jtag}
+Espressif JTAG driver to communicate with ESP32-C3, ESP32-S3 chips and ESP USB Bridge board using OpenOCD.
+These chips have built-in JTAG circuitry and can be debugged without any additional hardware.
+Only an USB cable connected to the D+/D- pins is necessary.
+
+@deffn {Config Command} {espusbjtag tdo}
+Returns the current state of the TDO line
+@end deffn
+
+@deffn {Config Command} {espusbjtag setio} setio
+Manually set the status of the output lines with the order of (tdi tms tck trst srst)
+@example
+espusbjtag setio 0 1 0 1 0
+@end example
+@end deffn
+
+@deffn {Config Command} {espusbjtag vid_pid} vid_pid
+Set vendor ID and product ID for the ESP usb jtag driver
+@example
+espusbjtag vid_pid 0x303a 0x1001
+@end example
+@end deffn
+
+@deffn {Config Command} {espusbjtag caps_descriptor} caps_descriptor
+Set the jtag descriptor to read capabilities of ESP usb jtag driver
+@example
+espusbjtag caps_descriptor 0x2000
+@end example
+@end deffn
+
+@deffn {Config Command} {espusbjtag chip_id} chip_id
+Set chip id to transfer to the ESP USB bridge board
+@example
+espusbjtag chip_id 1
+@end example
+@end deffn
+
+@end deffn
@section Transport Configuration
@cindex Transport
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.
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}
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]
@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]
Disabled by default
@end deffn
+@deffn {Config Command} {$dap_name nu_npcx_quirks} [@option{enable}]
+Set/get quirks mode for Nuvoton NPCX/NPCD MCU families
+Disabled by default
+@end deffn
@node CPU Configuration
@chapter CPU Configuration
@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.
@item @code{testee} -- a dummy target for cases without a real CPU, e.g. CPLD.
@item @code{xscale} -- this is actually an architecture,
not a CPU type. It is based on the ARMv5 architecture.
+@item @code{xtensa} -- this is a generic Cadence/Tensilica Xtensa core.
@end itemize
@end deffn
@anchor{rtostype}
@item @code{-rtos} @var{rtos_type} -- enable rtos support for target,
-@var{rtos_type} can be one of @option{auto}, @option{eCos},
+@var{rtos_type} can be one of @option{auto}, @option{none}, @option{eCos},
@option{ThreadX}, @option{FreeRTOS}, @option{linux}, @option{ChibiOS},
@option{embKernel}, @option{mqx}, @option{uCOS-III}, @option{nuttx},
@option{RIOT}, @option{Zephyr}
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.
@end example
@end deffn
+@deffn {Flash Driver} {rsl10}
+Supports Onsemi RSL10 microcontroller flash memory. Uses functions
+stored in ROM to control flash memory interface.
+
+@example
+flash bank $_FLASHNAME rsl10 $_FLASHBASE $_FLASHSIZE 0 0 $_TARGETNAME
+@end example
+
+@deffn {Command} {rsl10 lock} key1 key2 key3 key4
+Writes @var{key1 key2 key3 key4} words to @var{0x81044 0x81048 0x8104c
+0x8050}. Locks debug port by writing @var{0x4C6F634B} to @var{0x81040}.
+
+To unlock use the @command{rsl10 unlock key1 key2 key3 key4} command.
+@end deffn
+
+@deffn {Command} {rsl10 unlock} key1 key2 key3 key4
+Unlocks debug port, by writing @var{key1 key2 key3 key4} words to
+registers through DAP, and clears @var{0x81040} address in flash to 0x1.
+@end deffn
+
+@deffn {Command} {rsl10 mass_erase}
+Erases all unprotected flash sectors.
+@end deffn
+@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
other). If option @option{error} is used, OpenOCD will return a
non-zero exit code to the parent process.
-Like any TCL commands, also @command{shutdown} can be redefined, e.g.:
+If user types CTRL-C or kills OpenOCD, the command @command{shutdown}
+will be automatically executed to cause OpenOCD to exit.
+
+It is possible to specify, in the TCL list @var{pre_shutdown_commands} , a
+set of commands to be automatically executed before @command{shutdown} , e.g.:
@example
-# redefine shutdown
-rename shutdown original_shutdown
-proc shutdown @{@} @{
- puts "This is my implementation of shutdown"
- # my own stuff before exit OpenOCD
- original_shutdown
-@}
+lappend pre_shutdown_commands @{echo "Goodbye, my friend ..."@}
+lappend pre_shutdown_commands @{echo "see you soon !"@}
@end example
-If user types CTRL-C or kills OpenOCD, either the command @command{shutdown}
-or its replacement will be automatically executed before OpenOCD exits.
+The commands in the list will be executed (in the same order they occupy
+in the list) before OpenOCD exits. If one of the commands in the list
+fails, then the remaining commands are not executed anymore while OpenOCD
+will proceed to quit.
@end deffn
@anchor{debuglevel}
@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.
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
@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.
OpenOCD supports debugging STM8 through the STMicroelectronics debug
protocol SWIM, @pxref{swimtransport,,SWIM}.
+@section Xtensa Architecture
+
+Xtensa is a highly-customizable, user-extensible microprocessor and DSP
+architecture for complex embedded systems provided by Cadence Design
+Systems, Inc. See the
+@uref{https://www.cadence.com/en_US/home/tools/ip/tensilica-ip.html, Tensilica IP}
+website for additional information and documentation.
+
+OpenOCD supports generic Xtensa processor implementations which can be customized by
+providing a core-specific configuration file which describes every enabled
+Xtensa architecture option, e.g. number of address registers, exceptions, reduced
+size instructions support, memory banks configuration etc. OpenOCD also supports SMP
+configurations for Xtensa processors with any number of cores and allows configuring
+their debug interconnect (termed "break/stall networks"), which control how debug
+signals are distributed among cores. Xtensa "break networks" are compatible with
+ARM's Cross Trigger Interface (CTI). OpenOCD implements both generic Xtensa targets
+as well as several Espressif Xtensa-based chips from the
+@uref{https://www.espressif.com/en/products/socs, ESP32 family}.
+
+OCD sessions for Xtensa processor and DSP targets are accessed via the Xtensa
+Debug Module (XDM), which provides external connectivity either through a
+traditional JTAG interface or an ARM DAP interface. If used, the DAP interface
+can control Xtensa targets through JTAG or SWD probes.
+
+@subsection Xtensa Core Configuration
+
+Due to the high level of configurability in Xtensa cores, the Xtensa target
+configuration comprises two categories:
+
+@enumerate
+@item Base Xtensa support common to all core configurations, and
+@item Core-specific support as configured for individual cores.
+@end enumerate
+
+All common Xtensa support is built into the OpenOCD Xtensa target layer and
+is enabled through a combination of TCL scripts: the target-specific
+@file{target/xtensa.cfg} and a board-specific @file{board/xtensa-*.cfg},
+similar to other target architectures.
+
+Importantly, core-specific configuration information must be provided by
+the user, and takes the form of an @file{xtensa-core-XXX.cfg} TCL script that
+defines the core's configurable features through a series of Xtensa
+configuration commands (detailed below).
+
+This core-specific @file{xtensa-core-XXX.cfg} file is typically either:
+
+@itemize @bullet
+@item Located within the Xtensa core configuration build as
+@file{src/config/xtensa-core-openocd.cfg}, or
+@item Generated by running the command @code{xt-gdb --dump-oocd-config}
+from the Xtensa processor tool-chain's command-line tools.
+@end itemize
+
+NOTE: @file{xtensa-core-XXX.cfg} must match the target Xtensa hardware
+connected to OpenOCD.
+
+Some example Xtensa configurations are bundled with OpenOCD for reference:
+@itemize @bullet
+@item Cadence Palladium VDebug emulation target. The user can combine their
+@file{xtensa-core-XXX.cfg} with the provided
+@file{board/xtensa-palladium-vdebug.cfg} to debug an emulated Xtensa RTL design.
+@item NXP MIMXRT685-EVK evaluation kit. The relevant configuration files are
+@file{board/xtensa-rt685-jlink.cfg} and @file{board/xtensa-core-nxp_rt600.cfg}.
+Additional information is provided by
+@uref{https://www.nxp.com/design/development-boards/i-mx-evaluation-and-development-boards/i-mx-rt600-evaluation-kit:MIMXRT685-EVK,
+NXP}.
+@end itemize
+
+@subsection Xtensa Configuration Commands
+
+@deffn {Command} {xtensa xtdef} (@option{LX}|@option{NX})
+Configure the Xtensa target architecture. Currently, Xtensa support is limited
+to LX6, LX7, and NX cores.
+@end deffn
+
+@deffn {Command} {xtensa xtopt} option value
+Configure Xtensa target options that are relevant to the debug subsystem.
+@var{option} is one of: @option{arnum}, @option{windowed},
+@option{cpenable}, @option{exceptions}, @option{intnum}, @option{hipriints},
+@option{excmlevel}, @option{intlevels}, @option{debuglevel},
+@option{ibreaknum}, or @option{dbreaknum}. @var{value} is an integer with
+the exact range determined by each particular option.
+
+NOTE: Some options are specific to Xtensa LX or Xtensa NX architecture, while
+others may be common to both but have different valid ranges.
+@end deffn
+
+@deffn {Command} {xtensa xtmem} (@option{iram}|@option{dram}|@option{sram}|@option{irom}|@option{drom}|@option{srom}) baseaddr bytes
+Configure Xtensa target memory. Memory type determines access rights,
+where RAMs are read/write while ROMs are read-only. @var{baseaddr} and
+@var{bytes} are both integers, typically hexadecimal and decimal, respectively.
+@end deffn
+
+@deffn {Command} {xtensa xtmem} (@option{icache}|@option{dcache}) linebytes cachebytes ways [writeback]
+Configure Xtensa processor cache. All parameters are required except for
+the optional @option{writeback} parameter; all are integers.
+@end deffn
+
+@deffn {Command} {xtensa xtmpu} numfgseg minsegsz lockable execonly
+Configure an Xtensa Memory Protection Unit (MPU). MPUs can restrict access
+and/or control cacheability of specific address ranges, but are lighter-weight
+than a full traditional MMU. All parameters are required; all are integers.
+@end deffn
+
+@deffn {Command} {xtensa xtmmu} numirefillentries numdrefillentries
+(Xtensa-LX only) Configure an Xtensa Memory Management Unit (MMU). Both
+parameters are required; both are integers.
+@end deffn
+
+@deffn {Command} {xtensa xtregs} numregs
+Configure the total number of registers for the Xtensa core. Configuration
+logic expects to subsequently process this number of @code{xtensa xtreg}
+definitions. @var{numregs} is an integer.
+@end deffn
+
+@deffn {Command} {xtensa xtregfmt} (@option{sparse}|@option{contiguous}) [general]
+Configure the type of register map used by GDB to access the Xtensa core.
+Generic Xtensa tools (e.g. xt-gdb) require @option{sparse} mapping (default) while
+Espressif tools expect @option{contiguous} mapping. Contiguous mapping takes an
+additional, optional integer parameter @option{numgregs}, which specifies the number
+of general registers used in handling g/G packets.
+@end deffn
+
+@deffn {Command} {xtensa xtreg} name offset
+Configure an Xtensa core register. All core registers are 32 bits wide,
+while TIE and user registers may have variable widths. @var{name} is a
+character string identifier while @var{offset} is a hexadecimal integer.
+@end deffn
+
+@subsection Xtensa Operation Commands
+
+@deffn {Command} {xtensa maskisr} (@option{on}|@option{off})
+(Xtensa-LX only) Mask or unmask Xtensa interrupts during instruction step.
+When masked, an interrupt that occurs during a step operation is handled and
+its ISR is executed, with the user's debug session returning after potentially
+executing many instructions. When unmasked, a triggered interrupt will result
+in execution progressing the requested number of instructions into the relevant
+vector/ISR code.
+@end deffn
+
+@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 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 exe} <ascii-encoded hexadecimal instruction bytes>
+Execute arbitrary instruction(s) provided as an ascii string. The string represents an integer
+number of instruction bytes, thus its length must be even.
+@end deffn
+
+@subsection Xtensa Performance Monitor Configuration
+
+@deffn {Command} {xtensa perfmon_enable} <counter_id> <select> [mask] [kernelcnt] [tracelevel]
+Enable and start performance counter.
+@itemize @bullet
+@item @code{counter_id} - Counter ID (0-1).
+@item @code{select} - Selects performance metric to be counted by the counter,
+e.g. 0 - CPU cycles, 2 - retired instructions.
+@item @code{mask} - Selects input subsets to be counted (counter will
+increment only once even if more than one condition corresponding to a mask bit occurs).
+@item @code{kernelcnt} - 0 - count events with "CINTLEVEL <= tracelevel",
+1 - count events with "CINTLEVEL > tracelevel".
+@item @code{tracelevel} - Compares this value to "CINTLEVEL" when deciding
+whether to count.
+@end itemize
+@end deffn
+
+@deffn {Command} {xtensa perfmon_dump} (counter_id)
+Dump performance counter value. If no argument specified, dumps all counters.
+@end deffn
+
+@subsection Xtensa Trace Configuration
+
+@deffn {Command} {xtensa tracestart} [pc <pcval>/[<maskbitcount>]] [after <n> [ins|words]]
+Set up and start a HW trace. Optionally set PC address range to trigger tracing stop when reached during program execution.
+This command also allows to specify the amount of data to capture after stop trigger activation.
+@itemize @bullet
+@item @code{pcval} - PC value which will trigger trace data collection stop.
+@item @code{maskbitcount} - PC value mask.
+@item @code{n} - Maximum number of instructions/words to capture after trace stop trigger.
+@end itemize
+@end deffn
+
+@deffn {Command} {xtensa tracestop}
+Stop current trace as started by the tracestart command.
+@end deffn
+
+@deffn {Command} {xtensa tracedump} <outfile>
+Dump trace memory to a file.
+@end deffn
+
@anchor{softwaredebugmessagesandtracing}
@section Software Debug Messages and Tracing
@cindex Linux-ARM DCC support
@item @option{Zephyr}
@end itemize
+At any time, it's possible to drop the selected RTOS using:
+@example
+$_TARGETNAME configure -rtos none
+@end example
+
Before an RTOS can be detected, it must export certain symbols; otherwise, it cannot
be used by OpenOCD. Below is a list of the required symbols for each supported RTOS.
When the command ``proc'' is parsed (which creates a procedure
function) it gets 3 parameters on the command line. @b{1} the name of
the proc (function), @b{2} the list of parameters, and @b{3} the body
-of the function. Not the choice of words: LIST and BODY. The PROC
+of the function. Note the choice of words: LIST and BODY. The PROC
command stores these items in a table somewhere so it can be found by
``LookupCommand()''
Code Review / openocd.git / blobdiff