@item @b{TI XDS110 Debug Probe}
@* The XDS110 is included as the embedded debug probe on many Texas Instruments
LaunchPad evaluation boards.
+@* The XDS110 is also available as a stand-alone USB debug probe. The XDS110
+stand-alone probe has the additional ability to supply voltage to the target
+board via its AUX FUNCTIONS port. Use the
+@command{xds110_supply_voltage <millivolts>} command to set the voltage. 0 turns
+off the supply. Otherwise, the supply can be set to any value in the range 1800
+to 3600 millivolts.
@* Link: @url{http://processors.wiki.ti.com/index.php/XDS110}
@* Link: @url{http://processors.wiki.ti.com/index.php/XDS_Emulation_Software_Package#XDS110_Support_Utilities}
@end itemize
The SMP behaviour can be disabled/enabled dynamically. On cortex_a following
command have been implemented.
@itemize @bullet
-@item cortex_a smp_on : enable SMP mode, behaviour is as described above.
-@item cortex_a smp_off : disable SMP mode, the current target is the one
+@item cortex_a smp on : enable SMP mode, behaviour is as described above.
+@item cortex_a smp off : disable SMP mode, the current target is the one
displayed in the GDB session, only this target is now controlled by GDB
session. This behaviour is useful during system boot up.
+@item cortex_a smp : display current SMP mode.
@item cortex_a smp_gdb : display/fix the core id displayed in GDB session see
following example.
@end itemize
Returns the name of the debug adapter driver being used.
@end deffn
+@anchor{adapter_usb_location}
+@deffn Command {adapter usb location} <bus>-<port>[.<port>]...
+Specifies the physical USB port of the adapter to use. The path
+roots at @var{bus} and walks down the physical ports, with each
+@var{port} option specifying a deeper level in the bus topology, the last
+@var{port} denoting where the target adapter is actually plugged.
+The USB bus topology can be queried with the command @emph{lsusb -t} or @emph{dmesg}.
+
+This command is only available if your libusb1 is at least version 1.0.16.
+@end deffn
+
@section Interface Drivers
Each of the interface drivers listed here must be explicitly
and are not restricted to containing only decimal digits.)
@end deffn
-@deffn {Config Command} {ftdi_location} <bus>:<port>[,<port>]...
+@deffn {Config Command} {ftdi_location} <bus>-<port>[.<port>]...
+@emph{DEPRECATED -- avoid using this.
+Use the @xref{adapter_usb_location, adapter usb location} command instead.}
+
Specifies the physical USB port of the adapter to use. The path
roots at @var{bus} and walks down the physical ports, with each
@var{port} option specifying a deeper level in the bus topology, the last
nTRST (active-low JTAG TAP reset) before starting new JTAG operations.
@end deffn
+@anchor {reset_config}
@deffn {Command} reset_config mode_flag ...
This command displays or modifies the reset configuration
of your combination of JTAG board and target in target
@section Other TAP commands
+@deffn Command {jtag cget} dotted.name @option{-idcode}
+Get the value of the IDCODE found in hardware.
+@end deffn
+
@deffn Command {jtag cget} dotted.name @option{-event} event_name
@deffnx Command {jtag configure} dotted.name @option{-event} event_name handler
At this writing this TAP attribute
-mechanism is used only for event handling.
+mechanism is limited and used mostly for event handling.
(It is not a direct analogue of the @code{cget}/@code{configure}
mechanism for debugger targets.)
See the next section for information about the available events.
The current implementation supports eSi-32xx cores.
@item @code{fa526} -- resembles arm920 (w/o Thumb)
@item @code{feroceon} -- resembles arm926
+@item @code{mem_ap} -- this is an ARM debug infrastructure Access Port without a CPU, through which bus read and write cycles can be generated; it may be useful for working with non-CPU hardware behind an AP or during development of support for new CPUs.
@item @code{mips_m4k} -- a MIPS core
@item @code{xscale} -- this is actually an architecture,
not a CPU type. It is based on the ARMv5 architecture.
@item @code{ls1_sap} -- this is the SAP on NXP LS102x CPUs,
allowing access to physical memory addresses independently of CPU cores.
@itemize @minus
-@item @code{OpenCores TAP} (See: @url{http://opencores.org/project,jtag})
+@item @code{OpenCores TAP} (See: @url{http://opencores.org/project@comma{}jtag})
@item @code{Altera Virtual JTAG TAP} (See: @url{http://www.altera.com/literature/ug/ug_virtualjtag.pdf})
@item @code{Xilinx BSCAN_* virtual JTAG interface} (See: @url{http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_2/spartan6_hdl.pdf})
@end itemize
And two debug interfaces cores:
@itemize @minus
-@item @code{Advanced debug interface} (See: @url{http://opencores.org/project,adv_debug_sys})
-@item @code{SoC Debug Interface} (See: @url{http://opencores.org/project,dbg_interface})
+@item @code{Advanced debug interface} (See: @url{http://opencores.org/project@comma{}adv_debug_sys})
+@item @code{SoC Debug Interface} (See: @url{http://opencores.org/project@comma{}dbg_interface})
@end itemize
@end itemize
@end deffn
CS1/CS2 is routed to on the given SoC.
@example
-flash bank $_FLASHNAME ath79 0 0 0 0 $_TARGETNAME
+flash bank $_FLASHNAME ath79 0xbf000000 0 0 0 $_TARGETNAME
# When using multiple chipselects the base should be different for each,
# otherwise the write_image command is not able to distinguish the
# banks.
-flash bank flash0 ath79 0x00000000 0 0 0 $_TARGETNAME cs0
+flash bank flash0 ath79 0xbf000000 0 0 0 $_TARGETNAME cs0
flash bank flash1 ath79 0x10000000 0 0 0 $_TARGETNAME cs1
flash bank flash2 ath79 0x20000000 0 0 0 $_TARGETNAME cs2
@end example
@end deffn
+@deffn {Flash Driver} fespi
+@cindex Freedom E SPI
+@cindex fespi
+
+SiFive's Freedom E SPI controller, used in HiFive and other boards.
+
+@example
+flash bank $_FLASHNAME fespi 0x20000000 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
@subsection Internal Flash (Microcontrollers)
@deffn {Flash Driver} aduc702x
@anchor{at91samd}
@deffn {Flash Driver} at91samd
@cindex at91samd
-All members of the ATSAMD, ATSAMR, ATSAML and ATSAMC microcontroller
+All members of the ATSAM D2x, D1x, D0x, ATSAMR, ATSAML and ATSAMC microcontroller
families from Atmel include internal flash and use ARM's Cortex-M0+ core.
-This driver uses the same command names/syntax as @xref{at91sam3}.
+
+Do not use for ATSAM D51 and E5x: use @xref{atsame5}.
+
+The devices have one flash bank:
+
+@example
+flash bank $_FLASHNAME at91samd 0x00000000 0 1 1 $_TARGETNAME
+@end example
@deffn Command {at91samd chip-erase}
Issues a complete Flash erase via the Device Service Unit (DSU). This can be
@end deffn
@end deffn
+@anchor{atsame5}
+@deffn {Flash Driver} atsame5
+@cindex atsame5
+All members of the SAM E54, E53, E51 and D51 microcontroller
+families from Microchip (former Atmel) include internal flash
+and use ARM's Cortex-M4 core.
+
+The devices have two ECC flash banks with a swapping feature.
+This driver handles both banks together as it were one.
+Bank swapping is not supported yet.
+
+@example
+flash bank $_FLASHNAME atsame5 0x00000000 0 1 1 $_TARGETNAME
+@end example
+
+@deffn Command {atsame5 bootloader}
+Shows or sets the bootloader size configuration, stored in the User Page of the
+Flash. This is called the BOOTPROT region. When setting, the bootloader size
+must be specified in bytes. The nearest bigger protection size is used.
+Settings are written immediately but only take effect on MCU reset.
+Setting the bootloader size to 0 disables bootloader protection.
+
+@example
+atsame5 bootloader
+atsame5 bootloader 16384
+@end example
+@end deffn
+
+@deffn Command {atsame5 chip-erase}
+Issues a complete Flash erase via the Device Service Unit (DSU). This can be
+used to erase a chip back to its factory state and does not require the
+processor to be halted.
+@end deffn
+
+@deffn Command {atsame5 dsu_reset_deassert}
+This command releases internal reset held by DSU
+and prepares reset vector catch in case of reset halt.
+Command is used internally in event event reset-deassert-post.
+@end deffn
+
+@deffn Command {atsame5 userpage}
+Writes or reads the first 64 bits of NVM User Page which is located at
+0x804000. This field includes various fuses.
+Reading is done by invoking this command without any arguments.
+Writing is possible by giving 1 or 2 hex values. The first argument
+is the value to be written and the second one is an optional bit mask
+(a zero bit in the mask means the bit stays unchanged).
+The reserved fields are always masked out and cannot be changed.
+
+@example
+# Read
+>atsame5 userpage
+USER PAGE: 0xAEECFF80FE9A9239
+# Write
+>atsame5 userpage 0xAEECFF80FE9A9239
+# Write 2 to SEESBLK and 4 to SEEPSZ fields but leave other bits unchanged
+# (setup SmartEEPROM of virtual size 8192 bytes)
+>atsame5 userpage 0x4200000000 0x7f00000000
+@end example
+@end deffn
+
+@end deffn
+
@deffn {Flash Driver} atsamv
@cindex atsamv
-All members of the ATSAMV, ATSAMS, and ATSAME families from
+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}.
@end deffn
frequency, and @option{wait_states} is the number of configured read wait states.
@example
-flash bank $_FLASHNAME esirisc base_address size_bytes 0 0 $_TARGETNAME cfg_address clock_hz wait_states
+flash bank $_FLASHNAME esirisc base_address size_bytes 0 0 \
+ $_TARGETNAME cfg_address clock_hz wait_states
@end example
-@deffn Command {esirisc_flash mass_erase} (bank_id)
-Erases all pages in data memory for the bank identified by @option{bank_id}.
+@deffn Command {esirisc flash mass_erase} bank_id
+Erase all pages in data memory for the bank identified by @option{bank_id}.
@end deffn
-@deffn Command {esirisc_flash ref_erase} (bank_id)
-Erases the reference cell for the bank identified by @option{bank_id}. This is
-an uncommon operation.
+@deffn Command {esirisc flash ref_erase} bank_id
+Erase the reference cell for the bank identified by @option{bank_id}. @emph{This
+is an uncommon operation.}
@end deffn
@end deffn
@deffn {Flash Driver} lpc2000
This is the driver to support internal flash of all members of the
LPC11(x)00 and LPC1300 microcontroller families and most members of
-the LPC800, LPC1500, LPC1700, LPC1800, LPC2000, LPC4000 and LPC54100
-microcontroller families from NXP.
+the LPC800, LPC1500, LPC1700, LPC1800, LPC2000, LPC4000, LPC54100,
+LPC8Nxx and NHS31xx microcontroller families from NXP.
@quotation Note
There are LPC2000 devices which are not supported by the @var{lpc2000}
The LPC29xx family is supported by the @var{lpc2900} driver.
@end quotation
-The @var{lpc2000} driver defines two mandatory and one optional parameters,
+The @var{lpc2000} driver defines two mandatory and two optional parameters,
which must appear in the following order:
@itemize
@option{lpc54100} (LPC541xx)
@option{lpc4000} (LPC40xx)
or @option{auto} - automatically detects flash variant and size for LPC11(x)00,
-LPC8xx, LPC13xx, LPC17xx and LPC40xx
+LPC8xx, LPC13xx, LPC17xx, LPC40xx, LPC8Nxx and NHS31xx
@item @var{clock_kHz} ... the frequency, in kiloHertz,
at which the core is running
@item @option{calc_checksum} ... optional (but you probably want to provide this!),
However, if you do provide it,
with most tool chains @command{verify_image} will fail.
@end quotation
+@item @option{iap_entry} ... optional telling the driver to use a different
+ROM IAP entry point.
@end itemize
LPC flashes don't require the chip and bus width to be specified.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32f1x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP})
+@deffn Command {stm32f1x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP}) (@option{USEROPT} user_data)
Writes the stm32 option byte with the specified values.
The @var{num} parameter is a value shown by @command{flash banks}.
+The @var{user_data} parameter is content of higher 16 bits of the option byte register (Data0 and Data1 as one 16bit number).
@end deffn
@deffn Command {stm32f1x options_load} num
flash bank $_FLASHNAME stm32f2x 0 0 0 0 $_TARGETNAME
@end example
+If you use OTP (One-Time Programmable) memory define it as a second bank
+as per the following example.
+@example
+flash bank $_FLASHNAME stm32f2x 0x1FFF7800 0 0 0 $_TARGETNAME
+@end example
+
+@deffn Command {stm32f2x otp } num (@option{enable}|@option{disable}|@option{show})
+Enables or disables OTP write commands for bank @var{num}.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
Note that some devices have been found that have a flash size register that contains
an invalid value, to workaround this issue you can override the probed value used by
the flash driver.
@end deffn
@end deffn
+@deffn {Flash Driver} w600
+W60x series Wi-Fi SoC from WinnerMicro
+are designed with ARM Cortex-M3 and have 1M Byte QFLASH inside.
+The @var{w600} driver uses the @var{target} parameter to select the
+correct bank config.
+
+@example
+flash bank $_FLASHNAME w600 0x08000000 0 0 0 $_TARGETNAMEs
+@end example
+@end deffn
+
@deffn {Flash Driver} xmc1xxx
All members of the XMC1xxx microcontroller family from Infineon.
This driver does not require the chip and bus width to be specified.
Enables debug by unlocking the Software Lock and clearing sticky powerdown indications
@end deffn
-@deffn Command {cortex_a smp_off}
-Disable SMP mode
-@end deffn
-
-@deffn Command {cortex_a smp_on}
-Enable SMP mode
+@deffn Command {cortex_a smp} [on|off]
+Display/set the current SMP mode
@end deffn
@deffn Command {cortex_a smp_gdb} [core_id]
@subsection Cortex-M specific commands
@cindex Cortex-M
-@deffn Command {cortex_m maskisr} (@option{auto}|@option{on}|@option{off})
+@deffn Command {cortex_m maskisr} (@option{auto}|@option{on}|@option{off}|@option{steponly})
Control masking (disabling) interrupts during target step/resume.
The @option{auto} option handles interrupts during stepping in a way that they
are enabled again. If the interrupt handlers don't complete within 500ms,
the step command leaves with the core running.
+The @option{steponly} option disables interrupts during single-stepping but
+enables them during normal execution. This can be used as a partial workaround
+for 702596 erratum in Cortex-M7 r0p1. See "Cortex-M7 (AT610) and Cortex-M7 with
+FPU (AT611) Software Developer Errata Notice" from ARM for further details.
+
Note that a free hardware (FPB) breakpoint is required for the @option{auto}
option. If no breakpoint is available at the time of the step, then the step
is taken with interrupts enabled, i.e. the same way the @option{off} option
This finishes by listing the current vector catch configuration.
@end deffn
-@deffn Command {cortex_m reset_config} (@option{srst}|@option{sysresetreq}|@option{vectreset})
-Control reset handling. The default @option{srst} is to use srst if fitted,
-otherwise fallback to @option{vectreset}.
+@deffn Command {cortex_m reset_config} (@option{sysresetreq}|@option{vectreset})
+Control reset handling if hardware srst is not fitted
+@xref{reset_config,,reset_config}.
+
@itemize @minus
-@item @option{srst} use hardware srst if fitted otherwise fallback to @option{vectreset}.
-@item @option{sysresetreq} use NVIC SYSRESETREQ to reset system.
-@item @option{vectreset} use NVIC VECTRESET to reset system.
+@item @option{sysresetreq} use AIRCR SYSRESETREQ to reset system.
+@item @option{vectreset} use AIRCR VECTRESET to reset system (default).
@end itemize
-Using @option{vectreset} is a safe option for all current Cortex-M cores.
+
+Using @option{vectreset} is a safe option for Cortex-M3, M4 and M7 cores.
This however has the disadvantage of only resetting the core, all peripherals
-are unaffected. A solution would be to use a @code{reset-init} event handler to manually reset
-the peripherals.
+are unaffected. A solution would be to use a @code{reset-init} event handler
+to manually reset the peripherals.
@xref{targetevents,,Target Events}.
+
+Cortex-M0, M0+ and M1 do not support @option{vectreset}, use @option{sysresetreq}
+instead.
@end deffn
@subsection ARMv8-A specific commands
However, normally it is not necessary to use the command at all.
@end deffn
-@deffn Command {aarch64 smp_on|smp_off}
-Enable and disable SMP handling. The state of SMP handling influences the way targets in an SMP group
+@deffn Command {aarch64 smp} [on|off]
+Display, enable or disable SMP handling mode. The state of SMP handling influences the way targets in an SMP group
are handled by the run control. With SMP handling enabled, issuing halt or resume to one core will trigger
halting or resuming of all cores in the group. The command @code{target smp} defines which targets are in the SMP
group. With SMP handling disabled, all targets need to be treated individually.
eSi-RISC is a highly configurable microprocessor architecture for embedded systems
provided by EnSilica. (See: @url{http://www.ensilica.com/risc-ip/}.)
-@subsection esirisc specific commands
+@subsection eSi-RISC Configuration
+
@deffn Command {esirisc cache_arch} (@option{harvard}|@option{von_neumann})
Configure the caching architecture. Targets with the @code{UNIFIED_ADDRESS_SPACE}
option disabled employ a Harvard architecture. By default, @option{von_neumann} is assumed.
@end deffn
-@deffn Command {esirisc flush_caches}
-Flush instruction and data caches. This command requires that the target is halted
-when the command is issued and configured with an instruction or data cache.
-@end deffn
-
@deffn Command {esirisc hwdc} (@option{all}|@option{none}|mask ...)
Configure hardware debug control. The HWDC register controls which exceptions return
control back to the debugger. Possible masks are @option{all}, @option{none},
By default, @option{reset}, @option{error}, and @option{debug} are enabled.
@end deffn
+@subsection eSi-RISC Operation
+
+@deffn Command {esirisc flush_caches}
+Flush instruction and data caches. This command requires that the target is halted
+when the command is issued and configured with an instruction or data cache.
+@end deffn
+
+@subsection eSi-Trace Configuration
+
+eSi-RISC targets may be configured with support for instruction tracing. Trace
+data may be written to an in-memory buffer or FIFO. If a FIFO is configured, DMA
+is typically employed to move trace data off-device using a high-speed
+peripheral (eg. SPI). Collected trace data is encoded in one of three different
+formats. At a minimum, @command{esirisc trace buffer} or @command{esirisc trace
+fifo} must be issued along with @command{esirisc trace format} before trace data
+can be collected.
+
+OpenOCD provides rudimentary analysis of collected trace data. If more detail is
+needed, collected trace data can be dumped to a file and processed by external
+tooling.
+
+@quotation Issues
+OpenOCD is unable to process trace data sent to a FIFO. A potential workaround
+for this issue is to configure DMA to copy trace data to an in-memory buffer,
+which can then be passed to the @command{esirisc trace analyze} and
+@command{esirisc trace dump} commands.
+
+It is possible to corrupt trace data when using a FIFO if the peripheral
+responsible for draining data from the FIFO is not fast enough. This can be
+managed by enabling flow control, however this can impact timing-sensitive
+software operation on the CPU.
+@end quotation
+
+@deffn Command {esirisc trace buffer} address size [@option{wrap}]
+Configure trace buffer using the provided address and size. If the @option{wrap}
+option is specified, trace collection will continue once the end of the buffer
+is reached. By default, wrap is disabled.
+@end deffn
+
+@deffn Command {esirisc trace fifo} address
+Configure trace FIFO using the provided address.
+@end deffn
+
+@deffn Command {esirisc trace flow_control} (@option{enable}|@option{disable})
+Enable or disable stalling the CPU to collect trace data. By default, flow
+control is disabled.
+@end deffn
+
+@deffn Command {esirisc trace format} (@option{full}|@option{branch}|@option{icache}) pc_bits
+Configure trace format and number of PC bits to be captured. @option{pc_bits}
+must be within 1 and 31 as the LSB is not collected. If external tooling is used
+to analyze collected trace data, these values must match.
+
+Supported trace formats:
+@itemize
+@item @option{full} capture full trace data, allowing execution history and
+timing to be determined.
+@item @option{branch} capture taken branch instructions and branch target
+addresses.
+@item @option{icache} capture instruction cache misses.
+@end itemize
+@end deffn
+
+@deffn Command {esirisc trace trigger start} (@option{condition}) [start_data start_mask]
+Configure trigger start condition using the provided start data and mask. A
+brief description of each condition is provided below; for more detail on how
+these values are used, see the eSi-RISC Architecture Manual.
+
+Supported conditions:
+@itemize
+@item @option{none} manual tracing (see @command{esirisc trace start}).
+@item @option{pc} start tracing if the PC matches start data and mask.
+@item @option{load} start tracing if the effective address of a load
+instruction matches start data and mask.
+@item @option{store} start tracing if the effective address of a store
+instruction matches start data and mask.
+@item @option{exception} start tracing if the EID of an exception matches start
+data and mask.
+@item @option{eret} start tracing when an @code{ERET} instruction is executed.
+@item @option{wait} start tracing when a @code{WAIT} instruction is executed.
+@item @option{stop} start tracing when a @code{STOP} instruction is executed.
+@item @option{high} start tracing when an external signal is a logical high.
+@item @option{low} start tracing when an external signal is a logical low.
+@end itemize
+@end deffn
+
+@deffn Command {esirisc trace trigger stop} (@option{condition}) [stop_data stop_mask]
+Configure trigger stop condition using the provided stop data and mask. A brief
+description of each condition is provided below; for more detail on how these
+values are used, see the eSi-RISC Architecture Manual.
+
+Supported conditions:
+@itemize
+@item @option{none} manual tracing (see @command{esirisc trace stop}).
+@item @option{pc} stop tracing if the PC matches stop data and mask.
+@item @option{load} stop tracing if the effective address of a load
+instruction matches stop data and mask.
+@item @option{store} stop tracing if the effective address of a store
+instruction matches stop data and mask.
+@item @option{exception} stop tracing if the EID of an exception matches stop
+data and mask.
+@item @option{eret} stop tracing when an @code{ERET} instruction is executed.
+@item @option{wait} stop tracing when a @code{WAIT} instruction is executed.
+@item @option{stop} stop tracing when a @code{STOP} instruction is executed.
+@end itemize
+@end deffn
+
+@deffn Command {esirisc trace trigger delay} (@option{trigger}) [cycles]
+Configure trigger start/stop delay in clock cycles.
+
+Supported triggers:
+@itemize
+@item @option{none} no delay to start or stop collection.
+@item @option{start} delay @option{cycles} after trigger to start collection.
+@item @option{stop} delay @option{cycles} after trigger to stop collection.
+@item @option{both} delay @option{cycles} after both triggers to start or stop
+collection.
+@end itemize
+@end deffn
+
+@subsection eSi-Trace Operation
+
+@deffn Command {esirisc trace init}
+Initialize trace collection. This command must be called any time the
+configuration changes. If an trace buffer has been configured, the contents will
+be overwritten when trace collection starts.
+@end deffn
+
+@deffn Command {esirisc trace info}
+Display trace configuration.
+@end deffn
+
+@deffn Command {esirisc trace status}
+Display trace collection status.
+@end deffn
+
+@deffn Command {esirisc trace start}
+Start manual trace collection.
+@end deffn
+
+@deffn Command {esirisc trace stop}
+Stop manual trace collection.
+@end deffn
+
+@deffn Command {esirisc trace analyze} [address size]
+Analyze collected trace data. This command may only be used if a trace buffer
+has been configured. If a trace FIFO has been configured, trace data must be
+copied to an in-memory buffer identified by the @option{address} and
+@option{size} options using DMA.
+@end deffn
+
+@deffn Command {esirisc trace dump} [address size] @file{filename}
+Dump collected trace data to file. This command may only be used if a trace
+buffer has been configured. If a trace FIFO has been configured, trace data must
+be copied to an in-memory buffer identified by the @option{address} and
+@option{size} options using DMA.
+@end deffn
+
+@deffn Command {$target_name catch_exc} [@option{off}|@option{sec_el1}|@option{sec_el3}|@option{nsec_el1}|@option{nsec_el2}]+
+Cause @command{$target_name} to halt when an exception is taken. Any combination of
+Secure (sec) EL1/EL3 or Non-Secure (nsec) EL1/EL2 is valid. The target
+@command{$target_name} will halt before taking the exception. In order to resume
+the target, the exception catch must be disabled again with @command{$target_name catch_exc off}.
+Issuing the command without options prints the current configuration.
+@end deffn
+
@section Intel Architecture
Intel Quark X10xx is the first product in the Quark family of SoCs. It is an IA-32
CSRs.
@end deffn
+@deffn Command {riscv expose_custom} n0[-m0][,n1[-m1]]...
+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`.
+@end deffn
+
@deffn Command {riscv set_command_timeout_sec} [seconds]
Set the wall-clock timeout (in seconds) for individual commands. The default
should work fine for all but the slowest targets (eg. simulators).
use the Program Buffer to access memory.
@end deffn
+@deffn Command {riscv set_ir} (@option{idcode}|@option{dtmcs}|@option{dmi}) [value]
+Set the IR value for the specified JTAG register. This is useful, for
+example, when using the existing JTAG interface on a Xilinx FPGA by
+way of BSCANE2 primitives that only permit a limited selection of IR
+values.
+
+When utilizing version 0.11 of the RISC-V Debug Specification,
+@option{dtmcs} and @option{dmi} set the IR values for the DTMCONTROL
+and DBUS registers, respectively.
+@end deffn
+
@subsection RISC-V Authentication Commands
The following commands can be used to authenticate to a RISC-V system. Eg. a
Do not use this mode under an IDE like Eclipse as it caches values of
previously shown varibles.
-@anchor{usingopenocdsmpwithgdb}
-@section Using OpenOCD SMP with GDB
-@cindex SMP
-For SMP support following GDB serial protocol packet have been defined :
-@itemize @bullet
-@item j - smp status request
-@item J - smp set request
-@end itemize
-
-OpenOCD implements :
-@itemize @bullet
-@item @option{jc} packet for reading core id displayed by
-GDB connection. Reply is @option{XXXXXXXX} (8 hex digits giving core id) or
- @option{E01} for target not smp.
-@item @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue
-(core id -1 is reserved for returning to normal resume mode). Reply @option{E01}
-for target not smp or @option{OK} on success.
-@end itemize
-
-Handling of this packet within GDB can be done :
-@itemize @bullet
-@item by the creation of an internal variable (i.e @option{_core}) by mean
-of function allocate_computed_value allowing following GDB command.
-@example
-set $_core 1
-#Jc01 packet is sent
-print $_core
-#jc packet is sent and result is affected in $
-@end example
-
-@item by the usage of GDB maintenance command as described in following example (2 cpus in SMP with
-core id 0 and 1 @pxref{definecputargetsworkinginsmp,,Define CPU targets working in SMP}).
-
-@example
-# toggle0 : force display of coreid 0
-define toggle0
-maint packet Jc0
-continue
-main packet Jc-1
-end
-# toggle1 : force display of coreid 1
-define toggle1
-maint packet Jc1
-continue
-main packet Jc-1
-end
-@end example
-@end itemize
-
@section RTOS Support
@cindex RTOS Support
@anchor{gdbrtossupport}
@item @option{mqx}
@item @option{uCOS-III}
@item @option{nuttx}
+@item @option{hwthread} (This is not an actual RTOS. @xref{usingopenocdsmpwithgdb,,Using OpenOCD SMP with GDB}.)
@end itemize
-@quotation Note
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.
-@end quotation
@table @code
@item eCos symbols
contrib/rtos-helpers/uCOS-III-openocd.c
@end table
+@anchor{usingopenocdsmpwithgdb}
+@section Using OpenOCD SMP with GDB
+@cindex SMP
+@cindex RTOS
+@cindex hwthread
+OpenOCD includes a pseudo RTOS called @emph{hwthread} that presents CPU cores
+("hardware threads") in an SMP system as threads to GDB. With this extension,
+GDB can be used to inspect the state of an SMP system in a natural way.
+After halting the system, using the GDB command @command{info threads} will
+list the context of each active CPU core in the system. GDB's @command{thread}
+command can be used to switch the view to a different CPU core.
+The @command{step} and @command{stepi} commands can be used to step a specific core
+while other cores are free-running or remain halted, depending on the
+scheduler-locking mode configured in GDB.
+
+@section Legacy SMP core switching support
+@quotation Note
+This method is deprecated in favor of the @emph{hwthread} pseudo RTOS.
+@end quotation
+
+For SMP support following GDB serial protocol packet have been defined :
+@itemize @bullet
+@item j - smp status request
+@item J - smp set request
+@end itemize
+
+OpenOCD implements :
+@itemize @bullet
+@item @option{jc} packet for reading core id displayed by
+GDB connection. Reply is @option{XXXXXXXX} (8 hex digits giving core id) or
+ @option{E01} for target not smp.
+@item @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue
+(core id -1 is reserved for returning to normal resume mode). Reply @option{E01}
+for target not smp or @option{OK} on success.
+@end itemize
+
+Handling of this packet within GDB can be done :
+@itemize @bullet
+@item by the creation of an internal variable (i.e @option{_core}) by mean
+of function allocate_computed_value allowing following GDB command.
+@example
+set $_core 1
+#Jc01 packet is sent
+print $_core
+#jc packet is sent and result is affected in $
+@end example
+
+@item by the usage of GDB maintenance command as described in following example (2 cpus in SMP with
+core id 0 and 1 @pxref{definecputargetsworkinginsmp,,Define CPU targets working in SMP}).
+
+@example
+# toggle0 : force display of coreid 0
+define toggle0
+maint packet Jc0
+continue
+main packet Jc-1
+end
+# toggle1 : force display of coreid 1
+define toggle1
+maint packet Jc1
+continue
+main packet Jc-1
+end
+@end example
+@end itemize
+
@node Tcl Scripting API
@chapter Tcl Scripting API
@cindex Tcl Scripting API
Code Review / openocd.git / blobdiff