Open On-Chip Debugger: OpenOCD User's Guide for release 0.7.0 4 May 2013 This User's Guide documents release 0.7.0, dated 4 May 2013, of the Open On-Chip De- bugger (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 :::::::::::::::::::::::::::::::::::::: 10 4 Running:::::::::::::::::::::::::::::::::::::::::::: 11 5 OpenOCD Project Setup :::::::::::::::::::::::::::::: 13 6 Config File Guidelines :::::::::::::::::::::::::::::::: 20 7 Daemon Configuration :::::::::::::::::::::::::::::::: 35 8 Debug Adapter Configuration :::::::::::::::::::::::::: 39 9 Reset Configuration :::::::::::::::::::::::::::::::::: 51 10 TAP Declaration ::::::::::::::::::::::::::::::::::::: 56 11 CPU Configuration ::::::::::::::::::::::::::::::::::: 62 12 Flash Commands :::::::::::::::::::::::::::::::::::: 71 13 Flash Programming :::::::::::::::::::::::::::::::::: 86 14 NAND Flash Commands :::::::::::::::::::::::::::::: 87 15 PLD/FPGA Commands ::::::::::::::::::::::::::::::: 94 16 General Commands :::::::::::::::::::::::::::::::::: 95 17 Architecture and Core Commands :::::::::::::::::::::: 101 18 JTAG Commands ::::::::::::::::::::::::::::::::::: 114 19 Boundary Scan Commands ::::::::::::::::::::::::::: 117 20 TFTP :::::::::::::::::::::::::::::::::::::::::::: 118 21 GDB and OpenOCD::::::::::::::::::::::::::::::::: 119 22 Tcl Scripting API ::::::::::::::::::::::::::::::::::: 123 23 FAQ :::::::::::::::::::::::::::::::::::::::::::::: 125 24 Tcl Crash Course ::::::::::::::::::::::::::::::::::: 130 A The GNU Free Documentation License. ::::::::::::::::: 136 OpenOCD Concept Index :::::::::::::::::::::::::::::::: 143 Command and Driver Index :::::::::::::::::::::::::::::: 145 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 OpenOCD Developer Mailing List :::::::::::::::::::::::::::::: 3 1.4 OpenOCD Bug Database::::::::::::::::::::::::::::::::::::::: 4 2 Debug Adapter Hardware:::::::::::::::::::::: 5 2.1 Choosing a Dongle ::::::::::::::::::::::::::::::::::::::::::::: 5 2.2 Stand alone Systems ::::::::::::::::::::::::::::::::::::::::::: 5 2.3 USB FT2232 Based :::::::::::::::::::::::::::::::::::::::::::: 5 2.4 USB-JTAG / Altera USB-Blaster compatibles :::::::::::::::::: 7 2.5 USB JLINK 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 Other::::::::::::::::::::::::::::::::::::::::::::::::::::: 8 2.10 IBM PC Parallel Printer Port Based::::::::::::::::::::::::::: 8 2.11 Other... ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 9 3 About Jim-Tcl ::::::::::::::::::::::::::::::::: 10 4 Running :::::::::::::::::::::::::::::::::::::::: 11 4.1 Simple setup, no customization :::::::::::::::::::::::::::::::: 11 4.2 What OpenOCD does as it starts ::::::::::::::::::::::::::::: 12 5 OpenOCD Project Setup ::::::::::::::::::::: 13 5.1 Hooking up the JTAG Adapter:::::::::::::::::::::::::::::::: 13 5.2 Project Directory ::::::::::::::::::::::::::::::::::::::::::::: 14 5.3 Configuration Basics :::::::::::::::::::::::::::::::::::::::::: 14 5.4 User Config Files:::::::::::::::::::::::::::::::::::::::::::::: 14 5.5 Project-Specific Utilities::::::::::::::::::::::::::::::::::::::: 16 5.6 Target Software Changes :::::::::::::::::::::::::::::::::::::: 17 5.7 Target Hardware Setup ::::::::::::::::::::::::::::::::::::::: 18 iii 6 Config File Guidelines :::::::::::::::::::::::: 20 6.1 Interface Config Files ::::::::::::::::::::::::::::::::::::::::: 24 6.2 Board Config Files :::::::::::::::::::::::::::::::::::::::::::: 25 6.2.1 Communication Between Config files:::::::::::::::::::::: 25 6.2.2 Variable Naming Convention ::::::::::::::::::::::::::::: 26 6.2.3 The reset-init Event Handler ::::::::::::::::::::::::::::: 26 6.2.4 JTAG Clock Rate :::::::::::::::::::::::::::::::::::::::: 27 6.2.5 The init board procedure::::::::::::::::::::::::::::::::: 27 6.3 Target Config Files:::::::::::::::::::::::::::::::::::::::::::: 28 6.3.1 Default Value Boiler Plate Code :::::::::::::::::::::::::: 29 6.3.2 Adding TAPs to the Scan Chain:::::::::::::::::::::::::: 29 6.3.3 Add CPU targets :::::::::::::::::::::::::::::::::::::::: 30 6.3.4 Define CPU targets working in SMP:::::::::::::::::::::: 30 6.3.5 Chip Reset Setup :::::::::::::::::::::::::::::::::::::::: 31 6.3.6 The init targets procedure:::::::::::::::::::::::::::::::: 32 6.3.7 ARM Core Specific Hacks :::::::::::::::::::::::::::::::: 33 6.3.8 Internal Flash Configuration:::::::::::::::::::::::::::::: 33 6.4 Translating Configuration Files :::::::::::::::::::::::::::::::: 33 7 Daemon Configuration :::::::::::::::::::::::: 35 7.1 Configuration Stage ::::::::::::::::::::::::::::::::::::::::::: 35 7.2 Entering the Run Stage ::::::::::::::::::::::::::::::::::::::: 35 7.3 TCP/IP Ports :::::::::::::::::::::::::::::::::::::::::::::::: 36 7.4 GDB Configuration ::::::::::::::::::::::::::::::::::::::::::: 36 7.5 Event Polling ::::::::::::::::::::::::::::::::::::::::::::::::: 37 8 Debug Adapter Configuration :::::::::::::::: 39 8.1 Interface Configuration :::::::::::::::::::::::::::::::::::::::: 39 8.2 Interface Drivers :::::::::::::::::::::::::::::::::::::::::::::: 40 8.3 Transport Configuration::::::::::::::::::::::::::::::::::::::: 49 8.3.1 JTAG Transport ::::::::::::::::::::::::::::::::::::::::: 49 8.3.2 SWD Transport :::::::::::::::::::::::::::::::::::::::::: 49 8.3.3 SPI Transport:::::::::::::::::::::::::::::::::::::::::::: 49 8.4 JTAG Speed :::::::::::::::::::::::::::::::::::::::::::::::::: 49 9 Reset Configuration ::::::::::::::::::::::::::: 51 9.1 Types of Reset :::::::::::::::::::::::::::::::::::::::::::::::: 51 9.2 SRST and TRST Issues ::::::::::::::::::::::::::::::::::::::: 51 9.3 Commands for Handling Resets ::::::::::::::::::::::::::::::: 52 9.4 Custom Reset Handling ::::::::::::::::::::::::::::::::::::::: 54 iv 10 TAP Declaration ::::::::::::::::::::::::::::: 56 10.1 Scan Chains ::::::::::::::::::::::::::::::::::::::::::::::::: 56 10.2 TAP Names ::::::::::::::::::::::::::::::::::::::::::::::::: 57 10.3 TAP Declaration Commands ::::::::::::::::::::::::::::::::: 57 10.4 Other TAP commands ::::::::::::::::::::::::::::::::::::::: 59 10.5 TAP Events ::::::::::::::::::::::::::::::::::::::::::::::::: 59 10.6 Enabling and Disabling TAPs :::::::::::::::::::::::::::::::: 60 10.7 Autoprobing ::::::::::::::::::::::::::::::::::::::::::::::::: 61 11 CPU Configuration :::::::::::::::::::::::::: 62 11.1 Target List :::::::::::::::::::::::::::::::::::::::::::::::::: 62 11.2 Target CPU Types and Variants ::::::::::::::::::::::::::::: 63 11.3 Target Configuration ::::::::::::::::::::::::::::::::::::::::: 64 11.4 Other $target name Commands :::::::::::::::::::::::::::::: 66 11.5 Target Events:::::::::::::::::::::::::::::::::::::::::::::::: 68 12 Flash Commands ::::::::::::::::::::::::::::: 71 12.1 Flash Configuration Commands :::::::::::::::::::::::::::::: 71 12.2 Erasing, Reading, Writing to Flash ::::::::::::::::::::::::::: 72 12.3 Other Flash commands :::::::::::::::::::::::::::::::::::::: 74 12.4 Flash Driver List::::::::::::::::::::::::::::::::::::::::::::: 74 12.4.1 External Flash :::::::::::::::::::::::::::::::::::::::::: 74 12.4.2 Internal Flash (Microcontrollers) :::::::::::::::::::::::: 75 12.4.3 str9xpec driver :::::::::::::::::::::::::::::::::::::::::: 83 12.5 mFlash :::::::::::::::::::::::::::::::::::::::::::::::::::::: 85 12.5.1 mFlash Configuration ::::::::::::::::::::::::::::::::::: 85 12.5.2 mFlash commands :::::::::::::::::::::::::::::::::::::: 85 13 Flash Programming :::::::::::::::::::::::::: 86 14 NAND Flash Commands :::::::::::::::::::: 87 14.1 NAND Configuration Commands::::::::::::::::::::::::::::: 87 14.2 Erasing, Reading, Writing to NAND Flash ::::::::::::::::::: 88 14.3 Other NAND commands ::::::::::::::::::::::::::::::::::::: 90 14.4 NAND Driver List ::::::::::::::::::::::::::::::::::::::::::: 91 15 PLD/FPGA Commands ::::::::::::::::::::: 94 15.1 PLD/FPGA Configuration and Commands ::::::::::::::::::: 94 15.2 PLD/FPGA Drivers, Options, and Commands ::::::::::::::: 94 v 16 General Commands ::::::::::::::::::::::::::