Open On-Chip Debugger: OpenOCD User's Guide for release 0.10.0 19 June 2018 This User's Guide documents release 0.10.0, dated 19 June 2018, 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, with no Front-Cover Texts, and with 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 :::::::::::::::::::::::::::::::::: 49 10 TAP Declaration ::::::::::::::::::::::::::::::::::::: 54 11 CPU Configuration ::::::::::::::::::::::::::::::::::: 60 12 Flash Commands :::::::::::::::::::::::::::::::::::: 69 13 Flash Programming ::::::::::::::::::::::::::::::::: 100 14 PLD/FPGA Commands :::::::::::::::::::::::::::::: 101 15 General Commands:::::::::::::::::::::::::::::::::: 102 16 Architecture and Core Commands :::::::::::::::::::::: 109 17 JTAG Commands ::::::::::::::::::::::::::::::::::: 126 18 Boundary Scan Commands ::::::::::::::::::::::::::: 129 19 Utility Commands::::::::::::::::::::::::::::::::::: 130 20 TFTP :::::::::::::::::::::::::::::::::::::::::::: 131 21 GDB and OpenOCD::::::::::::::::::::::::::::::::: 132 22 Tcl Scripting API ::::::::::::::::::::::::::::::::::: 137 23 FAQ :::::::::::::::::::::::::::::::::::::::::::::: 140 24 Tcl Crash Course ::::::::::::::::::::::::::::::::::: 145 A The GNU Free Documentation License. ::::::::::::::::: 151 OpenOCD Concept Index :::::::::::::::::::::::::::::::: 158 Command and Driver Index :::::::::::::::::::::::::::::: 161 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 CMSIS-DAP based ::::::::::::::::::::::::::::::::::::::: 8 2.10 USB Other:::::::::::::::::::::::::::::::::::::::::::::::::::: 8 2.11 IBM PC Parallel Printer Port Based::::::::::::::::::::::::::: 9 2.12 Other... :::::::::::::::::::::::::::::::::::::::::::::::::::::: 10 3 About Jim-Tcl ::::::::::::::::::::::::::::::::: 11 4 Running :::::::::::::::::::::::::::::::::::::::: 12 4.1 Simple setup, no customization :::::::::::::::::::::::::::::::: 12 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 5.6 Target Software Changes :::::::::::::::::::::::::::::::::::::: 18 5.7 Target Hardware Setup ::::::::::::::::::::::::::::::::::::::: 19 iii 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 Interface Configuration :::::::::::::::::::::::::::::::::::::::: 36 8.2 Interface Drivers :::::::::::::::::::::::::::::::::::::::::::::: 37 8.3 Transport Configuration::::::::::::::::::::::::::::::::::::::: 46 8.3.1 JTAG Transport ::::::::::::::::::::::::::::::::::::::::: 46 8.3.2 SWD Transport :::::::::::::::::::::::::::::::::::::::::: 47 8.3.3 SPI Transport:::::::::::::::::::::::::::::::::::::::::::: 47 8.4 JTAG Speed :::::::::::::::::::::::::::::::::::::::::::::::::: 47 9 Reset Configuration ::::::::::::::::::::::::::: 49 9.1 Types of Reset :::::::::::::::::::::::::::::::::::::::::::::::: 49 9.2 SRST and TRST Issues ::::::::::::::::::::::::::::::::::::::: 49 9.3 Commands for Handling Resets ::::::::::::::::::::::::::::::: 50 9.4 Custom Reset Handling ::::::::::::::::::::::::::::::::::::::: 52 iv 10 TAP Declaration ::::::::::::::::::::::::::::: 54 10.1 Scan Chains ::::::::::::::::::::::::::::::::::::::::::::::::: 54 10.2 TAP Names ::::::::::::::::::::::::::::::::::::::::::::::::: 55 10.3 TAP Declaration Commands ::::::::::::::::::::::::::::::::: 55 10.4 Other TAP commands ::::::::::::::::::::::::::::::::::::::: 57 10.5 TAP Events ::::::::::::::::::::::::::::::::::::::::::::::::: 57 10.6 Enabling and Disabling TAPs :::::::::::::::::::::::::::::::: 57 10.7 Autoprobing ::::::::::::::::::::::::::::::::::::::::::::::::: 58 11 CPU Configuration :::::::::::::::::::::::::: 60 11.1 Target List :::::::::::::::::::::::::::::::::::::::::::::::::: 60 11.2 Target CPU Types::::::::::::::::::::::::::::::::::::::::::: 61 11.3 Target Configuration ::::::::::::::::::::::::::::::::::::::::: 62 11.4 Other $target name Commands :::::::::::::::::::::::::::::: 64 11.5 Target Events:::::::::::::::::::::::::::::::::::::::::::::::: 65 12 Flash Commands ::::::::::::::::::::::::::::: 69 12.1 Flash Configuration Commands :::::::::::::::::::::::::::::: 69 12.2 Erasing, Reading, Writing to Flash ::::::::::::::::::::::::::: 70 12.3 Other Flash commands :::::::::::::::::::::::::::::::::::::: 72 12.4 Flash Driver List::::::::::::::::::::::::::::::::::::::::::::: 72 12.4.1 External Flash :::::::::::::::::::::::::::::::::::::::::: 73 12.4.2 Internal Flash (Microcontrollers) :::::::::::::::::::::::: 75 12.5 NAND Flash Commands ::::::::::::::::::::::::::::::::::::: 92 12.5.1 NAND Configuration Commands :::::::::::::::::::::::: 93 12.5.2 Erasing, Reading, Writing to NAND Flash :::::::::::::: 94 12.5.3 Other NAND commands :::::::::::::::::::::::::::::::: 96 12.5.4 NAND Driver List :::::::::::::::::::::::::::::::::::::: 96 12.6 mFlash :::::::::::::::::::::::::::::::::::::::::::::::::::::: 98 12.6.1 mFlash Configuration ::::::::::::::::::::::::::::::::::: 98 12.6.2 mFlash commands :::::::::::::::::::::::::::::::::::::: 98 13 Flash Programming::::::::::::::::::::::::: 100 14 PLD/FPGA Commands:::::::::::::::::::: 101 14.1 PLD/FPGA Configuration