@* A JTAG driver acting as a client for the JTAG VPI server interface.
@* Link: @url{http://github.com/fjullien/jtag_vpi}
+@item @b{xlnx_pcie_xvc}
+@* A JTAG driver exposing Xilinx Virtual Cable over PCI Express to OpenOCD as JTAG interface.
+
@end itemize
@node About Jim-Tcl
If both the chip and the board support adaptive clocking,
use the @command{jtag_rclk}
command, in case your board is used with JTAG adapter which
-also supports it. Otherwise use @command{adapter_khz}.
+also supports it. Otherwise use @command{adapter speed}.
Set the slow rate at the beginning of the reset sequence,
and the faster rate as soon as the clocks are at full speed.
reset_config trst_and_srst trst_pulls_srst
$_TARGETNAME configure -event reset-start @{
- adapter_khz 100
+ adapter speed 100
@}
$_TARGETNAME configure -event reset-init @{
enable_fast_clock
- adapter_khz 10000
+ adapter speed 10000
@}
@}
@end example
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
@example
# jlink interface
-interface jlink
+adapter driver jlink
@end example
Most adapters need a bit more configuration than that.
-@section Interface Configuration
+@section Adapter Configuration
-The interface command tells OpenOCD what type of debug adapter you are
+The @command{adapter driver} command tells OpenOCD what type of debug adapter you are
using. Depending on the type of adapter, you may need to use one or
more additional commands to further identify or configure the adapter.
-@deffn {Config Command} {interface} name
-Use the interface driver @var{name} to connect to the
+@deffn {Config Command} {adapter driver} name
+Use the adapter driver @var{name} to connect to the
target.
@end deffn
-@deffn Command {interface_list}
+@deffn Command {adapter list}
List the debug adapter drivers that have been built into
the running copy of OpenOCD.
@end deffn
-@deffn Command {interface transports} transport_name+
+@deffn Command {adapter transports} transport_name+
Specifies the transports supported by this debug adapter.
The adapter driver builds-in similar knowledge; use this only
when external configuration (such as jumpering) changes what
-@deffn Command {adapter_name}
+@deffn Command {adapter name}
Returns the name of the debug adapter driver being used.
@end deffn
+@anchor{adapter_usb_location}
+@deffn Command {adapter usb location} [<bus>-<port>[.<port>]...]
+Displays or specifies the physical USB port of the adapter to use. The path
+roots at @var{bus} and walks down the physical ports, with each
+@var{port} option specifying a deeper level in the bus topology, the last
+@var{port} denoting where the target adapter is actually plugged.
+The USB bus topology can be queried with the command @emph{lsusb -t} or @emph{dmesg}.
+
+This command is only available if your libusb1 is at least version 1.0.16.
+@end deffn
+
@section Interface Drivers
Each of the interface drivers listed here must be explicitly
and are not restricted to containing only decimal digits.)
@end deffn
-@deffn {Config Command} {ftdi_location} <bus>:<port>[,<port>]...
+@deffn {Config Command} {ftdi_location} <bus>-<port>[.<port>]...
+@emph{DEPRECATED -- avoid using this.
+Use the command @ref{adapter_usb_location,,adapter usb location} 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
something like:
@example
-interface remote_bitbang
+adapter driver remote_bitbang
remote_bitbang_port 3335
remote_bitbang_host foobar
@end example
named mysocket:
@example
-interface remote_bitbang
+adapter driver remote_bitbang
remote_bitbang_port 0
remote_bitbang_host mysocket
@end example
@deffn Command {parport_toggling_time} [nanoseconds]
Displays how many nanoseconds the hardware needs to toggle TCK;
the parport driver uses this value to obey the
-@command{adapter_khz} configuration.
+@command{adapter speed} configuration.
When the optional @var{nanoseconds} parameter is given,
that setting is changed before displaying the current value.
oscilloscope, follow the procedure below:
@example
> parport_toggling_time 1000
-> adapter_khz 500
+> adapter speed 500
@end example
This sets the maximum JTAG clock speed of the hardware, but
the actual speed probably deviates from the requested 500 kHz.
@example
> parport_toggling_time <measured nanoseconds>
@end example
-Now the clock speed will be a better match for @command{adapter_khz rate}
-commands given in OpenOCD scripts and event handlers.
+Now the clock speed will be a better match for @command{adapter speed}
+command given in OpenOCD scripts and event handlers.
You can do something similar with many digital multimeters, but note
that you'll probably need to run the clock continuously for several
seconds before it decides what clock rate to show. Adjust the
toggling time up or down until the measured clock rate is a good
-match for the adapter_khz rate you specified; be conservative.
+match with the rate you specified in the @command{adapter speed} command;
+be conservative.
@end quotation
@end deffn
classic ``Wiggler'' cable on LPT2 might look something like this:
@example
-interface parport
+adapter driver parport
parport_port 0x278
parport_cable wiggler
@end example
@end deffn
@end deffn
+@anchor{st_link_dap_interface}
+@deffn {Interface Driver} {st-link}
+This is a driver that supports STMicroelectronics adapters ST-LINK/V2
+(from firmware V2J24) and STLINK-V3, thanks to a new API that provides
+directly access the arm ADIv5 DAP.
+
+The new API provide access to multiple AP on the same DAP, but the
+maximum number of the AP port is limited by the specific firmware version
+(e.g. firmware V2J29 has 3 as maximum AP number, while V2J32 has 8).
+An error is returned for any AP number above the maximum allowed value.
+
+@emph{Note:} Either these same adapters and their older versions are
+also supported by @ref{hla_interface, the hla interface driver}.
+
+@deffn {Config Command} {st-link serial} serial
+Specifies the serial number of the adapter.
+@end deffn
+
+@deffn {Config Command} {st-link vid_pid} [vid pid]+
+Pairs of vendor IDs and product IDs of the device.
+@end deffn
+@end deffn
+
@deffn {Interface Driver} {opendous}
opendous-jtag is a freely programmable USB adapter.
@end deffn
This is the Keil ULINK v1 JTAG debugger.
@end deffn
+@deffn {Interface Driver} {xlnx_pcie_xvc}
+This driver supports the Xilinx Virtual Cable (XVC) over PCI Express.
+It is commonly found in Xilinx based PCI Express designs. It allows debugging
+fabric based JTAG devices such as Cortex-M1/M3 microcontrollers. Access to this is
+exposed via extended capability registers in the PCI Express configuration space.
+
+For more information see Xilinx PG245 (Section on From_PCIE_to_JTAG mode).
+
+@deffn {Config Command} {xlnx_pcie_xvc_config} device
+Specifies the PCI Express device via parameter @var{device} to use.
+
+The correct value for @var{device} can be obtained by looking at the output
+of lscpi -D (first column) for the corresponding device.
+
+The string will be of the format "DDDD:BB:SS.F" such as "0000:65:00.1".
+
+@end deffn
+@end deffn
+
@deffn {Interface Driver} {ZY1000}
This is the Zylin ZY1000 JTAG debugger.
@end deffn
Flash programming support is built on top of debug support.
JTAG transport is selected with the command @command{transport select
-jtag}. Unless your adapter uses @ref{hla_interface,the hla interface
-driver}, in which case the command is @command{transport select
-hla_jtag}.
+jtag}. Unless your adapter uses either @ref{hla_interface,the hla interface
+driver} (in which case the command is @command{transport select hla_jtag})
+or @ref{st_link_dap_interface,the st-link interface driver} (in which case
+the command is @command{transport select dapdirect_jtag}).
@subsection SWD Transport
@cindex SWD
(Some processors support both JTAG and SWD.)
SWD transport is selected with the command @command{transport select
-swd}. Unless your adapter uses @ref{hla_interface,the hla interface
-driver}, in which case the command is @command{transport select
-hla_swd}.
+swd}. Unless your adapter uses either @ref{hla_interface,the hla interface
+driver} (in which case the command is @command{transport select hla_swd})
+or @ref{st_link_dap_interface,the st-link interface driver} (in which case
+the command is @command{transport select dapdirect_swd}).
@deffn Command {swd newdap} ...
Declares a single DAP which uses SWD transport.
may not be the fastest solution.
@b{NOTE:} Script writers should consider using @command{jtag_rclk}
-instead of @command{adapter_khz}, but only for (ARM) cores and boards
+instead of @command{adapter speed}, but only for (ARM) cores and boards
which support adaptive clocking.
-@deffn {Command} adapter_khz max_speed_kHz
+@deffn {Command} adapter speed max_speed_kHz
A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
JTAG interfaces usually support a limited number of
speeds. The speed actually used won't be faster
requirements that all reset pulses last for at least a
certain amount of time; and reset buttons commonly have
hardware debouncing.
-Use the @command{adapter_nsrst_delay} and @command{jtag_ntrst_delay}
+Use the @command{adapter srst delay} and @command{jtag_ntrst_delay}
commands to say when extra delays are needed.
@item @emph{Drive type} ... Reset lines often have a pullup
@section Commands for Handling Resets
-@deffn {Command} adapter_nsrst_assert_width milliseconds
+@deffn {Command} adapter srst pulse_width milliseconds
Minimum amount of time (in milliseconds) OpenOCD should wait
after asserting nSRST (active-low system reset) before
allowing it to be deasserted.
@end deffn
-@deffn {Command} adapter_nsrst_delay milliseconds
+@deffn {Command} adapter srst delay milliseconds
How long (in milliseconds) OpenOCD should wait after deasserting
nSRST (active-low system reset) before starting new JTAG operations.
When a board has a reset button connected to SRST line it will
nTRST (active-low JTAG TAP reset) before starting new JTAG operations.
@end deffn
-@anchor {reset_config}
+@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
or asserting both might trigger a stronger reset, which
needs special attention.
-Experiment with lower level operations, such as @command{jtag_reset}
+Experiment with lower level operations, such as
+@command{adapter assert}, @command{adapter deassert}
and the @command{jtag arp_*} operations shown here,
to find a sequence of operations that works.
@xref{JTAG Commands}.
The default implementation just invokes @command{jtag arp_init-reset}.
Replacements will normally build on low level JTAG
-operations such as @command{jtag_reset}.
+operations such as @command{adapter assert} and @command{adapter deassert}.
Operations here must not address individual TAPs
(or their associated targets)
until the JTAG scan chain has first been verified to work.
@section Other TAP commands
+@deffn Command {jtag cget} dotted.name @option{-idcode}
+Get the value of the IDCODE found in hardware.
+@end deffn
+
@deffn Command {jtag cget} dotted.name @option{-event} event_name
@deffnx Command {jtag configure} dotted.name @option{-event} event_name handler
At this writing this TAP attribute
-mechanism is used only for event handling.
+mechanism is limited and used mostly for event handling.
(It is not a direct analogue of the @code{cget}/@code{configure}
mechanism for debugger targets.)
See the next section for information about the available events.
The current implementation supports eSi-32xx cores.
@item @code{fa526} -- resembles arm920 (w/o Thumb)
@item @code{feroceon} -- resembles arm926
+@item @code{mem_ap} -- this is an ARM debug infrastructure Access Port without a CPU, through which bus read and write cycles can be generated; it may be useful for working with non-CPU hardware behind an AP or during development of support for new CPUs.
@item @code{mips_m4k} -- a MIPS core
@item @code{xscale} -- this is actually an architecture,
not a CPU type. It is based on the ARMv5 architecture.
@item @code{ls1_sap} -- this is the SAP on NXP LS102x CPUs,
allowing access to physical memory addresses independently of CPU cores.
@itemize @minus
-@item @code{OpenCores TAP} (See: @url{http://opencores.org/project,jtag})
+@item @code{OpenCores TAP} (See: @url{http://opencores.org/project@comma{}jtag})
@item @code{Altera Virtual JTAG TAP} (See: @url{http://www.altera.com/literature/ug/ug_virtualjtag.pdf})
@item @code{Xilinx BSCAN_* virtual JTAG interface} (See: @url{http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_2/spartan6_hdl.pdf})
@end itemize
And two debug interfaces cores:
@itemize @minus
-@item @code{Advanced debug interface} (See: @url{http://opencores.org/project,adv_debug_sys})
-@item @code{SoC Debug Interface} (See: @url{http://opencores.org/project,dbg_interface})
+@item @code{Advanced debug interface} (See: @url{http://opencores.org/project@comma{}adv_debug_sys})
+@item @code{SoC Debug Interface} (See: @url{http://opencores.org/project@comma{}dbg_interface})
@end itemize
@end itemize
@end deffn
code, for example by the reset code in @file{startup.tcl}.)
@end deffn
-@deffn Command {$target_name mdw} addr [count]
-@deffnx Command {$target_name mdh} addr [count]
-@deffnx Command {$target_name mdb} addr [count]
+@deffn Command {$target_name mdd} [phys] addr [count]
+@deffnx Command {$target_name mdw} [phys] addr [count]
+@deffnx Command {$target_name mdh} [phys] addr [count]
+@deffnx Command {$target_name mdb} [phys] addr [count]
Display contents of address @var{addr}, as
+64-bit doublewords (@command{mdd}),
32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}),
or 8-bit bytes (@command{mdb}).
+When the current target has an MMU which is present and active,
+@var{addr} is interpreted as a virtual address.
+Otherwise, or if the optional @var{phys} flag is specified,
+@var{addr} is interpreted as a physical address.
If @var{count} is specified, displays that many units.
(If you want to manipulate the data instead of displaying it,
see the @code{mem2array} primitives.)
@end deffn
-@deffn Command {$target_name mww} addr word
-@deffnx Command {$target_name mwh} addr halfword
-@deffnx Command {$target_name mwb} addr byte
-Writes the specified @var{word} (32 bits),
-@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+@deffn Command {$target_name mwd} [phys] addr doubleword [count]
+@deffnx Command {$target_name mww} [phys] addr word [count]
+@deffnx Command {$target_name mwh} [phys] addr halfword [count]
+@deffnx Command {$target_name mwb} [phys] addr byte [count]
+Writes the specified @var{doubleword} (64 bits), @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) value,
at the specified address @var{addr}.
+When the current target has an MMU which is present and active,
+@var{addr} is interpreted as a virtual address.
+Otherwise, or if the optional @var{phys} flag is specified,
+@var{addr} is interpreted as a physical address.
+If @var{count} is specified, fills that many units of consecutive address.
@end deffn
@anchor{targetevents}
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,
+or @command{adapter speed} to switch to a low JTAG clock rate,
when reset disables PLLs needed to use a fast clock.
@item @b{resume-start}
@* Before any target is resumed
@end quotation
@end deffn
-@comment the REAL name for this command is "ocd_flash_banks"
@comment less confusing would be: "flash list" (like "nand list")
@deffn Command {flash banks}
Prints a one-line summary of each device that was
but most don't bother.
@end deffn
+@section Preparing a Target before Flash Programming
+
+The target device should be in well defined state before the flash programming
+begins.
+
+@emph{Always issue} @command{reset init} before @ref{flashprogrammingcommands,,Flash Programming Commands}.
+Do not issue another @command{reset} or @command{reset halt} or @command{resume}
+until the programming session is finished.
+
+If you use @ref{programmingusinggdb,,Programming using GDB},
+the target is prepared automatically in the event gdb-flash-erase-start
+
+The jimtcl script @command{program} calls @command{reset init} explicitly.
+
@section Erasing, Reading, Writing to Flash
@cindex flash erasing
@cindex flash reading
before erase starts.
@end deffn
-@deffn Command {flash fillw} address word length
+@deffn Command {flash filld} address double-word length
+@deffnx Command {flash fillw} address word length
@deffnx Command {flash fillh} address halfword length
@deffnx Command {flash fillb} address byte length
-Fills flash memory with the specified @var{word} (32 bits),
+Fills flash memory with the specified @var{double-word} (64 bits), @var{word} (32 bits),
@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
starting at @var{address} and continuing
for @var{length} units (word/halfword/byte).
@end deffn
@anchor{program}
-@deffn Command {program} filename [verify] [reset] [exit] [offset]
+@deffn Command {program} filename [preverify] [verify] [reset] [exit] [offset]
This is a helper script that simplifies using OpenOCD as a standalone
programmer. The only required parameter is @option{filename}, the others are optional.
@xref{Flash Programming}.
@end deffn
+@deffn {Flash Driver} fespi
+@cindex Freedom E SPI
+@cindex fespi
+
+SiFive's Freedom E SPI controller, used in HiFive and other boards.
+
+@example
+flash bank $_FLASHNAME fespi 0x20000000 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
@subsection Internal Flash (Microcontrollers)
@deffn {Flash Driver} aduc702x
@anchor{at91samd}
@deffn {Flash Driver} at91samd
@cindex at91samd
-All members of the ATSAMD, ATSAMR, ATSAML and ATSAMC microcontroller
+All members of the ATSAM D2x, D1x, D0x, ATSAMR, ATSAML and ATSAMC microcontroller
families from Atmel include internal flash and use ARM's Cortex-M0+ core.
-This driver uses the same command names/syntax as @xref{at91sam3}.
+
+Do not use for ATSAM D51 and E5x: use @xref{atsame5}.
+
+The devices have one flash bank:
+
+@example
+flash bank $_FLASHNAME at91samd 0x00000000 0 1 1 $_TARGETNAME
+@end example
@deffn Command {at91samd chip-erase}
Issues a complete Flash erase via the Device Service Unit (DSU). This can be
@end deffn
@end deffn
+@anchor{atsame5}
+@deffn {Flash Driver} atsame5
+@cindex atsame5
+All members of the SAM E54, E53, E51 and D51 microcontroller
+families from Microchip (former Atmel) include internal flash
+and use ARM's Cortex-M4 core.
+
+The devices have two ECC flash banks with a swapping feature.
+This driver handles both banks together as it were one.
+Bank swapping is not supported yet.
+
+@example
+flash bank $_FLASHNAME atsame5 0x00000000 0 1 1 $_TARGETNAME
+@end example
+
+@deffn Command {atsame5 bootloader}
+Shows or sets the bootloader size configuration, stored in the User Page of the
+Flash. This is called the BOOTPROT region. When setting, the bootloader size
+must be specified in bytes. The nearest bigger protection size is used.
+Settings are written immediately but only take effect on MCU reset.
+Setting the bootloader size to 0 disables bootloader protection.
+
+@example
+atsame5 bootloader
+atsame5 bootloader 16384
+@end example
+@end deffn
+
+@deffn Command {atsame5 chip-erase}
+Issues a complete Flash erase via the Device Service Unit (DSU). This can be
+used to erase a chip back to its factory state and does not require the
+processor to be halted.
+@end deffn
+
+@deffn Command {atsame5 dsu_reset_deassert}
+This command releases internal reset held by DSU
+and prepares reset vector catch in case of reset halt.
+Command is used internally in event event reset-deassert-post.
+@end deffn
+
+@deffn Command {atsame5 userpage}
+Writes or reads the first 64 bits of NVM User Page which is located at
+0x804000. This field includes various fuses.
+Reading is done by invoking this command without any arguments.
+Writing is possible by giving 1 or 2 hex values. The first argument
+is the value to be written and the second one is an optional bit mask
+(a zero bit in the mask means the bit stays unchanged).
+The reserved fields are always masked out and cannot be changed.
+
+@example
+# Read
+>atsame5 userpage
+USER PAGE: 0xAEECFF80FE9A9239
+# Write
+>atsame5 userpage 0xAEECFF80FE9A9239
+# Write 2 to SEESBLK and 4 to SEEPSZ fields but leave other bits unchanged
+# (setup SmartEEPROM of virtual size 8192 bytes)
+>atsame5 userpage 0x4200000000 0x7f00000000
+@end example
+@end deffn
+
+@end deffn
+
@deffn {Flash Driver} atsamv
@cindex atsamv
-All members of the ATSAMV, ATSAMS, and ATSAME families from
+All members of the ATSAMV7x, ATSAMS70, and ATSAME70 families from
Atmel include internal flash and use ARM's Cortex-M7 core.
This driver uses the same command names/syntax as @xref{at91sam3}.
@end deffn
code.
@end deffn
+@deffn Command {nrf5 info}
+Decodes and shows informations from FICR and UICR registers.
+@end deffn
+
@end deffn
@deffn {Flash Driver} ocl
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32f1x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP})
+@deffn Command {stm32f1x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP}) (@option{USEROPT} user_data)
Writes the stm32 option byte with the specified values.
The @var{num} parameter is a value shown by @command{flash banks}.
+The @var{user_data} parameter is content of higher 16 bits of the option byte register (Data0 and Data1 as one 16bit number).
@end deffn
@deffn Command {stm32f1x options_load} num
flash bank $_FLASHNAME stm32f2x 0 0 0 0 $_TARGETNAME
@end example
+If you use OTP (One-Time Programmable) memory define it as a second bank
+as per the following example.
+@example
+flash bank $_FLASHNAME stm32f2x 0x1FFF7800 0 0 0 $_TARGETNAME
+@end example
+
+@deffn Command {stm32f2x otp } num (@option{enable}|@option{disable}|@option{show})
+Enables or disables OTP write commands for bank @var{num}.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
Note that some devices have been found that have a flash size register that contains
an invalid value, to workaround this issue you can override the probed value used by
the flash driver.
Mass erases the entire stm32h7x device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
+
+@deffn Command {stm32h7x option_read} num reg_offset
+Reads an option byte register from the stm32h7x 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 from the used bank registers' base.
+For example: in STM32H74x/H75x the bank 1 registers' base is 0x52002000 and 0x52002100 for bank 2.
+
+Example usage:
+@example
+# read OPTSR_CUR
+stm32h7x option_read 0 0x1c
+# read WPSN_CUR1R
+stm32h7x option_read 0 0x38
+# read WPSN_CUR2R
+stm32h7x option_read 1 0x38
+@end example
+@end deffn
+
+@deffn Command {stm32h7x option_write} num reg_offset value [reg_mask]
+Writes an option byte register of the stm32h7x 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 from the used bank register base,
+and @var{reg_mask} is the mask to apply when writing the register (only bits with a '1'
+will be touched).
+
+Example usage:
+@example
+# swap bank 1 and bank 2 in dual bank devices, by setting SWAP_BANK_OPT bit in OPTSR_PRG
+stm32h7x option_write 0 0x20 0x8000000 0x8000000
+@end example
+@end deffn
@end deffn
@deffn {Flash Driver} stm32lx
-All members of the STM32L microcontroller families from STMicroelectronics
+All members of the STM32L0 and STM32L1 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.
@end deffn
@deffn {Flash Driver} stm32l4x
-All members of the STM32L4 microcontroller families from STMicroelectronics
+All members of the STM32L4 and STM32WB 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.
For example to read the FLASH_OPTR register:
@example
stm32l4x option_read 0 0x20
-# Option Register: <0x40022020> = 0xffeff8aa
+# Option Register (for STM32L4x): <0x40022020> = 0xffeff8aa
+# Option Register (for STM32WBx): <0x58004020> = ...
+# The correct flash base address will be used automatically
@end example
The above example will read out the FLASH_OPTR register which contains the RDP
@example
# assert srst, we do not want core running
# while accessing str9xpec flash driver
-jtag_reset 0 1
+adapter assert srst
# turn off target polling
poll off
# disable str9 core
@end deffn
+@deffn {Flash Driver} swm050
+@cindex swm050
+All members of the swm050 microcontroller family from Foshan Synwit Tech.
+
+@example
+flash bank $_FLASHNAME swm050 0x0 0x2000 0 0 $_TARGETNAME
+@end example
+
+One swm050-specific command is defined:
+
+@deffn Command {swm050 mass_erase} bank_id
+Erases the entire flash bank.
+@end deffn
+
+@end deffn
+
+
@deffn {Flash Driver} tms470
Most members of the TMS470 microcontroller family from Texas Instruments
include internal flash and use ARM7TDMI cores.
change any behavior.
@end deffn
-@section mFlash
-
-@subsection mFlash Configuration
-@cindex mFlash Configuration
-
-@deffn {Config Command} {mflash bank} soc base RST_pin target
-Configures a mflash for @var{soc} host bank at
-address @var{base}.
-The pin number format depends on the host GPIO naming convention.
-Currently, the mflash driver supports s3c2440 and pxa270.
-
-Example for s3c2440 mflash where @var{RST pin} is GPIO B1:
-
-@example
-mflash bank $_FLASHNAME s3c2440 0x10000000 1b 0
-@end example
-
-Example for pxa270 mflash where @var{RST pin} is GPIO 43:
-
-@example
-mflash bank $_FLASHNAME pxa270 0x08000000 43 0
-@end example
-@end deffn
-
-@subsection mFlash commands
-@cindex mFlash commands
-
-@deffn Command {mflash config pll} frequency
-Configure mflash PLL.
-The @var{frequency} is the mflash input frequency, in Hz.
-Issuing this command will erase mflash's whole internal nand and write new pll.
-After this command, mflash needs power-on-reset for normal operation.
-If pll was newly configured, storage and boot(optional) info also need to be update.
-@end deffn
-
-@deffn Command {mflash config boot}
-Configure bootable option.
-If bootable option is set, mflash offer the first 8 sectors
-(4kB) for boot.
-@end deffn
-
-@deffn Command {mflash config storage}
-Configure storage information.
-For the normal storage operation, this information must be
-written.
-@end deffn
-
-@deffn Command {mflash dump} num filename offset size
-Dump @var{size} bytes, starting at @var{offset} bytes from the
-beginning of the bank @var{num}, to the file named @var{filename}.
-@end deffn
-
-@deffn Command {mflash probe}
-Probe mflash.
-@end deffn
-
-@deffn Command {mflash write} num filename offset
-Write the binary file @var{filename} to mflash bank @var{num}, starting at
-@var{offset} bytes from the beginning of the bank.
-@end deffn
-
@node Flash Programming
@chapter Flash Programming
OpenOCD implements numerous ways to program the target flash, whether internal or external.
-Programming can be achieved by either using GDB @ref{programmingusinggdb,,Programming using GDB},
+Programming can be achieved by either using @ref{programmingusinggdb,,Programming using GDB},
or using the commands given in @ref{flashprogrammingcommands,,Flash Programming Commands}.
@*To simplify using the flash commands directly a jimtcl script is available that handles the programming and verify stage.
@item 'init' is executed.
@item 'reset init' is called to reset and halt the target, any 'reset init' scripts are executed.
@item @code{flash write_image} is called to erase and write any flash using the filename given.
+@item If the @option{preverify} parameter is given, the target is "verified" first and only flashed if this fails.
@item @code{verify_image} is called if @option{verify} parameter is given.
@item @code{reset run} is called if @option{reset} parameter is given.
@item OpenOCD is shutdown if @option{exit} parameter is given.
@end example
@end deffn
-@deffn Command log_output [filename]
-Redirect logging to @var{filename};
-the initial log output channel is stderr.
+@deffn Command log_output [filename | "default"]
+Redirect logging to @var{filename} or set it back to default output;
+the default log output channel is stderr.
@end deffn
@deffn Command add_script_search_dir [directory]
state.
@end deffn
+@deffn Command {adapter assert} [signal [assert|deassert signal]]
+@deffnx Command {adapter deassert} [signal [assert|deassert signal]]
+Set values of reset signals.
+Without parameters returns current status of the signals.
+The @var{signal} parameter values may be
+@option{srst}, indicating that srst signal is to be asserted or deasserted,
+@option{trst}, indicating that trst signal is to be asserted or deasserted.
+
+The @command{reset_config} command should already have been used
+to configure how the board and the adapter treat these two
+signals, and to say if either signal is even present.
+@xref{Reset Configuration}.
+Trying to assert a signal that is not present triggers an error.
+If a signal is present on the adapter and not specified in the command,
+the signal will not be modified.
+
+@quotation Note
+TRST is specially handled.
+It actually signifies JTAG's @sc{reset} state.
+So if the board doesn't support the optional TRST signal,
+or it doesn't support it along with the specified SRST value,
+JTAG reset is triggered with TMS and TCK signals
+instead of the TRST signal.
+And no matter how that JTAG reset is triggered, once
+the scan chain enters @sc{reset} with TRST inactive,
+TAP @code{post-reset} events are delivered to all TAPs
+with handlers for that event.
+@end quotation
+@end deffn
+
@section I/O Utilities
These commands are available when
about what TAP is the current target, or about MMU configuration.
@end enumerate
-@deffn Command mdw [phys] addr [count]
+@deffn Command mdd [phys] addr [count]
+@deffnx Command mdw [phys] addr [count]
@deffnx Command mdh [phys] addr [count]
@deffnx Command mdb [phys] addr [count]
Display contents of address @var{addr}, as
+64-bit doublewords (@command{mdd}),
32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}),
or 8-bit bytes (@command{mdb}).
When the current target has an MMU which is present and active,
see the @code{mem2array} primitives.)
@end deffn
-@deffn Command mww [phys] addr word
-@deffnx Command mwh [phys] addr halfword
-@deffnx Command mwb [phys] addr byte
-Writes the specified @var{word} (32 bits),
+@deffn Command mwd [phys] addr doubleword [count]
+@deffnx Command mww [phys] addr word [count]
+@deffnx Command mwh [phys] addr halfword [count]
+@deffnx Command mwb [phys] addr byte [count]
+Writes the specified @var{doubleword} (64 bits), @var{word} (32 bits),
@var{halfword} (16 bits), or @var{byte} (8-bit) value,
at the specified address @var{addr}.
When the current target has an MMU which is present and active,
@var{addr} is interpreted as a virtual address.
Otherwise, or if the optional @var{phys} flag is specified,
@var{addr} is interpreted as a physical address.
+If @var{count} is specified, fills that many units of consecutive address.
@end deffn
@anchor{imageaccess}
Print the value read from the CTI register with the symbolic name @var{reg_name}.
@end deffn
+@deffn Command {$cti_name ack} @var{event}
+Acknowledge a CTI @var{event}.
+@end deffn
+
+@deffn Command {$cti_name channel} @var{channel_number} @var{operation}
+Perform a specific channel operation, the possible operations are:
+gate, ungate, set, clear and pulse
+@end deffn
+
@deffn Command {$cti_name testmode} @option{on|off}
Enable (@option{on}) or disable (@option{off}) the integration test mode
of the CTI.
Enables debug by unlocking the Software Lock and clearing sticky powerdown indications
@end deffn
-@deffn Command {cortex_a smp_off}
-Disable SMP mode
-@end deffn
-
-@deffn Command {cortex_a smp_on}
-Enable SMP mode
+@deffn Command {cortex_a smp} [on|off]
+Display/set the current SMP mode
@end deffn
@deffn Command {cortex_a smp_gdb} [core_id]
@subsection Cortex-M specific commands
@cindex Cortex-M
-@deffn Command {cortex_m maskisr} (@option{auto}|@option{on}|@option{off})
+@deffn Command {cortex_m maskisr} (@option{auto}|@option{on}|@option{off}|@option{steponly})
Control masking (disabling) interrupts during target step/resume.
The @option{auto} option handles interrupts during stepping in a way that they
are enabled again. If the interrupt handlers don't complete within 500ms,
the step command leaves with the core running.
+The @option{steponly} option disables interrupts during single-stepping but
+enables them during normal execution. This can be used as a partial workaround
+for 702596 erratum in Cortex-M7 r0p1. See "Cortex-M7 (AT610) and Cortex-M7 with
+FPU (AT611) Software Developer Errata Notice" from ARM for further details.
+
Note that a free hardware (FPB) breakpoint is required for the @option{auto}
option. If no breakpoint is available at the time of the step, then the step
is taken with interrupts enabled, i.e. the same way the @option{off} option
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.
@option{on}.
@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 EnSilica eSi-RISC Architecture
eSi-RISC is a highly configurable microprocessor architecture for embedded systems
@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
+configuration changes. If a trace buffer has been configured, the contents will
be overwritten when trace collection starts.
@end deffn
CSRs.
@end deffn
+@deffn Command {riscv expose_custom} n0[-m0][,n1[-m1]]...
+The RISC-V Debug Specification allows targets to expose custom registers
+through abstract commands. (See Section 3.5.1.1 in that document.) This command
+configures a list of inclusive ranges of those registers to expose. Number 0
+indicates the first custom register, whose abstract command number is 0xc000.
+This command must be executed before `init`.
+@end deffn
+
@deffn Command {riscv set_command_timeout_sec} [seconds]
Set the wall-clock timeout (in seconds) for individual commands. The default
should work fine for all but the slowest targets (eg. simulators).
use the Program Buffer to access memory.
@end deffn
+@deffn Command {riscv set_ir} (@option{idcode}|@option{dtmcs}|@option{dmi}) [value]
+Set the IR value for the specified JTAG register. This is useful, for
+example, when using the existing JTAG interface on a Xilinx FPGA by
+way of BSCANE2 primitives that only permit a limited selection of IR
+values.
+
+When utilizing version 0.11 of the RISC-V Debug Specification,
+@option{dtmcs} and @option{dmi} set the IR values for the DTMCONTROL
+and DBUS registers, respectively.
+@end deffn
+
@subsection RISC-V Authentication Commands
The following commands can be used to authenticate to a RISC-V system. Eg. a
trivial challenge-response protocol could be implemented as follows in a
configuration file, immediately following @command{init}:
@example
-set challenge [ocd_riscv authdata_read]
+set challenge [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}.
+Return the 32-bit value read from authdata.
@end deffn
@deffn Command {riscv authdata_write} value
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}.
+Perform a 32-bit DMI read at address, returning the value.
@end deffn
@deffn Command {riscv dmi_write} address value
@end quotation
@end deffn
-@deffn Command {jtag_reset} trst srst
-Set values of reset signals.
-The @var{trst} and @var{srst} parameter values may be
-@option{0}, indicating that reset is inactive (pulled or driven high),
-or @option{1}, indicating it is active (pulled or driven low).
-The @command{reset_config} command should already have been used
-to configure how the board and JTAG adapter treat these two
-signals, and to say if either signal is even present.
-@xref{Reset Configuration}.
-
-Note that TRST is specially handled.
-It actually signifies JTAG's @sc{reset} state.
-So if the board doesn't support the optional TRST signal,
-or it doesn't support it along with the specified SRST value,
-JTAG reset is triggered with TMS and TCK signals
-instead of the TRST signal.
-And no matter how that JTAG reset is triggered, once
-the scan chain enters @sc{reset} with TRST inactive,
-TAP @code{post-reset} events are delivered to all TAPs
-with handlers for that event.
-@end deffn
-
@deffn Command {pathmove} start_state [next_state ...]
Start by moving to @var{start_state}, which
must be one of the @emph{stable} states.
Do not use this mode under an IDE like Eclipse as it caches values of
previously shown varibles.
-@anchor{usingopenocdsmpwithgdb}
-@section Using OpenOCD SMP with GDB
-@cindex SMP
-For SMP support following GDB serial protocol packet have been defined :
-@itemize @bullet
-@item j - smp status request
-@item J - smp set request
-@end itemize
-
-OpenOCD implements :
-@itemize @bullet
-@item @option{jc} packet for reading core id displayed by
-GDB connection. Reply is @option{XXXXXXXX} (8 hex digits giving core id) or
- @option{E01} for target not smp.
-@item @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue
-(core id -1 is reserved for returning to normal resume mode). Reply @option{E01}
-for target not smp or @option{OK} on success.
-@end itemize
-
-Handling of this packet within GDB can be done :
-@itemize @bullet
-@item by the creation of an internal variable (i.e @option{_core}) by mean
-of function allocate_computed_value allowing following GDB command.
-@example
-set $_core 1
-#Jc01 packet is sent
-print $_core
-#jc packet is sent and result is affected in $
-@end example
-
-@item by the usage of GDB maintenance command as described in following example (2 cpus in SMP with
-core id 0 and 1 @pxref{definecputargetsworkinginsmp,,Define CPU targets working in SMP}).
-
-@example
-# toggle0 : force display of coreid 0
-define toggle0
-maint packet Jc0
-continue
-main packet Jc-1
-end
-# toggle1 : force display of coreid 1
-define toggle1
-maint packet Jc1
-continue
-main packet Jc-1
-end
-@end example
-@end itemize
-
@section RTOS Support
@cindex RTOS Support
@anchor{gdbrtossupport}
@item @option{mqx}
@item @option{uCOS-III}
@item @option{nuttx}
+@item @option{hwthread} (This is not an actual RTOS. @xref{usingopenocdsmpwithgdb,,Using OpenOCD SMP with GDB}.)
@end itemize
-@quotation Note
Before an RTOS can be detected, it must export certain symbols; otherwise, it cannot
be used by OpenOCD. Below is a list of the required symbols for each supported RTOS.
-@end quotation
@table @code
@item eCos symbols
contrib/rtos-helpers/uCOS-III-openocd.c
@end table
+@anchor{usingopenocdsmpwithgdb}
+@section Using OpenOCD SMP with GDB
+@cindex SMP
+@cindex RTOS
+@cindex hwthread
+OpenOCD includes a pseudo RTOS called @emph{hwthread} that presents CPU cores
+("hardware threads") in an SMP system as threads to GDB. With this extension,
+GDB can be used to inspect the state of an SMP system in a natural way.
+After halting the system, using the GDB command @command{info threads} will
+list the context of each active CPU core in the system. GDB's @command{thread}
+command can be used to switch the view to a different CPU core.
+The @command{step} and @command{stepi} commands can be used to step a specific core
+while other cores are free-running or remain halted, depending on the
+scheduler-locking mode configured in GDB.
+
+@section Legacy SMP core switching support
+@quotation Note
+This method is deprecated in favor of the @emph{hwthread} pseudo RTOS.
+@end quotation
+
+For SMP support following GDB serial protocol packet have been defined :
+@itemize @bullet
+@item j - smp status request
+@item J - smp set request
+@end itemize
+
+OpenOCD implements :
+@itemize @bullet
+@item @option{jc} packet for reading core id displayed by
+GDB connection. Reply is @option{XXXXXXXX} (8 hex digits giving core id) or
+ @option{E01} for target not smp.
+@item @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue
+(core id -1 is reserved for returning to normal resume mode). Reply @option{E01}
+for target not smp or @option{OK} on success.
+@end itemize
+
+Handling of this packet within GDB can be done :
+@itemize @bullet
+@item by the creation of an internal variable (i.e @option{_core}) by mean
+of function allocate_computed_value allowing following GDB command.
+@example
+set $_core 1
+#Jc01 packet is sent
+print $_core
+#jc packet is sent and result is affected in $
+@end example
+
+@item by the usage of GDB maintenance command as described in following example (2 cpus in SMP with
+core id 0 and 1 @pxref{definecputargetsworkinginsmp,,Define CPU targets working in SMP}).
+
+@example
+# toggle0 : force display of coreid 0
+define toggle0
+maint packet Jc0
+continue
+main packet Jc-1
+end
+# toggle1 : force display of coreid 1
+define toggle1
+maint packet Jc1
+continue
+main packet Jc-1
+end
+@end example
+@end itemize
+
@node Tcl Scripting API
@chapter Tcl Scripting API
@cindex Tcl Scripting API
By "low-level," we mean commands that a human would typically not
invoke directly.
-Some low-level commands need to be prefixed with "ocd_"; e.g.
-@command{ocd_flash_banks}
-is the low-level API upon which @command{flash banks} is implemented.
-
@itemize @bullet
@item @b{mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
@item @b{array2mem} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
Convert a Tcl array to memory locations and write the values
-@item @b{ocd_flash_banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...]
+@item @b{flash banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...]
Return information about the flash banks
value (it will be terminated with @code{0x1a} as well). This can be
repeated as many times as desired without reopening the connection.
-Remember that most of the OpenOCD commands need to be prefixed with
-@code{ocd_} to get the results back. Sometimes you might also need the
+It is not needed anymore to prefix the OpenOCD commands with
+@code{ocd_} to get the results back. But sometimes you might need the
@command{capture} command.
See @file{contrib/rpc_examples/} for specific client implementations.
@example
# Example: 1.234MHz
-adapter_khz 1234
+adapter speed 1234
@end example
"Warning: arm7_9_common.c:679 arm7_9_assert_reset(): srst resets test logic, too".
This warning doesn't indicate any serious problem, as long as you don't want to
-debug your core right out of reset. Your .cfg file specified @option{jtag_reset
+debug your core right out of reset. Your .cfg file specified @option{reset_config
trst_and_srst srst_pulls_trst} to tell OpenOCD that either your board,
your debugger or your target uC (e.g. LPC2000) can't assert the two reset signals
independently. With this setup, it's not possible to halt the core right out of
Code Review / openocd.git / blobdiff