Open On-Chip Debugger: OpenOCD User's Guide for release 0.11.0+dev 27 September 2021 This User's Guide documents release 0.11.0+dev, dated 27 September 2021, of the Open On-Chip Debugger (OpenOCD). • Copyright c 2008 The OpenOCD Project • Copyright c 2007-2008 Spencer Oliver [email protected] • Copyright c 2008-2010 Oyvind Harboe [email protected] • Copyright c 2008 Duane Ellis [email protected] • Copyright c 2009-2010 David Brownell 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". i Short Contents About :::::::::::::::::::::::::::::::::::::::::::::::::: 1 1 OpenOCD Developer Resources :::::::::::::::::::::::::: 3 2 Debug Adapter Hardware ::::::::::::::::::::::::::::::: 5 3 About Jim-Tcl ::::::::::::::::::::::::::::::::::::::: 11 4 Running :::::::::::::::::::::::::::::::::::::::::::: 12 5 OpenOCD Project Setup :::::::::::::::::::::::::::::: 14 6 Config File Guidelines ::::::::::::::::::::::::::::::::: 21 7 Server Configuration :::::::::::::::::::::::::::::::::: 32 8 Debug Adapter Configuration::::::::::::::::::::::::::: 36 9 Reset Configuration::::::::::::::::::::::::::::::::::: 56 10 TAP Declaration ::::::::::::::::::::::::::::::::::::: 61 11 CPU Configuration ::::::::::::::::::::::::::::::::::: 69 12 Flash Commands ::::::::::::::::::::::::::::::::::::: 79 13 Flash Programming :::::::::::::::::::::::::::::::::: 121 14 PLD/FPGA Commands :::::::::::::::::::::::::::::: 122 15 General Commands :::::::::::::::::::::::::::::::::: 123 16 Architecture and Core Commands :::::::::::::::::::::: 131 17 JTAG Commands ::::::::::::::::::::::::::::::::::: 157 18 Boundary Scan Commands :::::::::::::::::::::::::::: 160 19 Utility Commands ::::::::::::::::::::::::::::::::::: 162 20 GDB and OpenOCD ::::::::::::::::::::::::::::::::: 163 21 Tcl Scripting API ::::::::::::::::::::::::::::::::::: 169 22 FAQ :::::::::::::::::::::::::::::::::::::::::::::: 171 23 Tcl Crash Course :::::::::::::::::::::::::::::::::::: 176 A The GNU Free Documentation License. :::::::::::::::::: 183 OpenOCD Concept Index::::::::::::::::::::::::::::::::: 190 Command and Driver Index ::::::::::::::::::::::::::::::: 193 ii Table of Contents About :::::::::::::::::::::::::::::::::::::::::::::::: 1 What is OpenOCD? ::::::::::::::::::::::::::::::::::::::::::::::::: 1 OpenOCD Web Site ::::::::::::::::::::::::::::::::::::::::::::::::: 2 Latest User's Guide: ::::::::::::::::::::::::::::::::::::::::::::::::: 2 OpenOCD User's Forum ::::::::::::::::::::::::::::::::::::::::::::: 2 OpenOCD User's Mailing List ::::::::::::::::::::::::::::::::::::::: 2 OpenOCD IRC :::::::::::::::::::::::::::::::::::::::::::::::::::::: 2 1 OpenOCD Developer Resources ::::::::::::::: 3 1.1 OpenOCD Git Repository :::::::::::::::::::::::::::::::::::::: 3 1.2 Doxygen Developer Manual ::::::::::::::::::::::::::::::::::::: 3 1.3 Gerrit Review System :::::::::::::::::::::::::::::::::::::::::: 3 1.4 OpenOCD Developer Mailing List :::::::::::::::::::::::::::::: 4 1.5 OpenOCD Bug Tracker ::::::::::::::::::::::::::::::::::::::::: 4 2 Debug Adapter Hardware :::::::::::::::::::::: 5 2.1 Choosing a Dongle:::::::::::::::::::::::::::::::::::::::::::::: 5 2.2 USB FT2232 Based::::::::::::::::::::::::::::::::::::::::::::: 5 2.3 USB-JTAG / Altera USB-Blaster compatibles::::::::::::::::::: 6 2.4 USB J-Link based :::::::::::::::::::::::::::::::::::::::::::::: 7 2.5 USB RLINK based ::::::::::::::::::::::::::::::::::::::::::::: 7 2.6 USB ST-LINK based ::::::::::::::::::::::::::::::::::::::::::: 7 2.7 USB TI/Stellaris ICDI based ::::::::::::::::::::::::::::::::::: 8 2.8 USB Nuvoton Nu-Link ::::::::::::::::::::::::::::::::::::::::: 8 2.9 USB CMSIS-DAP based :::::::::::::::::::::::::::::::::::::::: 8 2.10 USB Other :::::::::::::::::::::::::::::::::::::::::::::::::::: 8 2.11 IBM PC Parallel Printer Port Based ::::::::::::::::::::::::::: 9 2.12 Other... ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 9 3 About Jim-Tcl ::::::::::::::::::::::::::::::::: 11 4 Running::::::::::::::::::::::::::::::::::::::::: 12 4.1 Simple setup, no customization :::::::::::::::::::::::::::::::: 13 4.2 What OpenOCD does as it starts :::::::::::::::::::::::::::::: 13 5 OpenOCD Project Setup :::::::::::::::::::::: 14 5.1 Hooking up the JTAG Adapter :::::::::::::::::::::::::::::::: 14 5.2 Project Directory:::::::::::::::::::::::::::::::::::::::::::::: 15 5.3 Configuration Basics::::::::::::::::::::::::::::::::::::::::::: 15 5.4 User Config Files :::::::::::::::::::::::::::::::::::::::::::::: 16 5.5 Project-Specific Utilities ::::::::::::::::::::::::::::::::::::::: 17 iii 5.6 Target Software Changes :::::::::::::::::::::::::::::::::::::: 18 5.7 Target Hardware Setup :::::::::::::::::::::::::::::::::::::::: 19 6 Config File Guidelines ::::::::::::::::::::::::: 21 6.1 Interface Config Files :::::::::::::::::::::::::::::::::::::::::: 21 6.2 Board Config Files :::::::::::::::::::::::::::::::::::::::::::: 21 6.2.1 Communication Between Config files :::::::::::::::::::::: 22 6.2.2 Variable Naming Convention:::::::::::::::::::::::::::::: 23 6.2.3 The reset-init Event Handler:::::::::::::::::::::::::::::: 23 6.2.4 JTAG Clock Rate :::::::::::::::::::::::::::::::::::::::: 24 6.2.5 The init board procedure ::::::::::::::::::::::::::::::::: 24 6.3 Target Config Files :::::::::::::::::::::::::::::::::::::::::::: 25 6.3.1 Default Value Boiler Plate Code :::::::::::::::::::::::::: 25 6.3.2 Adding TAPs to the Scan Chain :::::::::::::::::::::::::: 26 6.3.3 Add CPU targets ::::::::::::::::::::::::::::::::::::::::: 27 6.3.4 Define CPU targets working in SMP :::::::::::::::::::::: 27 6.3.5 Chip Reset Setup ::::::::::::::::::::::::::::::::::::::::: 28 6.3.6 The init targets procedure :::::::::::::::::::::::::::::::: 29 6.3.7 The init target events procedure :::::::::::::::::::::::::: 29 6.3.8 ARM Core Specific Hacks::::::::::::::::::::::::::::::::: 30 6.3.9 Internal Flash Configuration :::::::::::::::::::::::::::::: 30 6.4 Translating Configuration Files :::::::::::::::::::::::::::::::: 30 7 Server Configuration ::::::::::::::::::::::::::: 32 7.1 Configuration Stage ::::::::::::::::::::::::::::::::::::::::::: 32 7.2 Entering the Run Stage:::::::::::::::::::::::::::::::::::::::: 32 7.3 TCP/IP Ports ::::::::::::::::::::::::::::::::::::::::::::::::: 33 7.4 GDB Configuration:::::::::::::::::::::::::::::::::::::::::::: 34 7.5 Event Polling:::::::::::::::::::::::::::::::::::::::::::::::::: 34 8 Debug Adapter Configuration :::::::::::::::: 36 8.1 Adapter Configuration::::::::::::::::::::::::::::::::::::::::: 36 8.2 Interface Drivers::::::::::::::::::::::::::::::::::::::::::::::: 37 8.3 Transport Configuration ::::::::::::::::::::::::::::::::::::::: 53 8.3.1 JTAG Transport:::::::::::::::::::::::::::::::::::::::::: 53 8.3.2 SWD Transport :::::::::::::::::::::::::::::::::::::::::: 53 8.3.3 SPI Transport :::::::::::::::::::::::::::::::::::::::::::: 54 8.3.4 SWIM Transport ::::::::::::::::::::::::::::::::::::::::: 54 8.4 JTAG Speed :::::::::::::::::::::::::::::::::::::::::::::::::: 54 9 Reset Configuration:::::::::::::::::::::::::::: 56 9.1 Types of Reset :::::::::::::::::::::::::::::::::::::::::::::::: 56 9.2 SRST and TRST Issues ::::::::::::::::::::::::::::::::::::::: 56 9.3 Commands for Handling Resets :::::::::::::::::::::::::::::::: 57 9.4 Custom Reset Handling ::::::::::::::::::::::::::::::::::::::: 59 iv 10 TAP Declaration :::::::::::::::::::::::::::::: 61 10.1 Scan Chains:::::::::::::::::::::::::::::::::::::::::::::::::: 61 10.2 TAP Names :::::::::::::::::::::::::::::::::::::::::::::::::: 62 10.3 TAP Declaration Commands ::::::::::::::::::::::::::::::::: 62 10.4 Other TAP commands:::::::::::::::::::::::::::::::::::::::: 64 10.5 TAP Events :::::::::::::::::::::::::::::::::::::::::::::::::: 64 10.6 Enabling and Disabling TAPs :::::::::::::::::::::::::::::::: 65 10.7 Autoprobing ::::::::::::::::::::::::::::::::::::::::::::::::: 66 10.8 DAP declaration (ARMv6-M, ARMv7 and ARMv8 targets) ::: 66 11 CPU Configuration ::::::::::::::::::::::::::: 69 11.1 Target List ::::::::::::::::::::::::::::::::::::::::::::::::::: 69 11.2 Target CPU Types ::::::::::::::::::::::::::::::::::::::::::: 70 11.3 Target Configuration ::::::::::::::::::::::::::::::::::::::::: 71 11.4 Other $target name Commands :::::::::::::::::::::::::::::: 74 11.5 Target Events :::::::::::::::::::::::::::::::::::::::::::::::: 76 12 Flash Commands ::::::::::::::::::::::::::::: 79 12.1 Flash Configuration Commands :::::::::::::::::::::::::::::: 79 12.2 Preparing a Target before Flash Programming :::::::::::::::: 80 12.3 Erasing, Reading, Writing to Flash ::::::::::::::::::::::::::: 80 12.4 Other Flash commands ::::::::::::::::::::::::::::::::::::::: 82 12.5 Flash Driver List ::::::::::::::::::::::::::::::::::::::::::::: 83 12.5.1 External Flash :::::::::::::::::::::::::::::::::::::::::: 83 12.5.2 Internal Flash (Microcontrollers)::::::::::::::::::::::::: 88 12.6 NAND Flash Commands :::::::::::::::::::::::::::::::::::: 114 12.6.1 NAND Configuration Commands ::::::::::::::::::::::: 115 12.6.2 Erasing, Reading, Writing to NAND Flash :::::::::::::: 116 12.6.3 Other NAND commands ::::::::::::::::::::::::::::::: 118 12.6.4 NAND Driver List:::::::::::::::::::::::::::::::::::::: 118 13 Flash Programming ::::::::::::::::::::::::: 121 14 PLD/FPGA Commands :::::::::::::::::::: 122 14.1 PLD/FPGA Configuration