13832 lines
536 KiB
Plaintext
13832 lines
536 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename openocd.info
|
|
@settitle OpenOCD User's Guide
|
|
@dircategory Development
|
|
@direntry
|
|
* OpenOCD: (openocd). OpenOCD User's Guide
|
|
@end direntry
|
|
@paragraphindent 0
|
|
@c %**end of header
|
|
|
|
@include version.texi
|
|
|
|
@copying
|
|
|
|
This User's Guide documents
|
|
release @value{VERSION},
|
|
dated @value{UPDATED},
|
|
of the Open On-Chip Debugger (OpenOCD).
|
|
|
|
@itemize @bullet
|
|
@item Copyright @copyright{} 2008-2022 The OpenOCD Project
|
|
@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
|
|
@item Copyright @copyright{} 2008-2010 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
|
|
@item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com}
|
|
@item Copyright @copyright{} 2009-2010 David Brownell
|
|
@end itemize
|
|
|
|
@quotation
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
|
copy of the license is included in the section entitled ``GNU Free
|
|
Documentation License''.
|
|
@end quotation
|
|
@end copying
|
|
|
|
@titlepage
|
|
@titlefont{@emph{Open On-Chip Debugger:}}
|
|
@sp 1
|
|
@title OpenOCD User's Guide
|
|
@subtitle for release @value{VERSION}
|
|
@subtitle @value{UPDATED}
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@summarycontents
|
|
@contents
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top OpenOCD User's Guide
|
|
|
|
@insertcopying
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* About:: About OpenOCD
|
|
* Developers:: OpenOCD Developer Resources
|
|
* Debug Adapter Hardware:: Debug Adapter Hardware
|
|
* About Jim-Tcl:: About Jim-Tcl
|
|
* Running:: Running OpenOCD
|
|
* OpenOCD Project Setup:: OpenOCD Project Setup
|
|
* Config File Guidelines:: Config File Guidelines
|
|
* Server Configuration:: Server Configuration
|
|
* Debug Adapter Configuration:: Debug Adapter Configuration
|
|
* Reset Configuration:: Reset Configuration
|
|
* TAP Declaration:: TAP Declaration
|
|
* CPU Configuration:: CPU Configuration
|
|
* Flash Commands:: Flash Commands
|
|
* Flash Programming:: Flash Programming
|
|
* PLD/FPGA Commands:: PLD/FPGA Commands
|
|
* General Commands:: General Commands
|
|
* Architecture and Core Commands:: Architecture and Core Commands
|
|
* JTAG Commands:: JTAG Commands
|
|
* Boundary Scan Commands:: Boundary Scan Commands
|
|
* Utility Commands:: Utility Commands
|
|
* GDB and OpenOCD:: Using GDB and OpenOCD
|
|
* Tcl Scripting API:: Tcl Scripting API
|
|
* FAQ:: Frequently Asked Questions
|
|
* Tcl Crash Course:: Tcl Crash Course
|
|
* License:: GNU Free Documentation License
|
|
|
|
@comment DO NOT use the plain word ``Index'', reason: CYGWIN filename
|
|
@comment case issue with ``Index.html'' and ``index.html''
|
|
@comment Occurs when creating ``--html --no-split'' output
|
|
@comment This fix is based on: http://sourceware.org/ml/binutils/2006-05/msg00215.html
|
|
* OpenOCD Concept Index:: Concept Index
|
|
* Command and Driver Index:: Command and Driver Index
|
|
@end menu
|
|
|
|
@node About
|
|
@unnumbered About
|
|
@cindex about
|
|
|
|
OpenOCD was created by Dominic Rath as part of a 2005 diploma thesis written
|
|
at the University of Applied Sciences Augsburg (@uref{http://www.hs-augsburg.de}).
|
|
Since that time, the project has grown into an active open-source project,
|
|
supported by a diverse community of software and hardware developers from
|
|
around the world.
|
|
|
|
@section What is OpenOCD?
|
|
@cindex TAP
|
|
@cindex JTAG
|
|
|
|
The Open On-Chip Debugger (OpenOCD) aims to provide debugging,
|
|
in-system programming and boundary-scan testing for embedded target
|
|
devices.
|
|
|
|
It does so with the assistance of a @dfn{debug adapter}, which is
|
|
a small hardware module which helps provide the right kind of
|
|
electrical signaling to the target being debugged. These are
|
|
required since the debug host (on which OpenOCD runs) won't
|
|
usually have native support for such signaling, or the connector
|
|
needed to hook up to the target.
|
|
|
|
Such debug adapters support one or more @dfn{transport} protocols,
|
|
each of which involves different electrical signaling (and uses
|
|
different messaging protocols on top of that signaling). There
|
|
are many types of debug adapter, and little uniformity in what
|
|
they are called. (There are also product naming differences.)
|
|
|
|
These adapters are sometimes packaged as discrete dongles, which
|
|
may generically be called @dfn{hardware interface dongles}.
|
|
Some development boards also integrate them directly, which may
|
|
let the development board connect directly to the debug
|
|
host over USB (and sometimes also to power it over USB).
|
|
|
|
For example, a @dfn{JTAG Adapter} supports JTAG
|
|
signaling, and is used to communicate
|
|
with JTAG (IEEE 1149.1) compliant TAPs on your target board.
|
|
A @dfn{TAP} is a ``Test Access Port'', a module which processes
|
|
special instructions and data. TAPs are daisy-chained within and
|
|
between chips and boards. JTAG supports debugging and boundary
|
|
scan operations.
|
|
|
|
There are also @dfn{SWD Adapters} that support Serial Wire Debug (SWD)
|
|
signaling to communicate with some newer ARM cores, as well as debug
|
|
adapters which support both JTAG and SWD transports. SWD supports only
|
|
debugging, whereas JTAG also supports boundary scan operations.
|
|
|
|
For some chips, there are also @dfn{Programming Adapters} supporting
|
|
special transports used only to write code to flash memory, without
|
|
support for on-chip debugging or boundary scan.
|
|
(At this writing, OpenOCD does not support such non-debug adapters.)
|
|
|
|
|
|
@b{Dongles:} OpenOCD currently supports many types of hardware dongles:
|
|
USB-based, parallel port-based, and other standalone boxes that run
|
|
OpenOCD internally. @xref{Debug Adapter Hardware}.
|
|
|
|
@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
|
|
ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x), Cortex-M3
|
|
(Stellaris LM3, STMicroelectronics STM32 and Energy Micro EFM32) and
|
|
Intel Quark (x10xx) based cores to be debugged via the GDB protocol.
|
|
|
|
@b{Flash Programming:} Flash writing is supported for external
|
|
CFI-compatible NOR flashes (Intel and AMD/Spansion command set) and several
|
|
internal flashes (LPC1700, LPC1800, LPC2000, LPC4300, AT91SAM7, AT91SAM3U,
|
|
STR7x, STR9x, LM3, STM32x and EFM32). Preliminary support for various NAND flash
|
|
controllers (LPC3180, Orion, S3C24xx, more) is included.
|
|
|
|
@section OpenOCD Web Site
|
|
|
|
The OpenOCD web site provides the latest public news from the community:
|
|
|
|
@uref{http://openocd.org/}
|
|
|
|
@section Latest User's Guide:
|
|
|
|
The user's guide you are now reading may not be the latest one
|
|
available. A version for more recent code may be available.
|
|
Its HTML form is published regularly at:
|
|
|
|
@uref{http://openocd.org/doc/html/index.html}
|
|
|
|
PDF form is likewise published at:
|
|
|
|
@uref{http://openocd.org/doc/pdf/openocd.pdf}
|
|
|
|
@section OpenOCD User's Forum
|
|
|
|
There is an OpenOCD forum (phpBB) hosted by SparkFun,
|
|
which might be helpful to you. Note that if you want
|
|
anything to come to the attention of developers, you
|
|
should post it to the OpenOCD Developer Mailing List
|
|
instead of this forum.
|
|
|
|
@uref{http://forum.sparkfun.com/viewforum.php?f=18}
|
|
|
|
@section OpenOCD User's Mailing List
|
|
|
|
The OpenOCD User Mailing List provides the primary means of
|
|
communication between users:
|
|
|
|
@uref{https://lists.sourceforge.net/mailman/listinfo/openocd-user}
|
|
|
|
@section OpenOCD IRC
|
|
|
|
Support can also be found on irc:
|
|
@uref{irc://irc.libera.chat/openocd}
|
|
|
|
@node Developers
|
|
@chapter OpenOCD Developer Resources
|
|
@cindex developers
|
|
|
|
If you are interested in improving the state of OpenOCD's debugging and
|
|
testing support, new contributions will be welcome. Motivated developers
|
|
can produce new target, flash or interface drivers, improve the
|
|
documentation, as well as more conventional bug fixes and enhancements.
|
|
|
|
The resources in this chapter are available for developers wishing to explore
|
|
or expand the OpenOCD source code.
|
|
|
|
@section OpenOCD Git Repository
|
|
|
|
During the 0.3.x release cycle, OpenOCD switched from Subversion to
|
|
a Git repository hosted at SourceForge. The repository URL is:
|
|
|
|
@uref{git://git.code.sf.net/p/openocd/code}
|
|
|
|
or via http
|
|
|
|
@uref{http://git.code.sf.net/p/openocd/code}
|
|
|
|
You may prefer to use a mirror and the HTTP protocol:
|
|
|
|
@uref{http://repo.or.cz/r/openocd.git}
|
|
|
|
With standard Git tools, use @command{git clone} to initialize
|
|
a local repository, and @command{git pull} to update it.
|
|
There are also gitweb pages letting you browse the repository
|
|
with a web browser, or download arbitrary snapshots without
|
|
needing a Git client:
|
|
|
|
@uref{http://repo.or.cz/w/openocd.git}
|
|
|
|
The @file{README} file contains the instructions for building the project
|
|
from the repository or a snapshot.
|
|
|
|
Developers that want to contribute patches to the OpenOCD system are
|
|
@b{strongly} encouraged to work against mainline.
|
|
Patches created against older versions may require additional
|
|
work from their submitter in order to be updated for newer releases.
|
|
|
|
@section Doxygen Developer Manual
|
|
|
|
During the 0.2.x release cycle, the OpenOCD project began
|
|
providing a Doxygen reference manual. This document contains more
|
|
technical information about the software internals, development
|
|
processes, and similar documentation:
|
|
|
|
@uref{http://openocd.org/doc/doxygen/html/index.html}
|
|
|
|
This document is a work-in-progress, but contributions would be welcome
|
|
to fill in the gaps. All of the source files are provided in-tree,
|
|
listed in the Doxyfile configuration at the top of the source tree.
|
|
|
|
@section Gerrit Review System
|
|
|
|
All changes in the OpenOCD Git repository go through the web-based Gerrit
|
|
Code Review System:
|
|
|
|
@uref{https://review.openocd.org/}
|
|
|
|
After a one-time registration and repository setup, anyone can push commits
|
|
from their local Git repository directly into Gerrit.
|
|
All users and developers are encouraged to review, test, discuss and vote
|
|
for changes in Gerrit. The feedback provides the basis for a maintainer to
|
|
eventually submit the change to the main Git repository.
|
|
|
|
The @file{HACKING} file, also available as the Patch Guide in the Doxygen
|
|
Developer Manual, contains basic information about how to connect a
|
|
repository to Gerrit, prepare and push patches. Patch authors are expected to
|
|
maintain their changes while they're in Gerrit, respond to feedback and if
|
|
necessary rework and push improved versions of the change.
|
|
|
|
@section OpenOCD Developer Mailing List
|
|
|
|
The OpenOCD Developer Mailing List provides the primary means of
|
|
communication between developers:
|
|
|
|
@uref{https://lists.sourceforge.net/mailman/listinfo/openocd-devel}
|
|
|
|
@section OpenOCD Bug Tracker
|
|
|
|
The OpenOCD Bug Tracker is hosted on SourceForge:
|
|
|
|
@uref{http://bugs.openocd.org/}
|
|
|
|
|
|
@node Debug Adapter Hardware
|
|
@chapter Debug Adapter Hardware
|
|
@cindex dongles
|
|
@cindex FTDI
|
|
@cindex wiggler
|
|
@cindex printer port
|
|
@cindex USB Adapter
|
|
@cindex RTCK
|
|
|
|
Defined: @b{dongle}: A small device that plugs into a computer and serves as
|
|
an adapter .... [snip]
|
|
|
|
In the OpenOCD case, this generally refers to @b{a small adapter} that
|
|
attaches to your computer via USB or the parallel port.
|
|
|
|
|
|
@section Choosing a Dongle
|
|
|
|
There are several things you should keep in mind when choosing a dongle.
|
|
|
|
@enumerate
|
|
@item @b{Transport} Does it support the kind of communication that you need?
|
|
OpenOCD focuses mostly on JTAG. Your version may also support
|
|
other ways to communicate with target devices.
|
|
@item @b{Voltage} What voltage is your target - 1.8, 2.8, 3.3, or 5V?
|
|
Does your dongle support it? You might need a level converter.
|
|
@item @b{Pinout} What pinout does your target board use?
|
|
Does your dongle support it? You may be able to use jumper
|
|
wires, or an "octopus" connector, to convert pinouts.
|
|
@item @b{Connection} Does your computer have the USB, parallel, or
|
|
Ethernet port needed?
|
|
@item @b{RTCK} Do you expect to use it with ARM chips and boards with
|
|
RTCK support (also known as ``adaptive clocking'')?
|
|
@end enumerate
|
|
|
|
@section USB FT2232 Based
|
|
|
|
There are many USB JTAG dongles on the market, many of them based
|
|
on a chip from ``Future Technology Devices International'' (FTDI)
|
|
known as the FTDI FT2232; this is a USB full speed (12 Mbps) chip.
|
|
See: @url{http://www.ftdichip.com} for more information.
|
|
In summer 2009, USB high speed (480 Mbps) versions of these FTDI
|
|
chips started to become available in JTAG adapters. Around 2012, a new
|
|
variant appeared - FT232H - this is a single-channel version of FT2232H.
|
|
(Adapters using those high speed FT2232H or FT232H chips may support adaptive
|
|
clocking.)
|
|
|
|
The FT2232 chips are flexible enough to support some other
|
|
transport options, such as SWD or the SPI variants used to
|
|
program some chips. They have two communications channels,
|
|
and one can be used for a UART adapter at the same time the
|
|
other one is used to provide a debug adapter.
|
|
|
|
Also, some development boards integrate an FT2232 chip to serve as
|
|
a built-in low-cost debug adapter and USB-to-serial solution.
|
|
|
|
@itemize @bullet
|
|
@item @b{usbjtag}
|
|
@* Link @url{http://elk.informatik.fh-augsburg.de/hhweb/doc/openocd/usbjtag/usbjtag.html}
|
|
@item @b{jtagkey}
|
|
@* See: @url{http://www.amontec.com/jtagkey.shtml}
|
|
@item @b{jtagkey2}
|
|
@* See: @url{http://www.amontec.com/jtagkey2.shtml}
|
|
@item @b{oocdlink}
|
|
@* See: @url{http://www.oocdlink.com} By Joern Kaipf
|
|
@item @b{signalyzer}
|
|
@* See: @url{http://www.signalyzer.com}
|
|
@item @b{Stellaris Eval Boards}
|
|
@* See: @url{http://www.ti.com} - The Stellaris eval boards
|
|
bundle FT2232-based JTAG and SWD support, which can be used to debug
|
|
the Stellaris chips. Using separate JTAG adapters is optional.
|
|
These boards can also be used in a "pass through" mode as JTAG adapters
|
|
to other target boards, disabling the Stellaris chip.
|
|
@item @b{TI/Luminary ICDI}
|
|
@* See: @url{http://www.ti.com} - TI/Luminary In-Circuit Debug
|
|
Interface (ICDI) Boards are included in Stellaris LM3S9B9x
|
|
Evaluation Kits. Like the non-detachable FT2232 support on the other
|
|
Stellaris eval boards, they can be used to debug other target boards.
|
|
@item @b{olimex-jtag}
|
|
@* See: @url{http://www.olimex.com}
|
|
@item @b{Flyswatter/Flyswatter2}
|
|
@* See: @url{http://www.tincantools.com}
|
|
@item @b{turtelizer2}
|
|
@* See:
|
|
@uref{http://www.ethernut.de/en/hardware/turtelizer/index.html, Turtelizer 2}, or
|
|
@url{http://www.ethernut.de}
|
|
@item @b{comstick}
|
|
@* Link: @url{http://www.hitex.com/index.php?id=383}
|
|
@item @b{stm32stick}
|
|
@* Link @url{http://www.hitex.com/stm32-stick}
|
|
@item @b{axm0432_jtag}
|
|
@* Axiom AXM-0432 Link @url{http://www.axman.com} - NOTE: This JTAG does not appear
|
|
to be available anymore as of April 2012.
|
|
@item @b{cortino}
|
|
@* Link @url{http://www.hitex.com/index.php?id=cortino}
|
|
@item @b{dlp-usb1232h}
|
|
@* Link @url{http://www.dlpdesign.com/usb/usb1232h.shtml}
|
|
@item @b{digilent-hs1}
|
|
@* Link @url{http://www.digilentinc.com/Products/Detail.cfm?Prod=JTAG-HS1}
|
|
@item @b{opendous}
|
|
@* Link @url{http://code.google.com/p/opendous/wiki/JTAG} FT2232H-based
|
|
(OpenHardware).
|
|
@item @b{JTAG-lock-pick Tiny 2}
|
|
@* Link @url{http://www.distortec.com/jtag-lock-pick-tiny-2} FT232H-based
|
|
|
|
@item @b{GW16042}
|
|
@* Link: @url{https://www.gateworks.com/} FT2232H-based
|
|
|
|
@end itemize
|
|
@section USB-JTAG / Altera USB-Blaster compatibles
|
|
|
|
These devices also show up as FTDI devices, but are not
|
|
protocol-compatible with the FT2232 devices. They are, however,
|
|
protocol-compatible among themselves. USB-JTAG devices typically consist
|
|
of a FT245 followed by a CPLD that understands a particular protocol,
|
|
or emulates this protocol using some other hardware.
|
|
|
|
They may appear under different USB VID/PID depending on the particular
|
|
product. The driver can be configured to search for any VID/PID pair
|
|
(see the section on driver commands).
|
|
|
|
@itemize
|
|
@item @b{USB-JTAG} Kolja Waschk's USB Blaster-compatible adapter
|
|
@* Link: @url{http://ixo-jtag.sourceforge.net/}
|
|
@item @b{Altera USB-Blaster}
|
|
@* Link: @url{http://www.altera.com/literature/ug/ug_usb_blstr.pdf}
|
|
@end itemize
|
|
|
|
@section USB J-Link based
|
|
There are several OEM versions of the SEGGER @b{J-Link} adapter. It is
|
|
an example of a microcontroller based JTAG adapter, it uses an
|
|
AT91SAM764 internally.
|
|
|
|
@itemize @bullet
|
|
@item @b{SEGGER J-Link}
|
|
@* Link: @url{http://www.segger.com/jlink.html}
|
|
@item @b{Atmel SAM-ICE} (Only works with Atmel chips!)
|
|
@* Link: @url{http://www.atmel.com/tools/atmelsam-ice.aspx}
|
|
@item @b{IAR J-Link}
|
|
@end itemize
|
|
|
|
@section USB RLINK based
|
|
Raisonance has an adapter called @b{RLink}. It exists in a stripped-down form on the STM32 Primer,
|
|
permanently attached to the JTAG lines. It also exists on the STM32 Primer2, but that is wired for
|
|
SWD and not JTAG, thus not supported.
|
|
|
|
@itemize @bullet
|
|
@item @b{Raisonance RLink}
|
|
@* Link: @url{https://www.raisonance.com/rlink.html}
|
|
@item @b{STM32 Primer}
|
|
@* Link: @url{http://www.stm32circle.com/resources/stm32primer.php}
|
|
@item @b{STM32 Primer2}
|
|
@* Link: @url{http://www.stm32circle.com/resources/stm32primer2.php}
|
|
@end itemize
|
|
|
|
@section USB ST-LINK based
|
|
STMicroelectronics has an adapter called @b{ST-LINK}.
|
|
They only work with STMicroelectronics chips, notably STM32 and STM8.
|
|
|
|
@itemize @bullet
|
|
@item @b{ST-LINK}
|
|
@* This is available standalone and as part of some kits, eg. STM32VLDISCOVERY.
|
|
@* Link: @url{http://www.st.com/internet/evalboard/product/219866.jsp}
|
|
@item @b{ST-LINK/V2}
|
|
@* This is available standalone and as part of some kits, eg. STM32F4DISCOVERY.
|
|
@* Link: @url{http://www.st.com/internet/evalboard/product/251168.jsp}
|
|
@item @b{STLINK-V3}
|
|
@* This is available standalone and as part of some kits.
|
|
@* Link: @url{http://www.st.com/stlink-v3}
|
|
@item @b{STLINK-V3PWR}
|
|
@* This is available standalone.
|
|
Beside the debugger functionality, the probe includes a SMU (source
|
|
measurement unit) aimed at analyzing power consumption during code
|
|
execution. The SMU is not supported by OpenOCD.
|
|
@* Link: @url{http://www.st.com/stlink-v3pwr}
|
|
@end itemize
|
|
|
|
For info the original ST-LINK enumerates using the mass storage usb class; however,
|
|
its implementation is completely broken. The result is this causes issues under Linux.
|
|
The simplest solution is to get Linux to ignore the ST-LINK using one of the following methods:
|
|
@itemize @bullet
|
|
@item modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i
|
|
@item add "options usb-storage quirks=483:3744:i" to /etc/modprobe.conf
|
|
@end itemize
|
|
|
|
@section USB TI/Stellaris ICDI based
|
|
Texas Instruments has an adapter called @b{ICDI}.
|
|
It is not to be confused with the FTDI based adapters that were originally fitted to their
|
|
evaluation boards. This is the adapter fitted to the Stellaris LaunchPad.
|
|
|
|
@section USB Nuvoton Nu-Link
|
|
Nuvoton has an adapter called @b{Nu-Link}.
|
|
It is available either as stand-alone dongle and embedded on development boards.
|
|
It supports SWD, serial port bridge and mass storage for firmware update.
|
|
Both Nu-Link v1 and v2 are supported.
|
|
|
|
@section USB CMSIS-DAP based
|
|
ARM has released a interface standard called CMSIS-DAP that simplifies connecting
|
|
debuggers to ARM Cortex based targets @url{http://www.keil.com/support/man/docs/dapdebug/dapdebug_introduction.htm}.
|
|
|
|
@section USB Other
|
|
@itemize @bullet
|
|
@item @b{USBprog}
|
|
@* Link: @url{http://shop.embedded-projects.net/} - which uses an Atmel MEGA32 and a UBN9604
|
|
|
|
@item @b{USB - Presto}
|
|
@* Link: @url{http://tools.asix.net/prg_presto.htm}
|
|
|
|
@item @b{Versaloon-Link}
|
|
@* Link: @url{http://www.versaloon.com}
|
|
|
|
@item @b{ARM-JTAG-EW}
|
|
@* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html}
|
|
|
|
@item @b{angie}
|
|
@* Link: @url{https://nanoxplore.org/}
|
|
|
|
@item @b{Buspirate}
|
|
@* Link: @url{http://dangerousprototypes.com/bus-pirate-manual/}
|
|
|
|
@item @b{opendous}
|
|
@* Link: @url{http://code.google.com/p/opendous-jtag/} - which uses an AT90USB162
|
|
|
|
@item @b{estick}
|
|
@* Link: @url{http://code.google.com/p/estick-jtag/}
|
|
|
|
@item @b{Keil ULINK v1}
|
|
@* Link: @url{http://www.keil.com/ulink1/}
|
|
|
|
@item @b{TI XDS110 Debug Probe}
|
|
@* Link: @url{https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_xds110.html}
|
|
@* Link: @url{https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_xds_software_package_download.html#xds110-support-utilities}
|
|
@end itemize
|
|
|
|
@section IBM PC Parallel Printer Port Based
|
|
|
|
The two well-known ``JTAG Parallel Ports'' cables are the Xilinx DLC5
|
|
and the Macraigor Wiggler. There are many clones and variations of
|
|
these on the market.
|
|
|
|
Note that parallel ports are becoming much less common, so if you
|
|
have the choice you should probably avoid these adapters in favor
|
|
of USB-based ones.
|
|
|
|
@itemize @bullet
|
|
|
|
@item @b{Wiggler} - There are many clones of this.
|
|
@* Link: @url{http://www.macraigor.com/wiggler.htm}
|
|
|
|
@item @b{DLC5} - From XILINX - There are many clones of this
|
|
@* Link: Search the web for: ``XILINX DLC5'' - it is no longer
|
|
produced, PDF schematics are easily found and it is easy to make.
|
|
|
|
@item @b{Amontec - JTAG Accelerator}
|
|
@* Link: @url{http://www.amontec.com/jtag_accelerator.shtml}
|
|
|
|
@item @b{Wiggler2}
|
|
@* Link: @url{http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag}
|
|
|
|
@item @b{Wiggler_ntrst_inverted}
|
|
@* Yet another variation - See the source code, src/jtag/parport.c
|
|
|
|
@item @b{old_amt_wiggler}
|
|
@* Unknown - probably not on the market today
|
|
|
|
@item @b{arm-jtag}
|
|
@* Link: Most likely @url{http://www.olimex.com/dev/arm-jtag.html} [another wiggler clone]
|
|
|
|
@item @b{chameleon}
|
|
@* Link: @url{http://www.amontec.com/chameleon.shtml}
|
|
|
|
@item @b{Triton}
|
|
@* Unknown.
|
|
|
|
@item @b{Lattice}
|
|
@* ispDownload from Lattice Semiconductor
|
|
@url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf}
|
|
|
|
@item @b{flashlink}
|
|
@* From STMicroelectronics;
|
|
@* Link: @url{http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATA_BRIEF/DM00039500.pdf}
|
|
|
|
@end itemize
|
|
|
|
@section Other...
|
|
@itemize @bullet
|
|
|
|
@item @b{ep93xx}
|
|
@* An EP93xx based Linux machine using the GPIO pins directly.
|
|
|
|
@item @b{at91rm9200}
|
|
@* Like the EP93xx - but an ATMEL AT91RM9200 based solution using the GPIO pins on the chip.
|
|
|
|
@item @b{bcm2835gpio}
|
|
@* A BCM2835-based board (e.g. Raspberry Pi) using the GPIO pins of the expansion header.
|
|
|
|
@item @b{imx_gpio}
|
|
@* A NXP i.MX-based board (e.g. Wandboard) using the GPIO pins (should work on any i.MX processor).
|
|
|
|
@item @b{am335xgpio}
|
|
@* A Texas Instruments AM335x-based board (e.g. BeagleBone Black) using the GPIO pins of the expansion headers.
|
|
|
|
@item @b{jtag_vpi}
|
|
@* A JTAG driver acting as a client for the JTAG VPI server interface.
|
|
@* Link: @url{http://github.com/fjullien/jtag_vpi}
|
|
|
|
@item @b{vdebug}
|
|
@* A driver for Cadence virtual Debug Interface to emulated or simulated targets.
|
|
It implements a client connecting to the vdebug server, which in turn communicates
|
|
with the emulated or simulated RTL model through a transactor. The driver supports
|
|
JTAG and DAP-level transports.
|
|
|
|
@item @b{jtag_dpi}
|
|
@* A JTAG driver acting as a client for the SystemVerilog Direct Programming
|
|
Interface (DPI) for JTAG devices. DPI allows OpenOCD to connect to the JTAG
|
|
interface of a hardware model written in SystemVerilog, for example, on an
|
|
emulation model of target hardware.
|
|
|
|
@item @b{xlnx_pcie_xvc}
|
|
@* A JTAG driver exposing Xilinx Virtual Cable over PCI Express to OpenOCD as JTAG/SWD interface.
|
|
|
|
@item @b{linuxspidev}
|
|
@* A SPI based SWD driver using Linux SPI devices.
|
|
|
|
@item @b{linuxgpiod}
|
|
@* A bitbang JTAG driver using Linux GPIO through library libgpiod.
|
|
|
|
@item @b{sysfsgpio}
|
|
@* A bitbang JTAG driver using Linux legacy sysfs GPIO.
|
|
This is deprecated from Linux v5.3; prefer using @b{linuxgpiod}.
|
|
|
|
@item @b{esp_usb_jtag}
|
|
@* A JTAG driver to communicate with builtin debug modules of Espressif ESP32-C3 and ESP32-S3 chips using OpenOCD.
|
|
|
|
@end itemize
|
|
|
|
@node About Jim-Tcl
|
|
@chapter About Jim-Tcl
|
|
@cindex Jim-Tcl
|
|
@cindex tcl
|
|
|
|
OpenOCD uses a small ``Tcl Interpreter'' known as Jim-Tcl.
|
|
This programming language provides a simple and extensible
|
|
command interpreter.
|
|
|
|
All commands presented in this Guide are extensions to Jim-Tcl.
|
|
You can use them as simple commands, without needing to learn
|
|
much of anything about Tcl.
|
|
Alternatively, you can write Tcl programs with them.
|
|
|
|
You can learn more about Jim at its website, @url{http://jim.tcl.tk}.
|
|
There is an active and responsive community, get on the mailing list
|
|
if you have any questions. Jim-Tcl maintainers also lurk on the
|
|
OpenOCD mailing list.
|
|
|
|
@itemize @bullet
|
|
@item @b{Jim vs. Tcl}
|
|
@* Jim-Tcl is a stripped down version of the well known Tcl language,
|
|
which can be found here: @url{http://www.tcl.tk}. Jim-Tcl has far
|
|
fewer features. Jim-Tcl is several dozens of .C files and .H files and
|
|
implements the basic Tcl command set. In contrast: Tcl 8.6 is a
|
|
4.2 MB .zip file containing 1540 files.
|
|
|
|
@item @b{Missing Features}
|
|
@* Our practice has been: Add/clone the real Tcl feature if/when
|
|
needed. We welcome Jim-Tcl improvements, not bloat. Also there
|
|
are a large number of optional Jim-Tcl features that are not
|
|
enabled in OpenOCD.
|
|
|
|
@item @b{Scripts}
|
|
@* OpenOCD configuration scripts are Jim-Tcl Scripts. OpenOCD's
|
|
command interpreter today is a mixture of (newer)
|
|
Jim-Tcl commands, and the (older) original command interpreter.
|
|
|
|
@item @b{Commands}
|
|
@* At the OpenOCD telnet command line (or via the GDB monitor command) one
|
|
can type a Tcl for() loop, set variables, etc.
|
|
Some of the commands documented in this guide are implemented
|
|
as Tcl scripts, from a @file{startup.tcl} file internal to the server.
|
|
|
|
@item @b{Historical Note}
|
|
@* Jim-Tcl was introduced to OpenOCD in spring 2008. Fall 2010,
|
|
before OpenOCD 0.5 release, OpenOCD switched to using Jim-Tcl
|
|
as a Git submodule, which greatly simplified upgrading Jim-Tcl
|
|
to benefit from new features and bugfixes in Jim-Tcl.
|
|
|
|
@item @b{Need a crash course in Tcl?}
|
|
@*@xref{Tcl Crash Course}.
|
|
@end itemize
|
|
|
|
@node Running
|
|
@chapter Running
|
|
@cindex command line options
|
|
@cindex logfile
|
|
@cindex directory search
|
|
|
|
Properly installing OpenOCD sets up your operating system to grant it access
|
|
to the debug adapters. On Linux, this usually involves installing a file
|
|
in @file{/etc/udev/rules.d,} so OpenOCD has permissions. An example rules file
|
|
that works for many common adapters is shipped with OpenOCD in the
|
|
@file{contrib} directory. MS-Windows needs
|
|
complex and confusing driver configuration for every peripheral. Such issues
|
|
are unique to each operating system, and are not detailed in this User's Guide.
|
|
|
|
Then later you will invoke the OpenOCD server, with various options to
|
|
tell it how each debug session should work.
|
|
The @option{--help} option shows:
|
|
@verbatim
|
|
bash$ openocd --help
|
|
|
|
--help | -h display this help
|
|
--version | -v display OpenOCD version
|
|
--file | -f use configuration file <name>
|
|
--search | -s dir to search for config files and scripts
|
|
--debug | -d set debug level to 3
|
|
| -d<n> set debug level to <level>
|
|
--log_output | -l redirect log output to file <name>
|
|
--command | -c run <command>
|
|
@end verbatim
|
|
|
|
If you don't give any @option{-f} or @option{-c} options,
|
|
OpenOCD tries to read the configuration file @file{openocd.cfg}.
|
|
To specify one or more different
|
|
configuration files, use @option{-f} options. For example:
|
|
|
|
@example
|
|
openocd -f config1.cfg -f config2.cfg -f config3.cfg
|
|
@end example
|
|
|
|
Configuration files and scripts are searched for in
|
|
@enumerate
|
|
@item the current directory,
|
|
@item any search dir specified on the command line using the @option{-s} option,
|
|
@item any search dir specified using the @command{add_script_search_dir} command,
|
|
@item a directory in the @env{OPENOCD_SCRIPTS} environment variable (if set),
|
|
@item @file{%APPDATA%/OpenOCD} (only on Windows),
|
|
@item @file{$HOME/Library/Preferences/org.openocd} (only on Darwin),
|
|
@item @file{$XDG_CONFIG_HOME/openocd} (@env{$XDG_CONFIG_HOME} defaults to @file{$HOME/.config}),
|
|
@item @file{$HOME/.openocd},
|
|
@item the site wide script library @file{$pkgdatadir/site} and
|
|
@item the OpenOCD-supplied script library @file{$pkgdatadir/scripts}.
|
|
@end enumerate
|
|
The first found file with a matching file name will be used.
|
|
|
|
@quotation Note
|
|
Don't try to use configuration script names or paths which
|
|
include the "#" character. That character begins Tcl comments.
|
|
@end quotation
|
|
|
|
@section Simple setup, no customization
|
|
|
|
In the best case, you can use two scripts from one of the script
|
|
libraries, hook up your JTAG adapter, and start the server ... and
|
|
your JTAG setup will just work "out of the box". Always try to
|
|
start by reusing those scripts, but assume you'll need more
|
|
customization even if this works. @xref{OpenOCD Project Setup}.
|
|
|
|
If you find a script for your JTAG adapter, and for your board or
|
|
target, you may be able to hook up your JTAG adapter then start
|
|
the server with some variation of one of the following:
|
|
|
|
@example
|
|
openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg
|
|
openocd -f interface/ftdi/ADAPTER.cfg -f board/MYBOARD.cfg
|
|
@end example
|
|
|
|
You might also need to configure which reset signals are present,
|
|
using @option{-c 'reset_config trst_and_srst'} or something similar.
|
|
If all goes well you'll see output something like
|
|
|
|
@example
|
|
Open On-Chip Debugger 0.4.0 (2010-01-14-15:06)
|
|
For bug reports, read
|
|
http://openocd.org/doc/doxygen/bugs.html
|
|
Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477
|
|
(mfg: 0x23b, part: 0xba00, ver: 0x3)
|
|
@end example
|
|
|
|
Seeing that "tap/device found" message, and no warnings, means
|
|
the JTAG communication is working. That's a key milestone, but
|
|
you'll probably need more project-specific setup.
|
|
|
|
@section What OpenOCD does as it starts
|
|
|
|
OpenOCD starts by processing the configuration commands provided
|
|
on the command line or, if there were no @option{-c command} or
|
|
@option{-f file.cfg} options given, in @file{openocd.cfg}.
|
|
@xref{configurationstage,,Configuration Stage}.
|
|
At the end of the configuration stage it verifies the JTAG scan
|
|
chain defined using those commands; your configuration should
|
|
ensure that this always succeeds.
|
|
Normally, OpenOCD then starts running as a server.
|
|
Alternatively, commands may be used to terminate the configuration
|
|
stage early, perform work (such as updating some flash memory),
|
|
and then shut down without acting as a server.
|
|
|
|
Once OpenOCD starts running as a server, it waits for connections from
|
|
clients (Telnet, GDB, RPC) and processes the commands issued through
|
|
those channels.
|
|
|
|
If you are having problems, you can enable internal debug messages via
|
|
the @option{-d} option.
|
|
|
|
Also it is possible to interleave Jim-Tcl commands w/config scripts using the
|
|
@option{-c} command line switch.
|
|
|
|
To enable debug output (when reporting problems or working on OpenOCD
|
|
itself), use the @option{-d} command line switch. This sets the
|
|
@option{debug_level} to "3", outputting the most information,
|
|
including debug messages. The default setting is "2", outputting only
|
|
informational messages, warnings and errors. You can also change this
|
|
setting from within a telnet or gdb session using @command{debug_level<n>}
|
|
(@pxref{debuglevel,,debug_level}).
|
|
|
|
You can redirect all output from the server to a file using the
|
|
@option{-l <logfile>} switch.
|
|
|
|
Note! OpenOCD will launch the GDB & telnet server even if it can not
|
|
establish a connection with the target. In general, it is possible for
|
|
the JTAG controller to be unresponsive until the target is set up
|
|
correctly via e.g. GDB monitor commands in a GDB init script.
|
|
|
|
@node OpenOCD Project Setup
|
|
@chapter OpenOCD Project Setup
|
|
|
|
To use OpenOCD with your development projects, you need to do more than
|
|
just connect the JTAG adapter hardware (dongle) to your development board
|
|
and start the OpenOCD server.
|
|
You also need to configure your OpenOCD server so that it knows
|
|
about your adapter and board, and helps your work.
|
|
You may also want to connect OpenOCD to GDB, possibly
|
|
using Eclipse or some other GUI.
|
|
|
|
@section Hooking up the JTAG Adapter
|
|
|
|
Today's most common case is a dongle with a JTAG cable on one side
|
|
(such as a ribbon cable with a 10-pin or 20-pin IDC connector)
|
|
and a USB cable on the other.
|
|
Instead of USB, some dongles use Ethernet;
|
|
older ones may use a PC parallel port, or even a serial port.
|
|
|
|
@enumerate
|
|
@item @emph{Start with power to your target board turned off},
|
|
and nothing connected to your JTAG adapter.
|
|
If you're particularly paranoid, unplug power to the board.
|
|
It's important to have the ground signal properly set up,
|
|
unless you are using a JTAG adapter which provides
|
|
galvanic isolation between the target board and the
|
|
debugging host.
|
|
|
|
@item @emph{Be sure it's the right kind of JTAG connector.}
|
|
If your dongle has a 20-pin ARM connector, you need some kind
|
|
of adapter (or octopus, see below) to hook it up to
|
|
boards using 14-pin or 10-pin connectors ... or to 20-pin
|
|
connectors which don't use ARM's pinout.
|
|
|
|
In the same vein, make sure the voltage levels are compatible.
|
|
Not all JTAG adapters have the level shifters needed to work
|
|
with 1.2 Volt boards.
|
|
|
|
@item @emph{Be certain the cable is properly oriented} or you might
|
|
damage your board. In most cases there are only two possible
|
|
ways to connect the cable.
|
|
Connect the JTAG cable from your adapter to the board.
|
|
Be sure it's firmly connected.
|
|
|
|
In the best case, the connector is keyed to physically
|
|
prevent you from inserting it wrong.
|
|
This is most often done using a slot on the board's male connector
|
|
housing, which must match a key on the JTAG cable's female connector.
|
|
If there's no housing, then you must look carefully and
|
|
make sure pin 1 on the cable hooks up to pin 1 on the board.
|
|
Ribbon cables are frequently all grey except for a wire on one
|
|
edge, which is red. The red wire is pin 1.
|
|
|
|
Sometimes dongles provide cables where one end is an ``octopus'' of
|
|
color coded single-wire connectors, instead of a connector block.
|
|
These are great when converting from one JTAG pinout to another,
|
|
but are tedious to set up.
|
|
Use these with connector pinout diagrams to help you match up the
|
|
adapter signals to the right board pins.
|
|
|
|
@item @emph{Connect the adapter's other end} once the JTAG cable is connected.
|
|
A USB, parallel, or serial port connector will go to the host which
|
|
you are using to run OpenOCD.
|
|
For Ethernet, consult the documentation and your network administrator.
|
|
|
|
For USB-based JTAG adapters you have an easy sanity check at this point:
|
|
does the host operating system see the JTAG adapter? If you're running
|
|
Linux, try the @command{lsusb} command. If that host is an
|
|
MS-Windows host, you'll need to install a driver before OpenOCD works.
|
|
|
|
@item @emph{Connect the adapter's power supply, if needed.}
|
|
This step is primarily for non-USB adapters,
|
|
but sometimes USB adapters need extra power.
|
|
|
|
@item @emph{Power up the target board.}
|
|
Unless you just let the magic smoke escape,
|
|
you're now ready to set up the OpenOCD server
|
|
so you can use JTAG to work with that board.
|
|
|
|
@end enumerate
|
|
|
|
Talk with the OpenOCD server using
|
|
telnet (@code{telnet localhost 4444} on many systems) or GDB.
|
|
@xref{GDB and OpenOCD}.
|
|
|
|
@section Project Directory
|
|
|
|
There are many ways you can configure OpenOCD and start it up.
|
|
|
|
A simple way to organize them all involves keeping a
|
|
single directory for your work with a given board.
|
|
When you start OpenOCD from that directory,
|
|
it searches there first for configuration files, scripts,
|
|
files accessed through semihosting,
|
|
and for code you upload to the target board.
|
|
It is also the natural place to write files,
|
|
such as log files and data you download from the board.
|
|
|
|
@section Configuration Basics
|
|
|
|
There are two basic ways of configuring OpenOCD, and
|
|
a variety of ways you can mix them.
|
|
Think of the difference as just being how you start the server:
|
|
|
|
@itemize
|
|
@item Many @option{-f file} or @option{-c command} options on the command line
|
|
@item No options, but a @dfn{user config file}
|
|
in the current directory named @file{openocd.cfg}
|
|
@end itemize
|
|
|
|
Here is an example @file{openocd.cfg} file for a setup
|
|
using a Signalyzer FT2232-based JTAG adapter to talk to
|
|
a board with an Atmel AT91SAM7X256 microcontroller:
|
|
|
|
@example
|
|
source [find interface/ftdi/signalyzer.cfg]
|
|
|
|
# GDB can also flash my flash!
|
|
gdb memory_map enable
|
|
gdb flash_program enable
|
|
|
|
source [find target/sam7x256.cfg]
|
|
@end example
|
|
|
|
Here is the command line equivalent of that configuration:
|
|
|
|
@example
|
|
openocd -f interface/ftdi/signalyzer.cfg \
|
|
-c "gdb memory_map enable" \
|
|
-c "gdb flash_program enable" \
|
|
-f target/sam7x256.cfg
|
|
@end example
|
|
|
|
You could wrap such long command lines in shell scripts,
|
|
each supporting a different development task.
|
|
One might re-flash the board with a specific firmware version.
|
|
Another might set up a particular debugging or run-time environment.
|
|
|
|
@quotation Important
|
|
At this writing (October 2009) the command line method has
|
|
problems with how it treats variables.
|
|
For example, after @option{-c "set VAR value"}, or doing the
|
|
same in a script, the variable @var{VAR} will have no value
|
|
that can be tested in a later script.
|
|
@end quotation
|
|
|
|
Here we will focus on the simpler solution: one user config
|
|
file, including basic configuration plus any TCL procedures
|
|
to simplify your work.
|
|
|
|
@section User Config Files
|
|
@cindex config file, user
|
|
@cindex user config file
|
|
@cindex config file, overview
|
|
|
|
A user configuration file ties together all the parts of a project
|
|
in one place.
|
|
One of the following will match your situation best:
|
|
|
|
@itemize
|
|
@item Ideally almost everything comes from configuration files
|
|
provided by someone else.
|
|
For example, OpenOCD distributes a @file{scripts} directory
|
|
(probably in @file{/usr/share/openocd/scripts} on Linux).
|
|
Board and tool vendors can provide these too, as can individual
|
|
user sites; the @option{-s} command line option lets you say
|
|
where to find these files. (@xref{Running}.)
|
|
The AT91SAM7X256 example above works this way.
|
|
|
|
Three main types of non-user configuration file each have their
|
|
own subdirectory in the @file{scripts} directory:
|
|
|
|
@enumerate
|
|
@item @b{interface} -- one for each different debug adapter;
|
|
@item @b{board} -- one for each different board
|
|
@item @b{target} -- the chips which integrate CPUs and other JTAG TAPs
|
|
@end enumerate
|
|
|
|
Best case: include just two files, and they handle everything else.
|
|
The first is an interface config file.
|
|
The second is board-specific, and it sets up the JTAG TAPs and
|
|
their GDB targets (by deferring to some @file{target.cfg} file),
|
|
declares all flash memory, and leaves you nothing to do except
|
|
meet your deadline:
|
|
|
|
@example
|
|
source [find interface/olimex-jtag-tiny.cfg]
|
|
source [find board/csb337.cfg]
|
|
@end example
|
|
|
|
Boards with a single microcontroller often won't need more
|
|
than the target config file, as in the AT91SAM7X256 example.
|
|
That's because there is no external memory (flash, DDR RAM), and
|
|
the board differences are encapsulated by application code.
|
|
|
|
@item Maybe you don't know yet what your board looks like to JTAG.
|
|
Once you know the @file{interface.cfg} file to use, you may
|
|
need help from OpenOCD to discover what's on the board.
|
|
Once you find the JTAG TAPs, you can just search for appropriate
|
|
target and board
|
|
configuration files ... or write your own, from the bottom up.
|
|
@xref{autoprobing,,Autoprobing}.
|
|
|
|
@item You can often reuse some standard config files but
|
|
need to write a few new ones, probably a @file{board.cfg} file.
|
|
You will be using commands described later in this User's Guide,
|
|
and working with the guidelines in the next chapter.
|
|
|
|
For example, there may be configuration files for your JTAG adapter
|
|
and target chip, but you need a new board-specific config file
|
|
giving access to your particular flash chips.
|
|
Or you might need to write another target chip configuration file
|
|
for a new chip built around the Cortex-M3 core.
|
|
|
|
@quotation Note
|
|
When you write new configuration files, please submit
|
|
them for inclusion in the next OpenOCD release.
|
|
For example, a @file{board/newboard.cfg} file will help the
|
|
next users of that board, and a @file{target/newcpu.cfg}
|
|
will help support users of any board using that chip.
|
|
@end quotation
|
|
|
|
@item
|
|
You may need to write some C code.
|
|
It may be as simple as supporting a new FT2232 or parport
|
|
based adapter; a bit more involved, like a NAND or NOR flash
|
|
controller driver; or a big piece of work like supporting
|
|
a new chip architecture.
|
|
@end itemize
|
|
|
|
Reuse the existing config files when you can.
|
|
Look first in the @file{scripts/boards} area, then @file{scripts/targets}.
|
|
You may find a board configuration that's a good example to follow.
|
|
|
|
When you write config files, separate the reusable parts
|
|
(things every user of that interface, chip, or board needs)
|
|
from ones specific to your environment and debugging approach.
|
|
@itemize
|
|
|
|
@item
|
|
For example, a @code{gdb-attach} event handler that invokes
|
|
the @command{reset init} command will interfere with debugging
|
|
early boot code, which performs some of the same actions
|
|
that the @code{reset-init} event handler does.
|
|
|
|
@item
|
|
Likewise, the @command{arm9 vector_catch} command (or
|
|
@cindex vector_catch
|
|
its siblings @command{xscale vector_catch}
|
|
and @command{cortex_m vector_catch}) can be a time-saver
|
|
during some debug sessions, but don't make everyone use that either.
|
|
Keep those kinds of debugging aids in your user config file,
|
|
along with messaging and tracing setup.
|
|
(@xref{softwaredebugmessagesandtracing,,Software Debug Messages and Tracing}.)
|
|
|
|
@item
|
|
You might need to override some defaults.
|
|
For example, you might need to move, shrink, or back up the target's
|
|
work area if your application needs much SRAM.
|
|
|
|
@item
|
|
TCP/IP port configuration is another example of something which
|
|
is environment-specific, and should only appear in
|
|
a user config file. @xref{tcpipports,,TCP/IP Ports}.
|
|
@end itemize
|
|
|
|
@section Project-Specific Utilities
|
|
|
|
A few project-specific utility
|
|
routines may well speed up your work.
|
|
Write them, and keep them in your project's user config file.
|
|
|
|
For example, if you are making a boot loader work on a
|
|
board, it's nice to be able to debug the ``after it's
|
|
loaded to RAM'' parts separately from the finicky early
|
|
code which sets up the DDR RAM controller and clocks.
|
|
A script like this one, or a more GDB-aware sibling,
|
|
may help:
|
|
|
|
@example
|
|
proc ramboot @{ @} @{
|
|
# Reset, running the target's "reset-init" scripts
|
|
# to initialize clocks and the DDR RAM controller.
|
|
# Leave the CPU halted.
|
|
reset init
|
|
|
|
# Load CONFIG_SKIP_LOWLEVEL_INIT version into DDR RAM.
|
|
load_image u-boot.bin 0x20000000
|
|
|
|
# Start running.
|
|
resume 0x20000000
|
|
@}
|
|
@end example
|
|
|
|
Then once that code is working you will need to make it
|
|
boot from NOR flash; a different utility would help.
|
|
Alternatively, some developers write to flash using GDB.
|
|
(You might use a similar script if you're working with a flash
|
|
based microcontroller application instead of a boot loader.)
|
|
|
|
@example
|
|
proc newboot @{ @} @{
|
|
# Reset, leaving the CPU halted. The "reset-init" event
|
|
# proc gives faster access to the CPU and to NOR flash;
|
|
# "reset halt" would be slower.
|
|
reset init
|
|
|
|
# Write standard version of U-Boot into the first two
|
|
# sectors of NOR flash ... the standard version should
|
|
# do the same lowlevel init as "reset-init".
|
|
flash protect 0 0 1 off
|
|
flash erase_sector 0 0 1
|
|
flash write_bank 0 u-boot.bin 0x0
|
|
flash protect 0 0 1 on
|
|
|
|
# Reboot from scratch using that new boot loader.
|
|
reset run
|
|
@}
|
|
@end example
|
|
|
|
You may need more complicated utility procedures when booting
|
|
from NAND.
|
|
That often involves an extra bootloader stage,
|
|
running from on-chip SRAM to perform DDR RAM setup so it can load
|
|
the main bootloader code (which won't fit into that SRAM).
|
|
|
|
Other helper scripts might be used to write production system images,
|
|
involving considerably more than just a three stage bootloader.
|
|
|
|
@section Target Software Changes
|
|
|
|
Sometimes you may want to make some small changes to the software
|
|
you're developing, to help make JTAG debugging work better.
|
|
For example, in C or assembly language code you might
|
|
use @code{#ifdef JTAG_DEBUG} (or its converse) around code
|
|
handling issues like:
|
|
|
|
@itemize @bullet
|
|
|
|
@item @b{Watchdog Timers}...
|
|
Watchdog timers are typically used to automatically reset systems if
|
|
some application task doesn't periodically reset the timer. (The
|
|
assumption is that the system has locked up if the task can't run.)
|
|
When a JTAG debugger halts the system, that task won't be able to run
|
|
and reset the timer ... potentially causing resets in the middle of
|
|
your debug sessions.
|
|
|
|
It's rarely a good idea to disable such watchdogs, since their usage
|
|
needs to be debugged just like all other parts of your firmware.
|
|
That might however be your only option.
|
|
|
|
Look instead for chip-specific ways to stop the watchdog from counting
|
|
while the system is in a debug halt state. It may be simplest to set
|
|
that non-counting mode in your debugger startup scripts. You may however
|
|
need a different approach when, for example, a motor could be physically
|
|
damaged by firmware remaining inactive in a debug halt state. That might
|
|
involve a type of firmware mode where that "non-counting" mode is disabled
|
|
at the beginning then re-enabled at the end; a watchdog reset might fire
|
|
and complicate the debug session, but hardware (or people) would be
|
|
protected.@footnote{Note that many systems support a "monitor mode" debug
|
|
that is a somewhat cleaner way to address such issues. You can think of
|
|
it as only halting part of the system, maybe just one task,
|
|
instead of the whole thing.
|
|
At this writing, January 2010, OpenOCD based debugging does not support
|
|
monitor mode debug, only "halt mode" debug.}
|
|
|
|
@item @b{ARM Semihosting}...
|
|
@cindex ARM semihosting
|
|
When linked with a special runtime library provided with many
|
|
toolchains@footnote{See chapter 8 "Semihosting" in
|
|
@uref{http://infocenter.arm.com/help/topic/com.arm.doc.dui0203i/DUI0203I_rvct_developer_guide.pdf,
|
|
ARM DUI 0203I}, the "RealView Compilation Tools Developer Guide".
|
|
The CodeSourcery EABI toolchain also includes a semihosting library.},
|
|
your target code can use I/O facilities on the debug host. That library
|
|
provides a small set of system calls which are handled by OpenOCD.
|
|
It can let the debugger provide your system console and a file system,
|
|
helping with early debugging or providing a more capable environment
|
|
for sometimes-complex tasks like installing system firmware onto
|
|
NAND or SPI flash.
|
|
|
|
@item @b{ARM Wait-For-Interrupt}...
|
|
Many ARM chips synchronize the JTAG clock using the core clock.
|
|
Low power states which stop that core clock thus prevent JTAG access.
|
|
Idle loops in tasking environments often enter those low power states
|
|
via the @code{WFI} instruction (or its coprocessor equivalent, before ARMv7).
|
|
|
|
You may want to @emph{disable that instruction} in source code,
|
|
or otherwise prevent using that state,
|
|
to ensure you can get JTAG access at any time.@footnote{As a more
|
|
polite alternative, some processors have special debug-oriented
|
|
registers which can be used to change various features including
|
|
how the low power states are clocked while debugging.
|
|
The STM32 DBGMCU_CR register is an example; at the cost of extra
|
|
power consumption, JTAG can be used during low power states.}
|
|
For example, the OpenOCD @command{halt} command may not
|
|
work for an idle processor otherwise.
|
|
|
|
@item @b{Delay after reset}...
|
|
Not all chips have good support for debugger access
|
|
right after reset; many LPC2xxx chips have issues here.
|
|
Similarly, applications that reconfigure pins used for
|
|
JTAG access as they start will also block debugger access.
|
|
|
|
To work with boards like this, @emph{enable a short delay loop}
|
|
the first thing after reset, before "real" startup activities.
|
|
For example, one second's delay is usually more than enough
|
|
time for a JTAG debugger to attach, so that
|
|
early code execution can be debugged
|
|
or firmware can be replaced.
|
|
|
|
@item @b{Debug Communications Channel (DCC)}...
|
|
Some processors include mechanisms to send messages over JTAG.
|
|
Many ARM cores support these, as do some cores from other vendors.
|
|
(OpenOCD may be able to use this DCC internally, speeding up some
|
|
operations like writing to memory.)
|
|
|
|
Your application may want to deliver various debugging messages
|
|
over JTAG, by @emph{linking with a small library of code}
|
|
provided with OpenOCD and using the utilities there to send
|
|
various kinds of message.
|
|
@xref{softwaredebugmessagesandtracing,,Software Debug Messages and Tracing}.
|
|
|
|
@end itemize
|
|
|
|
@section Target Hardware Setup
|
|
|
|
Chip vendors often provide software development boards which
|
|
are highly configurable, so that they can support all options
|
|
that product boards may require. @emph{Make sure that any
|
|
jumpers or switches match the system configuration you are
|
|
working with.}
|
|
|
|
Common issues include:
|
|
|
|
@itemize @bullet
|
|
|
|
@item @b{JTAG setup} ...
|
|
Boards may support more than one JTAG configuration.
|
|
Examples include jumpers controlling pullups versus pulldowns
|
|
on the nTRST and/or nSRST signals, and choice of connectors
|
|
(e.g. which of two headers on the base board,
|
|
or one from a daughtercard).
|
|
For some Texas Instruments boards, you may need to jumper the
|
|
EMU0 and EMU1 signals (which OpenOCD won't currently control).
|
|
|
|
@item @b{Boot Modes} ...
|
|
Complex chips often support multiple boot modes, controlled
|
|
by external jumpers. Make sure this is set up correctly.
|
|
For example many i.MX boards from NXP need to be jumpered
|
|
to "ATX mode" to start booting using the on-chip ROM, when
|
|
using second stage bootloader code stored in a NAND flash chip.
|
|
|
|
Such explicit configuration is common, and not limited to
|
|
booting from NAND. You might also need to set jumpers to
|
|
start booting using code loaded from an MMC/SD card; external
|
|
SPI flash; Ethernet, UART, or USB links; NOR flash; OneNAND
|
|
flash; some external host; or various other sources.
|
|
|
|
|
|
@item @b{Memory Addressing} ...
|
|
Boards which support multiple boot modes may also have jumpers
|
|
to configure memory addressing. One board, for example, jumpers
|
|
external chipselect 0 (used for booting) to address either
|
|
a large SRAM (which must be pre-loaded via JTAG), NOR flash,
|
|
or NAND flash. When it's jumpered to address NAND flash, that
|
|
board must also be told to start booting from on-chip ROM.
|
|
|
|
Your @file{board.cfg} file may also need to be told this jumper
|
|
configuration, so that it can know whether to declare NOR flash
|
|
using @command{flash bank} or instead declare NAND flash with
|
|
@command{nand device}; and likewise which probe to perform in
|
|
its @code{reset-init} handler.
|
|
|
|
A closely related issue is bus width. Jumpers might need to
|
|
distinguish between 8 bit or 16 bit bus access for the flash
|
|
used to start booting.
|
|
|
|
@item @b{Peripheral Access} ...
|
|
Development boards generally provide access to every peripheral
|
|
on the chip, sometimes in multiple modes (such as by providing
|
|
multiple audio codec chips).
|
|
This interacts with software
|
|
configuration of pin multiplexing, where for example a
|
|
given pin may be routed either to the MMC/SD controller
|
|
or the GPIO controller. It also often interacts with
|
|
configuration jumpers. One jumper may be used to route
|
|
signals to an MMC/SD card slot or an expansion bus (which
|
|
might in turn affect booting); others might control which
|
|
audio or video codecs are used.
|
|
|
|
@end itemize
|
|
|
|
Plus you should of course have @code{reset-init} event handlers
|
|
which set up the hardware to match that jumper configuration.
|
|
That includes in particular any oscillator or PLL used to clock
|
|
the CPU, and any memory controllers needed to access external
|
|
memory and peripherals. Without such handlers, you won't be
|
|
able to access those resources without working target firmware
|
|
which can do that setup ... this can be awkward when you're
|
|
trying to debug that target firmware. Even if there's a ROM
|
|
bootloader which handles a few issues, it rarely provides full
|
|
access to all board-specific capabilities.
|
|
|
|
|
|
@node Config File Guidelines
|
|
@chapter Config File Guidelines
|
|
|
|
This chapter is aimed at any user who needs to write a config file,
|
|
including developers and integrators of OpenOCD and any user who
|
|
needs to get a new board working smoothly.
|
|
It provides guidelines for creating those files.
|
|
|
|
You should find the following directories under
|
|
@t{$(INSTALLDIR)/scripts}, with config files maintained upstream. Use
|
|
them as-is where you can; or as models for new files.
|
|
@itemize @bullet
|
|
@item @file{interface} ...
|
|
These are for debug adapters. Files that specify configuration to use
|
|
specific JTAG, SWD and other adapters go here.
|
|
@item @file{board} ...
|
|
Think Circuit Board, PWA, PCB, they go by many names. Board files
|
|
contain initialization items that are specific to a board.
|
|
|
|
They reuse target configuration files, since the same
|
|
microprocessor chips are used on many boards,
|
|
but support for external parts varies widely. For
|
|
example, the SDRAM initialization sequence for the board, or the type
|
|
of external flash and what address it uses. Any initialization
|
|
sequence to enable that external flash or SDRAM should be found in the
|
|
board file. Boards may also contain multiple targets: two CPUs; or
|
|
a CPU and an FPGA.
|
|
@item @file{target} ...
|
|
Think chip. The ``target'' directory represents the JTAG TAPs
|
|
on a chip
|
|
which OpenOCD should control, not a board. Two common types of targets
|
|
are ARM chips and FPGA or CPLD chips.
|
|
When a chip has multiple TAPs (maybe it has both ARM and DSP cores),
|
|
the target config file defines all of them.
|
|
@item @emph{more} ... browse for other library files which may be useful.
|
|
For example, there are various generic and CPU-specific utilities.
|
|
@end itemize
|
|
|
|
The @file{openocd.cfg} user config
|
|
file may override features in any of the above files by
|
|
setting variables before sourcing the target file, or by adding
|
|
commands specific to their situation.
|
|
|
|
@section Interface Config Files
|
|
|
|
The user config file
|
|
should be able to source one of these files with a command like this:
|
|
|
|
@example
|
|
source [find interface/FOOBAR.cfg]
|
|
@end example
|
|
|
|
A preconfigured interface file should exist for every debug adapter
|
|
in use today with OpenOCD.
|
|
That said, perhaps some of these config files
|
|
have only been used by the developer who created it.
|
|
|
|
A separate chapter gives information about how to set these up.
|
|
@xref{Debug Adapter Configuration}.
|
|
Read the OpenOCD source code (and Developer's Guide)
|
|
if you have a new kind of hardware interface
|
|
and need to provide a driver for it.
|
|
|
|
@deffn {Command} {find} 'filename'
|
|
Prints full path to @var{filename} according to OpenOCD search rules.
|
|
@end deffn
|
|
|
|
@deffn {Command} {ocd_find} 'filename'
|
|
Prints full path to @var{filename} according to OpenOCD search rules. This
|
|
is a low level function used by the @command{find}. Usually you want
|
|
to use @command{find}, instead.
|
|
@end deffn
|
|
|
|
@section Board Config Files
|
|
@cindex config file, board
|
|
@cindex board config file
|
|
|
|
The user config file
|
|
should be able to source one of these files with a command like this:
|
|
|
|
@example
|
|
source [find board/FOOBAR.cfg]
|
|
@end example
|
|
|
|
The point of a board config file is to package everything
|
|
about a given board that user config files need to know.
|
|
In summary the board files should contain (if present)
|
|
|
|
@enumerate
|
|
@item One or more @command{source [find target/...cfg]} statements
|
|
@item NOR flash configuration (@pxref{norconfiguration,,NOR Configuration})
|
|
@item NAND flash configuration (@pxref{nandconfiguration,,NAND Configuration})
|
|
@item Target @code{reset} handlers for SDRAM and I/O configuration
|
|
@item JTAG adapter reset configuration (@pxref{Reset Configuration})
|
|
@item All things that are not ``inside a chip''
|
|
@end enumerate
|
|
|
|
Generic things inside target chips belong in target config files,
|
|
not board config files. So for example a @code{reset-init} event
|
|
handler should know board-specific oscillator and PLL parameters,
|
|
which it passes to target-specific utility code.
|
|
|
|
The most complex task of a board config file is creating such a
|
|
@code{reset-init} event handler.
|
|
Define those handlers last, after you verify the rest of the board
|
|
configuration works.
|
|
|
|
@subsection Communication Between Config files
|
|
|
|
In addition to target-specific utility code, another way that
|
|
board and target config files communicate is by following a
|
|
convention on how to use certain variables.
|
|
|
|
The full Tcl/Tk language supports ``namespaces'', but Jim-Tcl does not.
|
|
Thus the rule we follow in OpenOCD is this: Variables that begin with
|
|
a leading underscore are temporary in nature, and can be modified and
|
|
used at will within a target configuration file.
|
|
|
|
Complex board config files can do the things like this,
|
|
for a board with three chips:
|
|
|
|
@example
|
|
# Chip #1: PXA270 for network side, big endian
|
|
set CHIPNAME network
|
|
set ENDIAN big
|
|
source [find target/pxa270.cfg]
|
|
# on return: _TARGETNAME = network.cpu
|
|
# other commands can refer to the "network.cpu" target.
|
|
$_TARGETNAME configure .... events for this CPU..
|
|
|
|
# Chip #2: PXA270 for video side, little endian
|
|
set CHIPNAME video
|
|
set ENDIAN little
|
|
source [find target/pxa270.cfg]
|
|
# on return: _TARGETNAME = video.cpu
|
|
# other commands can refer to the "video.cpu" target.
|
|
$_TARGETNAME configure .... events for this CPU..
|
|
|
|
# Chip #3: Xilinx FPGA for glue logic
|
|
set CHIPNAME xilinx
|
|
unset ENDIAN
|
|
source [find target/spartan3.cfg]
|
|
@end example
|
|
|
|
That example is oversimplified because it doesn't show any flash memory,
|
|
or the @code{reset-init} event handlers to initialize external DRAM
|
|
or (assuming it needs it) load a configuration into the FPGA.
|
|
Such features are usually needed for low-level work with many boards,
|
|
where ``low level'' implies that the board initialization software may
|
|
not be working. (That's a common reason to need JTAG tools. Another
|
|
is to enable working with microcontroller-based systems, which often
|
|
have no debugging support except a JTAG connector.)
|
|
|
|
Target config files may also export utility functions to board and user
|
|
config files. Such functions should use name prefixes, to help avoid
|
|
naming collisions.
|
|
|
|
Board files could also accept input variables from user config files.
|
|
For example, there might be a @code{J4_JUMPER} setting used to identify
|
|
what kind of flash memory a development board is using, or how to set
|
|
up other clocks and peripherals.
|
|
|
|
@subsection Variable Naming Convention
|
|
@cindex variable names
|
|
|
|
Most boards have only one instance of a chip.
|
|
However, it should be easy to create a board with more than
|
|
one such chip (as shown above).
|
|
Accordingly, we encourage these conventions for naming
|
|
variables associated with different @file{target.cfg} files,
|
|
to promote consistency and
|
|
so that board files can override target defaults.
|
|
|
|
Inputs to target config files include:
|
|
|
|
@itemize @bullet
|
|
@item @code{CHIPNAME} ...
|
|
This gives a name to the overall chip, and is used as part of
|
|
tap identifier dotted names.
|
|
While the default is normally provided by the chip manufacturer,
|
|
board files may need to distinguish between instances of a chip.
|
|
@item @code{ENDIAN} ...
|
|
By default @option{little} - although chips may hard-wire @option{big}.
|
|
Chips that can't change endianness don't need to use this variable.
|
|
@item @code{CPUTAPID} ...
|
|
When OpenOCD examines the JTAG chain, it can be told verify the
|
|
chips against the JTAG IDCODE register.
|
|
The target file will hold one or more defaults, but sometimes the
|
|
chip in a board will use a different ID (perhaps a newer revision).
|
|
@end itemize
|
|
|
|
Outputs from target config files include:
|
|
|
|
@itemize @bullet
|
|
@item @code{_TARGETNAME} ...
|
|
By convention, this variable is created by the target configuration
|
|
script. The board configuration file may make use of this variable to
|
|
configure things like a ``reset init'' script, or other things
|
|
specific to that board and that target.
|
|
If the chip has 2 targets, the names are @code{_TARGETNAME0},
|
|
@code{_TARGETNAME1}, ... etc.
|
|
@end itemize
|
|
|
|
@subsection The reset-init Event Handler
|
|
@cindex event, reset-init
|
|
@cindex reset-init handler
|
|
|
|
Board config files run in the OpenOCD configuration stage;
|
|
they can't use TAPs or targets, since they haven't been
|
|
fully set up yet.
|
|
This means you can't write memory or access chip registers;
|
|
you can't even verify that a flash chip is present.
|
|
That's done later in event handlers, of which the target @code{reset-init}
|
|
handler is one of the most important.
|
|
|
|
Except on microcontrollers, the basic job of @code{reset-init} event
|
|
handlers is setting up flash and DRAM, as normally handled by boot loaders.
|
|
Microcontrollers rarely use boot loaders; they run right out of their
|
|
on-chip flash and SRAM memory. But they may want to use one of these
|
|
handlers too, if just for developer convenience.
|
|
|
|
@quotation Note
|
|
Because this is so very board-specific, and chip-specific, no examples
|
|
are included here.
|
|
Instead, look at the board config files distributed with OpenOCD.
|
|
If you have a boot loader, its source code will help; so will
|
|
configuration files for other JTAG tools
|
|
(@pxref{translatingconfigurationfiles,,Translating Configuration Files}).
|
|
@end quotation
|
|
|
|
Some of this code could probably be shared between different boards.
|
|
For example, setting up a DRAM controller often doesn't differ by
|
|
much except the bus width (16 bits or 32?) and memory timings, so a
|
|
reusable TCL procedure loaded by the @file{target.cfg} file might take
|
|
those as parameters.
|
|
Similarly with oscillator, PLL, and clock setup;
|
|
and disabling the watchdog.
|
|
Structure the code cleanly, and provide comments to help
|
|
the next developer doing such work.
|
|
(@emph{You might be that next person} trying to reuse init code!)
|
|
|
|
The last thing normally done in a @code{reset-init} handler is probing
|
|
whatever flash memory was configured. For most chips that needs to be
|
|
done while the associated target is halted, either because JTAG memory
|
|
access uses the CPU or to prevent conflicting CPU access.
|
|
|
|
@subsection JTAG Clock Rate
|
|
|
|
Before your @code{reset-init} handler has set up
|
|
the PLLs and clocking, you may need to run with
|
|
a low JTAG clock rate.
|
|
@xref{jtagspeed,,JTAG Speed}.
|
|
Then you'd increase that rate after your handler has
|
|
made it possible to use the faster JTAG clock.
|
|
When the initial low speed is board-specific, for example
|
|
because it depends on a board-specific oscillator speed, then
|
|
you should probably set it up in the board config file;
|
|
if it's target-specific, it belongs in the target config file.
|
|
|
|
For most ARM-based processors the fastest JTAG clock@footnote{A FAQ
|
|
@uref{http://www.arm.com/support/faqdev/4170.html} gives details.}
|
|
is one sixth of the CPU clock; or one eighth for ARM11 cores.
|
|
Consult chip documentation to determine the peak JTAG clock rate,
|
|
which might be less than that.
|
|
|
|
@quotation Warning
|
|
On most ARMs, JTAG clock detection is coupled to the core clock, so
|
|
software using a @option{wait for interrupt} operation blocks JTAG access.
|
|
Adaptive clocking provides a partial workaround, but a more complete
|
|
solution just avoids using that instruction with JTAG debuggers.
|
|
@end quotation
|
|
|
|
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 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.
|
|
|
|
@anchor{theinitboardprocedure}
|
|
@subsection The init_board procedure
|
|
@cindex init_board procedure
|
|
|
|
The concept of @code{init_board} procedure is very similar to @code{init_targets}
|
|
(@xref{theinittargetsprocedure,,The init_targets procedure}.) - it's a replacement of ``linear''
|
|
configuration scripts. This procedure is meant to be executed when OpenOCD enters run stage
|
|
(@xref{enteringtherunstage,,Entering the Run Stage},) after @code{init_targets}. The idea to have
|
|
separate @code{init_targets} and @code{init_board} procedures is to allow the first one to configure
|
|
everything target specific (internal flash, internal RAM, etc.) and the second one to configure
|
|
everything board specific (reset signals, chip frequency, reset-init event handler, external memory, etc.).
|
|
Additionally ``linear'' board config file will most likely fail when target config file uses
|
|
@code{init_targets} scheme (``linear'' script is executed before @code{init} and @code{init_targets} - after),
|
|
so separating these two configuration stages is very convenient, as the easiest way to overcome this
|
|
problem is to convert board config file to use @code{init_board} procedure. Board config scripts don't
|
|
need to override @code{init_targets} defined in target config files when they only need to add some specifics.
|
|
|
|
Just as @code{init_targets}, the @code{init_board} procedure can be overridden by ``next level'' script (which sources
|
|
the original), allowing greater code reuse.
|
|
|
|
@example
|
|
### board_file.cfg ###
|
|
|
|
# source target file that does most of the config in init_targets
|
|
source [find target/target.cfg]
|
|
|
|
proc enable_fast_clock @{@} @{
|
|
# enables fast on-board clock source
|
|
# configures the chip to use it
|
|
@}
|
|
|
|
# initialize only board specifics - reset, clock, adapter frequency
|
|
proc init_board @{@} @{
|
|
reset_config trst_and_srst trst_pulls_srst
|
|
|
|
$_TARGETNAME configure -event reset-start @{
|
|
adapter speed 100
|
|
@}
|
|
|
|
$_TARGETNAME configure -event reset-init @{
|
|
enable_fast_clock
|
|
adapter speed 10000
|
|
@}
|
|
@}
|
|
@end example
|
|
|
|
@section Target Config Files
|
|
@cindex config file, target
|
|
@cindex target config file
|
|
|
|
Board config files communicate with target config files using
|
|
naming conventions as described above, and may source one or
|
|
more target config files like this:
|
|
|
|
@example
|
|
source [find target/FOOBAR.cfg]
|
|
@end example
|
|
|
|
The point of a target config file is to package everything
|
|
about a given chip that board config files need to know.
|
|
In summary the target files should contain
|
|
|
|
@enumerate
|
|
@item Set defaults
|
|
@item Add TAPs to the scan chain
|
|
@item Add CPU targets (includes GDB support)
|
|
@item CPU/Chip/CPU-Core specific features
|
|
@item On-Chip flash
|
|
@end enumerate
|
|
|
|
As a rule of thumb, a target file sets up only one chip.
|
|
For a microcontroller, that will often include a single TAP,
|
|
which is a CPU needing a GDB target, and its on-chip flash.
|
|
|
|
More complex chips may include multiple TAPs, and the target
|
|
config file may need to define them all before OpenOCD
|
|
can talk to the chip.
|
|
For example, some phone chips have JTAG scan chains that include
|
|
an ARM core for operating system use, a DSP,
|
|
another ARM core embedded in an image processing engine,
|
|
and other processing engines.
|
|
|
|
@subsection Default Value Boiler Plate Code
|
|
|
|
All target configuration files should start with code like this,
|
|
letting board config files express environment-specific
|
|
differences in how things should be set up.
|
|
|
|
@example
|
|
# Boards may override chip names, perhaps based on role,
|
|
# but the default should match what the vendor uses
|
|
if @{ [info exists CHIPNAME] @} @{
|
|
set _CHIPNAME $CHIPNAME
|
|
@} else @{
|
|
set _CHIPNAME sam7x256
|
|
@}
|
|
|
|
# ONLY use ENDIAN with targets that can change it.
|
|
if @{ [info exists ENDIAN] @} @{
|
|
set _ENDIAN $ENDIAN
|
|
@} else @{
|
|
set _ENDIAN little
|
|
@}
|
|
|
|
# TAP identifiers may change as chips mature, for example with
|
|
# new revision fields (the "3" here). Pick a good default; you
|
|
# can pass several such identifiers to the "jtag newtap" command.
|
|
if @{ [info exists CPUTAPID ] @} @{
|
|
set _CPUTAPID $CPUTAPID
|
|
@} else @{
|
|
set _CPUTAPID 0x3f0f0f0f
|
|
@}
|
|
@end example
|
|
@c but 0x3f0f0f0f is for an str73x part ...
|
|
|
|
@emph{Remember:} Board config files may include multiple target
|
|
config files, or the same target file multiple times
|
|
(changing at least @code{CHIPNAME}).
|
|
|
|
Likewise, the target configuration file should define
|
|
@code{_TARGETNAME} (or @code{_TARGETNAME0} etc) and
|
|
use it later on when defining debug targets:
|
|
|
|
@example
|
|
set _TARGETNAME $_CHIPNAME.cpu
|
|
target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
|
|
@end example
|
|
|
|
@subsection Adding TAPs to the Scan Chain
|
|
After the ``defaults'' are set up,
|
|
add the TAPs on each chip to the JTAG scan chain.
|
|
@xref{TAP Declaration}, and the naming convention
|
|
for taps.
|
|
|
|
In the simplest case the chip has only one TAP,
|
|
probably for a CPU or FPGA.
|
|
The config file for the Atmel AT91SAM7X256
|
|
looks (in part) like this:
|
|
|
|
@example
|
|
jtag newtap $_CHIPNAME cpu -irlen 4 -expected-id $_CPUTAPID
|
|
@end example
|
|
|
|
A board with two such at91sam7 chips would be able
|
|
to source such a config file twice, with different
|
|
values for @code{CHIPNAME}, so
|
|
it adds a different TAP each time.
|
|
|
|
If there are nonzero @option{-expected-id} values,
|
|
OpenOCD attempts to verify the actual tap id against those values.
|
|
It will issue error messages if there is mismatch, which
|
|
can help to pinpoint problems in OpenOCD configurations.
|
|
|
|
@example
|
|
JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f
|
|
(Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
|
|
ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f
|
|
ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
|
|
ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3
|
|
@end example
|
|
|
|
There are more complex examples too, with chips that have
|
|
multiple TAPs. Ones worth looking at include:
|
|
|
|
@itemize
|
|
@item @file{target/omap3530.cfg} -- with disabled ARM and DSP,
|
|
plus a JRC to enable them
|
|
@item @file{target/str912.cfg} -- with flash, CPU, and boundary scan
|
|
@item @file{target/ti_dm355.cfg} -- with ETM, ARM, and JRC (this JRC
|
|
is not currently used)
|
|
@end itemize
|
|
|
|
@subsection Add CPU targets
|
|
|
|
After adding a TAP for a CPU, you should set it up so that
|
|
GDB and other commands can use it.
|
|
@xref{CPU Configuration}.
|
|
For the at91sam7 example above, the command can look like this;
|
|
note that @code{$_ENDIAN} is not needed, since OpenOCD defaults
|
|
to little endian, and this chip doesn't support changing that.
|
|
|
|
@example
|
|
set _TARGETNAME $_CHIPNAME.cpu
|
|
target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
|
|
@end example
|
|
|
|
Work areas are small RAM areas associated with CPU targets.
|
|
They are used by OpenOCD to speed up downloads,
|
|
and to download small snippets of code to program flash chips.
|
|
If the chip includes a form of ``on-chip-ram'' - and many do - define
|
|
a work area if you can.
|
|
Again using the at91sam7 as an example, this can look like:
|
|
|
|
@example
|
|
$_TARGETNAME configure -work-area-phys 0x00200000 \
|
|
-work-area-size 0x4000 -work-area-backup 0
|
|
@end example
|
|
|
|
@subsection Define CPU targets working in SMP
|
|
@cindex SMP
|
|
After setting targets, you can define a list of targets working in SMP.
|
|
|
|
@example
|
|
set _TARGETNAME_1 $_CHIPNAME.cpu1
|
|
set _TARGETNAME_2 $_CHIPNAME.cpu2
|
|
target create $_TARGETNAME_1 cortex_a -chain-position $_CHIPNAME.dap \
|
|
-coreid 0 -dbgbase $_DAP_DBG1
|
|
target create $_TARGETNAME_2 cortex_a -chain-position $_CHIPNAME.dap \
|
|
-coreid 1 -dbgbase $_DAP_DBG2
|
|
#define 2 targets working in smp.
|
|
target smp $_CHIPNAME.cpu2 $_CHIPNAME.cpu1
|
|
@end example
|
|
In the above example on cortex_a, 2 cpus are working in SMP.
|
|
In SMP only one GDB instance is created and :
|
|
@itemize @bullet
|
|
@item a set of hardware breakpoint sets the same breakpoint on all targets in the list.
|
|
@item halt command triggers the halt of all targets in the list.
|
|
@item resume command triggers the write context and the restart of all targets in the list.
|
|
@item following a breakpoint: the target stopped by the breakpoint is displayed to the GDB session.
|
|
@item dedicated GDB serial protocol packets are implemented for switching/retrieving the target
|
|
displayed by the GDB session @pxref{usingopenocdsmpwithgdb,,Using OpenOCD SMP with GDB}.
|
|
@end itemize
|
|
|
|
The SMP behaviour can be disabled/enabled dynamically. On cortex_a following
|
|
command have been implemented.
|
|
@itemize @bullet
|
|
@item cortex_a smp on : enable SMP mode, behaviour is as described above.
|
|
@item cortex_a smp off : disable SMP mode, the current target is the one
|
|
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
|
|
>cortex_a smp_gdb
|
|
gdb coreid 0 -> -1
|
|
#0 : coreid 0 is displayed to GDB ,
|
|
#-> -1 : next resume triggers a real resume
|
|
> cortex_a smp_gdb 1
|
|
gdb coreid 0 -> 1
|
|
#0 :coreid 0 is displayed to GDB ,
|
|
#->1 : next resume displays coreid 1 to GDB
|
|
> resume
|
|
> cortex_a smp_gdb
|
|
gdb coreid 1 -> 1
|
|
#1 :coreid 1 is displayed to GDB ,
|
|
#->1 : next resume displays coreid 1 to GDB
|
|
> cortex_a smp_gdb -1
|
|
gdb coreid 1 -> -1
|
|
#1 :coreid 1 is displayed to GDB,
|
|
#->-1 : next resume triggers a real resume
|
|
@end example
|
|
|
|
|
|
@subsection Chip Reset Setup
|
|
|
|
As a rule, you should put the @command{reset_config} command
|
|
into the board file. Most things you think you know about a
|
|
chip can be tweaked by the board.
|
|
|
|
Some chips have specific ways the TRST and SRST signals are
|
|
managed. In the unusual case that these are @emph{chip specific}
|
|
and can never be changed by board wiring, they could go here.
|
|
For example, some chips can't support JTAG debugging without
|
|
both signals.
|
|
|
|
Provide a @code{reset-assert} event handler if you can.
|
|
Such a handler uses JTAG operations to reset the target,
|
|
letting this target config be used in systems which don't
|
|
provide the optional SRST signal, or on systems where you
|
|
don't want to reset all targets at once.
|
|
Such a handler might write to chip registers to force a reset,
|
|
use a JRC to do that (preferable -- the target may be wedged!),
|
|
or force a watchdog timer to trigger.
|
|
(For Cortex-M targets, this is not necessary. The target
|
|
driver knows how to use trigger an NVIC reset when SRST is
|
|
not available.)
|
|
|
|
Some chips need special attention during reset handling if
|
|
they're going to be used with JTAG.
|
|
An example might be needing to send some commands right
|
|
after the target's TAP has been reset, providing a
|
|
@code{reset-deassert-post} event handler that writes a chip
|
|
register to report that JTAG debugging is being done.
|
|
Another would be reconfiguring the watchdog so that it stops
|
|
counting while the core is halted in the debugger.
|
|
|
|
JTAG clocking constraints often change during reset, and in
|
|
some cases target config files (rather than board config files)
|
|
are the right places to handle some of those issues.
|
|
For example, immediately after reset most chips run using a
|
|
slower clock than they will use later.
|
|
That means that after reset (and potentially, as OpenOCD
|
|
first starts up) they must use a slower JTAG clock rate
|
|
than they will use later.
|
|
@xref{jtagspeed,,JTAG Speed}.
|
|
|
|
@quotation Important
|
|
When you are debugging code that runs right after chip
|
|
reset, getting these issues right is critical.
|
|
In particular, if you see intermittent failures when
|
|
OpenOCD verifies the scan chain after reset,
|
|
look at how you are setting up JTAG clocking.
|
|
@end quotation
|
|
|
|
@anchor{theinittargetsprocedure}
|
|
@subsection The init_targets procedure
|
|
@cindex init_targets procedure
|
|
|
|
Target config files can either be ``linear'' (script executed line-by-line when parsed in
|
|
configuration stage, @xref{configurationstage,,Configuration Stage},) or they can contain a special
|
|
procedure called @code{init_targets}, which will be executed when entering run stage
|
|
(after parsing all config files or after @code{init} command, @xref{enteringtherunstage,,Entering the Run Stage}.)
|
|
Such procedure can be overridden by ``next level'' script (which sources the original).
|
|
This concept facilitates code reuse when basic target config files provide generic configuration
|
|
procedures and @code{init_targets} procedure, which can then be sourced and enhanced or changed in
|
|
a ``more specific'' target config file. This is not possible with ``linear'' config scripts,
|
|
because sourcing them executes every initialization commands they provide.
|
|
|
|
@example
|
|
### generic_file.cfg ###
|
|
|
|
proc setup_my_chip @{chip_name flash_size ram_size@} @{
|
|
# basic initialization procedure ...
|
|
@}
|
|
|
|
proc init_targets @{@} @{
|
|
# initializes generic chip with 4kB of flash and 1kB of RAM
|
|
setup_my_chip MY_GENERIC_CHIP 4096 1024
|
|
@}
|
|
|
|
### specific_file.cfg ###
|
|
|
|
source [find target/generic_file.cfg]
|
|
|
|
proc init_targets @{@} @{
|
|
# initializes specific chip with 128kB of flash and 64kB of RAM
|
|
setup_my_chip MY_CHIP_WITH_128K_FLASH_64KB_RAM 131072 65536
|
|
@}
|
|
@end example
|
|
|
|
The easiest way to convert ``linear'' config files to @code{init_targets} version is to
|
|
enclose every line of ``code'' (i.e. not @code{source} commands, procedures, etc.) in this procedure.
|
|
|
|
For an example of this scheme see LPC2000 target config files.
|
|
|
|
The @code{init_boards} procedure is a similar concept concerning board config files
|
|
(@xref{theinitboardprocedure,,The init_board procedure}.)
|
|
|
|
@subsection The init_target_events procedure
|
|
@cindex init_target_events procedure
|
|
|
|
A special procedure called @code{init_target_events} is run just after
|
|
@code{init_targets} (@xref{theinittargetsprocedure,,The init_targets
|
|
procedure}.) and before @code{init_board}
|
|
(@xref{theinitboardprocedure,,The init_board procedure}.) It is used
|
|
to set up default target events for the targets that do not have those
|
|
events already assigned.
|
|
|
|
@subsection ARM Core Specific Hacks
|
|
|
|
If the chip has a DCC, enable it. If the chip is an ARM9 with some
|
|
special high speed download features - enable it.
|
|
|
|
If present, the MMU, the MPU and the CACHE should be disabled.
|
|
|
|
Some ARM cores are equipped with trace support, which permits
|
|
examination of the instruction and data bus activity. Trace
|
|
activity is controlled through an ``Embedded Trace Module'' (ETM)
|
|
on one of the core's scan chains. The ETM emits voluminous data
|
|
through a ``trace port''. (@xref{armhardwaretracing,,ARM Hardware Tracing}.)
|
|
If you are using an external trace port,
|
|
configure it in your board config file.
|
|
If you are using an on-chip ``Embedded Trace Buffer'' (ETB),
|
|
configure it in your target config file.
|
|
|
|
@example
|
|
etm config $_TARGETNAME 16 normal full etb
|
|
etb config $_TARGETNAME $_CHIPNAME.etb
|
|
@end example
|
|
|
|
@subsection Internal Flash Configuration
|
|
|
|
This applies @b{ONLY TO MICROCONTROLLERS} that have flash built in.
|
|
|
|
@b{Never ever} in the ``target configuration file'' define any type of
|
|
flash that is external to the chip. (For example a BOOT flash on
|
|
Chip Select 0.) Such flash information goes in a board file - not
|
|
the TARGET (chip) file.
|
|
|
|
Examples:
|
|
@itemize @bullet
|
|
@item at91sam7x256 - has 256K flash YES enable it.
|
|
@item str912 - has flash internal YES enable it.
|
|
@item imx27 - uses boot flash on CS0 - it goes in the board file.
|
|
@item pxa270 - again - CS0 flash - it goes in the board file.
|
|
@end itemize
|
|
|
|
@anchor{translatingconfigurationfiles}
|
|
@section Translating Configuration Files
|
|
@cindex translation
|
|
If you have a configuration file for another hardware debugger
|
|
or toolset (Abatron, BDI2000, BDI3000, CCS,
|
|
Lauterbach, SEGGER, Macraigor, etc.), translating
|
|
it into OpenOCD syntax is often quite straightforward. The most tricky
|
|
part of creating a configuration script is oftentimes the reset init
|
|
sequence where e.g. PLLs, DRAM and the like is set up.
|
|
|
|
One trick that you can use when translating is to write small
|
|
Tcl procedures to translate the syntax into OpenOCD syntax. This
|
|
can avoid manual translation errors and make it easier to
|
|
convert other scripts later on.
|
|
|
|
Example of transforming quirky arguments to a simple search and
|
|
replace job:
|
|
|
|
@example
|
|
# Lauterbach syntax(?)
|
|
#
|
|
# Data.Set c15:0x042f %long 0x40000015
|
|
#
|
|
# OpenOCD syntax when using procedure below.
|
|
#
|
|
# setc15 0x01 0x00050078
|
|
|
|
proc setc15 @{regs value@} @{
|
|
global TARGETNAME
|
|
|
|
echo [format "set p15 0x%04x, 0x%08x" $regs $value]
|
|
|
|
arm mcr 15 [expr @{($regs >> 12) & 0x7@}] \
|
|
[expr @{($regs >> 0) & 0xf@}] [expr @{($regs >> 4) & 0xf@}] \
|
|
[expr @{($regs >> 8) & 0x7@}] $value
|
|
@}
|
|
@end example
|
|
|
|
|
|
|
|
@node Server Configuration
|
|
@chapter Server Configuration
|
|
@cindex initialization
|
|
The commands here are commonly found in the openocd.cfg file and are
|
|
used to specify what TCP/IP ports are used, and how GDB should be
|
|
supported.
|
|
|
|
@anchor{configurationstage}
|
|
@section Configuration Stage
|
|
@cindex configuration stage
|
|
@cindex config command
|
|
|
|
When the OpenOCD server process starts up, it enters a
|
|
@emph{configuration stage} which is the only time that
|
|
certain commands, @emph{configuration commands}, may be issued.
|
|
Normally, configuration commands are only available
|
|
inside startup scripts.
|
|
|
|
In this manual, the definition of a configuration command is
|
|
presented as a @emph{Config Command}, not as a @emph{Command}
|
|
which may be issued interactively.
|
|
The runtime @command{help} command also highlights configuration
|
|
commands, and those which may be issued at any time.
|
|
|
|
Those configuration commands include declaration of TAPs,
|
|
flash banks,
|
|
the interface used for JTAG communication,
|
|
and other basic setup.
|
|
The server must leave the configuration stage before it
|
|
may access or activate TAPs.
|
|
After it leaves this stage, configuration commands may no
|
|
longer be issued.
|
|
|
|
@deffn {Command} {command mode} [command_name]
|
|
Returns the command modes allowed by a command: 'any', 'config', or
|
|
'exec'. If no command is specified, returns the current command
|
|
mode. Returns 'unknown' if an unknown command is given. Command can be
|
|
multiple tokens. (command valid any time)
|
|
|
|
In this document, the modes are described as stages, 'config' and
|
|
'exec' mode correspond configuration stage and run stage. 'any' means
|
|
the command can be executed in either
|
|
stages. @xref{configurationstage,,Configuration Stage}, and
|
|
@xref{enteringtherunstage,,Entering the Run Stage}.
|
|
@end deffn
|
|
|
|
@anchor{enteringtherunstage}
|
|
@section Entering the Run Stage
|
|
|
|
The first thing OpenOCD does after leaving the configuration
|
|
stage is to verify that it can talk to the scan chain
|
|
(list of TAPs) which has been configured.
|
|
It will warn if it doesn't find TAPs it expects to find,
|
|
or finds TAPs that aren't supposed to be there.
|
|
You should see no errors at this point.
|
|
If you see errors, resolve them by correcting the
|
|
commands you used to configure the server.
|
|
Common errors include using an initial JTAG speed that's too
|
|
fast, and not providing the right IDCODE values for the TAPs
|
|
on the scan chain.
|
|
|
|
Once OpenOCD has entered the run stage, a number of commands
|
|
become available.
|
|
A number of these relate to the debug targets you may have declared.
|
|
For example, the @command{mww} command will not be available until
|
|
a target has been successfully instantiated.
|
|
If you want to use those commands, you may need to force
|
|
entry to the run stage.
|
|
|
|
@deffn {Config Command} {init}
|
|
This command terminates the configuration stage and
|
|
enters the run stage. This helps when you need to have
|
|
the startup scripts manage tasks such as resetting the target,
|
|
programming flash, etc. To reset the CPU upon startup, add "init" and
|
|
"reset" at the end of the config script or at the end of the OpenOCD
|
|
command line using the @option{-c} command line switch.
|
|
|
|
If this command does not appear in any startup/configuration file
|
|
OpenOCD executes the command for you after processing all
|
|
configuration files and/or command line options.
|
|
|
|
@b{NOTE:} This command normally occurs near the end of your
|
|
openocd.cfg file to force OpenOCD to ``initialize'' and make the
|
|
targets ready. For example: If your openocd.cfg file needs to
|
|
read/write memory on your target, @command{init} must occur before
|
|
the memory read/write commands. This includes @command{nand probe}.
|
|
|
|
@command{init} calls the following internal OpenOCD commands to initialize
|
|
corresponding subsystems:
|
|
@deffn {Config Command} {target init}
|
|
@deffnx {Command} {transport init}
|
|
@deffnx {Command} {dap init}
|
|
@deffnx {Config Command} {flash init}
|
|
@deffnx {Config Command} {nand init}
|
|
@deffnx {Config Command} {pld init}
|
|
@deffnx {Command} {tpiu init}
|
|
@end deffn
|
|
|
|
At last, @command{init} executes all the commands that are specified in
|
|
the TCL list @var{post_init_commands}. The commands are executed in the
|
|
same order they occupy in the list. If one of the commands fails, then
|
|
the error is propagated and OpenOCD fails too.
|
|
@example
|
|
lappend post_init_commands @{echo "OpenOCD successfully initialized."@}
|
|
lappend post_init_commands @{echo "Have fun with OpenOCD !"@}
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {noinit}
|
|
Prevent OpenOCD from implicit @command{init} call at the end of startup.
|
|
Allows issuing configuration commands over telnet or Tcl connection.
|
|
When you are done with configuration use @command{init} to enter
|
|
the run stage.
|
|
@end deffn
|
|
|
|
@deffn {Overridable Procedure} {jtag_init}
|
|
This is invoked at server startup to verify that it can talk
|
|
to the scan chain (list of TAPs) which has been configured.
|
|
|
|
The default implementation first tries @command{jtag arp_init},
|
|
which uses only a lightweight JTAG reset before examining the
|
|
scan chain.
|
|
If that fails, it tries again, using a harder reset
|
|
from the overridable procedure @command{init_reset}.
|
|
|
|
Implementations must have verified the JTAG scan chain before
|
|
they return.
|
|
This is done by calling @command{jtag arp_init}
|
|
(or @command{jtag arp_init-reset}).
|
|
@end deffn
|
|
|
|
@anchor{tcpipports}
|
|
@section TCP/IP Ports
|
|
@cindex TCP port
|
|
@cindex server
|
|
@cindex port
|
|
@cindex security
|
|
The OpenOCD server accepts remote commands in several syntaxes.
|
|
Each syntax uses a different TCP/IP port, which you may specify
|
|
only during configuration (before those ports are opened).
|
|
|
|
For reasons including security, you may wish to prevent remote
|
|
access using one or more of these ports.
|
|
In such cases, just specify the relevant port number as "disabled".
|
|
|
|
You can request the operating system to select one of the available
|
|
ports for the server by specifying the relevant port number as "0".
|
|
|
|
@anchor{gdb port}
|
|
@deffn {Config Command} {gdb port} [number]
|
|
@cindex GDB server
|
|
Normally gdb listens to a TCP/IP port, but GDB can also
|
|
communicate via pipes(stdin/out or named pipes). The name
|
|
"gdb port" stuck because it covers probably more than 90% of
|
|
the normal use cases.
|
|
|
|
No arguments reports GDB port. "pipe" means listen to stdin
|
|
output to stdout, an integer is base port number, "disabled"
|
|
disables the gdb server.
|
|
|
|
When using "pipe", also use log_output to redirect the log
|
|
output to a file so as not to flood the stdin/out pipes.
|
|
|
|
Any other string is interpreted as named pipe to listen to.
|
|
Output pipe is the same name as input pipe, but with 'o' appended,
|
|
e.g. /var/gdb, /var/gdbo.
|
|
|
|
The GDB port for the first target will be the base port, the
|
|
second target will listen on port + 1, and so on.
|
|
When not specified during the configuration stage,
|
|
the port @var{number} defaults to 3333.
|
|
When @var{number} is not a numeric value, incrementing it to compute
|
|
the next port number does not work. In this case, specify the proper
|
|
@var{number} for each target by using the option @code{-gdb-port} of the
|
|
commands @command{target create} or @command{$target_name configure}.
|
|
@xref{gdbportoverride,,option -gdb-port}.
|
|
|
|
Note: when using "gdb port pipe", increasing the default remote timeout in
|
|
gdb (with 'set remotetimeout') is recommended. An insufficient timeout may
|
|
cause initialization to fail with "Unknown remote qXfer reply: OK".
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {tcl port} [number]
|
|
Specify or query the port used for a simplified RPC
|
|
connection that can be used by clients to issue TCL commands and get the
|
|
output from the Tcl engine.
|
|
Intended as a machine interface.
|
|
When not specified during the configuration stage,
|
|
the port @var{number} defaults to 6666.
|
|
When specified as "disabled", this service is not activated.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {telnet port} [number]
|
|
Specify or query the
|
|
port on which to listen for incoming telnet connections.
|
|
This port is intended for interaction with one human through TCL commands.
|
|
When not specified during the configuration stage,
|
|
the port @var{number} defaults to 4444.
|
|
When specified as "disabled", this service is not activated.
|
|
@end deffn
|
|
|
|
@anchor{gdbconfiguration}
|
|
@section GDB Configuration
|
|
@cindex GDB
|
|
@cindex GDB configuration
|
|
You can reconfigure some GDB behaviors if needed.
|
|
The ones listed here are static and global.
|
|
@xref{targetconfiguration,,Target Configuration}, about configuring individual targets.
|
|
@xref{targetevents,,Target Events}, about configuring target-specific event handling.
|
|
|
|
@anchor{gdbbreakpointoverride}
|
|
@deffn {Command} {gdb breakpoint_override} [@option{hard}|@option{soft}|@option{disable}]
|
|
Force breakpoint type for gdb @command{break} commands.
|
|
This option supports GDB GUIs which don't
|
|
distinguish hard versus soft breakpoints, if the default OpenOCD and
|
|
GDB behaviour is not sufficient. GDB normally uses hardware
|
|
breakpoints if the memory map has been set up for flash regions.
|
|
@end deffn
|
|
|
|
@anchor{gdbflashprogram}
|
|
@deffn {Config Command} {gdb flash_program} (@option{enable}|@option{disable})
|
|
Set to @option{enable} to cause OpenOCD to program the flash memory when a
|
|
vFlash packet is received.
|
|
The default behaviour is @option{enable}.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {gdb memory_map} (@option{enable}|@option{disable})
|
|
Set to @option{enable} to cause OpenOCD to send the memory configuration to GDB when
|
|
requested. GDB will then know when to set hardware breakpoints, and program flash
|
|
using the GDB load command. @command{gdb flash_program enable} must also be enabled
|
|
for flash programming to work.
|
|
Default behaviour is @option{enable}.
|
|
@xref{gdbflashprogram,,gdb flash_program}.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {gdb report_data_abort} (@option{enable}|@option{disable})
|
|
Specifies whether data aborts cause an error to be reported
|
|
by GDB memory read packets.
|
|
The default behaviour is @option{disable};
|
|
use @option{enable} see these errors reported.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {gdb report_register_access_error} (@option{enable}|@option{disable})
|
|
Specifies whether register accesses requested by GDB register read/write
|
|
packets report errors or not.
|
|
The default behaviour is @option{disable};
|
|
use @option{enable} see these errors reported.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {gdb target_description} (@option{enable}|@option{disable})
|
|
Set to @option{enable} to cause OpenOCD to send the target descriptions to gdb via qXfer:features:read packet.
|
|
The default behaviour is @option{enable}.
|
|
@end deffn
|
|
|
|
@deffn {Command} {gdb save_tdesc}
|
|
Saves the target description file to the local file system.
|
|
|
|
The file name is @i{target_name}.xml.
|
|
@end deffn
|
|
|
|
@anchor{eventpolling}
|
|
@section Event Polling
|
|
|
|
Hardware debuggers are parts of asynchronous systems,
|
|
where significant events can happen at any time.
|
|
The OpenOCD server needs to detect some of these events,
|
|
so it can report them to through TCL command line
|
|
or to GDB.
|
|
|
|
Examples of such events include:
|
|
|
|
@itemize
|
|
@item One of the targets can stop running ... maybe it triggers
|
|
a code breakpoint or data watchpoint, or halts itself.
|
|
@item Messages may be sent over ``debug message'' channels ... many
|
|
targets support such messages sent over JTAG,
|
|
for receipt by the person debugging or tools.
|
|
@item Loss of power ... some adapters can detect these events.
|
|
@item Resets not issued through JTAG ... such reset sources
|
|
can include button presses or other system hardware, sometimes
|
|
including the target itself (perhaps through a watchdog).
|
|
@item Debug instrumentation sometimes supports event triggering
|
|
such as ``trace buffer full'' (so it can quickly be emptied)
|
|
or other signals (to correlate with code behavior).
|
|
@end itemize
|
|
|
|
None of those events are signaled through standard JTAG signals.
|
|
However, most conventions for JTAG connectors include voltage
|
|
level and system reset (SRST) signal detection.
|
|
Some connectors also include instrumentation signals, which
|
|
can imply events when those signals are inputs.
|
|
|
|
In general, OpenOCD needs to periodically check for those events,
|
|
either by looking at the status of signals on the JTAG connector
|
|
or by sending synchronous ``tell me your status'' JTAG requests
|
|
to the various active targets.
|
|
There is a command to manage and monitor that polling,
|
|
which is normally done in the background.
|
|
|
|
@deffn {Command} {poll} [@option{on}|@option{off}]
|
|
Poll the current target for its current state.
|
|
(Also, @pxref{targetcurstate,,target curstate}.)
|
|
If that target is in debug mode, architecture
|
|
specific information about the current state is printed.
|
|
An optional parameter
|
|
allows background polling to be enabled and disabled.
|
|
|
|
You could use this from the TCL command shell, or
|
|
from GDB using @command{monitor poll} command.
|
|
Leave background polling enabled while you're using GDB.
|
|
@example
|
|
> poll
|
|
background polling: on
|
|
target state: halted
|
|
target halted in ARM state due to debug-request, \
|
|
current mode: Supervisor
|
|
cpsr: 0x800000d3 pc: 0x11081bfc
|
|
MMU: disabled, D-Cache: disabled, I-Cache: enabled
|
|
>
|
|
@end example
|
|
@end deffn
|
|
|
|
@node Debug Adapter Configuration
|
|
@chapter Debug Adapter Configuration
|
|
@cindex config file, interface
|
|
@cindex interface config file
|
|
|
|
Correctly installing OpenOCD includes making your operating system give
|
|
OpenOCD access to debug adapters. Once that has been done, Tcl commands
|
|
are used to select which one is used, and to configure how it is used.
|
|
|
|
@quotation Note
|
|
Because OpenOCD started out with a focus purely on JTAG, you may find
|
|
places where it wrongly presumes JTAG is the only transport protocol
|
|
in use. Be aware that recent versions of OpenOCD are removing that
|
|
limitation. JTAG remains more functional than most other transports.
|
|
Other transports do not support boundary scan operations, or may be
|
|
specific to a given chip vendor. Some might be usable only for
|
|
programming flash memory, instead of also for debugging.
|
|
@end quotation
|
|
|
|
Debug Adapters/Interfaces/Dongles are normally configured
|
|
through commands in an interface configuration
|
|
file which is sourced by your @file{openocd.cfg} file, or
|
|
through a command line @option{-f interface/....cfg} option.
|
|
|
|
@example
|
|
source [find interface/olimex-jtag-tiny.cfg]
|
|
@end example
|
|
|
|
These commands tell
|
|
OpenOCD what type of JTAG adapter you have, and how to talk to it.
|
|
A few cases are so simple that you only need to say what driver to use:
|
|
|
|
@example
|
|
# jlink interface
|
|
adapter driver jlink
|
|
@end example
|
|
|
|
Most adapters need a bit more configuration than that.
|
|
|
|
|
|
@section Adapter Configuration
|
|
|
|
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} {adapter driver} name
|
|
Use the adapter driver @var{name} to connect to the
|
|
target.
|
|
@end deffn
|
|
|
|
@deffn {Command} {adapter list}
|
|
List the debug adapter drivers that have been built into
|
|
the running copy of OpenOCD.
|
|
@end deffn
|
|
@deffn {Config 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
|
|
the hardware can support.
|
|
@end deffn
|
|
|
|
@anchor{adapter gpio}
|
|
@deffn {Config Command} {adapter gpio [ @
|
|
@option{tdo} | @option{tdi} | @option{tms} | @option{tck} | @option{trst} | @
|
|
@option{swdio} | @option{swdio_dir} | @option{swclk} | @option{srst} | @
|
|
@option{led} @
|
|
[ @
|
|
gpio_number | @option{-chip} chip_number | @
|
|
@option{-active-high} | @option{-active-low} | @
|
|
@option{-push-pull} | @option{-open-drain} | @option{-open-source} | @
|
|
@option{-pull-none} | @option{-pull-up} | @option{-pull-down} | @
|
|
@option{-init-inactive} | @option{-init-active} | @option{-init-input} @
|
|
] ]}
|
|
|
|
Define the GPIO mapping that the adapter will use. The following signals can be
|
|
defined:
|
|
|
|
@itemize @minus
|
|
@item @option{tdo}, @option{tdi}, @option{tms}, @option{tck}, @option{trst}:
|
|
JTAG transport signals
|
|
@item @option{swdio}, @option{swclk}: SWD transport signals
|
|
@item @option{swdio_dir}: optional swdio buffer control signal
|
|
@item @option{srst}: system reset signal
|
|
@item @option{led}: optional activity led
|
|
|
|
@end itemize
|
|
|
|
Some adapters require that the GPIO chip number is set in addition to the GPIO
|
|
number. The configuration options enable signals to be defined as active-high or
|
|
active-low. The output drive mode can be set to push-pull, open-drain or
|
|
open-source. Most adapters will have to emulate open-drain or open-source drive
|
|
modes by switching between an input and output. Input and output signals can be
|
|
instructed to use a pull-up or pull-down resistor, assuming it is supported by
|
|
the adaptor driver and hardware. The initial state of outputs may also be set,
|
|
"active" state means 1 for active-high outputs and 0 for active-low outputs.
|
|
Bidirectional signals may also be initialized as an input. If the swdio signal
|
|
is buffered the buffer direction can be controlled with the swdio_dir signal;
|
|
the active state means that the buffer should be set as an output with respect
|
|
to the adapter. The command options are cumulative with later commands able to
|
|
override settings defined by earlier ones. The two commands @command{gpio led 7
|
|
-active-high} and @command{gpio led -chip 1 -active-low} sent sequentially are
|
|
equivalent to issuing the single command @command{gpio led 7 -chip 1
|
|
-active-low}. It is not permissible to set the drive mode or initial state for
|
|
signals which are inputs. The drive mode for the srst and trst signals must be
|
|
set with the @command{adapter reset_config} command. It is not permissible to
|
|
set the initial state of swdio_dir as it is derived from the initial state of
|
|
swdio. The command @command{adapter gpio} prints the current configuration for
|
|
all GPIOs while the command @command{adapter gpio gpio_name} prints the current
|
|
configuration for gpio_name. Not all adapters support this generic GPIO mapping,
|
|
some require their own commands to define the GPIOs used. Adapters that support
|
|
the generic mapping may not support all of the listed options.
|
|
@end deffn
|
|
|
|
@deffn {Command} {adapter name}
|
|
Returns the name of the debug adapter driver being used.
|
|
@end deffn
|
|
|
|
@deffn {Config 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
|
|
|
|
@deffn {Config Command} {adapter serial} serial_string
|
|
Specifies the @var{serial_string} of the adapter to use.
|
|
If this command is not specified, serial strings are not checked.
|
|
Only the following adapter drivers use the serial string from this command:
|
|
arm-jtag-ew, cmsis_dap, esp_usb_jtag, ft232r, ftdi, hla (ti-icdi), jlink, kitprog, opendus,
|
|
openjtag, osbdm, presto, rlink, st-link, usb_blaster (ublast2), usbprog, vsllink, xds110.
|
|
@end deffn
|
|
|
|
@section Interface Drivers
|
|
|
|
Each of the interface drivers listed here must be explicitly
|
|
enabled when OpenOCD is configured, in order to be made
|
|
available at run time.
|
|
|
|
@deffn {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:
|
|
|
|
@deffn {Config Command} {parport port} number
|
|
Specifies either the address of the I/O port (default: 0x378 for LPT1) or
|
|
the number of the @file{/dev/parport} device.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {rtck} [@option{enable}|@option{disable}]
|
|
Displays status of RTCK option.
|
|
Optionally sets that option first.
|
|
@end deffn
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {angie}
|
|
This is the NanoXplore's ANGIE USB-JTAG Adapter.
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {arm-jtag-ew}
|
|
Olimex ARM-JTAG-EW USB adapter
|
|
This has one driver-specific command:
|
|
|
|
@deffn {Command} {armjtagew_info}
|
|
Logs some status
|
|
@end deffn
|
|
@end deffn
|
|
|
|
@deffn {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.
|
|
@c command: at91rm9200_device NAME
|
|
@c chooses among list of bit configs ... only one option
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {cmsis-dap}
|
|
ARM CMSIS-DAP compliant based adapter v1 (USB HID based)
|
|
or v2 (USB bulk).
|
|
|
|
@deffn {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 [@var{vid}, @var{pid}] pairs may be given, e.g.
|
|
@example
|
|
cmsis-dap vid_pid 0xc251 0xf001 0x0d28 0x0204
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {cmsis-dap backend} [@option{auto}|@option{usb_bulk}|@option{hid}]
|
|
Specifies how to communicate with the adapter:
|
|
|
|
@itemize @minus
|
|
@item @option{hid} Use HID generic reports - CMSIS-DAP v1
|
|
@item @option{usb_bulk} Use USB bulk - CMSIS-DAP v2
|
|
@item @option{auto} First try USB bulk CMSIS-DAP v2, if not found try HID CMSIS-DAP v1.
|
|
This is the default if @command{cmsis-dap backend} is not specified.
|
|
@end itemize
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {cmsis-dap usb interface} [number]
|
|
Specifies the @var{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.
|
|
@end deffn
|
|
|
|
@deffn {Command} {cmsis-dap quirk} [@option{enable}|@option{disable}]
|
|
Enables or disables the following workarounds of known CMSIS-DAP adapter
|
|
quirks:
|
|
@itemize @minus
|
|
@item disconnect and re-connect before sending a switch sequence
|
|
@item packets pipelining is suppressed, only one packet at a time is
|
|
submitted to the adapter
|
|
@end itemize
|
|
The quirk workarounds are disabled by default.
|
|
The command without a parameter displays current setting.
|
|
@end deffn
|
|
|
|
@deffn {Command} {cmsis-dap info}
|
|
Display various device information, like hardware version, firmware version, current bus status.
|
|
@end deffn
|
|
|
|
@deffn {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 @url{https://arm-software.github.io/CMSIS_5/DAP/html/group__DAP__Commands__gr.html}
|
|
@end deffn
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {dummy}
|
|
A dummy software-only driver for debugging.
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {ep93xx}
|
|
Cirrus Logic EP93xx based single-board computer bit-banging (in development)
|
|
@end deffn
|
|
|
|
@deffn {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 @command{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
|
|
@command{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:
|
|
|
|
@itemize @minus
|
|
@item Push-pull with one FTDI output as (non-)inverted data line
|
|
@item Open drain with one FTDI output as (non-)inverted output-enable
|
|
@item Tristate with one FTDI output as (non-)inverted data line and another
|
|
FTDI output as (non-)inverted output-enable
|
|
@item Unbuffered, using the FTDI GPIO as a tristate output directly by
|
|
switching data and direction as necessary
|
|
@end itemize
|
|
|
|
These interfaces have several commands, used to configure the driver
|
|
before initializing the JTAG scan chain:
|
|
|
|
@deffn {Config Command} {ftdi vid_pid} [vid pid]+
|
|
The vendor ID and product ID of the adapter. Up to eight
|
|
[@var{vid}, @var{pid}] pairs may be given, e.g.
|
|
@example
|
|
ftdi vid_pid 0x0403 0xcff8 0x15ba 0x0003
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {ftdi device_desc} description
|
|
Provides the USB device description (the @emph{iProduct string})
|
|
of the adapter. If not specified, the device description is ignored
|
|
during device selection.
|
|
@end deffn
|
|
|
|
@deffn {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.
|
|
@end deffn
|
|
|
|
@deffn {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.
|
|
@end deffn
|
|
|
|
@deffn {Command} {ftdi oscan1_mode} on|off
|
|
Enable or disable OScan1 mode. This mode is intended for use with an adapter,
|
|
such as the ARM-JTAG-SWD by Olimex, that sits in between the FTDI chip and the
|
|
target. The cJTAG prococol is composed of two wires: TCKC (clock) and TMSC (data).
|
|
TMSC is a bidirectional signal which is time-multiplexed alternating TDI, TMS and
|
|
TDO. The multiplexing is achieved by a tri-state buffer which puts TMSC in Hi-Z
|
|
when the device is supposed to take the control of the line (TDO phase).
|
|
|
|
The ARM-JTAG-SWD adapter uses standard TRST and TMS signals to control TMSC
|
|
direction. TRST is used by the adapter as selector for the multiplexers which set
|
|
the JTAG probe in 2-wire mode. Whatever signal is used for this purpose, it must
|
|
be defined with the name JTAG_SEL using @command{ftdi layout_signal}. JTAG_SEL is
|
|
set to 0 during OScan1 initialization.
|
|
|
|
Some JTAG probes like the Digilent JTAG-HS2, support cJTAG by using a
|
|
separate pin to control when TMS is driven onto TMSC. You can use such
|
|
probes by defining the signal TMSC_EN using
|
|
@command{ftdi layout_signal TMSC_EN -data <mask>}.
|
|
@end deffn
|
|
|
|
@deffn {Command} {ftdi jscan3_mode} on|off
|
|
Enable or disable JScan3 mode. This mode uses the classic 4-wire JTAG protocol
|
|
in chips whose JTAG port is only compliant with the cJTAG standard (IEEE 1149.7).
|
|
|
|
Since cJTAG needs a 2-wire escape sequence to select the operating mode,
|
|
a cJTAG adapter like ARM-JTAG-SWD by Olimex is still required. This means
|
|
that a cJTAG probe configuration script must be used too.
|
|
@end deffn
|
|
|
|
@deffn {Command} {ftdi layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-input}|@option{-ninput} input_mask] [@option{-oe}|@option{-noe} oe_mask] [@option{-alias}|@option{-nalias} name]
|
|
Creates a signal with the specified @var{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. @var{data_mask} is the bitmask for the
|
|
pin(s) connected to the data input of the output buffer. @option{-ndata} is
|
|
used with inverting data inputs and @option{-data} with non-inverting inputs.
|
|
The @option{-oe} (or @option{-noe}) option tells where the output-enable (or
|
|
not-output-enable) input to the output buffer is connected. The options
|
|
@option{-input} and @option{-ninput} specify the bitmask for pins to be read
|
|
with the method @command{ftdi get_signal}.
|
|
|
|
Both @var{data_mask} and @var{oe_mask} need not be specified. For example, a
|
|
simple open-collector transistor driver would be specified with @option{-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, @command{reset_config} must be specified as
|
|
@option{srst_open_drain}, not @option{srst_push_pull}.
|
|
|
|
A special case is provided when @option{-data} and @option{-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 @option{-alias} or @option{-nalias} is used, the signal is created
|
|
identical (or with data inverted) to an already specified signal
|
|
@var{name}.
|
|
@end deffn
|
|
|
|
@deffn {Command} {ftdi set_signal} name @option{0}|@option{1}|@option{z}
|
|
Set a previously defined signal to the specified level.
|
|
@itemize @minus
|
|
@item @option{0}, drive low
|
|
@item @option{1}, drive high
|
|
@item @option{z}, set to high-impedance
|
|
@end itemize
|
|
@end deffn
|
|
|
|
@deffn {Command} {ftdi get_signal} name
|
|
Get the value of a previously defined signal.
|
|
@end deffn
|
|
|
|
@deffn {Command} {ftdi tdo_sample_edge} @option{rising}|@option{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.
|
|
@itemize @minus
|
|
@item @option{rising}, sample TDO on rising edge of TCK - this is the default
|
|
@item @option{falling}, sample TDO on falling edge of TCK
|
|
@end itemize
|
|
@end deffn
|
|
|
|
For example adapter definitions, see the configuration files shipped in the
|
|
@file{interface/ftdi} directory.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {ft232r}
|
|
This driver is implementing synchronous bitbang mode of an FTDI FT232R,
|
|
FT230X, FT231X and similar USB UART bridge ICs by reusing RS232 signals as GPIO.
|
|
It currently doesn't support using CBUS pins as GPIO.
|
|
|
|
List of connections (default physical pin numbers for FT232R in 28-pin SSOP package):
|
|
@itemize @minus
|
|
@item RXD(5) - TDI
|
|
@item TXD(1) - TCK
|
|
@item RTS(3) - TDO
|
|
@item CTS(11) - TMS
|
|
@item DTR(2) - TRST
|
|
@item DCD(10) - SRST
|
|
@end itemize
|
|
|
|
User can change default pinout by supplying configuration
|
|
commands with GPIO numbers or RS232 signal names.
|
|
GPIO numbers correspond to bit numbers in FTDI GPIO register.
|
|
They differ from physical pin numbers.
|
|
For details see actual FTDI chip datasheets.
|
|
Every JTAG line must be configured to unique GPIO number
|
|
different than any other JTAG line, even those lines
|
|
that are sometimes not used like TRST or SRST.
|
|
|
|
FT232R
|
|
@itemize @minus
|
|
@item bit 7 - RI
|
|
@item bit 6 - DCD
|
|
@item bit 5 - DSR
|
|
@item bit 4 - DTR
|
|
@item bit 3 - CTS
|
|
@item bit 2 - RTS
|
|
@item bit 1 - RXD
|
|
@item bit 0 - TXD
|
|
@end itemize
|
|
|
|
These interfaces have several commands, used to configure the driver
|
|
before initializing the JTAG scan chain:
|
|
|
|
@deffn {Config Command} {ft232r vid_pid} @var{vid} @var{pid}
|
|
The vendor ID and product ID of the adapter. If not specified, default
|
|
0x0403:0x6001 is used.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {ft232r jtag_nums} @var{tck} @var{tms} @var{tdi} @var{tdo}
|
|
Set four JTAG GPIO numbers at once.
|
|
If not specified, default 0 3 1 2 or TXD CTS RXD RTS is used.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {ft232r tck_num} @var{tck}
|
|
Set TCK GPIO number. If not specified, default 0 or TXD is used.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {ft232r tms_num} @var{tms}
|
|
Set TMS GPIO number. If not specified, default 3 or CTS is used.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {ft232r tdi_num} @var{tdi}
|
|
Set TDI GPIO number. If not specified, default 1 or RXD is used.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {ft232r tdo_num} @var{tdo}
|
|
Set TDO GPIO number. If not specified, default 2 or RTS is used.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {ft232r trst_num} @var{trst}
|
|
Set TRST GPIO number. If not specified, default 4 or DTR is used.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {ft232r srst_num} @var{srst}
|
|
Set SRST GPIO number. If not specified, default 6 or DCD is used.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {ft232r restore_serial} @var{word}
|
|
Restore serial port after JTAG. This USB bitmode control word
|
|
(16-bit) will be sent before quit. Lower byte should
|
|
set GPIO direction register to a "sane" state:
|
|
0x15 for TXD RTS DTR as outputs (1), others as inputs (0). Higher
|
|
byte is usually 0 to disable bitbang mode.
|
|
When kernel driver reattaches, serial port should continue to work.
|
|
Value 0xFFFF disables sending control word and serial port,
|
|
then kernel driver will not reattach.
|
|
If not specified, default 0xFFFF is used.
|
|
@end deffn
|
|
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {remote_bitbang}
|
|
Drive JTAG and SWD 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 and SWD.
|
|
|
|
The remote_bitbang driver is useful for debugging software running on
|
|
processors which are being simulated.
|
|
|
|
@deffn {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.
|
|
@end deffn
|
|
|
|
@deffn {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.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {remote_bitbang use_remote_sleep} (on|off)
|
|
If this option is enabled, delays will not be executed locally but instead
|
|
forwarded to the remote host. This is useful if the remote host performs its
|
|
own request queuing rather than executing requests immediately.
|
|
|
|
This is disabled by default. This option must only be enabled if the given
|
|
remote_bitbang host supports receiving the delay information.
|
|
@end deffn
|
|
|
|
For example, to connect remotely via TCP to the host foobar you might have
|
|
something like:
|
|
|
|
@example
|
|
adapter driver remote_bitbang
|
|
remote_bitbang port 3335
|
|
remote_bitbang host foobar
|
|
@end example
|
|
|
|
And if you also wished to enable remote sleeping:
|
|
|
|
@example
|
|
adapter driver remote_bitbang
|
|
remote_bitbang port 3335
|
|
remote_bitbang host foobar
|
|
remote_bitbang use_remote_sleep on
|
|
@end example
|
|
|
|
To connect to another process running locally via UNIX sockets with socket
|
|
named mysocket:
|
|
|
|
@example
|
|
adapter driver remote_bitbang
|
|
remote_bitbang port 0
|
|
remote_bitbang host mysocket
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {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:
|
|
|
|
@deffn {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 @var{vid}, @var{pid} pair may be given, e.g. for
|
|
Altera USB-Blaster (default):
|
|
@example
|
|
usb_blaster vid_pid 0x09FB 0x6001
|
|
@end example
|
|
The following VID/PID is for Kolja Waschk's USB JTAG:
|
|
@example
|
|
usb_blaster vid_pid 0x16C0 0x06AD
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Command} {usb_blaster pin} (@option{pin6}|@option{pin8}) (@option{0}|@option{1}|@option{s}|@option{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:
|
|
@example
|
|
usb_blaster pin pin6 s
|
|
reset_config srst_only
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {usb_blaster lowlevel_driver} (@option{ftdi}|@option{ublast2})
|
|
Chooses the low level access method for the adapter. If not specified,
|
|
@option{ftdi} is selected unless it wasn't enabled during the
|
|
configure stage. USB-Blaster II needs @option{ublast2}.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {usb_blaster firmware} @var{path}
|
|
This command specifies @var{path} to access USB-Blaster II firmware
|
|
image. To be used with USB-Blaster II only.
|
|
@end deffn
|
|
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {gw16012}
|
|
Gateworks GW16012 JTAG programmer.
|
|
This has one driver-specific command:
|
|
|
|
@deffn {Config Command} {parport port} [port_number]
|
|
Display either the address of the I/O port
|
|
(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
|
|
If a parameter is provided, first switch to use that port.
|
|
This is a write-once setting.
|
|
@end deffn
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {jlink}
|
|
SEGGER J-Link family of USB adapters. It currently supports JTAG and SWD
|
|
transports.
|
|
|
|
@quotation 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.
|
|
@end quotation
|
|
|
|
@deffn {Command} {jlink hwstatus}
|
|
Display various hardware related information, for example target voltage and pin
|
|
states.
|
|
@end deffn
|
|
@deffn {Command} {jlink freemem}
|
|
Display free device internal memory.
|
|
@end deffn
|
|
@deffn {Command} {jlink jtag} [@option{2}|@option{3}]
|
|
Set the JTAG command version to be used. Without argument, show the actual JTAG
|
|
command version.
|
|
@end deffn
|
|
@deffn {Command} {jlink targetpower} [@option{0}|@option{1}|@option{on}|@option{off}]
|
|
Switch the 5@ V target power supply on or off.
|
|
Without argument, show the state of the target power supply.
|
|
The target power supply is usually connected to pin 19 of the 20-pin connector.
|
|
@end deffn
|
|
@deffn {Command} {jlink config}
|
|
Display the device configuration.
|
|
@end deffn
|
|
@deffn {Command} {jlink config targetpower} [@option{on}|@option{off}]
|
|
Set the target power state on JTAG-pin 19. Without argument, show the target
|
|
power state.
|
|
@end deffn
|
|
@deffn {Command} {jlink config mac} [@option{ff:ff:ff:ff:ff:ff}]
|
|
Set the MAC address of the device. Without argument, show the MAC address.
|
|
@end deffn
|
|
@deffn {Command} {jlink config ip} [@option{A.B.C.D}(@option{/E}|@option{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.
|
|
@end deffn
|
|
@deffn {Command} {jlink config usb} [@option{0} to @option{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.
|
|
@end deffn
|
|
@deffn {Command} {jlink config reset}
|
|
Reset the current configuration.
|
|
@end deffn
|
|
@deffn {Command} {jlink config write}
|
|
Write the current configuration to the internal persistent storage.
|
|
@end deffn
|
|
@deffn {Command} {jlink emucom write} <channel> <data>
|
|
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:
|
|
@example
|
|
> jlink emucom write 0x10 aa0b23
|
|
@end example
|
|
@end deffn
|
|
@deffn {Command} {jlink emucom read} <channel> <length>
|
|
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:
|
|
@example
|
|
> jlink emucom read 0x0 4
|
|
77a90000
|
|
@end example
|
|
@end deffn
|
|
@deffn {Config Command} {jlink usb} <@option{0} to @option{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'.
|
|
@end deffn
|
|
@end deffn
|
|
|
|
@deffn {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
|
|
@command{kitprog init_acquire_psoc} or @command{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:
|
|
@itemize @bullet
|
|
@item The frequency of SWCLK cannot be configured, and varies between 1.6 MHz
|
|
and 2.7 MHz.
|
|
@item 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.
|
|
@item Due in part to the limitation above, KitProg devices with firmware below
|
|
version 2.14 will need to use @command{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.
|
|
@end itemize
|
|
|
|
@deffn {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.
|
|
@end deffn
|
|
|
|
@deffn {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.
|
|
@end deffn
|
|
|
|
@deffn {Command} {kitprog info}
|
|
Display various adapter information, such as the hardware version, firmware
|
|
version, and target voltage.
|
|
@end deffn
|
|
@end deffn
|
|
|
|
@deffn {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:
|
|
|
|
@deffn {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 @var{name} values include:
|
|
|
|
@itemize @minus
|
|
@item @b{altium} Altium Universal JTAG cable.
|
|
@item @b{arm-jtag} Same as original wiggler except SRST and
|
|
TRST connections reversed and TRST is also inverted.
|
|
@item @b{chameleon} The Amontec Chameleon's CPLD when operated
|
|
in configuration mode. This is only used to
|
|
program the Chameleon itself, not a connected target.
|
|
@item @b{dlc5} The Xilinx Parallel cable III.
|
|
@item @b{flashlink} The ST Parallel cable.
|
|
@item @b{lattice} Lattice ispDOWNLOAD Cable
|
|
@item @b{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 ('@var{wiggler}')
|
|
@item @b{triton} The parallel port adapter found on the
|
|
``Karo Triton 1 Development Board''.
|
|
This is also the layout used by the HollyGates design
|
|
(see @uref{http://www.lartmaker.nl/projects/jtag/}).
|
|
@item @b{wiggler} The original Wiggler layout, also supported by
|
|
several clones, such as the Olimex ARM-JTAG
|
|
@item @b{wiggler2} Same as original wiggler except an led is fitted on D5.
|
|
@item @b{wiggler_ntrst_inverted} Same as original wiggler except TRST is inverted.
|
|
@end itemize
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {parport port} [port_number]
|
|
Display either the address of the I/O port
|
|
(default: 0x378 for LPT1) or the number of the @file{/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:
|
|
@option{parport port 0} (the default). If @option{parport port 0x378} is specified
|
|
you may encounter a problem.
|
|
@end deffn
|
|
|
|
@deffn {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
|
|
@command{adapter speed} configuration.
|
|
When the optional @var{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.
|
|
@quotation Tip
|
|
To measure the toggling time with a logic analyzer or a digital storage
|
|
oscilloscope, follow the procedure below:
|
|
@example
|
|
> parport toggling_time 1000
|
|
> 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.
|
|
Now, measure the time between the two closest spaced TCK transitions.
|
|
You can use @command{runtest 1000} or something similar to generate a
|
|
large set of samples.
|
|
Update the setting to match your measurement:
|
|
@example
|
|
> parport toggling_time <measured nanoseconds>
|
|
@end example
|
|
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 with the rate you specified in the @command{adapter speed} command;
|
|
be conservative.
|
|
@end quotation
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {parport write_on_exit} (@option{on}|@option{off})
|
|
This will configure the parallel driver to write a known
|
|
cable-specific value to the parallel interface on exiting OpenOCD.
|
|
@end deffn
|
|
|
|
For example, the interface configuration file for a
|
|
classic ``Wiggler'' cable on LPT2 might look something like this:
|
|
|
|
@example
|
|
adapter driver parport
|
|
parport port 0x278
|
|
parport cable wiggler
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {presto}
|
|
ASIX PRESTO USB JTAG programmer.
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {rlink}
|
|
Raisonance RLink USB adapter
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {usbprog}
|
|
usbprog is a freely programmable USB adapter.
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {vsllink}
|
|
vsllink is part of Versaloon which is a versatile USB programmer.
|
|
|
|
@quotation Note
|
|
This defines quite a few driver-specific commands,
|
|
which are not currently documented here.
|
|
@end quotation
|
|
@end deffn
|
|
|
|
@anchor{hla_interface}
|
|
@deffn {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.
|
|
|
|
@deffn {Config Command} {hla device_desc} description
|
|
Currently Not Supported.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {hla layout} (@option{icdi}|@option{nulink})
|
|
Specifies the adapter layout to use.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {hla vid_pid} [vid pid]+
|
|
Pairs of vendor IDs and product IDs of the device.
|
|
@end deffn
|
|
|
|
@deffn {Command} {hla command} command
|
|
Execute a custom adapter-specific command. The @var{command} string is
|
|
passed as is to the underlying adapter layout handler.
|
|
@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 2015 firmware V2J24), STLINK-V3 and STLINK-V3PWR, thanks to a new API that provides
|
|
directly access the arm ADIv5 DAP.
|
|
|
|
The older API that requires HLA transport is deprecated and will be dropped
|
|
from OpenOCD. In mean time it's still available by using @file{interface/stlink-hla.cfg}.
|
|
|
|
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 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).
|
|
|
|
@emph{Note:} ST-Link TCP server is a binary application provided by ST
|
|
available from @url{https://www.st.com/en/development-tools/st-link-server.html,
|
|
ST-LINK server software module}.
|
|
|
|
@emph{Note:} ST-Link TCP server does not support the SWIM transport.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {st-link vid_pid} [vid pid]+
|
|
Pairs of vendor IDs and product IDs of the device.
|
|
@end deffn
|
|
|
|
@deffn {Command} {st-link cmd} rx_n (tx_byte)+
|
|
Sends an arbitrary command composed by the sequence of bytes @var{tx_byte}
|
|
and receives @var{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.
|
|
@example
|
|
> 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
|
|
@end example
|
|
The result can be converted to Volts (ignoring the most significant bytes, always zero)
|
|
@example
|
|
> 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
|
|
@end example
|
|
@end deffn
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {opendous}
|
|
opendous-jtag is a freely programmable USB adapter.
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {ulink}
|
|
This is the Keil ULINK v1 JTAG debugger.
|
|
@end deffn
|
|
|
|
@deffn {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:
|
|
|
|
@deffn {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.
|
|
@end deffn
|
|
|
|
@deffn {Command} {xds110 info}
|
|
Displays information about the connected XDS110 debug probe (e.g. firmware
|
|
version).
|
|
@end deffn
|
|
@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/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).
|
|
|
|
@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} {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 @ref{adapter gpio, @command{adapter gpio}}.
|
|
|
|
See @file{interface/raspberrypi-native.cfg} for a sample config and
|
|
@file{interface/raspberrypi-gpio-connector.cfg} for pinout.
|
|
|
|
@deffn {Config Command} {bcm2835gpio speed_coeffs} @var{speed_coeff} @var{speed_offset}
|
|
Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified,
|
|
speed_coeff defaults to 113714, and speed_offset defaults to 28.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {bcm2835gpio peripheral_mem_dev} @var{device}
|
|
Set the device path for access to the memory mapped GPIO control registers.
|
|
Uses @file{/dev/gpiomem} by default, this is also the preferred option with
|
|
respect to system security.
|
|
If overridden to @file{/dev/mem}:
|
|
@itemize @minus
|
|
@item OpenOCD needs @code{cap_sys_rawio} or run as root to open @file{/dev/mem}.
|
|
Please be aware of security issues imposed by running OpenOCD with
|
|
elevated user rights and by @file{/dev/mem} itself.
|
|
@item correct @command{peripheral_base} must be configured.
|
|
@item GPIO 0-27 pads are set to the limited slew rate
|
|
and drive strength is reduced to 4 mA (2 mA on RPi 4).
|
|
@end itemize
|
|
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {bcm2835gpio peripheral_base} @var{base}
|
|
Set the peripheral base register address to access GPIOs.
|
|
Ignored if @file{/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
|
|
@uref{https://www.raspberrypi.org/documentation/hardware/raspberrypi/peripheral_addresses.md, official guide}.
|
|
@end deffn
|
|
|
|
@end deffn
|
|
|
|
@deffn {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 @file{interface/imx-native.cfg} for a sample config and
|
|
pinout.
|
|
|
|
@end deffn
|
|
|
|
|
|
@deffn {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 @ref{adapter gpio, @command{adapter gpio}}.
|
|
|
|
@deffn {Config Command} {am335xgpio speed_coeffs} @var{speed_coeff} @var{speed_offset}
|
|
Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified
|
|
speed_coeff defaults to 600000 and speed_offset defaults to 575.
|
|
@end deffn
|
|
|
|
See @file{interface/beaglebone-swd-native.cfg} for a sample configuration file.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {linuxspidev}
|
|
Linux provides userspace access to SPI through spidev. Full duplex SPI
|
|
transactions are used to simultaneously read and write to/from the target to
|
|
emulate the SWD transport.
|
|
|
|
@deffn {Config Command} {spidev path} path
|
|
Specifies the path to the spidev device.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {spidev mode} value
|
|
Set the mode of the spi port with optional bit flags (default=3).
|
|
See /usr/include/linux/spi/spidev.h for all of the SPI mode options.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {spidev queue_entries} value
|
|
Set the maximum number of queued transactions per spi exchange (default=64).
|
|
More queued transactions may offer greater performance when the target doesn't
|
|
need to wait. On the contrary higher numbers will reduce performance when the
|
|
target requests a wait as all queued transactions will need to be exchanged
|
|
before spidev can see the wait request.
|
|
@end deffn
|
|
|
|
See @file{tcl/interface/spidev_example.cfg} for a sample configuration file.
|
|
|
|
Electrical connections:
|
|
@example
|
|
+--------------+ +--------------+
|
|
| | 1K | |
|
|
| MOSI|---/\/\/\---+ | |
|
|
| Host | | | Target |
|
|
| MISO|------------+---|SWDIO |
|
|
| | | |
|
|
| SCK|----------------|SWDCLK |
|
|
| | | |
|
|
+--------------+ +--------------+
|
|
@end example
|
|
|
|
The 1K resistor works well with most MCUs up to 3 MHz. A lower resistance
|
|
could be used to achieve higher speeds granted that the target SWDIO pin has
|
|
enough drive strength to pull the signal high while being pulled low by this
|
|
resistor.
|
|
|
|
If you are having trouble here are some tips:
|
|
|
|
@itemize @bullet
|
|
|
|
@item @b{Make sure MISO and MOSI are tied together with a 1K resistor.}
|
|
MISO should be attached to the target.
|
|
|
|
@item @b{Make sure that your host and target are using the same I/O voltage}
|
|
(for example both are using 3.3 volts).
|
|
|
|
@item @b{Your host's SPI port may not idle low.}
|
|
This will lead to an additional clock edge being sent to the target, causing
|
|
the host and target being 1 clock off from each other. Try setting
|
|
SPI_MOSI_IDLE_LOW in spi_mode. Try using a different spi_mode (0 - 3).
|
|
|
|
@item @b{Your target may pull SWDIO and/or SWDCLK high.}
|
|
This will create an extra edge when the host releases control of the SPI port
|
|
at the end of a transaction. You'll need to confirm this with a scope or meter.
|
|
Try installing 10K resistors on SWDIO and SWDCLK to ground to stop this.
|
|
|
|
@end itemize
|
|
@end deffn
|
|
|
|
@deffn {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 @ref{adapter gpio, @command{adapter gpio}}. This
|
|
driver supports the resistor pull options provided by the @command{adapter gpio}
|
|
command but the underlying hardware may not be able to support them.
|
|
|
|
See @file{interface/dln-2-gpiod.cfg} for a sample configuration file.
|
|
@end deffn
|
|
|
|
|
|
@deffn {Interface Driver} {sysfsgpio}
|
|
Linux legacy userspace access to GPIO through sysfs is deprecated from Linux kernel version v5.3.
|
|
Prefer using @b{linuxgpiod}, instead.
|
|
|
|
See @file{interface/sysfsgpio-raspberrypi.cfg} for a sample config.
|
|
@end deffn
|
|
|
|
|
|
@deffn {Interface Driver} {openjtag}
|
|
OpenJTAG compatible USB adapter.
|
|
This defines some driver-specific commands:
|
|
|
|
@deffn {Config Command} {openjtag variant} variant
|
|
Specifies the variant of the OpenJTAG adapter (see @uref{http://www.openjtag.org/}).
|
|
Currently valid @var{variant} values include:
|
|
|
|
@itemize @minus
|
|
@item @b{standard} Standard variant (default).
|
|
@item @b{cy7c65215} Cypress CY7C65215 Dual Channel USB-Serial Bridge Controller
|
|
(see @uref{http://www.cypress.com/?rID=82870}).
|
|
@end itemize
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {openjtag device_desc} string
|
|
The USB device description string of the adapter.
|
|
This value is only used with the standard variant.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {openjtag vid_pid} vid pid
|
|
The USB vendor ID and product ID of the adapter. If not specified, default
|
|
0x0403:0x6001 is used.
|
|
This value is only used with the standard variant.
|
|
@example
|
|
openjtag vid_pid 0x403 0x6014
|
|
@end example
|
|
@end deffn
|
|
@end deffn
|
|
|
|
|
|
@deffn {Interface Driver} {vdebug}
|
|
Cadence Virtual Debug Interface driver.
|
|
|
|
@deffn {Config Command} {vdebug server} host:port
|
|
Specifies the host and TCP port number where the vdebug server runs.
|
|
@end deffn
|
|
|
|
@deffn {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
|
|
@end deffn
|
|
|
|
@deffn {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.
|
|
@end deffn
|
|
|
|
@deffn {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.
|
|
@end deffn
|
|
|
|
@deffn {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.
|
|
@end deffn
|
|
@end deffn
|
|
|
|
@deffn {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.
|
|
|
|
@deffn {Config Command} {jtag_dpi set_port} port
|
|
Specifies the TCP/IP port number of the SystemVerilog DPI server interface.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {jtag_dpi set_address} address
|
|
Specifies the TCP/IP address of the SystemVerilog DPI server interface.
|
|
@end deffn
|
|
@end deffn
|
|
|
|
|
|
@deffn {Interface Driver} {buspirate}
|
|
|
|
This driver is for the Bus Pirate (see @url{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.
|
|
|
|
@deffn {Config Command} {buspirate port} serial_port
|
|
Specify the serial port's filename. For example:
|
|
@example
|
|
buspirate port /dev/ttyUSB0
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {buspirate speed} (normal|fast)
|
|
Set the communication speed to 115k (normal) or 1M (fast). For example:
|
|
@example
|
|
buspirate speed normal
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {buspirate mode} (normal|open-drain)
|
|
Set the Bus Pirate output mode.
|
|
@itemize @minus
|
|
@item In normal mode (push/pull), do not enable the pull-ups, and do not connect I/O header pin VPU to JTAG VREF.
|
|
@item In open drain mode, you will then need to enable the pull-ups.
|
|
@end itemize
|
|
For example:
|
|
@example
|
|
buspirate mode normal
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {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:
|
|
@example
|
|
buspirate pullup 0
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {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:
|
|
@example
|
|
buspirate vreg 0
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Command} {buspirate led} (0|1)
|
|
Turns the Bus Pirate's LED on (1) or off (0). For example:
|
|
@end deffn
|
|
@example
|
|
buspirate led 1
|
|
@end example
|
|
|
|
@end deffn
|
|
|
|
@deffn {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.
|
|
|
|
@deffn {Command} {espusbjtag tdo}
|
|
Returns the current state of the TDO line
|
|
@end deffn
|
|
|
|
@deffn {Command} {espusbjtag setio} setio
|
|
Manually set the status of the output lines with the order of (tdi tms tck trst srst)
|
|
@example
|
|
espusbjtag setio 0 1 0 1 0
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {espusbjtag vid_pid} vid_pid
|
|
Set vendor ID and product ID for the ESP usb jtag driver
|
|
@example
|
|
espusbjtag vid_pid 0x303a 0x1001
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {espusbjtag caps_descriptor} caps_descriptor
|
|
Set the jtag descriptor to read capabilities of ESP usb jtag driver
|
|
@example
|
|
espusbjtag caps_descriptor 0x2000
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {espusbjtag chip_id} chip_id
|
|
Set chip id to transfer to the ESP USB bridge board
|
|
@example
|
|
espusbjtag chip_id 1
|
|
@end example
|
|
@end deffn
|
|
|
|
@end deffn
|
|
|
|
@deffn {Interface Driver} {dmem} Direct Memory access debug interface
|
|
|
|
The Texas Instruments K3 SoC family provides memory access to DAP
|
|
and coresight control registers. This allows control over the
|
|
microcontrollers directly from one of the processors on the SOC
|
|
itself.
|
|
|
|
For maximum performance, the driver accesses the debug registers
|
|
directly over the SoC memory map. The memory mapping requires read
|
|
and write permission to kernel memory via "/dev/mem" and assumes that
|
|
the system firewall configurations permit direct access to the debug
|
|
memory space.
|
|
|
|
@verbatim
|
|
+-----------+
|
|
| OpenOCD | SoC mem map (/dev/mem)
|
|
| on +--------------+
|
|
| Cortex-A53| |
|
|
+-----------+ |
|
|
|
|
|
+-----------+ +-----v-----+
|
|
|Cortex-M4F <--------+ |
|
|
+-----------+ | |
|
|
| DebugSS |
|
|
+-----------+ | |
|
|
|Cortex-M4F <--------+ |
|
|
+-----------+ +-----------+
|
|
@end verbatim
|
|
|
|
NOTE: Firewalls are configurable in K3 SoC and depending on various types of
|
|
device configuration, this function may be blocked out. Typical behavior
|
|
observed in such cases is a firewall exception report on the security
|
|
controller and armv8 processor reporting a system error.
|
|
|
|
See @file{tcl/interface/ti_k3_am625-swd-native.cfg} for a sample configuration
|
|
file.
|
|
|
|
@deffn {Command} {dmem info}
|
|
Print the DAPBUS dmem configuration.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {dmem device} device_path
|
|
Set the DAPBUS memory access device (default: /dev/mem).
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {dmem base_address} base_address
|
|
Set the DAPBUS base address which is used to access CoreSight
|
|
compliant Access Ports (APs) directly.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {dmem ap_address_offset} offset_address
|
|
Set the address offset between Access Ports (APs).
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {dmem max_aps} n
|
|
Set the maximum number of valid access ports on the SoC.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {dmem emu_ap_list} n
|
|
Set the list of Access Ports (APs) that need to be emulated. This
|
|
emulation mode supports software translation of an AP request into an
|
|
address mapped transaction that does not rely on physical AP hardware.
|
|
This maybe needed if the AP is either denied access via memory map or
|
|
protected using other SoC mechanisms.
|
|
@end deffn
|
|
|
|
@deffn {Config Command} {dmem emu_base_address_range} base_address address_window_size
|
|
Set the emulated address and address window size. Both of these
|
|
parameters must be aligned to page size.
|
|
@end deffn
|
|
|
|
@end deffn
|
|
|
|
@section Transport Configuration
|
|
@cindex Transport
|
|
As noted earlier, depending on the version of OpenOCD you use,
|
|
and the debug adapter you are using,
|
|
several transports may be available to
|
|
communicate with debug targets (or perhaps to program flash memory).
|
|
@deffn {Command} {transport list}
|
|
displays the names of the transports supported by this
|
|
version of OpenOCD.
|
|
@end deffn
|
|
|
|
@deffn {Command} {transport select} [transport_name]
|
|
Select which of the supported transports to use in this OpenOCD session.
|
|
|
|
When invoked with @option{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).
|
|
When invoked with no transport name:
|
|
@itemize @minus
|
|
@item if no transport has been selected yet, it auto-selects the first transport supported by the debug adapter
|
|
@item it returns the name of the session's selected transport
|
|
@end itemize
|
|
@end deffn
|
|
|
|
@subsection JTAG Transport
|
|
@cindex JTAG
|
|
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 @command{transport select
|
|
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
|
|
@cindex Serial Wire Debug
|
|
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 @command{transport select
|
|
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 {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.
|
|
@end deffn
|
|
|
|
@cindex SWD multi-drop
|
|
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 @ref{dap_create,DAP} is configured
|
|
with both @code{-dp-id} and @code{-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.
|
|
|
|
@subsection SPI Transport
|
|
@cindex SPI
|
|
@cindex Serial Peripheral Interface
|
|
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.
|
|
|
|
@anchor{swimtransport}
|
|
@subsection SWIM Transport
|
|
@cindex SWIM
|
|
@cindex Single Wire Interface Module
|
|
The Single Wire Interface Module (SWIM) is a low-pin-count debug protocol used
|
|
by the STMicroelectronics MCU family STM8 and documented in the
|
|
@uref{https://www.st.com/resource/en/user_manual/cd00173911.pdf, User Manual UM470}.
|
|
|
|
SWIM does not support boundary scan testing nor multiple cores.
|
|
|
|
The SWIM transport is selected with the command @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 @command{swim newtap basename tap_type}.
|
|
The TAP definition must precede the target definition command
|
|
@command{target create target_name stm8 -chain-position basename.tap_type}.
|
|
|
|
@anchor{jtagspeed}
|
|
@section JTAG Speed
|
|
JTAG clock setup is part of system setup.
|
|
It @emph{does not belong with interface setup} since any interface
|
|
only knows a few of the constraints for the JTAG clock speed.
|
|
Sometimes the JTAG speed is
|
|
changed during the target initialization process: (1) slow at
|
|
reset, (2) program the CPU clocks, (3) run fast.
|
|
Both the "slow" and "fast" clock rates are functions of the
|
|
oscillators used, the chip, the board design, and sometimes
|
|
power management software that may be active.
|
|
|
|
The speed used during reset, and the scan chain verification which
|
|
follows reset, can be adjusted using a @code{reset-start}
|
|
target event handler.
|
|
It can then be reconfig |