调试适配器配置
正确安装OpenOCD包括使您的操作系统允许OpenOCD访问调试适配器。一旦完成，Tcl命令将被用来选择使用哪个命令，并配置如何使用它。
注意：因为OpenOCD一开始只关注JTAG，所以您可能会发现它错误地认为JTAG是唯一正在使用的传输协议。请注意，最近版本的OpenOCD正在消除这一限制。JTAG仍然比大多数其他传输工具更有功能。其他传输不支持边界扫描操作，或者可能是特定于给定的芯片供应商的。有些可能只用于编程闪存，而不适用于调试。
调试适配器/接口/加密狗通常通过由openocd.cfg文件提供的接口配置文件中的命令进行配置，或通过命令行-f interface/…cfg选项进行配置。
source [find interface/olimex-jtag-tiny.cfg]
这些命令告诉OpenOCD您有什么类型的JTAG适配器，以及如何与它对话。一些情况是如此简单，你只需要说使用什么驱动程序：
# jlink interface adapter driver jlink
大多数适配器需要比更多的配置。
1适配器配置
适配器驱动程序命令告诉OpenOCD您正在使用什么类型的调试适配器。根据适配器的类型，您可能需要使用一个或多个附加命令来进一步识别或配置适配器。
- Config Command: adapter driver name
使用适配器驱动程序名称连接到目标。 - Command: adapter list
列出已内置到OpenOCD运行副本中的调试适配器驱动程序。 - Config Command: adapter transports transport_name+
指定此调试适配器支持的传输。适配器驱动程序构建在类似的知识中；只有当外部配置（如跳线）改变了硬件可以支持的内容时，才使用此选项。 - Config Command: adapter gpio [ tdo | tdi | tms | tck | trst | swdio | swdio_dir | swclk | srst | led [ gpio_number | -chip chip_number | -active-high | -active-low | -push-pull | -open-drain | -open-source | -pull-none | -pull-up | -pull-down | -init-inactive | -init-active | -init-input ] ]定义适配器将使用的GPIO映射。可以定义以下信号：
- tdo, tdi, tms, tck, trst: JTAG transport signals
- swdio, swclk: SWD transport signals
- swdio_dir: optional swdio buffer control signal
- srst: system reset signal
- led: optional activity led
有些适配器要求除了GPIO编号之外，还设置GPIO芯片编号。配置选项使信号能够被定义为有效高电平或有效低电平。输出驱动模式可以设置为推挽、开漏或开源。
大多数适配器将不得不通过在输入和输出之间切换来模拟开漏或开源驱动模式。输入和输出信号可以被指示使用上拉或下拉电阻器，假设它得到适配器驱动器和硬件的支持。
输出的初始状态也可以设置，“活动”状态表示高活动输出为1，低活动输出为0。双向信号也可以被初始化为输入。如果swdio信号被缓冲，则可以利用swdio_dir信号来控制缓冲方向；活动状态意味着应该将缓冲区设置为适配器的输出。命令选项是累积的，以后的命令可以覆盖以前的命令定义的设置。
顺序发送的两个命令gpio led 7-active high和gpio led-chip 1-active low相当于发出一个命令gpio-led 7-chip 1-active low。不允许为作为输入的信号设置驱动模式或初始状态。srst和trst信号的驱动模式必须使用adapter reset_config命令设置。不允许设置swdio_dir的初始状态，因为它是从swdio的初始状态导出的。
命令适配器gpio打印所有gpio的当前配置，而命令适配器gpiogpio_name打印gpio_name的当前配置。并非所有适配器都支持这种通用GPIO映射，有些适配器需要自己的命令来定义所使用的GPIO。支持通用映射的适配器可能不支持所有列出的选项。
- Command: adapter name
返回正在使用的调试适配器驱动程序的名称。 - Config Command: adapter usb location [-[.]…]
显示或指定要使用的适配器的物理USB端口。路径从总线开始，沿着物理端口走，每个端口选项都指定总线拓扑中的更深层次，最后一个端口表示目标适配器实际插入的位置。可以使用命令lsusb-t或dmesg查询USB总线拓扑。
只有当您的libusb1版本至少为1.0.16时，此命令才可用。 - Config Command: adapter serial serial_string
指定要使用的适配器的serial_string。如果未指定此命令，则不会检查串行字符串。只有以下适配器驱动程序使用此命令中的串行字符串：arm jtag ew、cmsis_dap、esp_usb_jtag、ft232r、ftdi、hla（stlink、ti icdi）、jlink、kitprog、opendus、openjtag、osbdm、presto、rlink、st link、usb_blaster（ublast2）、usbprog、vsllink、xds10。
2接口驱动程序
在配置OpenOCD时，必须显式启用此处列出的每个接口驱动程序，以便在运行时可用。
Interface Driver: amt_jtagaccel
Amontec Chameleon in its JTAG Accelerator configuration, connected to a PC’s EPP mode parallel port. This defines some driver-specific commands:
Config Command: parport port number
Specifies either the address of the I/O port (default: 0x378 for LPT1) or the number of the /dev/parport device.
Config Command: rtck [enable|disable]
Displays status of RTCK option. Optionally sets that option first.
Interface Driver: arm-jtag-ew
Olimex ARM-JTAG-EW USB adapter This has one driver-specific command:
Command: armjtagew_info
Logs some status
Interface Driver: at91rm9200
Supports bitbanged JTAG from the local system, presuming that system is an Atmel AT91rm9200 and a specific set of GPIOs is used.
Interface Driver: cmsis-dap
ARM CMSIS-DAP compliant based adapter v1 (USB HID based) or v2 (USB bulk).
Config Command: cmsis_dap_vid_pid [vid pid]+
The vendor ID and product ID of the CMSIS-DAP device. If not specified the driver will attempt to auto detect the CMSIS-DAP device. Currently, up to eight [vid, pid] pairs may be given, e.g.
cmsis_dap_vid_pid 0xc251 0xf001 0x0d28 0x0204
Config Command: cmsis_dap_backend [auto|usb_bulk|hid]
Specifies how to communicate with the adapter:
- hid Use HID generic reports - CMSIS-DAP v1
- usb_bulk Use USB bulk - CMSIS-DAP v2
- auto First try USB bulk CMSIS-DAP v2, if not found try HID CMSIS-DAP v1. This is the default if cmsis_dap_backend is not specified.
Config Command: cmsis_dap_usb interface [number]
Specifies the number of the USB interface to use in v2 mode (USB bulk). In most cases need not to be specified and interfaces are searched by interface string or for user class interface.
Command: cmsis-dap info
Display various device information, like hardware version, firmware version, current bus status.
Command: cmsis-dap cmd number number …
Execute an arbitrary CMSIS-DAP command. Use for adapter testing or for handling of an adapter vendor specific command from a Tcl script.
Take given numbers as bytes, assemble a CMSIS-DAP protocol command packet from them and send it to the adapter. The first 4 bytes of the adapter response are logged. See https://arm-software.github.io/CMSIS_5/DAP/html/group__DAP__Commands__gr.html
Interface Driver: dummy
A dummy software-only driver for debugging.
Interface Driver: ep93xx
Cirrus Logic EP93xx based single-board computer bit-banging (in development)
Interface Driver: ftdi
This driver is for adapters using the MPSSE (Multi-Protocol Synchronous Serial Engine) mode built into many FTDI chips, such as the FT2232, FT4232 and FT232H.
The driver is using libusb-1.0 in asynchronous mode to talk to the FTDI device, bypassing intermediate libraries like libftdi.
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 define outputs for one or several FTDI GPIO. These outputs can then be controlled using the ftdi set_signal command. Special signal names are reserved for nTRST, nSRST and LED (for blink) so that they, if defined, will be used for their customary purpose. Inputs can be read using the ftdi get_signal command.
To support SWD, a signal named SWD_EN must be defined. It is set to 1 when the SWD protocol is selected. When set, the adapter should route the SWDIO pin to the data input. An SWDIO_OE signal, if defined, will be set to 1 or 0 as required by the protocol, to tell the adapter to drive the data output onto the SWDIO pin or keep the SWDIO pin Hi-Z, respectively.
Depending on the type of buffer attached to the FTDI GPIO, the outputs have to be controlled differently. In order to support tristateable signals such as nSRST, both a data GPIO and an output-enable GPIO can be specified for each signal. The following output buffer configurations are supported:
- Push-pull with one FTDI output as (non-)inverted data line
- Open drain with one FTDI output as (non-)inverted output-enable
- Tristate with one FTDI output as (non-)inverted data line and another FTDI output as (non-)inverted output-enable
- Unbuffered, using the FTDI GPIO as a tristate output directly by switching data and direction as necessary
These interfaces have several commands, used to configure the driver before initializing the JTAG scan chain:
Config Command: ftdi vid_pid [vid pid]+
The vendor ID and product ID of the adapter. Up to eight [vid, pid] pairs may be given, e.g.
ftdi vid_pid 0x0403 0xcff8 0x15ba 0x0003
Config Command: ftdi device_desc description
Provides the USB device description (the iProduct string) of the adapter. If not specified, the device description is ignored during device selection.
Config Command: ftdi channel channel
Selects the channel of the FTDI device to use for MPSSE operations. Most adapters use the default, channel 0, but there are exceptions.
Config Command: ftdi layout_init data direction
Specifies the initial values of the FTDI GPIO data and direction registers. Each value is a 16-bit number corresponding to the concatenation of the high and low FTDI GPIO registers. The values should be selected based on the schematics of the adapter, such that all signals are set to safe levels with minimal impact on the target system. Avoid floating inputs, conflicting outputs and initially asserted reset signals.
Command: ftdi layout_signal name [-data|-ndata data_mask] [-input|-ninput input_mask] [-oe|-noe oe_mask] [-alias|-nalias name]
Creates a signal with the specified name, controlled by one or more FTDI GPIO pins via a range of possible buffer connections. The masks are FTDI GPIO register bitmasks to tell the driver the connection and type of the output buffer driving the respective signal. data_mask is the bitmask for the pin(s) connected to the data input of the output buffer. -ndata is used with inverting data inputs and -data with non-inverting inputs. The -oe (or -noe) option tells where the output-enable (or not-output-enable) input to the output buffer is connected. The options -input and -ninput specify the bitmask for pins to be read with the method ftdi get_signal.
Both data_mask and oe_mask need not be specified. For example, a simple open-collector transistor driver would be specified with -oe only. In that case the signal can only be set to drive low or to Hi-Z and the driver will complain if the signal is set to drive high. Which means that if it’s a reset signal, reset_config must be specified as srst_open_drain, not srst_push_pull.
A special case is provided when -data and -oe is set to the same bitmask. Then the FTDI pin is considered being connected straight to the target without any buffer. The FTDI pin is then switched between output and input as necessary to provide the full set of low, high and Hi-Z characteristics. In all other cases, the pins specified in a signal definition are always driven by the FTDI.
If -alias or -nalias is used, the signal is created identical (or with data inverted) to an already specified signal name.
Command: ftdi set_signal name 0|1|z
Set a previously defined signal to the specified level.
- 0, drive low
- 1, drive high
- z, set to high-impedance
Command: ftdi get_signal name
Get the value of a previously defined signal.
Command: ftdi tdo_sample_edge rising|falling
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 possibility to sample TDO on falling edge of TCK. With some board/adapter configurations, this may increase stability at higher JTAG clocks.
- rising, sample TDO on rising edge of TCK - this is the default
- falling, sample TDO on falling edge of TCK
For example adapter definitions, see the configuration files shipped in the interface/ftdi directory.
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):
- RXD(5) - TDI
- TXD(1) - TCK
- RTS(3) - TDO
- CTS(11) - TMS
- DTR(2) - TRST
- DCD(10) - SRST
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
- bit 7 - RI
- bit 6 - DCD
- bit 5 - DSR
- bit 4 - DTR
- bit 3 - CTS
- bit 2 - RTS
- bit 1 - RXD
- bit 0 - TXD
These interfaces have several commands, used to configure the driver before initializing the JTAG scan chain:
Config Command: ft232r vid_pid vid pid
The vendor ID and product ID of the adapter. If not specified, default 0x0403:0x6001 is used.
Config Command: ft232r jtag_nums tck tms tdi tdo
Set four JTAG GPIO numbers at once. If not specified, default 0 3 1 2 or TXD CTS RXD RTS is used.
Config Command: ft232r tck_num tck
Set TCK GPIO number. If not specified, default 0 or TXD is used.
Config Command: ft232r tms_num tms
Set TMS GPIO number. If not specified, default 3 or CTS is used.
Config Command: ft232r tdi_num tdi
Set TDI GPIO number. If not specified, default 1 or RXD is used.
Config Command: ft232r tdo_num tdo
Set TDO GPIO number. If not specified, default 2 or RTS is used.
Config Command: ft232r trst_num trst
Set TRST GPIO number. If not specified, default 4 or DTR is used.
Config Command: ft232r srst_num srst
Set SRST GPIO number. If not specified, default 6 or DCD is used.
Config Command: ft232r restore_serial 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.
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 instead of directly driving JTAG.
The remote_bitbang driver is useful for debugging software running on processors which are being simulated.
Config Command: remote_bitbang port number
Specifies the TCP port of the remote process to connect to or 0 to use UNIX sockets instead of TCP.
Config Command: remote_bitbang host hostname
Specifies the hostname of the remote process to connect to using TCP, or the name of the UNIX socket to use if remote_bitbang port is 0.
For example, to connect remotely via TCP to the host foobar you might have something like:
adapter driver remote_bitbang
remote_bitbang port 3335
remote_bitbang host foobar
To connect to another process running locally via UNIX sockets with socket named mysocket:
adapter driver remote_bitbang
remote_bitbang port 0
remote_bitbang host mysocket
Interface Driver: usb_blaster
USB JTAG/USB-Blaster compatibles over one of the userspace libraries for FTDI chips. These interfaces have several commands, used to configure the driver before initializing the JTAG scan chain:
Config Command: usb_blaster vid_pid vid pid
The vendor ID and product ID of the FTDI FT245 device. If not specified, default values are used. Currently, only one vid, pid pair may be given, e.g. for Altera USB-Blaster (default):
usb_blaster vid_pid 0x09FB 0x6001
The following VID/PID is for Kolja Waschk’s USB JTAG:
usb_blaster vid_pid 0x16C0 0x06AD
Command: usb_blaster pin (pin6|pin8) (0|1|s|t)
Sets the state or function of the unused GPIO pins on USB-Blasters (pins 6 and 8 on the female JTAG header). These pins can be used as SRST and/or TRST provided the appropriate connections are made on the target board.
For example, to use pin 6 as SRST:
usb_blaster pin pin6 s
reset_config srst_only
Config Command: usb_blaster lowlevel_driver (ftdi|ublast2)
Chooses the low level access method for the adapter. If not specified, ftdi is selected unless it wasn’t enabled during the configure stage. USB-Blaster II needs ublast2.
Config Command: usb_blaster firmware path
This command specifies path to access USB-Blaster II firmware image. To be used with USB-Blaster II only.
Interface Driver: gw16012
Gateworks GW16012 JTAG programmer. This has one driver-specific command:
Config Command: parport port [port_number]
Display either the address of the I/O port (default: 0x378 for LPT1) or the number of the /dev/parport device. If a parameter is provided, first switch to use that port. This is a write-once setting.
Interface Driver: jlink
SEGGER J-Link family of USB adapters. It currently supports JTAG and SWD transports.
Compatibility Note: 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 available for each hardware version. However the current V8 is a moving target, and SEGGER firmware versions released after the OpenOCD was released may not be compatible. In such cases it is recommended to revert to the last known functional version. For 0.5.0, this is from “Feb 8 2012 14:30:39”, packed with 4.42c. For 0.6.0, the last known version is from “May 3 2012 18:36:22”, packed with 4.46f.
Command: jlink hwstatus
Display various hardware related information, for example target voltage and pin states.
Command: jlink freemem
Display free device internal memory.
Command: jlink jtag [2|3]
Set the JTAG command version to be used. Without argument, show the actual JTAG command version.
Command: jlink config
Display the device configuration.
Command: jlink config targetpower [on|off]
Set the target power state on JTAG-pin 19. Without argument, show the target power state.
Command: jlink config mac [ff:ff:ff:ff:ff:ff]
Set the MAC address of the device. Without argument, show the MAC address.
Command: jlink config ip [A.B.C.D(/E|F.G.H.I)]
Set the IP configuration of the device, where A.B.C.D is the IP address, E the bit of the subnet mask and F.G.H.I the subnet mask. Without arguments, show the IP configuration.
Command: jlink config usb [0 to 3]
Set the USB address of the device. This will also change the USB Product ID (PID) of the device. Without argument, show the USB address.
Command: jlink config reset
Reset the current configuration.
Command: jlink config write
Write the current configuration to the internal persistent storage.
Command: jlink emucom write
Write data to an EMUCOM channel. The data needs to be encoded as hexadecimal pairs.
The following example shows how to write the three bytes 0xaa, 0x0b and 0x23 to the EMUCOM channel 0x10:
jlink emucom write 0x10 aa0b23
Command: jlink emucom read
Read data from an EMUCOM channel. The read data is encoded as hexadecimal pairs.
The following example shows how to read 4 bytes from the EMUCOM channel 0x0:
jlink emucom read 0x0 4
77a90000
Config Command: jlink usb <0 to 3>
Set the USB address of the interface, in case more than one adapter is connected to the host. If not specified, USB addresses are not considered. Device selection via USB address is not always unambiguous. It is recommended to use the serial number instead, if possible.
As a configuration command, it can be used only before ’init’.
Interface Driver: kitprog
This driver is for Cypress Semiconductor’s KitProg adapters. The KitProg is an SWD-only adapter that is designed to be used with Cypress’s PSoC and PRoC device families, but it is possible to use it with some other devices. If you are using this adapter with a PSoC or a PRoC, you may need to add kitprog_init_acquire_psoc or kitprog acquire_psoc to your configuration script.
Note that this driver is for the proprietary KitProg protocol, not the CMSIS-DAP mode introduced in firmware 2.14. If the KitProg is in CMSIS-DAP mode, it cannot be used with this driver, and must either be used with the cmsis-dap driver or switched back to KitProg mode. See the Cypress KitProg User Guide for instructions on how to switch KitProg modes.
Known limitations:
The frequency of SWCLK cannot be configured, and varies between 1.6 MHz and 2.7 MHz.
For firmware versions below 2.14, “JTAG to SWD” sequences are replaced by “SWD line reset” in the driver. This is for two reasons. First, the KitProg does not support sending arbitrary SWD sequences, and only firmware 2.14 and later implement both “JTAG to SWD” and “SWD line reset” in firmware. Earlier firmware versions only implement “SWD line reset”. Second, due to a firmware quirk, an SWD sequence must be sent after every target reset in order to re-establish communications with the target.
Due in part to the limitation above, KitProg devices with firmware below version 2.14 will need to use kitprog_init_acquire_psoc in order to communicate with PSoC 5LP devices. This is because, assuming debug is not disabled on the PSoC, the PSoC 5LP needs its JTAG interface switched to SWD mode before communication can begin, but prior to firmware 2.14, “JTAG to SWD” could only be sent with an acquisition sequence.
Config Command: kitprog_init_acquire_psoc
Indicate that a PSoC acquisition sequence needs to be run during adapter init. Please be aware that the acquisition sequence hard-resets the target.
Command: kitprog acquire_psoc
Run a PSoC acquisition sequence immediately. Typically, this should not be used outside of the target-specific configuration scripts since it hard-resets the target as a side-effect. This is necessary for “reset halt” on some PSoC 4 series devices.
Command: kitprog info
Display various adapter information, such as the hardware version, firmware version, and target voltage.
Interface Driver: parport
Supports PC parallel port bit-banging cables: Wigglers, PLD download cable, and more. These interfaces have several commands, used to configure the driver before initializing the JTAG scan chain:
Config Command: parport cable name
Set the layout of the parallel port cable used to connect to the target. This is a write-once setting. Currently valid cable name values include:
- altium Altium Universal JTAG cable.
- arm-jtag Same as original wiggler except SRST and TRST connections reversed and TRST is also inverted.
- chameleon The Amontec Chameleon’s CPLD when operated in configuration mode. This is only used to program the Chameleon itself, not a connected target.
- dlc5 The Xilinx Parallel cable III.
- flashlink The ST Parallel cable.
- lattice Lattice ispDOWNLOAD Cable
- old_amt_wiggler The Wiggler configuration that comes with some versions of Amontec’s Chameleon Programmer. The new version available from the website uses the original Wiggler layout (’wiggler’)
- triton The parallel port adapter found on the “Karo Triton 1 Development Board”. This is also the layout used by the HollyGates design (see http://www.lartmaker.nl/projects/jtag/).
- wiggler The original Wiggler layout, also supported by several clones, such as the Olimex ARM-JTAG
- wiggler2 Same as original wiggler except an led is fitted on D5.
- wiggler_ntrst_inverted Same as original wiggler except TRST is inverted.
Config Command: parport port [port_number]
Display either the address of the I/O port (default: 0x378 for LPT1) or the number of the /dev/parport device. If a parameter is provided, first switch to use that port. This is a write-once setting.
When using PPDEV to access the parallel port, use the number of the parallel port: parport port 0 (the default). If parport port 0x378 is specified you may encounter a problem.
Config Command: parport toggling_time [nanoseconds]
Displays how many nanoseconds the hardware needs to toggle TCK; the parport driver uses this value to obey the adapter speed configuration. When the optional nanoseconds parameter is given, that setting is changed before displaying the current value.
The default setting should work reasonably well on commodity PC hardware. However, you may want to calibrate for your specific hardware.
Tip: To measure the toggling time with a logic analyzer or a digital storage oscilloscope, follow the procedure below:
parport toggling_time 1000
adapter speed 500
This sets the maximum JTAG clock speed of the hardware, but the actual speed probably deviates from the requested 500 kHz. Now, measure the time between the two closest spaced TCK transitions. You can use runtest 1000 or something similar to generate a large set of samples. Update the setting to match your measurement:
parport toggling_time
Now the clock speed will be a better match for 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 with the rate you specified in the adapter speed command; be conservative.
Config Command: parport write_on_exit (on|off)
This will configure the parallel driver to write a known cable-specific value to the parallel interface on exiting OpenOCD.
For example, the interface configuration file for a classic “Wiggler” cable on LPT2 might look something like this:
adapter driver parport
parport port 0x278
parport cable wiggler
Interface Driver: presto
ASIX PRESTO USB JTAG programmer.
Interface Driver: rlink
Raisonance RLink USB adapter
Interface Driver: usbprog
usbprog is a freely programmable USB adapter.
Interface Driver: vsllink
vsllink is part of Versaloon which is a versatile USB programmer.
Note: This defines quite a few driver-specific commands, which are not currently documented here.
Interface Driver: hla
This is a driver that supports multiple High Level Adapters. 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 STMicroelectronics ST-LINK, TI ICDI and Nuvoton Nu-Link. 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 ST-LINK firmware even if current version reported is V2.J21.S4.
Config Command: hla_device_desc description
Currently Not Supported.
Config Command: hla_layout (stlink|icdi|nulink)
Specifies the adapter layout to use.
Config Command: hla_vid_pid [vid pid]+
Pairs of vendor IDs and product IDs of the device.
Config Command: hla_stlink_backend (usb | tcp [port])
ST-Link only: Choose between ’exclusive’ USB communication (the default backend) or ’shared’ mode using ST-Link TCP server (the default port is 7184).
Note: ST-Link TCP server is a binary application provided by ST available from ST-LINK server software module.
Command: hla_command command
Execute a custom adapter-specific command. The command string is passed as is to the underlying adapter layout handler.
Interface Driver: st-link
This is a driver that supports STMicroelectronics adapters ST-LINK/V2 (from firmware V2J24), STLINK-V3 and STLINK-V3PWR, 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.
Note: Either these same adapters and their older versions are also supported by the hla interface driver.
Config Command: st-link backend (usb | tcp [port])
Choose between ’exclusive’ USB communication (the default backend) or ’shared’ mode using ST-Link TCP server (the default port is 7184).
Note: ST-Link TCP server is a binary application provided by ST available from ST-LINK server software module.
Note: ST-Link TCP server does not support the SWIM transport.
Config Command: st-link vid_pid [vid pid]+
Pairs of vendor IDs and product IDs of the device.
Command: st-link cmd rx_n (tx_byte)+
Sends an arbitrary command composed by the sequence of bytes tx_byte and receives rx_n bytes.
For example, the command to read the target’s supply voltage is one byte 0xf7 followed by 15 bytes zero. It returns 8 bytes, where the first 4 bytes represent the ADC sampling of the reference voltage 1.2V and the last 4 bytes represent the ADC sampling of half the target’s supply voltage.
> st-link cmd 8 0xf7 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0xf1 0x05 0x00 0x00 0x0b 0x08 0x00 0x00
The result can be converted to Volts (ignoring the most significant bytes, always zero)
> set a [st-link cmd 8 0xf7 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0] > set n [expr {[lindex $a 4] + 256 * [lindex $a 5]}] > set d [expr {[lindex $a 0] + 256 * [lindex $a 1]}] > echo [expr {2 * 1.2 * $n / $d}] 3.24891518738
Interface Driver: opendous
opendous-jtag is a freely programmable USB adapter.
Interface Driver: ulink
This is the Keil ULINK v1 JTAG debugger.
Interface Driver: xds110
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 with the added capability to supply power to the target board. The following commands are supported by the XDS110 driver:
Config Command: xds110 supply voltage_in_millivolts
Available only on the XDS110 stand-alone probe. Sets the voltage level of the XDS110 power supply. A value of 0 leaves the supply off. Otherwise, the supply can be set to any value in the range 1800 to 3600 millivolts.
Command: xds110 info
Displays information about the connected XDS110 debug probe (e.g. firmware version).
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/SWD 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).
Config Command: xlnx_pcie_xvc config device
Specifies the PCI Express device via parameter device to use.
The correct value for 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”.
Interface Driver: bcm2835gpio
This SoC is present in Raspberry Pi which is a cheap single-board computer exposing some GPIOs on its expansion header.
The driver accesses memory-mapped GPIO peripheral registers directly for maximum performance, but the only possible race condition is for the pins’ modes/muxing (which is highly unlikely), so it should be able to coexist nicely with both sysfs bitbanging and various peripherals’ kernel drivers. The driver restores the previous configuration on exit.
GPIO numbers >= 32 can’t be used for performance reasons. GPIO configuration is handled by the generic command adapter gpio.
See interface/raspberrypi-native.cfg for a sample config and interface/raspberrypi-gpio-connector.cfg for pinout.
Config Command: bcm2835gpio speed_coeffs speed_coeff speed_offset
Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified, speed_coeff defaults to 113714, and speed_offset defaults to 28.
Config Command: bcm2835gpio peripheral_mem_dev device
Set the device path for access to the memory mapped GPIO control registers. Uses /dev/gpiomem by default, this is also the preferred option with respect to system security. If overridden to /dev/mem:
- OpenOCD needs cap_sys_rawio or run as root to open /dev/mem. Please be aware of security issues imposed by running OpenOCD with elevated user rights and by /dev/mem itself.
- correct peripheral_base must be configured.
- GPIO 0-27 pads are set to the limited slew rate and drive strength is reduced to 4 mA (2 mA on RPi 4).
Config Command: bcm2835gpio peripheral_base base
Set the peripheral base register address to access GPIOs. Ignored if /dev/gpiomem is used. For the RPi1, use 0x20000000. For RPi2 and RPi3, use 0x3F000000. For RPi4, use 0xFE000000. A full list can be found in the official guide.
Interface Driver: imx_gpio
i.MX SoC is present in many community boards. Wandboard is an example of the one which is most popular.
This driver is mostly the same as bcm2835gpio.
See interface/imx-native.cfg for a sample config and pinout.
Interface Driver: am335xgpio The AM335x SoC is present in BeagleBone
Black and BeagleBone Green single-board computers which expose some of the GPIOs on the two expansion headers.
For maximum performance the driver accesses memory-mapped GPIO peripheral registers directly. The memory mapping requires read and write permission to kernel memory; if /dev/gpiomem exists it will be used, otherwise /dev/mem will be used. The driver restores the GPIO state on exit.
All four GPIO ports are available. GPIO configuration is handled by the generic command adapter gpio.
Config Command: am335xgpio speed_coeffs speed_coeff speed_offset
Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified speed_coeff defaults to 600000 and speed_offset defaults to 575.
See interface/beaglebone-swd-native.cfg for a sample configuration file.
Interface Driver: linuxgpiod
Linux provides userspace access to GPIO through libgpiod since Linux kernel version v4.6. The driver emulates either JTAG or SWD transport through bitbanging. There are no driver-specific commands, all GPIO configuration is handled by the generic command adapter gpio. This driver supports the resistor pull options provided by the adapter gpio command but the underlying hardware may not be able to support them.
See interface/dln-2-gpiod.cfg for a sample configuration file.
Interface Driver: sysfsgpio
Linux legacy userspace access to GPIO through sysfs is deprecated from Linux kernel version v5.3. Prefer using linuxgpiod, instead.
See interface/sysfsgpio-raspberrypi.cfg for a sample config.
Interface Driver: openjtag
OpenJTAG compatible USB adapter. This defines some driver-specific commands:
Config Command: openjtag variant variant
Specifies the variant of the OpenJTAG adapter (see http://www.openjtag.org/). Currently valid variant values include:
- standard Standard variant (default).
- cy7c65215 Cypress CY7C65215 Dual Channel USB-Serial Bridge Controller (see http://www.cypress.com/?rID=82870).
Config Command: openjtag device_desc string
The USB device description string of the adapter. This value is only used with the standard variant.
Interface Driver: vdebug
Cadence Virtual Debug Interface driver.
Config Command: vdebug server host:port
Specifies the host and TCP port number where the vdebug server runs.
Config Command: vdebug batching value
Specifies the batching method for the vdebug request. Possible values are 0 for no batching 1 or wr to batch write transactions together (default) 2 or rw to batch both read and write transactions
Config Command: vdebug polling min max
Takes two values, representing the polling interval in ms. Lower values mean faster debugger responsiveness, but lower emulation performance. The minimum should be around 10, maximum should not exceed 1000, which is the default gdb and keepalive timeout value.
Config Command: vdebug bfm_path path clk_period
Specifies the hierarchical path and input clk period of the vdebug BFM in the design. The hierarchical path uses Verilog notation top.inst.inst The clock period must include the unit, for instance 40ns.
Config Command: vdebug mem_path path base size
Specifies the hierarchical path to the design memory instance for backdoor access. Up to 4 memories can be specified. The hierarchical path uses Verilog notation. The base specifies start address in the design address space, size its size in bytes. Both values can use hexadecimal notation with prefix 0x.
Interface Driver: jtag_dpi
SystemVerilog Direct Programming Interface (DPI) compatible driver for JTAG devices in emulation. The driver acts as a client for the SystemVerilog DPI server interface.
Config Command: jtag_dpi set_port port
Specifies the TCP/IP port number of the SystemVerilog DPI server interface.
Config Command: jtag_dpi set_address address
Specifies the TCP/IP address of the SystemVerilog DPI server interface.
Interface Driver: buspirate
This driver is for the Bus Pirate (see http://dangerousprototypes.com/docs/Bus_Pirate) and compatible devices. It uses a simple data protocol over a serial port connection.
Most hardware development boards have a UART, a real serial port, or a virtual USB serial device, so this driver allows you to start building your own JTAG adapter without the complexity of a custom USB connection.
Config Command: buspirate port serial_port
Specify the serial port’s filename. For example:
buspirate port /dev/ttyUSB0
Config Command: buspirate speed (normal|fast)
Set the communication speed to 115k (normal) or 1M (fast). For example:
buspirate speed normal
Config Command: buspirate mode (normal|open-drain)
Set the Bus Pirate output mode.
- In normal mode (push/pull), do not enable the pull-ups, and do not connect I/O header pin VPU to JTAG VREF.
- In open drain mode, you will then need to enable the pull-ups.
For example:
buspirate mode normal
Config Command: buspirate pullup (0|1)
Whether to connect (1) or not (0) the I/O header pin VPU (JTAG VREF) to the pull-up/pull-down resistors on MOSI (JTAG TDI), CLK (JTAG TCK), MISO (JTAG TDO) and CS (JTAG TMS). For example:
buspirate pullup 0
Config Command: buspirate vreg (0|1)
Whether to enable (1) or disable (0) the built-in voltage regulator, which can be used to supply power to a test circuit through I/O header pins +3V3 and +5V. For example:
buspirate vreg 0
Command: buspirate led (0|1)
Turns the Bus Pirate’s LED on (1) or off (0). For example:
buspirate led 1
Interface Driver: esp_usb_jtag
Espressif JTAG driver to communicate with ESP32-C3, ESP32-S3 chips and ESP USB Bridge board using OpenOCD. These chips have built-in JTAG circuitry and can be debugged without any additional hardware. Only an USB cable connected to the D+/D- pins is necessary.
Command: espusbjtag tdo
Returns the current state of the TDO line
Command: espusbjtag setio setio
Manually set the status of the output lines with the order of (tdi tms tck trst srst)
espusbjtag setio 0 1 0 1 0
Config Command: espusbjtag vid_pid vid_pid
Set vendor ID and product ID for the ESP usb jtag driver
espusbjtag vid_pid 0x303a 0x1001
Config Command: espusbjtag caps_descriptor caps_descriptor
Set the jtag descriptor to read capabilities of ESP usb jtag driver
espusbjtag caps_descriptor 0x2000
Config Command: espusbjtag chip_id chip_id
Set chip id to transfer to the ESP USB bridge board
espusbjtag chip_id 1
3传输配置
如前所述，根据您使用的OpenOCD版本和正在使用的调试适配器，可能有几种传输可用于与调试目标通信（或编程闪存）。
Command: transport list
displays the names of the transports supported by this version of OpenOCD.
Command: transport select transport_name
Select which of the supported transports to use in this OpenOCD session.
When invoked with transport_name, attempts to select the named transport. The transport must be supported by the debug adapter hardware and by the version of OpenOCD you are using (including the adapter’s driver).
If no transport has been selected and no transport_name is provided, transport select auto-selects the first transport supported by the debug adapter.
transport select always returns the name of the session’s selected transport, if any.
1 JTAG Transport
JTAG is the original transport supported by OpenOCD, and most of the OpenOCD commands support it. JTAG transports expose a chain of one or more Test Access Points (TAPs), each of which must be explicitly declared. JTAG supports both debugging and boundary scan testing. Flash programming support is built on top of debug support.
JTAG transport is selected with the command transport select jtag. Unless your adapter uses either the hla interface driver (in which case the command is transport select hla_jtag) or the st-link interface driver (in which case the command is transport select dapdirect_jtag).
2 SWD Transport
SWD (Serial Wire Debug) is an ARM-specific transport which exposes one Debug Access Point (DAP, which must be explicitly declared. (SWD uses fewer signal wires than JTAG.) SWD is debug-oriented, and does not support boundary scan testing. Flash programming support is built on top of debug support. (Some processors support both JTAG and SWD.)
SWD transport is selected with the command transport select swd. Unless your adapter uses either the hla interface driver (in which case the command is transport select hla_swd) or the st-link interface driver (in which case the command is transport select dapdirect_swd).
Config Command: swd newdap …
Declares a single DAP which uses SWD transport. Parameters are currently the same as “jtag newtap” but this is expected to change.
The newer SWD devices (SW-DP v2 or SWJ-DP v2) support the multi-drop extension of SWD protocol: two or more devices can be connected to one SWD adapter. SWD transport works in multi-drop mode if DAP is configured with both -dp-id and -instance-id parameters regardless how many DAPs are created.
Not all adapters and adapter drivers support SWD multi-drop. Only the following adapter drivers are SWD multi-drop capable: cmsis_dap (use an adapter with CMSIS-DAP version 2.0), ftdi, all bitbang based.
3 SPI Transport
The Serial Peripheral Interface (SPI) is a general purpose transport which uses four wire signaling. Some processors use it as part of a solution for flash programming.
4 SWIM Transport
The Single Wire Interface Module (SWIM) is a low-pin-count debug protocol used by the STMicroelectronics MCU family STM8 and documented in the User Manual UM470.
SWIM does not support boundary scan testing nor multiple cores.
The SWIM transport is selected with the command transport select swim.
The concept of TAPs does not fit in the protocol since SWIM does not implement a scan chain. Nevertheless, the current SW model of OpenOCD requires defining a virtual SWIM TAP through the command swim newtap basename tap_type. The TAP definition must precede the target definition command target create target_name stm8 -chain-position basename.tap_type.
4 JTAG Speed
JTAG时钟设置是系统设置的一部分。它不属于接口设置，因为任何接口都只知道JTAG时钟速度的一些限制。有时，在目标初始化过程中，JTAG的速度会发生变化：
- （1）重置时速度较慢，
- （2）对CPU时钟进行编程，
- （3）运行速度较快。
“慢”和“快”时钟速率都是所用振荡器、芯片、板设计的功能，有时还包括可能激活的电源管理软件。
重置期间使用的速度以及重置后的扫描链验证可以使用重置启动目标事件处理程序进行调整。
然后，在重新编程这些CPU时钟后，可以通过重置init目标事件处理程序将其重新配置为更快的速度，或者手动（如果其他东西（如引导加载程序）设置了这些时钟）。
请参阅目标事件。当最初的低JTAG速度是芯片特性时，可能是因为所需的振荡器速度，请在目标配置文件中提供这样的处理程序。当该速度是板特定特性的函数（例如使用哪个速度振荡器）时，它属于板配置文件。
在这两种情况下，最安全的做法是将初始JTAG时钟速率设置为相同的慢速，这样OpenOCD就永远不会使用比扫描链所能支持的更快的时钟速度启动。
jtag_rclk 3000 $_TARGET.cpu configure -event reset-start { jtag_rclk 3000 }
如果您的系统支持自适应时钟（RTCK），那么将JTAG配置为使用它可能是最稳健的方法。然而，它引入了延迟来同步时钟；因此它可能不是最快的解决方案。
注意：脚本编写器应该考虑使用jtag_rclk而不是适配器速度，但仅适用于支持自适应时钟的（ARM）内核和板。
- Command: adapter speed max_speed_kHz
非零速度以KHZ为单位。因此：3000为3mhz。JTAG接口通常支持有限数量的速度。实际使用的速度不会比指定的速度快。
芯片数据表通常包括最高JTAG时钟速率。实际速率通常是CPU核心时钟的函数，并且通常小于峰值速率。例如，大多数ARM内核最多接受六分之一的CPU时钟。
速度0（khz）选择RTCK方法。请参阅常见问题RTCK。如果您的系统使用RTCK，则在设置后不需要更改JTAG时钟。并非所有接口、板或目标都支持“rtck”。如果接口设备无法支持它，则在尝试使用RTCK时会返回错误。 - Function: jtag_rclk fallback_speed_kHz
此Tcl进程（在startup.Tcl中定义）尝试启用RTCK/RCLK。如果失败（可能是接口、板或目标不支持），则返回指定频率。
# Fall back to 3mhz if RTCK is not supported jtag_rclk 3000
