@* 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
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
@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
@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
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.
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 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
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
@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.
@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