@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x), Cortex-M3
-(Stellaris LM3, ST STM32 and Energy Micro EFM32) and Intel Quark (x10xx)
-based cores to be debugged via the GDB protocol.
+(Stellaris LM3, STMicroelectronics STM32 and Energy Micro EFM32) and
+Intel Quark (x10xx) based cores to be debugged via the GDB protocol.
@b{Flash Programming:} Flash writing is supported for external
CFI-compatible NOR flashes (Intel and AMD/Spansion command set) and several
@end itemize
@section USB ST-LINK based
-ST Micro has an adapter called @b{ST-LINK}.
-They only work with ST Micro chips, notably STM32 and STM8.
+STMicroelectronics has an adapter called @b{ST-LINK}.
+They only work with STMicroelectronics chips, notably STM32 and STM8.
@itemize @bullet
@item @b{ST-LINK}
@item @b{ST-LINK/V2}
@* This is available standalone and as part of some kits, eg. STM32F4DISCOVERY.
@* Link: @url{http://www.st.com/internet/evalboard/product/251168.jsp}
+@item @b{STLINK-V3}
+@* This is available standalone and as part of some kits.
+@* Link: @url{http://www.st.com/stlink-v3}
@end itemize
For info the original ST-LINK enumerates using the mass storage usb class; however,
@item @b{Keil ULINK v1}
@* Link: @url{http://www.keil.com/ulink1/}
+
+@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
@section IBM PC Parallel Printer Port Based
@url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf}
@item @b{flashlink}
-@* From ST Microsystems;
+@* From STMicroelectronics;
@* Link: @url{http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATA_BRIEF/DM00039500.pdf}
@end itemize
Likewise, the @command{arm9 vector_catch} command (or
@cindex vector_catch
its siblings @command{xscale vector_catch}
-and @command{cortex_m vector_catch}) can be a timesaver
+and @command{cortex_m vector_catch}) can be a time-saver
during some debug sessions, but don't make everyone use that either.
Keep those kinds of debugging aids in your user config file,
along with messaging and tracing setup.
@itemize @bullet
@item @b{Watchdog Timers}...
-Watchog timers are typically used to automatically reset systems if
+Watchdog timers are typically used to automatically reset systems if
some application task doesn't periodically reset the timer. (The
assumption is that the system has locked up if the task can't run.)
When a JTAG debugger halts the system, that task won't be able to run
board files may need to distinguish between instances of a chip.
@item @code{ENDIAN} ...
By default @option{little} - although chips may hard-wire @option{big}.
-Chips that can't change endianness don't need to use this variable.
+Chips that can't change endianess don't need to use this variable.
@item @code{CPUTAPID} ...
When OpenOCD examines the JTAG chain, it can be told verify the
chips against the JTAG IDCODE register.
proc init_board @{@} @{
reset_config trst_and_srst trst_pulls_srst
+ $_TARGETNAME configure -event reset-start @{
+ adapter_khz 100
+ @}
+
$_TARGETNAME configure -event reset-init @{
- adapter_khz 1
enable_fast_clock
adapter_khz 10000
@}
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
configuration stage, @xref{configurationstage,,Configuration Stage},) or they can contain a special
procedure called @code{init_targets}, which will be executed when entering run stage
(after parsing all config files or after @code{init} command, @xref{enteringtherunstage,,Entering the Run Stage}.)
-Such procedure can be overriden by ``next level'' script (which sources the original).
-This concept faciliates code reuse when basic target config files provide generic configuration
-procedures and @code{init_targets} procedure, which can then be sourced and enchanced or changed in
+Such procedure can be overridden by ``next level'' script (which sources the original).
+This concept facilitates code reuse when basic target config files provide generic configuration
+procedures and @code{init_targets} procedure, which can then be sourced and enhanced or changed in
a ``more specific'' target config file. This is not possible with ``linear'' config scripts,
because sourcing them executes every initialization commands they provide.
become available.
A number of these relate to the debug targets you may have declared.
For example, the @command{mww} command will not be available until
-a target has been successfuly instantiated.
+a target has been successfully instantiated.
If you want to use those commands, you may need to force
entry to the run stage.
If you disable all access through TCP/IP, you will need to
use the command line @option{-pipe} option.
+@anchor{gdb_port}
@deffn {Command} gdb_port [number]
@cindex GDB server
Normally gdb listens to a TCP/IP port, but GDB can also
second target will listen on gdb_port + 1, and so on.
When not specified during the configuration stage,
the port @var{number} defaults to 3333.
+When @var{number} is not a numeric value, incrementing it to compute
+the next port number does not work. In this case, specify the proper
+@var{number} for each target by using the option @code{-gdb-port} of the
+commands @command{target create} or @command{$target_name configure}.
+@xref{gdbportoverride,,option -gdb-port}.
Note: when using "gdb_port pipe", increasing the default remote timeout in
gdb (with 'set remotetimeout') is recommended. An insufficient timeout may
cause initialization to fail with "Unknown remote qXfer reply: OK".
-
@end deffn
@deffn {Command} tcl_port [number]
use @option{enable} see these errors reported.
@end deffn
+@deffn {Config Command} gdb_report_register_access_error (@option{enable}|@option{disable})
+Specifies whether register accesses requested by GDB register read/write
+packets report errors or not.
+The default behaviour is @option{disable};
+use @option{enable} see these errors reported.
+@end deffn
+
@deffn {Config Command} gdb_target_description (@option{enable}|@option{disable})
Set to @option{enable} to cause OpenOCD to send the target descriptions to gdb via qXfer:features:read packet.
The default behaviour is @option{enable}.
@end deffn
@deffn {Command} gdb_save_tdesc
-Saves the target descripton file to the local file system.
+Saves the target description file to the local file system.
The file name is @i{target_name}.xml.
@end deffn
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
The driver is using libusb-1.0 in asynchronous mode to talk to the FTDI device,
bypassing intermediate libraries like libftdi or D2XX.
-Support for new FTDI based adapters can be added competely through
+Support for new FTDI based adapters can be added completely through
configuration files, without the need to patch and rebuild OpenOCD.
The driver uses a signal abstraction to enable Tcl configuration files to
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
Configure TCK edge at which the adapter samples the value of the TDO signal
Due to signal propagation delays, sampling TDO on rising TCK can become quite
-peculiar at high JTAG clock speeds. However, FTDI chips offer a possiblity to sample
+peculiar at high JTAG clock speeds. However, FTDI chips offer a possibility to sample
TDO on falling edge of TCK. With some board/adapter configurations, this may increase
stability at higher JTAG clocks.
@itemize @minus
@end deffn
+@deffn {Interface Driver} {ft232r}
+This driver is implementing synchronous bitbang mode of an FTDI FT232R,
+FT230X, FT231X and similar USB UART bridge ICs by reusing RS232 signals as GPIO.
+It currently doesn't support using CBUS pins as GPIO.
+
+List of connections (default physical pin numbers for FT232R in 28-pin SSOP package):
+@itemize @minus
+@item RXD(5) - TDI
+@item TXD(1) - TCK
+@item RTS(3) - TDO
+@item CTS(11) - TMS
+@item DTR(2) - TRST
+@item DCD(10) - SRST
+@end itemize
+
+User can change default pinout by supplying configuration
+commands with GPIO numbers or RS232 signal names.
+GPIO numbers correspond to bit numbers in FTDI GPIO register.
+They differ from physical pin numbers.
+For details see actual FTDI chip datasheets.
+Every JTAG line must be configured to unique GPIO number
+different than any other JTAG line, even those lines
+that are sometimes not used like TRST or SRST.
+
+FT232R
+@itemize @minus
+@item bit 7 - RI
+@item bit 6 - DCD
+@item bit 5 - DSR
+@item bit 4 - DTR
+@item bit 3 - CTS
+@item bit 2 - RTS
+@item bit 1 - RXD
+@item bit 0 - TXD
+@end itemize
+
+These interfaces have several commands, used to configure the driver
+before initializing the JTAG scan chain:
+
+@deffn {Config Command} {ft232r_vid_pid} @var{vid} @var{pid}
+The vendor ID and product ID of the adapter. If not specified, default
+0x0403:0x6001 is used.
+@end deffn
+
+@deffn {Config Command} {ft232r_serial_desc} @var{serial}
+Specifies the @var{serial} of the adapter to use, in case the
+vendor provides unique IDs and more than one adapter is connected to
+the host. If not specified, serial numbers are not considered.
+@end deffn
+
+@deffn {Config Command} {ft232r_jtag_nums} @var{tck} @var{tms} @var{tdi} @var{tdo}
+Set four JTAG GPIO numbers at once.
+If not specified, default 0 3 1 2 or TXD CTS RXD RTS is used.
+@end deffn
+
+@deffn {Config Command} {ft232r_tck_num} @var{tck}
+Set TCK GPIO number. If not specified, default 0 or TXD is used.
+@end deffn
+
+@deffn {Config Command} {ft232r_tms_num} @var{tms}
+Set TMS GPIO number. If not specified, default 3 or CTS is used.
+@end deffn
+
+@deffn {Config Command} {ft232r_tdi_num} @var{tdi}
+Set TDI GPIO number. If not specified, default 1 or RXD is used.
+@end deffn
+
+@deffn {Config Command} {ft232r_tdo_num} @var{tdo}
+Set TDO GPIO number. If not specified, default 2 or RTS is used.
+@end deffn
+
+@deffn {Config Command} {ft232r_trst_num} @var{trst}
+Set TRST GPIO number. If not specified, default 4 or DTR is used.
+@end deffn
+
+@deffn {Config Command} {ft232r_srst_num} @var{srst}
+Set SRST GPIO number. If not specified, default 6 or DCD is used.
+@end deffn
+
+@deffn {Config Command} {ft232r_restore_serial} @var{word}
+Restore serial port after JTAG. This USB bitmode control word
+(16-bit) will be sent before quit. Lower byte should
+set GPIO direction register to a "sane" state:
+0x15 for TXD RTS DTR as outputs (1), others as inputs (0). Higher
+byte is usually 0 to disable bitbang mode.
+When kernel driver reattaches, serial port should continue to work.
+Value 0xFFFF disables sending control word and serial port,
+then kernel driver will not reattach.
+If not specified, default 0xFFFF is used.
+@end deffn
+
+@end deffn
+
@deffn {Interface Driver} {remote_bitbang}
Drive JTAG from a remote process. This sets up a UNIX or TCP socket connection
with a remote process and sends ASCII encoded bitbang requests to that process
transports.
@quotation Compatibility Note
-SEGGER released many firmware versions for the many harware versions they
+SEGGER released many firmware versions for the many hardware versions they
produced. OpenOCD was extensively tested and intended to run on all of them,
but some combinations were reported as incompatible. As a general
recommendation, it is advisable to use the latest firmware version
This type of adapter does not expose some of the lower level api's
that OpenOCD would normally use to access the target.
-Currently supported adapters include the ST STLINK and TI ICDI.
-STLINK firmware version >= V2.J21.S4 recommended due to issues with earlier
+Currently supported adapters include the STMicroelectronics ST-LINK and TI ICDI.
+ST-LINK firmware version >= V2.J21.S4 recommended due to issues with earlier
versions of firmware where serial number is reset after first use. Suggest
-using ST firmware update utility to upgrade STLINK firmware even if current
+using ST firmware update utility to upgrade ST-LINK firmware even if current
version reported is V2.J21.S4.
@deffn {Config Command} {hla_device_desc} description
Specifies the adapter layout to use.
@end deffn
-@deffn {Config Command} {hla_vid_pid} vid pid
-The vendor ID and product ID of the device.
+@deffn {Config Command} {hla_vid_pid} [vid pid]+
+Pairs of vendor IDs and product IDs of the device.
@end deffn
@deffn {Command} {hla_command} command
expected to change.
@end deffn
@deffn Command {swd wcr trn prescale}
-Updates TRN (turnaraound delay) and prescaling.fields of the
+Updates TRN (turnaround delay) and prescaling.fields of the
Wire Control Register (WCR).
No parameters: displays current settings.
@end deffn
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
@item
The @var{gates} tokens control flags that describe some cases where
-JTAG may be unvailable during reset.
+JTAG may be unavailable during reset.
@option{srst_gates_jtag} (default)
indicates that asserting SRST gates the
JTAG clock. This means that no communication can happen on JTAG
are the default @option{srst_open_drain}, and @option{srst_push_pull}.
Most boards connect this signal to a pullup, and allow the
signal to be pulled low by various events including system
-powerup and pressing a reset button.
+power-up and pressing a reset button.
@end itemize
@end deffn
both inside a single chip and between them.
@xref{faqtaporder,,FAQ TAP Order}.
-For example, the ST Microsystems STR912 chip has
+For example, the STMicroelectronics STR912 chip has
three separate TAPs@footnote{See the ST
document titled: @emph{STR91xFAxxx, Section 3.15 Jtag Interface, Page:
28/102, Figure 3: JTAG chaining inside the STR91xFA}.
to verify that instruction scans work correctly.
Such scans are not used by OpenOCD except to verify that
there seems to be no problems with JTAG scan chain operations.
+@item @code{-ignore-syspwrupack}
+@*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.
@end itemize
@end deffn
resources; then a @file{board.cfg} with off-chip resources, clocking,
and so forth.
+@anchor{dapdeclaration}
+@section DAP declaration (ARMv6-M, ARMv7 and ARMv8 targets)
+@cindex DAP declaration
+
+Since OpenOCD version 0.11.0, the Debug Access Port (DAP) is
+no longer implicitly created together with the target. It must be
+explicitly declared using the @command{dap create} command. For all ARMv6-M, ARMv7
+and ARMv8 targets, the option "@option{-dap} @var{dap_name}" has to be used
+instead of "@option{-chain-position} @var{dotted.name}" when the target is created.
+
+The @command{dap} command group supports the following sub-commands:
+
+@deffn Command {dap create} dap_name @option{-chain-position} dotted.name configparams...
+Declare a DAP instance named @var{dap_name} linked to the JTAG tap
+@var{dotted.name}. This also creates a new command (@command{dap_name})
+which is used for various purposes including additional configuration.
+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{-ignore-syspwrupack}
+@*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.
+@end itemize
+@end deffn
+
+@deffn Command {dap names}
+This command returns a list of all registered DAP objects. It it useful mainly
+for TCL scripting.
+@end deffn
+
+@deffn Command {dap info} [num]
+Displays the ROM table for MEM-AP @var{num},
+defaulting to the currently selected AP of the currently selected target.
+@end deffn
+
+@deffn Command {dap init}
+Initialize all registered DAPs. This command is used internally
+during initialization. It can be issued at any time after the
+initialization, too.
+@end deffn
+
+The following commands exist as subcommands of DAP instances:
+
+@deffn Command {$dap_name info} [num]
+Displays the ROM table for MEM-AP @var{num},
+defaulting to the currently selected AP.
+@end deffn
+
+@deffn Command {$dap_name apid} [num]
+Displays ID register from AP @var{num}, defaulting to the currently selected 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}.
+@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.
+@end deffn
+
+@deffn Command {$dap_name dpreg} reg [value]
+Displays the content of DP register at address @var{reg}, or set it to a new
+value @var{value}.
+
+In case of SWD, @var{reg} is a value in packed format
+@math{dpbanksel << 4 | addr} and assumes values 0, 4, 8 ... 0xfc.
+In case of JTAG it only assumes values 0, 4, 8 and 0xc.
+
+@emph{Note:} Consider using @command{poll off} to avoid any disturbing
+background activity by OpenOCD while you are operating at such low-level.
+@end deffn
+
+@deffn Command {$dap_name baseaddr} [num]
+Displays debug base address from MEM-AP @var{num},
+defaulting to the currently selected AP.
+@end deffn
+
+@deffn Command {$dap_name memaccess} [value]
+Displays the number of extra tck cycles in the JTAG idle to use for MEM-AP
+memory bus access [0-255], giving additional time to respond to reads.
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@deffn Command {$dap_name apcsw} [value [mask]]
+Displays or changes CSW bit pattern for MEM-AP transfers.
+
+At the begin of each memory access the CSW pattern is extended (bitwise or-ed)
+by @dfn{Size} and @dfn{AddrInc} bit-fields according to transfer requirements
+and the result is written to the real CSW register. All bits except dynamically
+updated fields @dfn{Size} and @dfn{AddrInc} can be changed by changing
+the CSW pattern. Refer to ARM ADI v5 manual chapter 7.6.4 and appendix A
+for details.
+
+Use @var{value} only syntax if you want to set the new CSW pattern as a whole.
+The example sets HPROT1 bit (required by Cortex-M) and clears the rest of
+the pattern:
+@example
+kx.dap apcsw 0x2000000
+@end example
+
+If @var{mask} is also used, the CSW pattern is changed only on bit positions
+where the mask bit is 1. The following example sets HPROT3 (cacheable)
+and leaves the rest of the pattern intact. It configures memory access through
+DCache on Cortex-M7.
+@example
+set CSW_HPROT3_CACHEABLE [expr 1 << 27]
+samv.dap apcsw $CSW_HPROT3_CACHEABLE $CSW_HPROT3_CACHEABLE
+@end example
+
+Another example clears SPROT bit and leaves the rest of pattern intact:
+@example
+set CSW_SPROT [expr 1 << 30]
+samv.dap apcsw 0 $CSW_SPROT
+@end example
+
+@emph{Note:} If you want to check the real value of CSW, not CSW pattern, use
+@code{xxx.dap apreg 0}. @xref{DAP subcommand apreg,,}.
+
+@emph{Warning:} Some of the CSW bits are vital for working memory transfer.
+If you set a wrong CSW pattern and MEM-AP stopped working, use the following
+example with a proper dap name:
+@example
+xxx.dap apcsw default
+@end example
+@end deffn
+
+@deffn Command {$dap_name ti_be_32_quirks} [@option{enable}]
+Set/get quirks mode for TI TMS450/TMS570 processors
+Disabled by default
+@end deffn
+
+
@node CPU Configuration
@chapter CPU Configuration
@cindex GDB target
@item @code{dragonite} -- resembles arm966e
@item @code{dsp563xx} -- implements Freescale's 24-bit DSP.
(Support for this is still incomplete.)
+@item @code{esirisc} -- this is an EnSilica eSi-RISC core.
+The current implementation supports eSi-32xx cores.
@item @code{fa526} -- resembles arm920 (w/o Thumb)
@item @code{feroceon} -- resembles arm926
@item @code{mips_m4k} -- a MIPS core
this key point: @emph{ARM is a technology licencing company}.
(See: @url{http://www.arm.com}.)
The CPU name used by OpenOCD will reflect the CPU design that was
-licenced, not a vendor brand which incorporates that design.
+licensed, not a vendor brand which incorporates that design.
Name prefixes like arm7, arm9, arm11, and cortex
reflect design generations;
while names like ARMv4, ARMv5, ARMv6, ARMv7 and ARMv8
The key steps you use might look something like this
@example
-target create MyTarget cortex_m -chain-position mychip.cpu
-$MyTarget configure -work-area-phys 0x08000 -work-area-size 8096
-$MyTarget configure -event reset-deassert-pre @{ jtag_rclk 5 @}
-$MyTarget configure -event reset-init @{ myboard_reinit @}
+dap create mychip.dap -chain-position mychip.cpu
+target create MyTarget cortex_m -dap mychip.dap
+MyTarget configure -work-area-phys 0x08000 -work-area-size 8096
+MyTarget configure -event reset-deassert-pre @{ jtag_rclk 5 @}
+MyTarget configure -event reset-init @{ myboard_reinit @}
@end example
You should specify a working area if you can; typically it uses some
inaccessible when application code
(such as an operating system)
enables or disables the MMU.
-For example, the particular MMU context used to acess the virtual
+For example, the particular MMU context used to access the virtual
address will probably matter ... and that context might not have
easy access to other addresses needed.
At this writing, OpenOCD doesn't have much MMU intelligence.
@command{$target_name configure} are permitted.
If the target is big-endian, set it here with @code{-endian big}.
-You @emph{must} set the @code{-chain-position @var{dotted.name}} here.
+You @emph{must} set the @code{-chain-position @var{dotted.name}} or
+@code{-dap @var{dap_name}} here.
@end itemize
@end deffn
@item @code{-chain-position} @var{dotted.name} -- names the TAP
used to access this target.
+@item @code{-dap} @var{dap_name} -- names the DAP used to access
+this target. @xref{dapdeclaration,,DAP declaration}, on how to
+create and manage DAP instances.
+
@item @code{-endian} (@option{big}|@option{little}) -- specifies
whether the CPU uses big or little endian conventions
two different handlers, but calling it twice with the
same event name assigns only one handler.
+Current target is temporarily overridden to the event issuing target
+before handler code starts and switched back after handler is done.
+
@item @code{-work-area-backup} (@option{0}|@option{1}) -- says
whether the work area gets backed up; by default,
@emph{it is not backed up.}
@item @code{-rtos} @var{rtos_type} -- enable rtos support for target,
@var{rtos_type} can be one of @option{auto}, @option{eCos},
@option{ThreadX}, @option{FreeRTOS}, @option{linux}, @option{ChibiOS},
-@option{embKernel}, @option{mqx}, @option{uCOS-III}
+@option{embKernel}, @option{mqx}, @option{uCOS-III}, @option{nuttx}
@xref{gdbrtossupport,,RTOS Support}.
@item @code{-defer-examine} -- skip target examination at initial JTAG chain
Use this option with systems where multiple, independent cores are connected
to separate access ports of the same DAP.
-@item @code{-ctibase} @var{address} -- set base address of Cross-Trigger interface (CTI) connected
-to the target. Currently, only the @code{aarch64} target makes use of this option, where it is
-a mandatory configuration for the target run control.
+@item @code{-cti} @var{cti_name} -- set Cross-Trigger Interface (CTI) connected
+to the target. Currently, only the @code{aarch64} target makes use of this option,
+where it is a mandatory configuration for the target run control.
+@xref{armcrosstrigger,,ARM Cross-Trigger Interface},
+for instruction on how to declare and control a CTI instance.
+
+@anchor{gdbportoverride}
+@item @code{-gdb-port} @var{number} -- see command @command{gdb_port} for the
+possible values of the parameter @var{number}, which are not only numeric values.
+Use this option to override, for this target only, the global parameter set with
+command @command{gdb_port}.
+@xref{gdb_port,,command gdb_port}.
@end itemize
@end deffn
and invokes a small procedure while the other inlines it.
@example
-proc my_attach_proc @{ @} @{
- echo "Reset..."
- reset halt
+proc my_init_proc @{ @} @{
+ echo "Disabling watchdog..."
+ mww 0xfffffd44 0x00008000
@}
-mychip.cpu configure -event gdb-attach my_attach_proc
-mychip.cpu configure -event gdb-attach @{
- echo "Reset..."
- # To make flash probe and gdb load to flash work
- # we need a reset init.
- reset init
+mychip.cpu configure -event reset-init my_init_proc
+mychip.cpu configure -event reset-init @{
+ echo "Disabling watchdog..."
+ mww 0xfffffd44 0x00008000
@}
@end example
@item @b{debug-halted}
@* The target has halted for debug reasons (i.e.: breakpoint)
@item @b{debug-resumed}
-@* The target has resumed (i.e.: gdb said run)
+@* The target has resumed (i.e.: GDB said run)
@item @b{early-halted}
@* Occurs early in the halt process
@item @b{examine-start}
@item @b{examine-end}
@* After target examine is called with no errors.
@item @b{gdb-attach}
-@* When GDB connects. This is before any communication with the target, so this
-can be used to set up the target so it is possible to probe flash. Probing flash
-is necessary during gdb connect if gdb load is to write the image to flash. Another
-use of the flash memory map is for GDB to automatically hardware/software breakpoints
-depending on whether the breakpoint is in RAM or read only memory.
+@* When GDB connects. Issued before any GDB communication with the target
+starts. GDB expects the target is halted during attachment.
+@xref{gdbmeminspect,,GDB as a non-intrusive memory inspector}, how to
+connect GDB to running target.
+The event can be also used to set up the target so it is possible to probe flash.
+Probing flash is necessary during GDB connect if you want to use
+@pxref{programmingusinggdb,,programming using GDB}.
+Another use of the flash memory map is for GDB to automatically choose
+hardware or software breakpoints depending on whether the breakpoint
+is in RAM or read only memory.
+Default is @code{halt}
@item @b{gdb-detach}
@* When GDB disconnects
@item @b{gdb-end}
@item @b{gdb-flash-write-end}
@* After GDB writes to the flash (default is @code{reset halt})
@item @b{gdb-start}
-@* Before the target steps, gdb is trying to start/resume the target
+@* Before the target steps, GDB is trying to start/resume the target
@item @b{halted}
@* The target has halted
@item @b{reset-assert-pre}
@* Issued as part of @command{reset} processing
-after @command{reset_init} was triggered
-but before either SRST alone is re-asserted on the scan chain,
+after @command{reset-start} was triggered
+but before either SRST alone is asserted on the scan chain,
or @code{reset-assert} is triggered.
@item @b{reset-assert}
@* Issued as part of @command{reset} processing
released on the scan chain.
@item @b{reset-end}
@* Issued as the final step in @command{reset} processing.
-@ignore
-@item @b{reset-halt-post}
-@* Currently not used
-@item @b{reset-halt-pre}
-@* Currently not used
-@end ignore
@item @b{reset-init}
@* Used by @b{reset init} command for board-specific initialization.
This event fires after @emph{reset-deassert-post}.
(You may be able to switch to a fast JTAG clock rate here, after
the target clocks are fully set up.)
@item @b{reset-start}
-@* Issued as part of @command{reset} processing
-before @command{reset_init} is called.
+@* Issued as the first step in @command{reset} processing
+before @command{reset-assert-pre} is called.
This is the most robust place to use @command{jtag_rclk}
or @command{adapter_khz} to switch to a low JTAG clock rate,
when reset disables PLLs needed to use a fast clock.
-@ignore
-@item @b{reset-wait-pos}
-@* Currently not used
-@item @b{reset-wait-pre}
-@* Currently not used
-@end ignore
@item @b{resume-start}
@* Before any target is resumed
@item @b{resume-end}
@xref{gdbconfiguration,,GDB Configuration}.
@end enumerate
-Many CPUs have the ablity to ``boot'' from the first flash bank.
+Many CPUs have the ability to ``boot'' from the first flash bank.
This means that misprogramming that bank can ``brick'' a system,
so that it can't boot.
JTAG tools, like OpenOCD, are often then used to ``de-brick'' the
@anchor{flashprogrammingcommands}
One feature distinguishing NOR flash from NAND or serial flash technologies
-is that for read access, it acts exactly like any other addressible memory.
+is that for read access, it acts exactly like any other addressable memory.
This means you can use normal memory read commands like @command{mdw} or
@command{dump_image} with it, with no special @command{flash} subcommands.
@xref{memoryaccess,,Memory access}, and @ref{imageaccess,,Image access}.
JTAG target, and map from an address in that target's address space
back to a flash bank.
@comment In May 2009, those mappings may fail if any bank associated
-@comment with that target doesn't succesfuly autoprobe ... bug worth fixing?
+@comment with that target doesn't successfully autoprobe ... bug worth fixing?
A few commands use abstract addressing based on bank and sector numbers,
and don't depend on searching the current target and its address space.
Avoid confusing the two command models.
@deffn Command {flash padded_value} num value
Sets the default value used for padding any image sections, This should
normally match the flash bank erased value. If not specified by this
-comamnd or the flash driver then it defaults to 0xff.
+command or the flash driver then it defaults to 0xff.
@end deffn
@anchor{program}
@end itemize
So in the following example addresses 0xbfc00000 and 0x9fc00000 refer to
-the flash bank defined at address 0x1fc00000. Any cmds executed on
-the virtual banks are actually performed on the physical banks.
+the flash bank defined at address 0x1fc00000. Any command executed on
+the virtual banks is actually performed on the physical banks.
@example
flash bank $_FLASHNAME pic32mx 0x1fc00000 0 0 0 $_TARGETNAME
flash bank vbank0 virtual 0xbfc00000 0 0 0 \
@item @var{x16_as_x8} ... when a 16-bit flash is hooked up to an 8-bit bus.
@item @var{bus_swap} ... when data bytes in a 16-bit flash needs to be swapped.
@item @var{data_swap} ... when data bytes in a 16-bit flash needs to be
-swapped when writing data values (ie. not CFI commands).
+swapped when writing data values (i.e. not CFI commands).
@end itemize
To configure two adjacent banks of 16 MBytes each, both sixteen bits (two bytes)
@item @var{ir} ... is loaded into the JTAG IR to map the flash as the JTAG DR.
For the bitstreams generated from @file{xilinx_bscan_spi.py} this is the
@var{USER1} instruction.
-@item @var{dr_length} ... is the length of the DR register. This will be 1 for
-@file{xilinx_bscan_spi.py} bitstreams and most other cases.
@end itemize
@example
target create $_TARGETNAME testee -chain-position $_CHIPNAME.fpga
set _XILINX_USER1 0x02
-set _DR_LENGTH 1
flash bank $_FLASHNAME spi 0x0 0 0 0 \
- $_TARGETNAME $_XILINX_USER1 $_DR_LENGTH
+ $_TARGETNAME $_XILINX_USER1
+@end example
+@end deffn
+
+@deffn {Flash Driver} xcf
+@cindex Xilinx Platform flash driver
+@cindex xcf
+Xilinx FPGAs can be configured from specialized flash ICs named Platform Flash.
+It is (almost) regular NOR flash with erase sectors, program pages, etc. The
+only difference is special registers controlling its FPGA specific behavior.
+They must be properly configured for successful FPGA loading using
+additional @var{xcf} driver command:
+
+@deffn Command {xcf ccb} <bank_id>
+command accepts additional parameters:
+@itemize
+@item @var{external|internal} ... selects clock source.
+@item @var{serial|parallel} ... selects serial or parallel data bus mode.
+@item @var{slave|master} ... selects slave of master mode for flash device.
+@item @var{40|20} ... selects clock frequency in MHz for internal clock
+in master mode.
+@end itemize
+@example
+xcf ccb 0 external parallel slave 40
@end example
+All of them must be specified even if clock frequency is pointless
+in slave mode. If only bank id specified than command prints current
+CCB register value. Note: there is no need to write this register
+every time you erase/program data sectors because it stores in
+dedicated sector.
+@end deffn
+
+@deffn Command {xcf configure} <bank_id>
+Initiates FPGA loading procedure. Useful if your board has no "configure"
+button.
+@example
+xcf configure 0
+@end example
+@end deffn
+
+Additional driver notes:
+@itemize
+@item Only single revision supported.
+@item Driver automatically detects need of bit reverse, but
+only "bin" (raw binary, do not confuse it with "bit") and "mcs"
+(Intel hex) file types supported.
+@item For additional info check xapp972.pdf and ug380.pdf.
+@end itemize
@end deffn
@deffn {Flash Driver} lpcspifi
@cindex STMicroelectronics Serial Memory Interface
@cindex SMI
@cindex stmsmi
-Some devices form STMicroelectronics (e.g. STR75x MCU family,
+Some devices from STMicroelectronics (e.g. STR75x MCU family,
SPEAr MPU family) include a proprietary
``Serial Memory Interface'' (SMI) controller able to drive external
SPI flash devices.
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
The @var{ambiqmicro} driver reads the Chip Information Register detect
the device class of the MCU.
-The Flash and Sram sizes directly follow device class, and are used
+The Flash and SRAM sizes directly follow device class, and are used
to set up the flash banks.
If this fails, the driver will use default values set to the minimum
sizes of an Apollo chip.
@end deffn
@deffn Command {ambiqmicro program_otp} <bank> <offset> <count>
Program OTP is a one time operation to create write protected flash.
-The user writes sectors to sram starting at 0x10000010.
-Program OTP will write these sectors from sram to flash, and write protect
+The user writes sectors to SRAM starting at 0x10000010.
+Program OTP will write these sectors from SRAM to flash, and write protect
the flash.
@end deffn
@end deffn
@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 cmd 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
of the Flash. When setting, the EEPROM size must be specified in bytes and it
must be one of the permitted sizes according to the datasheet. Settings are
written immediately but only take effect on MCU reset. EEPROM emulation
-requires additional firmware support and the minumum EEPROM size may not be
+requires additional firmware support and the minimum EEPROM size may not be
the same as the minimum that the hardware supports. Set the EEPROM size to 0
in order to disable this feature.
Command is used internally in event event reset-deassert-post.
@end deffn
+@deffn Command {at91samd nvmuserrow}
+Writes or reads the entire 64 bit wide NVM user row register which is located at
+0x804000. This register includes various fuses lock-bits and factory calibration
+data. Reading the register is done by invoking this command without any
+arguments. Writing is possible by giving 1 or 2 hex values. The first argument
+is the register value to be written and the second one is an optional changemask.
+Every bit which value in changemask is 0 will stay unchanged. The lock- and
+reserved-bits are masked out and cannot be changed.
+
+@example
+# Read user row
+>at91samd nvmuserrow
+NVMUSERROW: 0xFFFFFC5DD8E0C788
+# Write 0xFFFFFC5DD8E0C788 to user row
+>at91samd nvmuserrow 0xFFFFFC5DD8E0C788
+# Write 0x12300 to user row but leave other bits and low byte unchanged
+>at91samd nvmuserrow 0x12345 0xFFF00
+@end example
+@end deffn
+
@end deffn
@anchor{at91sam3}
that the driver was orginaly developed and tested using the
AT91SAM3U4E, using a SAM3U-EK eval board. Support for other chips in
the family was cribbed from the data sheet. @emph{Note to future
-readers/updaters: Please remove this worrysome comment after other
+readers/updaters: Please remove this worrisome comment after other
chips are confirmed.}
The AT91SAM3U4[E/C] (256K) chips have two flash banks; most other chips
@cindex at91sam4
All members of the AT91SAM4 microcontroller family from
Atmel include internal flash and use ARM's Cortex-M4 core.
-This driver uses the same cmd names/syntax as @xref{at91sam3}.
+This driver uses the same command names/syntax as @xref{at91sam3}.
@end deffn
@deffn {Flash Driver} at91sam4l
@cindex at91sam4l
All members of the AT91SAM4L microcontroller family from
Atmel include internal flash and use ARM's Cortex-M4 core.
-This driver uses the same cmd names/syntax as @xref{at91sam3}.
+This driver uses the same command names/syntax as @xref{at91sam3}.
The AT91SAM4L driver adds some additional commands:
@deffn Command {at91sam4l smap_reset_deassert}
@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 cmd names/syntax as @xref{at91sam3}.
+This driver uses the same command names/syntax as @xref{at91sam3}.
@end deffn
@deffn {Flash Driver} at91sam7
@comment - defines mass_erase ... pointless given flash_erase_address
@end deffn
+@deffn {Flash Driver} bluenrg-x
+STMicroelectronics BlueNRG-1 and BlueNRG-2 Bluetooth low energy wireless system-on-chip. They include ARM Cortex-M0 core and internal flash memory.
+The driver automatically recognizes these chips using
+the chip identification registers, and autoconfigures itself.
+
+@example
+flash bank $_FLASHNAME bluenrg-x 0 0 0 0 $_TARGETNAME
+@end example
+
+Note that when users ask to erase all the sectors of the flash, a mass erase command is used which is faster than erasing
+each single sector one by one.
+
+@example
+flash erase_sector 0 0 79 # It will perform a mass erase on BlueNRG-1
+@end example
+
+@example
+flash erase_sector 0 0 127 # It will perform a mass erase on BlueNRG-2
+@end example
+
+Triggering a mass erase is also useful when users want to disable readout protection.
+@end deffn
+
+@deffn {Flash Driver} cc26xx
+All versions of the SimpleLink CC13xx and CC26xx microcontrollers from Texas
+Instruments include internal flash. The cc26xx flash driver supports both the
+CC13xx and CC26xx family of devices. The driver automatically recognizes the
+specific version's flash parameters and autoconfigures itself. The flash bank
+starts at address 0.
+
+@example
+flash bank $_FLASHNAME cc26xx 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
+@deffn {Flash Driver} cc3220sf
+The CC3220SF version of the SimpleLink CC32xx microcontrollers from Texas
+Instruments includes 1MB of internal flash. The cc3220sf flash driver only
+supports the internal flash. The serial flash on SimpleLink boards is
+programmed via the bootloader over a UART connection. Security features of
+the CC3220SF may erase the internal flash during power on reset. Refer to
+documentation at @url{www.ti.com/cc3220sf} for details on security features
+and programming the serial flash.
+
+@example
+flash bank $_FLASHNAME cc3220sf 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
@deffn {Flash Driver} efm32
All members of the EFM32 microcontroller family from Energy Micro include
internal flash and use ARM Cortex-M3 cores. The driver automatically recognizes
supported.}
@end deffn
+@deffn {Flash Driver} esirisc
+Members of the eSi-RISC family may optionally include internal flash programmed
+via the eSi-TSMC Flash interface. Additional parameters are required to
+configure the driver: @option{cfg_address} is the base address of the
+configuration register interface, @option{clock_hz} is the expected clock
+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
+@end example
+
+@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
+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} fm3
All members of the FM3 microcontroller family from Fujitsu
include internal flash and use ARM Cortex-M3 cores.
internal flash and use ARM Cortex-M0+ or M4 cores. The driver automatically
recognizes flash size and a number of flash banks (1-4) using the chip
identification register, and autoconfigures itself.
-Use kinetis_ke driver for KE0x devices.
+Use kinetis_ke driver for KE0x and KEAx devices.
The @var{kinetis} driver defines option:
@itemize
@deffn {Flash Driver} kinetis_ke
@cindex kinetis_ke
-KE0x members of the Kinetis microcontroller family from Freescale include
+KE0x and KEAx members of the Kinetis microcontroller family from NXP include
internal flash and use ARM Cortex-M0+. The driver automatically recognizes
the KE0x sub-family using the chip identification register, and
autoconfigures itself.
@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 index sector of the flash is a @emph{write-only} sector. It cannot be
erased! In order to guard against unintentional write access, all following
-commands need to be preceeded by a successful call to the @code{password}
+commands need to be preceded by a successful call to the @code{password}
command:
@deffn Command {lpc2900 password} bank password
@end example
@end deffn
+@deffn {Flash Driver} msp432
+All versions of the SimpleLink MSP432 microcontrollers from Texas
+Instruments include internal flash. The msp432 flash driver automatically
+recognizes the specific version's flash parameters and autoconfigures itself.
+Main program flash (starting at address 0) is flash bank 0. Information flash
+region on MSP432P4 versions (starting at address 0x200000) is flash bank 1.
+
+@example
+flash bank $_FLASHNAME msp432 0 0 0 0 $_TARGETNAME
+@end example
+
+@deffn Command {msp432 mass_erase} [main|all]
+Performs a complete erase of flash. By default, @command{mass_erase} will erase
+only the main program flash.
+
+On MSP432P4 versions, using @command{mass_erase all} will erase both the
+main program and information flash regions. To also erase the BSL in information
+flash, the user must first use the @command{bsl} command.
+@end deffn
+
+@deffn Command {msp432 bsl} [unlock|lock]
+On MSP432P4 versions, @command{bsl} unlocks and locks the bootstrap loader (BSL)
+region in information flash so that flash commands can erase or write the BSL.
+Leave the BSL locked to prevent accidentally corrupting the bootstrap loader.
+
+To erase and program the BSL:
+@example
+msp432 bsl unlock
+flash erase_address 0x202000 0x2000
+flash write_image bsl.bin 0x202000
+msp432 bsl lock
+@end example
+@end deffn
+@end deffn
+
@deffn {Flash Driver} niietcm4
This drivers handles the integrated NOR flash on NIIET Cortex-M4
based controllers. Flash size and sector layout are auto-configured by the driver.
There is additional not memory mapped flash called "Userflash", which
also have division into regions: main and info.
Purpose of userflash - to store system and user settings.
-Driver has special commands to perform operations with this memmory.
+Driver has special commands to perform operations with this memory.
@example
flash bank $_FLASHNAME niietcm4 0 0 0 0 $_TARGETNAME
@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
-and SWD interface.
-The @var{sim3x} driver tries to probe the device to auto detect the MCU.
-If this failes, it will use the @var{size} parameter as the size of flash bank.
+@deffn {Flash Driver} psoc5lp
+All members of the PSoC 5LP microcontroller family from Cypress
+include internal program flash and use ARM Cortex-M3 cores.
+The driver probes for a number of these chips and autoconfigures itself,
+apart from the base address.
@example
-flash bank $_FLASHNAME sim3x 0 $_CPUROMSIZE 0 0 $_TARGETNAME
+flash bank $_FLASHNAME psoc5lp 0x00000000 0 0 0 $_TARGETNAME
@end example
-There are 2 commands defined in the @var{sim3x} driver:
+@b{Note:} PSoC 5LP chips can be configured to have ECC enabled or disabled.
+@quotation Attention
+If flash operations are performed in ECC-disabled mode, they will also affect
+the ECC flash region. Erasing a 16k flash sector in the 0x00000000 area will
+then also erase the corresponding 2k data bytes in the 0x48000000 area.
+Writing to the ECC data bytes in ECC-disabled mode is not implemented.
+@end quotation
-@deffn Command {sim3x mass_erase}
-Erases the complete flash. This is used to unlock the flash.
-And this command is only possible when using the SWD interface.
-@end deffn
+Commands defined in the @var{psoc5lp} driver:
-@deffn Command {sim3x lock}
-Lock the flash. To unlock use the @command{sim3x mass_erase} command.
+@deffn Command {psoc5lp mass_erase}
+Erases all flash data and ECC/configuration bytes, all flash protection rows,
+and all row latches in all flash arrays on the device.
@end deffn
@end deffn
-@deffn {Flash Driver} stellaris
-All members of the Stellaris LM3Sxxx, LM4x and Tiva C microcontroller
-families from Texas Instruments include internal flash. The driver
-automatically recognizes a number of these chips using the chip
-identification register, and autoconfigures itself.
-@footnote{Currently there is a @command{stellaris mass_erase} command.
-That seems pointless since the same effect can be had using the
-standard @command{flash erase_address} command.}
+@deffn {Flash Driver} psoc5lp_eeprom
+All members of the PSoC 5LP microcontroller family from Cypress
+include internal EEPROM and use ARM Cortex-M3 cores.
+The driver probes for a number of these chips and autoconfigures itself,
+apart from the base address.
@example
-flash bank $_FLASHNAME stellaris 0 0 0 0 $_TARGETNAME
+flash bank $_CHIPNAME.eeprom psoc5lp_eeprom 0x40008000 0 0 0 $_TARGETNAME
@end example
+@end deffn
-@deffn Command {stellaris recover}
-Performs the @emph{Recovering a "Locked" Device} procedure to restore
-the flash and its associated nonvolatile registers to their factory
-default values (erased). This is the only way to remove flash
-protection or re-enable debugging if that capability has been
-disabled.
+@deffn {Flash Driver} psoc5lp_nvl
+All members of the PSoC 5LP microcontroller family from Cypress
+include internal Nonvolatile Latches and use ARM Cortex-M3 cores.
+The driver probes for a number of these chips and autoconfigures itself.
-Note that the final "power cycle the chip" step in this procedure
-must be performed by hand, since OpenOCD can't do it.
-@quotation Warning
+@example
+flash bank $_CHIPNAME.nvl psoc5lp_nvl 0 0 0 0 $_TARGETNAME
+@end example
+
+PSoC 5LP chips have multiple NV Latches:
+
+@itemize
+@item Device Configuration NV Latch - 4 bytes
+@item Write Once (WO) NV Latch - 4 bytes
+@end itemize
+
+@b{Note:} This driver only implements the Device Configuration NVL.
+
+The @var{psoc5lp} driver reads the ECC mode from Device Configuration NVL.
+@quotation Attention
+Switching ECC mode via write to Device Configuration NVL will require a reset
+after successful write.
+@end quotation
+@end deffn
+
+@deffn {Flash Driver} psoc6
+Supports PSoC6 (CY8C6xxx) family of Cypress microcontrollers.
+PSoC6 is a dual-core device with CM0+ and CM4 cores. Both cores share
+the same Flash/RAM/MMIO address space.
+
+Flash in PSoC6 is split into three regions:
+@itemize @bullet
+@item Main Flash - this is the main storage for user application.
+Total size varies among devices, sector size: 256 kBytes, row size:
+512 bytes. Supports erase operation on individual rows.
+@item Work Flash - intended to be used as storage for user data
+(e.g. EEPROM emulation). Total size: 32 KBytes, sector size: 32 KBytes,
+row size: 512 bytes.
+@item Supervisory Flash - special region which contains device-specific
+service data. This region does not support erase operation. Only few rows can
+be programmed by the user, most of the rows are read only. Programming
+operation will erase row automatically.
+@end itemize
+
+All three flash regions are supported by the driver. Flash geometry is detected
+automatically by parsing data in SPCIF_GEOMETRY register.
+
+PSoC6 is equipped with NOR Flash so erased Flash reads as 0x00.
+
+@example
+flash bank main_flash_cm0 psoc6 0x10000000 0 0 0 $@{TARGET@}.cm0
+flash bank work_flash_cm0 psoc6 0x14000000 0 0 0 $@{TARGET@}.cm0
+flash bank super_flash_user_cm0 psoc6 0x16000800 0 0 0 $@{TARGET@}.cm0
+flash bank super_flash_nar_cm0 psoc6 0x16001A00 0 0 0 $@{TARGET@}.cm0
+flash bank super_flash_key_cm0 psoc6 0x16005A00 0 0 0 $@{TARGET@}.cm0
+flash bank super_flash_toc2_cm0 psoc6 0x16007C00 0 0 0 $@{TARGET@}.cm0
+
+flash bank main_flash_cm4 psoc6 0x10000000 0 0 0 $@{TARGET@}.cm4
+flash bank work_flash_cm4 psoc6 0x14000000 0 0 0 $@{TARGET@}.cm4
+flash bank super_flash_user_cm4 psoc6 0x16000800 0 0 0 $@{TARGET@}.cm4
+flash bank super_flash_nar_cm4 psoc6 0x16001A00 0 0 0 $@{TARGET@}.cm4
+flash bank super_flash_key_cm4 psoc6 0x16005A00 0 0 0 $@{TARGET@}.cm4
+flash bank super_flash_toc2_cm4 psoc6 0x16007C00 0 0 0 $@{TARGET@}.cm4
+@end example
+
+psoc6-specific commands
+@deffn Command {psoc6 reset_halt}
+Command can be used to simulate broken Vector Catch from gdbinit or tcl scripts.
+When invoked for CM0+ target, it will set break point at application entry point
+and issue SYSRESETREQ. This will reset both cores and all peripherals. CM0+ will
+reset CM4 during boot anyway so this is safe. On CM4 target, VECTRESET is used
+instead of SYSRESETREQ to avoid unwanted reset of CM0+;
+@end deffn
+
+@deffn Command {psoc6 mass_erase} num
+Erases the contents given flash bank. The @var{num} parameter is a value shown
+by @command{flash banks}.
+Note: only Main and Work flash regions support Erase operation.
+@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
+and SWD interface.
+The @var{sim3x} driver tries to probe the device to auto detect the MCU.
+If this fails, it will use the @var{size} parameter as the size of flash bank.
+
+@example
+flash bank $_FLASHNAME sim3x 0 $_CPUROMSIZE 0 0 $_TARGETNAME
+@end example
+
+There are 2 commands defined in the @var{sim3x} driver:
+
+@deffn Command {sim3x mass_erase}
+Erases the complete flash. This is used to unlock the flash.
+And this command is only possible when using the SWD interface.
+@end deffn
+
+@deffn Command {sim3x lock}
+Lock the flash. To unlock use the @command{sim3x mass_erase} command.
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} stellaris
+All members of the Stellaris LM3Sxxx, LM4x and Tiva C microcontroller
+families from Texas Instruments include internal flash. The driver
+automatically recognizes a number of these chips using the chip
+identification register, and autoconfigures itself.
+
+@example
+flash bank $_FLASHNAME stellaris 0 0 0 0 $_TARGETNAME
+@end example
+
+@deffn Command {stellaris recover}
+Performs the @emph{Recovering a "Locked" Device} procedure to restore
+the flash and its associated nonvolatile registers to their factory
+default values (erased). This is the only way to remove flash
+protection or re-enable debugging if that capability has been
+disabled.
+
+Note that the final "power cycle the chip" step in this procedure
+must be performed by hand, since OpenOCD can't do it.
+@quotation Warning
if more than one Stellaris chip is connected, the procedure is
applied to all of them.
@end quotation
@deffn {Flash Driver} stm32f1x
All members of the STM32F0, STM32F1 and STM32F3 microcontroller families
-from ST Microelectronics include internal flash and use ARM Cortex-M0/M3/M4 cores.
+from STMicroelectronics include internal flash and use ARM Cortex-M0/M3/M4 cores.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
flash bank $_FLASHNAME stm32f1x 0x08080000 0 0 0 $_TARGETNAME
@end example
-Some stm32f1x-specific commands
-@footnote{Currently there is a @command{stm32f1x mass_erase} command.
-That seems pointless since the same effect can be had using the
-standard @command{flash erase_address} command.}
-are defined:
+Some stm32f1x-specific commands are defined:
@deffn Command {stm32f1x lock} num
-Locks the entire stm32 device.
+Locks the entire stm32 device against reading.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@deffn Command {stm32f1x unlock} num
-Unlocks the entire stm32 device.
+Unlocks the entire stm32 device for reading. This command will cause
+a mass erase of the entire stm32 device if previously locked.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32f1x mass_erase} num
+Mass erases the entire stm32 device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@deffn Command {stm32f1x options_read} num
-Read and display the stm32 option bytes written by
-the @command{stm32f1x options_write} command.
+Reads and displays active stm32 option bytes loaded during POR
+or upon executing the @command{stm32f1x options_load} command.
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
+Generates a special kind of reset to re-load the stm32 option bytes written
+by the @command{stm32f1x options_write} or @command{flash protect} commands
+without having to power cycle the target. Not applicable to stm32f1x devices.
+The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@end deffn
@deffn {Flash Driver} stm32f2x
-All members of the STM32F2, STM32F4 and STM32F7 microcontroller families from ST Microelectronics
+All members of the STM32F2, STM32F4 and STM32F7 microcontroller families from STMicroelectronics
include internal flash and use ARM Cortex-M3/M4/M7 cores.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
+@example
+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.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
+@deffn Command {stm32f2x mass_erase} num
+Mass erases the entire stm32f2x device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
@deffn Command {stm32f2x options_read} num
Reads and displays user options and (where implemented) boot_addr0, boot_addr1, optcr2.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@end deffn
+@deffn {Flash Driver} stm32h7x
+All members of the STM32H7 microcontroller families from STMicroelectronics
+include internal flash and use ARM Cortex-M7 core.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+
+@example
+flash bank $_FLASHNAME stm32h7x 0 0 0 0 $_TARGETNAME
+@end example
+
+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.
+
+@example
+flash bank $_FLASHNAME stm32h7x 0 0x20000 0 0 $_TARGETNAME
+@end example
+
+Some stm32h7x-specific commands are defined:
+
+@deffn Command {stm32h7x lock} num
+Locks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32h7x unlock} num
+Unlocks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32h7x mass_erase} num
+Mass erases the entire stm32h7x device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+@end deffn
+
@deffn {Flash Driver} stm32lx
-All members of the STM32L microcontroller families from ST Microelectronics
+All members of the STM32L microcontroller families from STMicroelectronics
include internal flash and use ARM Cortex-M3 and Cortex-M0+ cores.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
+@example
+flash bank $_FLASHNAME stm32lx 0 0 0 0 $_TARGETNAME
+@end example
+
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. If you use 0 as the bank base address, it tells the
Some stm32lx-specific commands are defined:
+@deffn Command {stm32lx lock} num
+Locks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32lx unlock} num
+Unlocks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
@deffn Command {stm32lx mass_erase} num
Mass erases the entire stm32lx device (all flash banks and EEPROM
data). This is the only way to unlock a protected flash (unless RDP
@end deffn
@end deffn
+@deffn {Flash Driver} stm32l4x
+All members of the STM32L4 microcontroller families from STMicroelectronics
+include internal flash and use ARM Cortex-M4 cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+
+@example
+flash bank $_FLASHNAME stm32l4x 0 0 0 0 $_TARGETNAME
+@end example
+
+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.
+
+@example
+flash bank $_FLASHNAME stm32l4x 0x08000000 0x40000 0 0 $_TARGETNAME
+@end example
+
+Some stm32l4x-specific commands are defined:
+
+@deffn Command {stm32l4x lock} num
+Locks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32l4x unlock} num
+Unlocks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32l4x mass_erase} num
+Mass erases the entire stm32l4x device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32l4x option_read} num reg_offset
+Reads an option byte register from the stm32l4x device.
+The @var{num} parameter is a value shown by @command{flash banks}, @var{reg_offset}
+is the register offset of the Option byte to read.
+
+For example to read the FLASH_OPTR register:
+@example
+stm32l4x option_read 0 0x20
+# Option Register: <0x40022020> = 0xffeff8aa
+@end example
+
+The above example will read out the FLASH_OPTR register which contains the RDP
+option byte, Watchdog configuration, BOR level etc.
+@end deffn
+
+@deffn Command {stm32l4x option_write} num reg_offset reg_mask
+Write an option byte register of the stm32l4x device.
+The @var{num} parameter is a value shown by @command{flash banks}, @var{reg_offset}
+is the register offset of the Option byte to write, and @var{reg_mask} is the mask
+to apply when writing the register (only bits with a '1' will be touched).
+
+For example to write the WRP1AR option bytes:
+@example
+stm32l4x option_write 0 0x28 0x00FF0000 0x00FF00FF
+@end example
+
+The above example will write the WRP1AR option register configuring the Write protection
+Area A for bank 1. The above example set WRP1AR_END=255, WRP1AR_START=0.
+This will effectively write protect all sectors in flash bank 1.
+@end deffn
+
+@deffn Command {stm32l4x option_load} num
+Forces a re-load of the option byte registers. Will cause a reset of the device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+@end deffn
+
@deffn {Flash Driver} str7x
-All members of the STR7 microcontroller family from ST Microelectronics
+All members of the STR7 microcontroller family from STMicroelectronics
include internal flash and use ARM7TDMI cores.
The @var{str7x} driver defines one mandatory parameter, @var{variant},
which is either @code{STR71x}, @code{STR73x} or @code{STR75x}.
@end deffn
@deffn {Flash Driver} str9x
-Most members of the STR9 microcontroller family from ST Microelectronics
+Most members of the STR9 microcontroller family from STMicroelectronics
include internal flash and use ARM966E cores.
The str9 needs the flash controller to be configured using
the @command{str9x flash_config} command prior to Flash programming.
flash programming as it is faster than the @option{str9xpec} driver.
@item
Direct programming @option{str9xpec} using the flash controller. This is an
-ISC compilant (IEEE 1532) tap connected in series with the str9 core. The str9
+ISC compliant (IEEE 1532) tap connected in series with the str9 core. The str9
core does not need to be running to program using this flash driver. Typical use
for this driver is locking/unlocking the target and programming the option bytes.
@end enumerate
@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.
every 512 bytes of data.
You will need to make sure that any data you write using
-OpenOCD includes the apppropriate kind of ECC. For example,
+OpenOCD includes the appropriate kind of ECC. For example,
that may mean passing the @code{oob_softecc} flag when
writing NAND data, or ensuring that the correct hardware
ECC mode is used.
@itemize @bullet
@item no oob_* parameter
@*File has only page data, which is written.
-If raw acccess is in use, the OOB area will not be written.
+If raw access is in use, the OOB area will not be written.
Otherwise, if the underlying NAND controller driver has
a @code{write_page} routine, that routine may write the OOB
with hardware-computed ECC data.
@b{NOTE:} This will not work when the underlying NAND controller
driver's @code{write_page} routine must update the OOB with a
-hardward-computed ECC before the data is written. This limitation may
+hardware-computed ECC before the data is written. This limitation may
be removed in a future release.
@end deffn
@deffn {NAND Driver} mx3
This driver handles the NAND controller in i.MX31. The mxc driver
-should work for this chip aswell.
+should work for this chip as well.
@end deffn
@deffn {NAND Driver} mxc
nand device mx35.nand mxc imx35.cpu mx35 hwecc biswap
@end example
@deffn Command {mxc biswap} bank_num [enable|disable]
-Turns on/off bad block information swaping from main area,
+Turns on/off bad block information swapping from main area,
without parameter query status.
@end deffn
@end deffn
@chapter Flash Programming
OpenOCD implements numerous ways to program the target flash, whether internal or external.
-Programming can be acheived by either using GDB @ref{programmingusinggdb,,Programming using GDB},
-or using the cmds given in @ref{flashprogrammingcommands,,Flash Programming Commands}.
+Programming can be achieved by either using GDB @ref{programmingusinggdb,,Programming using GDB},
+or using the commands given in @ref{flashprogrammingcommands,,Flash Programming Commands}.
-@*To simplify using the flash cmds directly a jimtcl script is available that handles the programming and verify stage.
+@*To simplify using the flash commands directly a jimtcl script is available that handles the programming and verify stage.
OpenOCD will program/verify/reset the target and optionally shutdown.
-The script is executed as follows and by default the following actions will be peformed.
+The script is executed as follows and by default the following actions will be performed.
@enumerate
@item 'init' is executed.
@item 'reset init' is called to reset and halt the target, any 'reset init' scripts are executed.
@itemize @bullet
@item @b{Source Of Commands}
@* OpenOCD commands can occur in a configuration script (discussed
-elsewhere) or typed manually by a human or supplied programatically,
+elsewhere) or typed manually by a human or supplied programmatically,
or via one of several TCP/IP Ports.
@item @b{From the human}
Close the OpenOCD server, disconnecting all clients (GDB, telnet,
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.:
+@example
+# redefine shutdown
+rename shutdown original_shutdown
+proc shutdown @{@} @{
+ puts "This is my implementation of shutdown"
+ # my own stuff before exit OpenOCD
+ original_shutdown
+@}
+@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.
@end deffn
@anchor{debuglevel}
Add @var{directory} to the file/script search path.
@end deffn
-@deffn Command bindto [name]
-Specify address by name on which to listen for incoming TCP/IP connections.
-By default, OpenOCD will listen on all available interfaces.
+@deffn Command bindto [@var{name}]
+Specify hostname or IPv4 address on which to listen for incoming
+TCP/IP connections. By default, OpenOCD will listen on the loopback
+interface only. If your network environment is safe, @code{bindto
+0.0.0.0} can be used to cover all available interfaces.
@end deffn
@anchor{targetstatehandling}
A more complete workaround is to not use that operation while you
work with a JTAG debugger.
-Tasking environments generaly have idle loops where the body is the
+Tasking environments generally have idle loops where the body is the
@emph{wait for interrupt} operation.
(On older cores, it is a coprocessor action;
newer cores have a @option{wfi} instruction.)
@deffn Command {fast_load}
Loads an image stored in memory by @command{fast_load_image} to the
-current target. Must be preceeded by fast_load_image.
+current target. Must be preceded by fast_load_image.
@end deffn
@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}|@option{s19}]
Load image from file @var{filename} to target memory offset by @var{address} from its load address.
The file format may optionally be specified
(@option{bin}, @option{ihex}, @option{elf}, or @option{s19}).
-In addition the following arguments may be specifed:
+In addition the following arguments may be specified:
@var{min_addr} - ignore data below @var{min_addr} (this is w.r.t. to the target's load address + @var{address})
@var{max_length} - maximum number of bytes to load.
@example
with a given trace port @var{driver}. @xref{traceportdrivers,,Trace Port Drivers}.
Several of the parameters must reflect the trace port capabilities,
-which are a function of silicon capabilties (exposed later
+which are a function of silicon capabilities (exposed later
using @command{etm info}) and of what hardware is connected to
that port (such as an external pod, or ETB).
The @var{width} must be either 4, 8, or 16,
@end deffn
@end deffn
+@anchor{armcrosstrigger}
+@section ARM Cross-Trigger Interface
+@cindex CTI
+
+The ARM Cross-Trigger Interface (CTI) is a generic CoreSight component
+that connects event sources like tracing components or CPU cores with each
+other through a common trigger matrix (CTM). For ARMv8 architecture, a
+CTI is mandatory for core run control and each core has an individual
+CTI instance attached to it. OpenOCD has limited support for CTI using
+the @emph{cti} group of commands.
+
+@deffn Command {cti create} cti_name @option{-dap} dap_name @option{-ap-num} apn @option{-ctibase} 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
+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.
+@end deffn
+
+@deffn Command {$cti_name enable} @option{on|off}
+Enable (@option{on}) or disable (@option{off}) the CTI.
+@end deffn
+
+@deffn Command {$cti_name dump}
+Displays a register dump of the CTI.
+@end deffn
+
+@deffn Command {$cti_name write } @var{reg_name} @var{value}
+Write @var{value} to the CTI register with the symbolic name @var{reg_name}.
+@end deffn
+
+@deffn Command {$cti_name read} @var{reg_name}
+Print the value read from the CTI register with the symbolic name @var{reg_name}.
+@end deffn
+
+@deffn Command {$cti_name testmode} @option{on|off}
+Enable (@option{on}) or disable (@option{off}) the integration test mode
+of the CTI.
+@end deffn
+
+@deffn Command {cti names}
+Prints a list of names of all CTI objects created. This command is mainly
+useful in TCL scripting.
+@end deffn
@section Generic ARM
@cindex ARM
Supervisor Call vector by OpenOCD.
@end deffn
+@deffn Command {arm semihosting_cmdline} [@option{enable}|@option{disable}]
+@cindex ARM semihosting
+Set the command line to be passed to the debugger.
+
+@example
+arm semihosting_cmdline argv0 argv1 argv2 ...
+@end example
+
+This option lets one set the command line arguments to be passed to
+the program. The first argument (argv0) is the program name in a
+standard C environment (argv[0]). Depending on the program (not much
+programs look at argv[0]), argv0 is ignored and can be any string.
+@end deffn
+
@deffn Command {arm semihosting_fileio} [@option{enable}|@option{disable}]
@cindex ARM semihosting
Display status of semihosting fileio, after optionally changing that
debugger.
@end deffn
+@deffn Command {arm semihosting_resexit} [@option{enable}|@option{disable}]
+@cindex ARM semihosting
+Enable resumable SEMIHOSTING_SYS_EXIT.
+
+When SEMIHOSTING_SYS_EXIT is called outside a debug session,
+things are simple, the openocd process calls exit() and passes
+the value returned by the target.
+
+When SEMIHOSTING_SYS_EXIT is called during a debug session,
+by default execution returns to the debugger, leaving the
+debugger in a HALT state, similar to the state entered when
+encountering a break.
+
+In some use cases, it is useful to have SEMIHOSTING_SYS_EXIT
+return normally, as any semihosting call, and do not break
+to the debugger.
+The standard allows this to happen, but the condition
+to trigger it is a bit obscure ("by performing an RDI_Execute
+request or equivalent").
+
+To make the SEMIHOSTING_SYS_EXIT call return normally, enable
+this option (default: disabled).
+@end deffn
+
@section ARMv4 and ARMv5 Architecture
@cindex ARMv4
@cindex ARMv5
handlers from the mini-IC, ignoring the code in RAM.
To address this situation, OpenOCD provides the @code{xscale
-vector_table} command, which allows the user to explicity write
+vector_table} command, which allows the user to explicitly write
individual entries to either the high or low vector table stored in
the mini-IC.
@cindex ARMv7
@cindex ARMv8
-@subsection ARMv7 and ARMv8 Debug Access Port (DAP) specific commands
-@cindex Debug Access Port
-@cindex DAP
-These commands are specific to ARM architecture v7 and v8 Debug Access Port (DAP),
-included on Cortex-M and Cortex-A systems.
-They are available in addition to other core-specific commands that may be available.
-
-@deffn Command {dap apid} [num]
-Displays ID register from AP @var{num},
-defaulting to the currently selected AP.
-@end deffn
-
-@deffn Command {dap apreg} ap_num reg [value]
-Displays content of a register @var{reg} from AP @var{ap_num}
-or set a new value @var{value}.
-@var{reg} is byte address of a word register, 0, 4, 8 ... 0xfc.
-@end deffn
-
-@deffn Command {dap apsel} [num]
-Select AP @var{num}, defaulting to 0.
-@end deffn
-
-@deffn Command {dap baseaddr} [num]
-Displays debug base address from MEM-AP @var{num},
-defaulting to the currently selected AP.
-@end deffn
-
-@deffn Command {dap info} [num]
-Displays the ROM table for MEM-AP @var{num},
-defaulting to the currently selected AP.
-@end deffn
-
-@deffn Command {dap memaccess} [value]
-Displays the number of extra tck cycles in the JTAG idle to use for MEM-AP
-memory bus access [0-255], giving additional time to respond to reads.
-If @var{value} is defined, first assigns that.
-@end deffn
-
-@deffn Command {dap apcsw} [0 / 1]
-fix CSW_SPROT from register AP_REG_CSW on selected dap.
-Defaulting to 0.
-@end deffn
-
-@deffn Command {dap ti_be_32_quirks} [@option{enable}]
-Set/get quirks mode for TI TMS450/TMS570 processors
-Disabled by default
-@end deffn
-
-
@subsection ARMv7-A specific commands
@cindex Cortex-A
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]
configure l2x cache
@end deffn
+@deffn Command {cortex_a mmu dump} [@option{0}|@option{1}|@option{addr} address [@option{num_entries}]]
+Dump the MMU translation table from TTB0 or TTB1 register, or from physical
+memory location @var{address}. When dumping the table from @var{address}, print at most
+@var{num_entries} page table entries. @var{num_entries} is optional, if omitted, the maximum
+possible (4096) entries are printed.
+@end deffn
@subsection ARMv7-R specific commands
@cindex Cortex-R
@item @code{itmdump -f /dev/ttyUSB1 -d1}
@item OpenOCD invocation line:
@example
-openocd -f interface/stlink-v2-1.cfg \
+openocd -f interface/stlink.cfg \
-c "transport select hla_swd" \
-f target/stm32l1.cfg \
-c "tpiu config external uart off 24000000 12000000"
@deffn Command {cortex_m maskisr} (@option{auto}|@option{on}|@option{off})
Control masking (disabling) interrupts during target step/resume.
-The @option{auto} option handles interrupts during stepping a way they get
-served but don't disturb the program flow. The step command first allows
+The @option{auto} option handles interrupts during stepping in a way that they
+get served but don't disturb the program flow. The step command first allows
pending interrupt handlers to execute, then disables interrupts and steps over
the next instruction where the core was halted. After the step interrupts
are enabled again. If the interrupt handlers don't complete within 500ms,
the step command leaves with the core running.
-Note that a free 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 does.
+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
+does.
Default is @option{auto}.
@end deffn
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 uneffected. 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.
@end deffn
+@deffn Command {aarch64 maskisr} [@option{on}|@option{off}]
+Selects whether interrupts will be processed when single stepping. The default configuration is
+@option{on}.
+@end deffn
+
+@section EnSilica eSi-RISC Architecture
+
+eSi-RISC is a highly configurable microprocessor architecture for embedded systems
+provided by EnSilica. (See: @url{http://www.ensilica.com/risc-ip/}.)
+
+@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 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},
+@option{reset}, @option{interrupt}, @option{syscall}, @option{error}, and @option{debug}.
+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
"timer" or any new group created with addreg command.
@end deffn
+@section RISC-V Architecture
+
+@uref{http://riscv.org/, RISC-V} is a free and open ISA. OpenOCD supports JTAG
+debug of RV32 and RV64 cores in heterogeneous multicore systems of up to 32
+harts. (It's possible to increase this limit to 1024 by changing
+RISCV_MAX_HARTS in riscv.h.) OpenOCD primarily supports 0.13 of the RISC-V
+Debug Specification, but there is also support for legacy targets that
+implement version 0.11.
+
+@subsection RISC-V Terminology
+
+A @emph{hart} is a hardware thread. A hart may share resources (eg. FPU) with
+another hart, or may be a separate core. RISC-V treats those the same, and
+OpenOCD exposes each hart as a separate core.
+
+@subsection RISC-V Debug Configuration Commands
+
+@deffn Command {riscv expose_csrs} n0[-m0][,n1[-m1]]...
+Configure a list of inclusive ranges for CSRs to expose in addition to the
+standard ones. This must be executed before `init`.
+
+By default OpenOCD attempts to expose only CSRs that are mentioned in a spec,
+and then only if the corresponding extension appears to be implemented. This
+command can be used if OpenOCD gets this wrong, or a target implements custom
+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).
+@end deffn
+
+@deffn Command {riscv set_reset_timeout_sec} [seconds]
+Set the maximum time to wait for a hart to come out of reset after reset is
+deasserted.
+@end deffn
+
+@deffn Command {riscv set_scratch_ram} none|[address]
+Set the address of 16 bytes of scratch RAM the debugger can use, or 'none'.
+This is used to access 64-bit floating point registers on 32-bit targets.
+@end deffn
+
+@deffn Command {riscv set_prefer_sba} on|off
+When on, prefer to use System Bus Access to access memory. When off, prefer to
+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
+trivial challenge-response protocol could be implemented as follows in a
+configuration file, immediately following @command{init}:
+@example
+set challenge [ocd_riscv authdata_read]
+riscv authdata_write [expr $challenge + 1]
+@end example
+
+@deffn Command {riscv authdata_read}
+Return the 32-bit value read from authdata. Note that to get read value back in
+a TCL script, it needs to be invoked as @command{ocd_riscv authdata_read}.
+@end deffn
+
+@deffn Command {riscv authdata_write} value
+Write the 32-bit value to authdata.
+@end deffn
+
+@subsection RISC-V DMI Commands
+
+The following commands allow direct access to the Debug Module Interface, which
+can be used to interact with custom debug features.
+
+@deffn Command {riscv dmi_read}
+Perform a 32-bit DMI read at address, returning the value. Note that to get
+read value back in a TCL script, it needs to be invoked as @command{ocd_riscv
+dmi_read}.
+@end deffn
+
+@deffn Command {riscv dmi_write} address value
+Perform a 32-bit DMI write of value at address.
+@end deffn
+
@anchor{softwaredebugmessagesandtracing}
@section Software Debug Messages and Tracing
@cindex Linux-ARM DCC support
In a debug session using JTAG for its transport protocol,
OpenOCD supports running such test files.
-@deffn Command {svf} filename [@option{quiet}]
+@deffn Command {svf} @file{filename} [@option{-tap @var{tapname}}] [@option{[-]quiet}] @
+ [@option{[-]nil}] [@option{[-]progress}] [@option{[-]ignore_error}]
This issues a JTAG reset (Test-Logic-Reset) and then
runs the SVF script from @file{filename}.
-Unless the @option{quiet} option is specified,
-each command is logged before it is executed.
+
+Arguments can be specified in any order; the optional dash doesn't
+affect their semantics.
+
+Command options:
+@itemize @minus
+@item @option{-tap @var{tapname}} ignore IR and DR headers and footers
+specified by the SVF file with HIR, TIR, HDR and TDR commands;
+instead, calculate them automatically according to the current JTAG
+chain configuration, targeting @var{tapname};
+@item @option{[-]quiet} do not log every command before execution;
+@item @option{[-]nil} ``dry run'', i.e., do not perform any operations
+on the real interface;
+@item @option{[-]progress} enable progress indication;
+@item @option{[-]ignore_error} continue execution despite TDO check
+errors.
+@end itemize
@end deffn
@section XSVF: Xilinx Serial Vector Format
only work for code running from flash memory. Most other ARM systems
do not have such restrictions.
-Another example of useful GDB configuration came from a user who
-found that single stepping his Cortex-M3 didn't work well with IRQs
-and an RTOS until he told GDB to disable the IRQs while stepping:
-
-@example
-define hook-step
-mon cortex_m maskisr on
-end
-define hookpost-step
-mon cortex_m maskisr off
-end
-@end example
-
Rather than typing such commands interactively, you may prefer to
save them in a file and have GDB execute them as it starts, perhaps
using a @file{.gdbinit} in your project directory or starting GDB
areas to be programmed lie within the target flash area the vFlash packets
will be used.
-If the target needs configuring before GDB programming, an event
-script can be executed:
+If the target needs configuring before GDB programming, set target
+event gdb-flash-erase-start:
@example
-$_TARGETNAME configure -event EVENTNAME BODY
+$_TARGETNAME configure -event gdb-flash-erase-start BODY
@end example
+@xref{targetevents,,Target Events}, for other GDB programming related events.
To verify any flash programming the GDB command @option{compare-sections}
can be used.
-@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
+@section Using GDB as a non-intrusive memory inspector
+@cindex Using GDB as a non-intrusive memory inspector
+@anchor{gdbmeminspect}
-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.
+If your project controls more than a blinking LED, let's say a heavy industrial
+robot or an experimental nuclear reactor, stopping the controlling process
+just because you want to attach GDB is not a good option.
+
+OpenOCD does not support GDB non-stop mode (might be implemented in the future).
+Though there is a possible setup where the target does not get stopped
+and GDB treats it as it were running.
+If the target supports background access to memory while it is running,
+you can use GDB in this mode to inspect memory (mainly global variables)
+without any intrusion of the target process.
+
+Remove default setting of gdb-attach event. @xref{targetevents,,Target Events}.
+Place following command after target configuration:
@example
-set $_core 1
-#Jc01 packet is sent
-print $_core
-#jc packet is sent and result is affected in $
+$_TARGETNAME configure -event gdb-attach @{@}
@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}).
+If any of installed flash banks does not support probe on running target,
+switch off gdb_memory_map:
+@example
+gdb_memory_map disable
+@end example
+Ensure GDB is configured without interrupt-on-connect.
+Some GDB versions set it by default, some does not.
@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
+set remote interrupt-on-connect off
@end example
-@end itemize
+
+If you switched gdb_memory_map off, you may want to setup GDB memory map
+manually or issue @command{set mem inaccessible-by-default off}
+
+Now you can issue GDB command @command{target remote ...} and inspect memory
+of a running target. Do not use GDB commands @command{continue},
+@command{step} or @command{next} as they synchronize GDB with your target
+and GDB would require stopping the target to get the prompt back.
+
+Do not use this mode under an IDE like Eclipse as it caches values of
+previously shown varibles.
@section RTOS Support
@cindex RTOS Support
@item @option{embKernel}
@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
_mqx_kernel_data, MQX_init_struct.
@item uC/OS-III symbols
OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty
+@item nuttx symbols
+g_readytorun, g_tasklisttable
@end table
For most RTOS supported the above symbols will be exported by default. However for
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
@itemize @bullet
@item @b{cygwin} Running under Cygwin
-@item @b{darwin} Darwin (Mac-OS) is the underlying operating sytem.
+@item @b{darwin} Darwin (Mac-OS) is the underlying operating system.
@item @b{freebsd} Running under FreeBSD
@item @b{openbsd} Running under OpenBSD
@item @b{netbsd} Running under NetBSD
-@item @b{linux} Linux is the underlying operating sytem
+@item @b{linux} Linux is the underlying operating system
@item @b{mingw32} Running under MingW32
@item @b{winxx} Built using Microsoft Visual Studio
@item @b{ecos} Running under eCos
@item @b{other} Unknown, none of the above.
@end itemize
-Note: 'winxx' was choosen because today (March-2009) no distinction is made between Win32 and Win64.
+Note: 'winxx' was chosen because today (March-2009) no distinction is made between Win32 and Win64.
@quotation Note
We should add support for a variable like Tcl variable
@cindex adaptive clocking
@*
-In digital circuit design it is often refered to as ``clock
+In digital circuit design it is often referred to as ``clock
synchronisation'' the JTAG interface uses one clock (TCK or TCLK)
operating at some speed, your CPU target is operating at another.
The two clocks are not synchronised, they are ``asynchronous''
claims to come with all the necessary DLLs. When using Cygwin, try launching
OpenOCD from the Cygwin shell.
-@item @b{Breakpoint Issue} I'm trying to set a breakpoint using GDB (or a frontend like Insight or
+@item @b{Breakpoint Issue} I'm trying to set a breakpoint using GDB (or a front-end like Insight or
Eclipse), but OpenOCD complains that "Info: arm7_9_common.c:213
arm7_9_add_breakpoint(): sw breakpoint requested, but software breakpoints not enabled".
gracefully stops.
@b{Debugging Interrupt Service Routines} - In your ISR before you call
-your C code, do the same - artifically push some zeros onto the stack,
+your C code, do the same - artificially push some zeros onto the stack,
remember to pop them off when the ISR is done.
@b{Also note:} If you have a multi-threaded operating system, they
Yes; whenever you have more than one, you must declare them in
the same order used by the hardware.
-Many newer devices have multiple JTAG TAPs. For example: ST
-Microsystems STM32 chips have two TAPs, a ``boundary scan TAP'' and
+Many newer devices have multiple JTAG TAPs. For example:
+STMicroelectronics STM32 chips have two TAPs, a ``boundary scan TAP'' and
``Cortex-M3'' TAP. Example: The STM32 reference manual, Document ID:
RM0008, Section 26.5, Figure 259, page 651/681, the ``TDI'' pin is
connected to the boundary scan TAP, which then connects to the
@section Per Rule #1 - All Results are strings
Every Tcl command results in a string. The word ``result'' is used
-deliberatly. No result is just an empty string. Remember: @i{Rule #1 -
+deliberately. No result is just an empty string. Remember: @i{Rule #1 -
Everything is a string}
@section Tcl Quoting Operators
By now you should know $VARIABLES always start with a $DOLLAR
sign. BTW: To set a variable, you actually use the command ``set'', as
-in ``set VARNAME VALUE'' much like the ancient BASIC langauge ``let x
+in ``set VARNAME VALUE'' much like the ancient BASIC language ``let x
= 1'' statement, but without the equal sign.
@itemize @bullet
As a script is parsed, each (multi) line in the script file is
tokenised and according to the quoting rules. After tokenisation, that
-line is immedatly executed.
+line is immediately executed.
Multi line statements end with one or more ``still-open''
@{curly-braces@} which - eventually - closes a few lines later.
@end example
Real Tcl is nearly identical. Although the newer versions have
-introduced a byte-code parser and intepreter, but at the core, it
+introduced a byte-code parser and interpreter, but at the core, it
still operates in the same basic way.
@subsection FOR command implementation
Remember Rule #1 - You are a string.
The @b{first} helper parses and executes commands found in an ascii
-string. Commands can be seperated by semicolons, or newlines. While
+string. Commands can be separated by semicolons, or newlines. While
parsing, variables are expanded via the quoting rules.
The @b{second} helper evaluates an ascii string as a numerical
@}
$_TARGETNAME configure -event FOO someproc
#2 Good - no variables
- $_TARGETNAME confgure -event foo "this ; that;"
+ $_TARGETNAME configure -event foo "this ; that;"
#3 Good Curly Braces
$_TARGETNAME configure -event FOO @{
puts "Time: [date]"
@*There are 4 examples:
@enumerate
@item The TCLBODY is a simple string that happens to be a proc name
-@item The TCLBODY is several simple commands seperated by semicolons
+@item The TCLBODY is several simple commands separated by semicolons
@item The TCLBODY is a multi-line @{curly-brace@} quoted string
@item The TCLBODY is a string with variables that get expanded.
@end enumerate
Code Review / openocd.git / blobdiff