Open On-Chip Debugger: OpenOCD User’s Guide

1 Open On-Chip Debugger: OpenOCD User s Guidefor release March 2021 This User s Guide documents release , dated 7 March 2021, of the Open On-ChipDebugger ( OpenOCD ). Copyrightc 2008 The OpenOCD Project Copyrightc 2007-2008 Spencer Copyrightc 2008-2010 Oyvind Copyrightc 2008 Duane Copyrightc 2009-2010 David BrownellPermission is granted to copy, distribute and/or modify this document under theterms of the GNU Free Documentation License, Version or any later versionpublished by the Free Software Foundation; with no Invariant Sections, noFront-Cover Texts, and no Back-Cover Texts. A copy of the license is includedin the section entitled GNU Free Documentation License .iShort Developer Adapter Project File Adapter TAP CPU flash flash PLD/FPGA General Architecture and Core JTAG Boundary Scan Utility GDB and Tcl Scripting Tcl Crash GNU Free Documentation Concept and Driver of is OpenOCD ?

2 1 OpenOCD Web Site..2 Latest User s Guide :..2 OpenOCD User s Forum..2 OpenOCD User s Mailing List..2 OpenOCD IRC..21 OpenOCD Developer OpenOCD Git Repository.. Doxygen Developer Manual.. Gerrit Review System.. OpenOCD Developer Mailing List.. OpenOCD Bug Tracker..42 Debug Adapter Choosing a Dongle.. Stand-alone JTAG Probe.. USB FT2232 Based.. USB-JTAG / Altera USB-Blaster compatibles.. USB J-Link based.. USB RLINK based.. USB ST-LINK based.. USB TI/Stellaris ICDI based.. USB Nuvoton Nu-Link.. USB CMSIS-DAP based.. USB Other.. IBM PC Parallel Printer Port Based..103 About Simple setup, no customization.. What OpenOCD does as it starts..135 OpenOCD Project Hooking up the JTAG Adapter.. Project Directory.. Configuration Basics.. User Config Files.. Project-Specific Utilities.. Target Software Changes.. Target Hardware Setup..196 Config File Interface Config Files.

3 Board Config Files.. Communication Between Config files.. Variable Naming Convention.. The reset-init Event Handler.. JTAG Clock Rate.. The initboard procedure.. Target Config Files.. Default Value Boiler Plate Code.. Adding TAPs to the Scan Chain.. Add CPU targets.. Define CPU targets working in SMP.. Chip Reset Setup.. The inittargets procedure.. The inittargetevents procedure.. ARM Core Specific Hacks.. Internal flash Configuration.. Translating Configuration Files..307 Server Configuration Stage.. Entering the Run Stage.. TCP/IP Ports.. GDB Configuration.. Event Polling..348 Debug Adapter Adapter Configuration.. Interface Drivers.. Transport Configuration.. JTAG Transport.. SWD Transport.. SPI Transport.. SWIM Transport.. JTAG Speed..529 Reset Types of Reset.. SRST and TRST Issues.. Commands for Handling Resets.. Custom Reset Handling.

4 57iv10 TAP Scan Chains.. TAP Names.. TAP Declaration Commands.. Other TAP commands.. TAP Events.. Enabling and Disabling TAPs.. Autoprobing.. DAP declaration (ARMv6-M, ARMv7 and ARMv8 targets)..6411 CPU Target List.. Target CPU Types.. Target Configuration.. Other $targetname Commands.. Target Events..7412 flash flash Configuration Commands.. Preparing a Target before flash Programming.. Erasing, Reading, Writing to flash .. Other flash commands.. flash Driver List.. External flash .. Internal flash (Microcontrollers).. NAND flash Commands.. NAND Configuration Commands.. Erasing, Reading, Writing to NAND flash .. Other NAND commands.. NAND Driver List..11513 flash PLD/FPGA PLD/FPGA Configuration and Commands.. PLD/FPGA Drivers, Options, and Commands..11915 General Server Commands.. Target State handling.. I/O Utilities.. Memory access commands.

5 Image loading commands.. Breakpoint and Watchpoint commands.. Real Time Transfer (RTT).. Misc Commands..127v16 Architecture and Core ARM Hardware Tracing.. ETM Configuration.. ETM Trace Operation.. Trace Port Drivers.. ARM Cross-Trigger Interface.. Generic ARM.. ARMv4 and ARMv5 Architecture.. ARM7 and ARM9 specific commands.. ARM720T specific commands.. ARM9 specific commands.. ARM920T specific commands.. ARM926ej-s specific commands.. ARM966E specific commands.. XScale specific commands.. ARMv6 Architecture.. ARM11 specific commands.. ARMv7 and ARMv8 Architecture.. ARMv7-A specific commands.. ARMv7-R specific commands.. ARMv7-M specific commands.. Cortex-M specific commands.. ARMv8-A specific commands.. EnSilica eSi-RISC Architecture.. eSi-RISC Configuration.. eSi-RISC Operation.. eSi-Trace Configuration.. eSi-Trace Operation.. Intel Architecture.. x86 32-bit specific commands.

