Open On-Chip Debugger: OpenOCD User's Guide for release 0.11.0 7 March 2021 This User's Guide documents release 0.11.0, dated 7 March 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::::::::::::::::::::::::::::::::::: 54 10 TAP Declaration ::::::::::::::::::::::::::::::::::::: 59 11 CPU Configuration ::::::::::::::::::::::::::::::::::: 67 12 Flash Commands ::::::::::::::::::::::::::::::::::::: 77 13 Flash Programming :::::::::::::::::::::::::::::::::: 118 14 PLD/FPGA Commands :::::::::::::::::::::::::::::: 119 15 General Commands :::::::::::::::::::::::::::::::::: 120 16 Architecture and Core Commands :::::::::::::::::::::: 129 17 JTAG Commands ::::::::::::::::::::::::::::::::::: 155 18 Boundary Scan Commands :::::::::::::::::::::::::::: 158 19 Utility Commands ::::::::::::::::::::::::::::::::::: 160 20 GDB and OpenOCD ::::::::::::::::::::::::::::::::: 161 21 Tcl Scripting API ::::::::::::::::::::::::::::::::::: 167 22 FAQ :::::::::::::::::::::::::::::::::::::::::::::: 170 23 Tcl Crash Course :::::::::::::::::::::::::::::::::::: 175 A The GNU Free Documentation License. :::::::::::::::::: 182 OpenOCD Concept Index::::::::::::::::::::::::::::::::: 189 Command and Driver Index ::::::::::::::::::::::::::::::: 192 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 Stand-alone JTAG Probe ::::::::::::::::::::::::::::::::::::::: 5 2.3 USB FT2232 Based::::::::::::::::::::::::::::::::::::::::::::: 5 2.4 USB-JTAG / Altera USB-Blaster compatibles::::::::::::::::::: 7 2.5 USB J-Link based :::::::::::::::::::::::::::::::::::::::::::::: 7 2.6 USB RLINK based ::::::::::::::::::::::::::::::::::::::::::::: 7 2.7 USB ST-LINK based ::::::::::::::::::::::::::::::::::::::::::: 8 2.8 USB TI/Stellaris ICDI based ::::::::::::::::::::::::::::::::::: 8 2.9 USB Nuvoton Nu-Link ::::::::::::::::::::::::::::::::::::::::: 8 2.10 USB CMSIS-DAP based ::::::::::::::::::::::::::::::::::::::: 8 2.11 USB Other :::::::::::::::::::::::::::::::::::::::::::::::::::: 9 2.12 IBM PC Parallel Printer Port Based ::::::::::::::::::::::::::: 9 2.13 Other... :::::::::::::::::::::::::::::::::::::::::::::::::::::: 10 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 iii 5.5 Project-Specific Utilities ::::::::::::::::::::::::::::::::::::::: 17 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 ::::::::::::::::::::::::::::::::::::::: 50 8.3.1 JTAG Transport:::::::::::::::::::::::::::::::::::::::::: 51 8.3.2 SWD Transport :::::::::::::::::::::::::::::::::::::::::: 51 8.3.3 SPI Transport :::::::::::::::::::::::::::::::::::::::::::: 51 8.3.4 SWIM Transport ::::::::::::::::::::::::::::::::::::::::: 51 8.4 JTAG Speed :::::::::::::::::::::::::::::::::::::::::::::::::: 52 9 Reset Configuration:::::::::::::::::::::::::::: 54 9.1 Types of Reset :::::::::::::::::::::::::::::::::::::::::::::::: 54 9.2 SRST and TRST Issues ::::::::::::::::::::::::::::::::::::::: 54 9.3 Commands for Handling Resets :::::::::::::::::::::::::::::::: 55 9.4 Custom Reset Handling ::::::::::::::::::::::::::::::::::::::: 57 iv 10 TAP Declaration :::::::::::::::::::::::::::::: 59 10.1 Scan Chains:::::::::::::::::::::::::::::::::::::::::::::::::: 59 10.2 TAP Names :::::::::::::::::::::::::::::::::::::::::::::::::: 60 10.3 TAP Declaration Commands ::::::::::::::::::::::::::::::::: 60 10.4 Other TAP commands:::::::::::::::::::::::::::::::::::::::: 62 10.5 TAP Events :::::::::::::::::::::::::::::::::::::::::::::::::: 62 10.6 Enabling and Disabling TAPs :::::::::::::::::::::::::::::::: 63 10.7 Autoprobing ::::::::::::::::::::::::::::::::::::::::::::::::: 64 10.8 DAP declaration (ARMv6-M, ARMv7 and ARMv8 targets) ::: 64 11 CPU Configuration ::::::::::::::::::::::::::: 67 11.1 Target List ::::::::::::::::::::::::::::::::::::::::::::::::::: 67 11.2 Target CPU Types ::::::::::::::::::::::::::::::::::::::::::: 68 11.3 Target Configuration ::::::::::::::::::::::::::::::::::::::::: 69 11.4 Other $target name Commands :::::::::::::::::::::::::::::: 72 11.5 Target Events :::::::::::::::::::::::::::::::::::::::::::::::: 74 12 Flash Commands ::::::::::::::::::::::::::::: 77 12.1 Flash Configuration Commands :::::::::::::::::::::::::::::: 77 12.2 Preparing a Target before Flash Programming :::::::::::::::: 78 12.3 Erasing, Reading, Writing to Flash ::::::::::::::::::::::::::: 78 12.4 Other Flash commands ::::::::::::::::::::::::::::::::::::::: 80 12.5 Flash Driver List ::::::::::::::::::::::::::::::::::::::::::::: 81 12.5.1 External Flash :::::::::::::::::::::::::::::::::::::::::: 81 12.5.2 Internal Flash (Microcontrollers)::::::::::::::::::::::::: 86 12.6 NAND Flash Commands :::::::::::::::::::::::::::::::::::: 111 12.6.1 NAND Configuration Commands ::::::::::::::::::::::: 112 12.6.2 Erasing, Reading, Writing to NAND Flash :::::::::::::: 112 12.6.3 Other NAND commands ::::::::::::::::::::::::::::::: 114 12.6.4 NAND Driver List:::::::::::::::::::::::::::::::::::::: 115 13 Flash Programming ::::::::::::::::::::::::: 118 14 PLD/FPGA Commands