X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=2a8626b8040a08fdffb66d32fa615a2612cd8b82;hb=eb3d5c1a945fb09a76d9d4cb20aba903fc6e53c2;hp=27a552286f1cb7445c851473414edba0ed09163e;hpb=ace028262ba0bda0e921afb11e6eb7d87708d889;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 27a552286f..2a8626b804 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -19,7 +19,7 @@ dated @value{UPDATED}, 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} @@ -3292,66 +3292,12 @@ able to coexist nicely with both sysfs bitbanging and various 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. @@ -3401,87 +3347,14 @@ See @file{interface/beaglebone-swd-native.cfg} for a sample configuration file. @deffn {Interface Driver} {linuxgpiod} -Linux provides userspace access to GPIO through libgpiod since Linux kernel version v4.6. -The driver emulates either JTAG or SWD transport through bitbanging. - -See @file{interface/dln-2-gpiod.cfg} for a sample config. - -@deffn {Config Command} {linuxgpiod gpiochip} @var{chip} -Set the GPIO chip number for all GPIOs used by linuxgpiod. If GPIOs use -different GPIO chips then the individual GPIO configuration commands (i.e., not -@command{linuxgpiod jtag_nums} or @command{linuxgpiod swd_nums}) can be used to -set chip numbers independently for each GPIO. -@end deffn - -@deffn {Config Command} {linuxgpiod 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} {linuxgpiod tck_num} [@var{chip}] @var{tck} -Set TCK GPIO number, and optionally TCK chip number. Must be specified to enable -JTAG transport. Can also be specified using the configuration command -@command{linuxgpiod jtag_nums}. -@end deffn - -@deffn {Config Command} {linuxgpiod tms_num} [@var{chip}] @var{tms} -Set TMS GPIO number, and optionally TMS chip number. Must be specified to enable -JTAG transport. Can also be specified using the configuration command -@command{linuxgpiod jtag_nums}. -@end deffn - -@deffn {Config Command} {linuxgpiod tdo_num} [@var{chip}] @var{tdo} -Set TDO GPIO number, and optionally TDO chip number. Must be specified to enable -JTAG transport. Can also be specified using the configuration command -@command{linuxgpiod jtag_nums}. -@end deffn - -@deffn {Config Command} {linuxgpiod tdi_num} [@var{chip}] @var{tdi} -Set TDI GPIO number, and optionally TDI chip number. Must be specified to enable -JTAG transport. Can also be specified using the configuration command -@command{linuxgpiod jtag_nums}. -@end deffn - -@deffn {Config Command} {linuxgpiod trst_num} [@var{chip}] @var{trst} -Set TRST GPIO number, and optionally TRST chip number. Must be specified to -enable TRST. -@end deffn - -@deffn {Config Command} {linuxgpiod 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} {linuxgpiod swclk_num} [@var{chip}] @var{swclk} -Set SWCLK GPIO number, and optionally SWCLK chip number. Must be specified to -enable SWD transport. Can also be specified using the configuration command -@command{linuxgpiod swd_nums}. -@end deffn - -@deffn {Config Command} {linuxgpiod swdio_num} [@var{chip}] @var{swdio} -Set SWDIO GPIO number, and optionally SWDIO chip number. Must be specified to -enable SWD transport. Can also be specified using the configuration command -@command{linuxgpiod swd_nums}. -@end deffn - -@deffn {Config Command} {linuxgpiod swdio_dir_num} [@var{chip}] @var{swdio_dir} -Set SWDIO direction control GPIO number, and optionally SWDIO direction control -chip number. If specified, this GPIO can be used to control the direction of an -external buffer connected to the SWDIO GPIO (set=output mode, clear=input mode). -@end deffn - -@deffn {Config Command} {linuxgpiod srst_num} [@var{chip}] @var{srst} -Set SRST GPIO number, and optionally SRST chip number. Must be specified to -enable SRST. -@end deffn - -@deffn {Config Command} {linuxgpiod led_num} [@var{chip}] @var{led} -Set activity LED GPIO number, and optionally activity LED chip number. If not -specified an activity LED is not enabled. -@end deffn +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 configuration file. @end deffn @@ -4979,6 +4852,7 @@ And two debug interfaces cores: @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 @@ -7468,6 +7342,31 @@ flash bank $_FLASHNAME rp2040_flash $_FLASHBASE $_FLASHSIZE 1 32 $_TARGETNAME @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 @@ -11008,33 +10907,150 @@ 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 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. 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 +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}. -@subsection General Xtensa Commands +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 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 @@ -11058,6 +11074,13 @@ This feature is not well implemented and tested yet. @end itemize @end deffn +@deffn {Command} {xtensa exe} +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}