6 OpenRISC Architecture.. TAP and Debug Unit selection commands.. Registers commands.. RISC-V Architecture.. RISC-V Terminology.. RISC-V Debug Configuration Commands.. RISC-V Authentication Commands.. RISC-V DMI Commands.. ARC Architecture.. General ARC commands.. ARC JTAG commands.. STM8 Architecture.. Software Debug Messages and Tracing..15317 JTAG Low Level JTAG Commands.. TAP state names..156vi18 Boundary Scan SVF: Serial Vector Format.. XSVF: Xilinx Serial Vector Format..15819 Utility RAM testing.. Firmware recovery helpers..16020 GDB and Connecting to GDB.. Sample GDB session startup.. Configuring GDB for OpenOCD .. Programming using GDB.. Using GDB as a non-intrusive memory inspector.. RTOS Support.. Using OpenOCD SMP with GDB.. Legacy SMP core switching support..16621 Tcl Scripting API rules.. Internal low-level Commands.. OpenOCD specific Global Variables.

7 Tcl RPC server.. Tcl RPC server notifications.. Tcl RPC server trace output..16922 Tcl Crash Tcl Rule #1.. Tcl Rule #1b.. Per Rule #1 - All Results are strings.. Tcl Quoting Operators.. Consequences of Rule 1/2/3/4.. Tokenisation & .. Command Execution.. The FOR command.. FOR command implementation.. OpenOCD Tcl Usage.. source and find commands.. format command.. Body or Inlined Text.. Global Variables.. Other Tcl Hacks..180viiAppendix A The GNU FreeDocumentation : How to use this License for your documents..188 OpenOCD Concept and Driver was created by Dominic Rath as part of a 2005 diploma thesis written at theUniversity of Applied Sciences Augsburg ( ). Since that time,the project has grown into an active open-source project, supported by a diverse communityof software and hardware developers from around the is OpenOCD ?The Open On-Chip Debugger ( OpenOCD ) aims to provide debugging, in-system program-ming and boundary-scan testing for embedded target does so with the assistance of adebug adapter, which is a small hardware module whichhelps provide the right kind of electrical signaling to the target being debugged.

8 These arerequired since the debug host (on which OpenOCD runs) won t usually have native supportfor such signaling, or the connector needed to hook up to the debug adapters support one or moretransportprotocols, each of which involves dif-ferent 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 calledhardware interface dongles. Some development boards also integrate them directly, whichmay let the development board connect directly to the debug host over USB (and sometimesalso to power it over USB).For example, aJTAG Adaptersupports JTAG signaling, and is used to communicate withJTAG (IEEE ) compliant TAPs on your target board. ATAPis a Test Access Port ,a module which processes special instructions and data. TAPs are daisy-chained within andbetween chips and boards.

9 JTAG supports debugging and boundary scan are alsoSWD Adaptersthat support Serial Wire Debug (SWD) signaling to commu-nicate with some newer ARM cores, as well as debug adapters which support both JTAGand SWD transports. SWD supports only debugging, whereas JTAG also supports bound-ary scan some chips, there are alsoProgramming Adapterssupporting special transports usedonly to write code to flash memory, without support for On-Chip debugging or boundaryscan. (At this writing, OpenOCD does not support such non-debug adapters.)Dongles: OpenOCD currently supports many types of hardware dongles: USB-based, par-allel port-based, and other standalone boxes that run OpenOCD internally. SeeChapter 2[Debug Adapter Hardware], page Debug:It allows ARM7 (ARM7 TDMI and ARM720t), ARM9 (ARM920T,ARM922T, ARM926EJ S, ARM966E S), XScale (PXA25x, IXP42x), Cortex-M3 (StellarisLM3, STMicroelectronics STM32 and Energy Micro EFM32) and Intel Quark (x10xx)based cores to be debugged via the GDB 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, AT91 SAM7, AT91 SAM3U, STR7x, STR9x, LM3, STM32x andEFM32).

10 Preliminary support for various NAND flash controllers (LPC3180, Orion,S3C24xx, more) is Web SiteThe OpenOCD web site provides the latest public news from the community: User s Guide :The user s Guide you are now reading may not be the latest one available. A version formore recent code may be available. Its HTML form is published regularly at: form is likewise published at: User s ForumThere is an OpenOCD forum (phpBB) hosted by SparkFun, which might be helpful to that if you want anything to come to the attention of developers, you should post itto the OpenOCD Developer Mailing List instead of this User s Mailing ListThe OpenOCD User Mailing List provides the primary means of communication betweenusers: IRCS upport can also be found on irc: OpenOCD Developer ResourcesIf 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 orinterface drivers, improve the documentation, as well as more conventional bug fixes resources in this chapter are available for developers wishing to explore or expand theOpenOCD source OpenOCD Git RepositoryDuring the release cycle, OpenOCD switched from Subversion to a Git repositoryhosted at SourceForge.