http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/69f466b5/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/openocd.texi ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/openocd.texi b/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/openocd.texi deleted file mode 100755 index 3e249c0..0000000 --- a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/openocd.texi +++ /dev/null @@ -1,9748 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename openocd.info -@settitle OpenOCD User's Guide -@dircategory Development -@direntry -* OpenOCD: (openocd). OpenOCD User's Guide -@end direntry -@paragraphindent 0 -@c %**end of header - -@include version.texi - -@copying - -This User's Guide documents -release @value{VERSION}, -dated @value{UPDATED}, -of the Open On-Chip Debugger (OpenOCD). - -@itemize @bullet -@item Copyright @copyright{} 2008 The OpenOCD Project -@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk} -@item Copyright @copyright{} 2008-2010 Oyvind Harboe @email{oyvind.harboe@@zylin.com} -@item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com} -@item Copyright @copyright{} 2009-2010 David Brownell -@end itemize - -@quotation -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''. -@end quotation -@end copying - -@titlepage -@titlefont{@emph{Open On-Chip Debugger:}} -@sp 1 -@title OpenOCD User's Guide -@subtitle for release @value{VERSION} -@subtitle @value{UPDATED} - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@ifnottex -@node Top -@top OpenOCD User's Guide - -@insertcopying -@end ifnottex - -@menu -* About:: About OpenOCD -* Developers:: OpenOCD Developer Resources -* Debug Adapter Hardware:: Debug Adapter Hardware -* About Jim-Tcl:: About Jim-Tcl -* Running:: Running OpenOCD -* OpenOCD Project Setup:: OpenOCD Project Setup -* Config File Guidelines:: Config File Guidelines -* Daemon Configuration:: Daemon Configuration -* Debug Adapter Configuration:: Debug Adapter Configuration -* Reset Configuration:: Reset Configuration -* TAP Declaration:: TAP Declaration -* CPU Configuration:: CPU Configuration -* Flash Commands:: Flash Commands -* Flash Programming:: Flash Programming -* PLD/FPGA Commands:: PLD/FPGA Commands -* General Commands:: General Commands -* Architecture and Core Commands:: Architecture and Core Commands -* JTAG Commands:: JTAG Commands -* Boundary Scan Commands:: Boundary Scan Commands -* Utility Commands:: Utility Commands -* TFTP:: TFTP -* GDB and OpenOCD:: Using GDB and OpenOCD -* Tcl Scripting API:: Tcl Scripting API -* FAQ:: Frequently Asked Questions -* Tcl Crash Course:: Tcl Crash Course -* License:: GNU Free Documentation License - -@comment DO NOT use the plain word ``Index'', reason: CYGWIN filename -@comment case issue with ``Index.html'' and ``index.html'' -@comment Occurs when creating ``--html --no-split'' output -@comment This fix is based on: http://sourceware.org/ml/binutils/2006-05/msg00215.html -* OpenOCD Concept Index:: Concept Index -* Command and Driver Index:: Command and Driver Index -@end menu - -@node About -@unnumbered About -@cindex about - -OpenOCD was created by Dominic Rath as part of a 2005 diploma thesis written -at the University of Applied Sciences Augsburg (@uref{http://www.hs-augsburg.de}). -Since that time, the project has grown into an active open-source project, -supported by a diverse community of software and hardware developers from -around the world. - -@section What is OpenOCD? -@cindex TAP -@cindex JTAG - -The Open On-Chip Debugger (OpenOCD) aims to provide debugging, -in-system programming and boundary-scan testing for embedded target -devices. - -It does so with the assistance of a @dfn{debug adapter}, which is -a small hardware module which helps provide the right kind of -electrical signaling to the target being debugged. These are -required since the debug host (on which OpenOCD runs) won't -usually have native support for such signaling, or the connector -needed to hook up to the target. - -Such debug adapters support one or more @dfn{transport} protocols, -each of which involves different 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 called @dfn{hardware interface dongles}. -Some development boards also integrate them directly, which may -let the development board connect directly to the debug -host over USB (and sometimes also to power it over USB). - -For example, a @dfn{JTAG Adapter} supports JTAG -signaling, and is used to communicate -with JTAG (IEEE 1149.1) compliant TAPs on your target board. -A @dfn{TAP} is a ``Test Access Port'', a module which processes -special instructions and data. TAPs are daisy-chained within and -between chips and boards. JTAG supports debugging and boundary -scan operations. - -There are also @dfn{SWD Adapters} that support Serial Wire Debug (SWD) -signaling to communicate with some newer ARM cores, as well as debug -adapters which support both JTAG and SWD transports. SWD supports only -debugging, whereas JTAG also supports boundary scan operations. - -For some chips, there are also @dfn{Programming Adapters} supporting -special transports used only to write code to flash memory, without -support for on-chip debugging or boundary scan. -(At this writing, OpenOCD does not support such non-debug adapters.) - - -@b{Dongles:} OpenOCD currently supports many types of hardware dongles: -USB-based, parallel port-based, and other standalone boxes that run -OpenOCD internally. @xref{Debug Adapter Hardware}. - -@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T, -ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x), Cortex-M3 -(Stellaris LM3, ST STM32 and Energy Micro EFM32) and Intel Quark (x10xx) -based cores to be debugged via the GDB protocol. - -@b{Flash 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, AT91SAM7, AT91SAM3U, -STR7x, STR9x, LM3, STM32x and EFM32). Preliminary support for various NAND flash -controllers (LPC3180, Orion, S3C24xx, more) is included. - -@section OpenOCD Web Site - -The OpenOCD web site provides the latest public news from the community: - -@uref{http://openocd.org/} - -@section Latest User's Guide: - -The user's guide you are now reading may not be the latest one -available. A version for more recent code may be available. -Its HTML form is published regularly at: - -@uref{http://openocd.org/doc/html/index.html} - -PDF form is likewise published at: - -@uref{http://openocd.org/doc/pdf/openocd.pdf} - -@section OpenOCD User's Forum - -There is an OpenOCD forum (phpBB) hosted by SparkFun, -which might be helpful to you. Note that if you want -anything to come to the attention of developers, you -should post it to the OpenOCD Developer Mailing List -instead of this forum. - -@uref{http://forum.sparkfun.com/viewforum.php?f=18} - -@section OpenOCD User's Mailing List - -The OpenOCD User Mailing List provides the primary means of -communication between users: - -@uref{https://lists.sourceforge.net/mailman/listinfo/openocd-user} - -@section OpenOCD IRC - -Support can also be found on irc: -@uref{irc://irc.freenode.net/openocd} - -@node Developers -@chapter OpenOCD Developer Resources -@cindex developers - -If 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 or interface drivers, improve the -documentation, as well as more conventional bug fixes and enhancements. - -The resources in this chapter are available for developers wishing to explore -or expand the OpenOCD source code. - -@section OpenOCD Git Repository - -During the 0.3.x release cycle, OpenOCD switched from Subversion to -a Git repository hosted at SourceForge. The repository URL is: - -@uref{git://git.code.sf.net/p/openocd/code} - -or via http - -@uref{http://git.code.sf.net/p/openocd/code} - -You may prefer to use a mirror and the HTTP protocol: - -@uref{http://repo.or.cz/r/openocd.git} - -With standard Git tools, use @command{git clone} to initialize -a local repository, and @command{git pull} to update it. -There are also gitweb pages letting you browse the repository -with a web browser, or download arbitrary snapshots without -needing a Git client: - -@uref{http://repo.or.cz/w/openocd.git} - -The @file{README} file contains the instructions for building the project -from the repository or a snapshot. - -Developers that want to contribute patches to the OpenOCD system are -@b{strongly} encouraged to work against mainline. -Patches created against older versions may require additional -work from their submitter in order to be updated for newer releases. - -@section Doxygen Developer Manual - -During the 0.2.x release cycle, the OpenOCD project began -providing a Doxygen reference manual. This document contains more -technical information about the software internals, development -processes, and similar documentation: - -@uref{http://openocd.org/doc/doxygen/html/index.html} - -This document is a work-in-progress, but contributions would be welcome -to fill in the gaps. All of the source files are provided in-tree, -listed in the Doxyfile configuration at the top of the source tree. - -@section Gerrit Review System - -All changes in the OpenOCD Git repository go through the web-based Gerrit -Code Review System: - -@uref{http://openocd.zylin.com/} - -After a one-time registration and repository setup, anyone can push commits -from their local Git repository directly into Gerrit. -All users and developers are encouraged to review, test, discuss and vote -for changes in Gerrit. The feedback provides the basis for a maintainer to -eventually submit the change to the main Git repository. - -The @file{HACKING} file, also available as the Patch Guide in the Doxygen -Developer Manual, contains basic information about how to connect a -repository to Gerrit, prepare and push patches. Patch authors are expected to -maintain their changes while they're in Gerrit, respond to feedback and if -necessary rework and push improved versions of the change. - -@section OpenOCD Developer Mailing List - -The OpenOCD Developer Mailing List provides the primary means of -communication between developers: - -@uref{https://lists.sourceforge.net/mailman/listinfo/openocd-devel} - -@section OpenOCD Bug Tracker - -The OpenOCD Bug Tracker is hosted on SourceForge: - -@uref{http://bugs.openocd.org/} - - -@node Debug Adapter Hardware -@chapter Debug Adapter Hardware -@cindex dongles -@cindex FTDI -@cindex wiggler -@cindex zy1000 -@cindex printer port -@cindex USB Adapter -@cindex RTCK - -Defined: @b{dongle}: A small device that plugs into a computer and serves as -an adapter .... [snip] - -In the OpenOCD case, this generally refers to @b{a small adapter} that -attaches to your computer via USB or the parallel port. One -exception is the Ultimate Solutions ZY1000, packaged as a small box you -attach via an ethernet cable. The ZY1000 has the advantage that it does not -require any drivers to be installed on the developer PC. It also has -a built in web interface. It supports RTCK/RCLK or adaptive clocking -and has a built-in relay to power cycle targets remotely. - - -@section Choosing a Dongle - -There are several things you should keep in mind when choosing a dongle. - -@enumerate -@item @b{Transport} Does it support the kind of communication that you need? -OpenOCD focusses mostly on JTAG. Your version may also support -other ways to communicate with target devices. -@item @b{Voltage} What voltage is your target - 1.8, 2.8, 3.3, or 5V? -Does your dongle support it? You might need a level converter. -@item @b{Pinout} What pinout does your target board use? -Does your dongle support it? You may be able to use jumper -wires, or an "octopus" connector, to convert pinouts. -@item @b{Connection} Does your computer have the USB, parallel, or -Ethernet port needed? -@item @b{RTCK} Do you expect to use it with ARM chips and boards with -RTCK support (also known as ``adaptive clocking'')? -@end enumerate - -@section Stand-alone JTAG Probe - -The ZY1000 from Ultimate Solutions is technically not a dongle but a -stand-alone JTAG probe that, unlike most dongles, doesn't require any drivers -running on the developer's host computer. -Once installed on a network using DHCP or a static IP assignment, users can -access the ZY1000 probe locally or remotely from any host with access to the -IP address assigned to the probe. -The ZY1000 provides an intuitive web interface with direct access to the -OpenOCD debugger. -Users may also run a GDBSERVER directly on the ZY1000 to take full advantage -of GCC & GDB to debug any distribution of embedded Linux or NetBSD running on -the target. -The ZY1000 supports RTCK & RCLK or adaptive clocking and has a built-in relay -to power cycle the target remotely. - -For more information, visit: - -@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/210-zylin-zy1000-main} - -@section USB FT2232 Based - -There are many USB JTAG dongles on the market, many of them based -on a chip from ``Future Technology Devices International'' (FTDI) -known as the FTDI FT2232; this is a USB full speed (12 Mbps) chip. -See: @url{http://www.ftdichip.com} for more information. -In summer 2009, USB high speed (480 Mbps) versions of these FTDI -chips started to become available in JTAG adapters. Around 2012, a new -variant appeared - FT232H - this is a single-channel version of FT2232H. -(Adapters using those high speed FT2232H or FT232H chips may support adaptive -clocking.) - -The FT2232 chips are flexible enough to support some other -transport options, such as SWD or the SPI variants used to -program some chips. They have two communications channels, -and one can be used for a UART adapter at the same time the -other one is used to provide a debug adapter. - -Also, some development boards integrate an FT2232 chip to serve as -a built-in low-cost debug adapter and USB-to-serial solution. - -@itemize @bullet -@item @b{usbjtag} -@* Link @url{http://elk.informatik.fh-augsburg.de/hhweb/doc/openocd/usbjtag/usbjtag.html} -@item @b{jtagkey} -@* See: @url{http://www.amontec.com/jtagkey.shtml} -@item @b{jtagkey2} -@* See: @url{http://www.amontec.com/jtagkey2.shtml} -@item @b{oocdlink} -@* See: @url{http://www.oocdlink.com} By Joern Kaipf -@item @b{signalyzer} -@* See: @url{http://www.signalyzer.com} -@item @b{Stellaris Eval Boards} -@* See: @url{http://www.ti.com} - The Stellaris eval boards -bundle FT2232-based JTAG and SWD support, which can be used to debug -the Stellaris chips. Using separate JTAG adapters is optional. -These boards can also be used in a "pass through" mode as JTAG adapters -to other target boards, disabling the Stellaris chip. -@item @b{TI/Luminary ICDI} -@* See: @url{http://www.ti.com} - TI/Luminary In-Circuit Debug -Interface (ICDI) Boards are included in Stellaris LM3S9B9x -Evaluation Kits. Like the non-detachable FT2232 support on the other -Stellaris eval boards, they can be used to debug other target boards. -@item @b{olimex-jtag} -@* See: @url{http://www.olimex.com} -@item @b{Flyswatter/Flyswatter2} -@* See: @url{http://www.tincantools.com} -@item @b{turtelizer2} -@* See: -@uref{http://www.ethernut.de/en/hardware/turtelizer/index.html, Turtelizer 2}, or -@url{http://www.ethernut.de} -@item @b{comstick} -@* Link: @url{http://www.hitex.com/index.php?id=383} -@item @b{stm32stick} -@* Link @url{http://www.hitex.com/stm32-stick} -@item @b{axm0432_jtag} -@* Axiom AXM-0432 Link @url{http://www.axman.com} - NOTE: This JTAG does not appear -to be available anymore as of April 2012. -@item @b{cortino} -@* Link @url{http://www.hitex.com/index.php?id=cortino} -@item @b{dlp-usb1232h} -@* Link @url{http://www.dlpdesign.com/usb/usb1232h.shtml} -@item @b{digilent-hs1} -@* Link @url{http://www.digilentinc.com/Products/Detail.cfm?Prod=JTAG-HS1} -@item @b{opendous} -@* Link @url{http://code.google.com/p/opendous/wiki/JTAG} FT2232H-based -(OpenHardware). -@item @b{JTAG-lock-pick Tiny 2} -@* Link @url{http://www.distortec.com/jtag-lock-pick-tiny-2} FT232H-based - -@item @b{GW16042} -@* Link: @url{http://shop.gateworks.com/index.php?route=product/product&path=70_80&product_id=64} -FT2232H-based - -@end itemize -@section USB-JTAG / Altera USB-Blaster compatibles - -These devices also show up as FTDI devices, but are not -protocol-compatible with the FT2232 devices. They are, however, -protocol-compatible among themselves. USB-JTAG devices typically consist -of a FT245 followed by a CPLD that understands a particular protocol, -or emulates this protocol using some other hardware. - -They may appear under different USB VID/PID depending on the particular -product. The driver can be configured to search for any VID/PID pair -(see the section on driver commands). - -@itemize -@item @b{USB-JTAG} Kolja Waschk's USB Blaster-compatible adapter -@* Link: @url{http://ixo-jtag.sourceforge.net/} -@item @b{Altera USB-Blaster} -@* Link: @url{http://www.altera.com/literature/ug/ug_usb_blstr.pdf} -@end itemize - -@section USB J-Link based -There are several OEM versions of the SEGGER @b{J-Link} adapter. It is -an example of a microcontroller based JTAG adapter, it uses an -AT91SAM764 internally. - -@itemize @bullet -@item @b{SEGGER J-Link} -@* Link: @url{http://www.segger.com/jlink.html} -@item @b{Atmel SAM-ICE} (Only works with Atmel chips!) -@* Link: @url{http://www.atmel.com/tools/atmelsam-ice.aspx} -@item @b{IAR J-Link} -@end itemize - -@section USB RLINK based -Raisonance has an adapter called @b{RLink}. It exists in a stripped-down form on the STM32 Primer, -permanently attached to the JTAG lines. It also exists on the STM32 Primer2, but that is wired for -SWD and not JTAG, thus not supported. - -@itemize @bullet -@item @b{Raisonance RLink} -@* Link: @url{http://www.mcu-raisonance.com/~rlink-debugger-programmer__@/microcontrollers__tool~tool__T018:4cn9ziz4bnx6.html} -@item @b{STM32 Primer} -@* Link: @url{http://www.stm32circle.com/resources/stm32primer.php} -@item @b{STM32 Primer2} -@* Link: @url{http://www.stm32circle.com/resources/stm32primer2.php} -@end itemize - -@section USB ST-LINK based -ST Micro has an adapter called @b{ST-LINK}. -They only work with ST Micro chips, notably STM32 and STM8. - -@itemize @bullet -@item @b{ST-LINK} -@* This is available standalone and as part of some kits, eg. STM32VLDISCOVERY. -@* Link: @url{http://www.st.com/internet/evalboard/product/219866.jsp} -@item @b{ST-LINK/V2} -@* This is available standalone and as part of some kits, eg. STM32F4DISCOVERY. -@* Link: @url{http://www.st.com/internet/evalboard/product/251168.jsp} -@end itemize - -For info the original ST-LINK enumerates using the mass storage usb class; however, -its implementation is completely broken. The result is this causes issues under Linux. -The simplest solution is to get Linux to ignore the ST-LINK using one of the following methods: -@itemize @bullet -@item modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i -@item add "options usb-storage quirks=483:3744:i" to /etc/modprobe.conf -@end itemize - -@section USB TI/Stellaris ICDI based -Texas Instruments has an adapter called @b{ICDI}. -It is not to be confused with the FTDI based adapters that were originally fitted to their -evaluation boards. This is the adapter fitted to the Stellaris LaunchPad. - -@section USB CMSIS-DAP based -ARM has released a interface standard called CMSIS-DAP that simplifies connecting -debuggers to ARM Cortex based targets @url{http://www.keil.com/support/man/docs/dapdebug/dapdebug_introduction.htm}. - -@section USB Other -@itemize @bullet -@item @b{USBprog} -@* Link: @url{http://shop.embedded-projects.net/} - which uses an Atmel MEGA32 and a UBN9604 - -@item @b{USB - Presto} -@* Link: @url{http://tools.asix.net/prg_presto.htm} - -@item @b{Versaloon-Link} -@* Link: @url{http://www.versaloon.com} - -@item @b{ARM-JTAG-EW} -@* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html} - -@item @b{Buspirate} -@* Link: @url{http://dangerousprototypes.com/bus-pirate-manual/} - -@item @b{opendous} -@* Link: @url{http://code.google.com/p/opendous-jtag/} - which uses an AT90USB162 - -@item @b{estick} -@* Link: @url{http://code.google.com/p/estick-jtag/} - -@item @b{Keil ULINK v1} -@* Link: @url{http://www.keil.com/ulink1/} -@end itemize - -@section IBM PC Parallel Printer Port Based - -The two well-known ``JTAG Parallel Ports'' cables are the Xilinx DLC5 -and the Macraigor Wiggler. There are many clones and variations of -these on the market. - -Note that parallel ports are becoming much less common, so if you -have the choice you should probably avoid these adapters in favor -of USB-based ones. - -@itemize @bullet - -@item @b{Wiggler} - There are many clones of this. -@* Link: @url{http://www.macraigor.com/wiggler.htm} - -@item @b{DLC5} - From XILINX - There are many clones of this -@* Link: Search the web for: ``XILINX DLC5'' - it is no longer -produced, PDF schematics are easily found and it is easy to make. - -@item @b{Amontec - JTAG Accelerator} -@* Link: @url{http://www.amontec.com/jtag_accelerator.shtml} - -@item @b{Wiggler2} -@* Link: @url{http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag} - -@item @b{Wiggler_ntrst_inverted} -@* Yet another variation - See the source code, src/jtag/parport.c - -@item @b{old_amt_wiggler} -@* Unknown - probably not on the market today - -@item @b{arm-jtag} -@* Link: Most likely @url{http://www.olimex.com/dev/arm-jtag.html} [another wiggler clone] - -@item @b{chameleon} -@* Link: @url{http://www.amontec.com/chameleon.shtml} - -@item @b{Triton} -@* Unknown. - -@item @b{Lattice} -@* ispDownload from Lattice Semiconductor -@url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf} - -@item @b{flashlink} -@* From ST Microsystems; -@* Link: @url{http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATA_BRIEF/DM00039500.pdf} - -@end itemize - -@section Other... -@itemize @bullet - -@item @b{ep93xx} -@* An EP93xx based Linux machine using the GPIO pins directly. - -@item @b{at91rm9200} -@* Like the EP93xx - but an ATMEL AT91RM9200 based solution using the GPIO pins on the chip. - -@item @b{bcm2835gpio} -@* A BCM2835-based board (e.g. Raspberry Pi) using the GPIO pins of the expansion header. - -@item @b{jtag_vpi} -@* A JTAG driver acting as a client for the JTAG VPI server interface. -@* Link: @url{http://github.com/fjullien/jtag_vpi} - -@end itemize - -@node About Jim-Tcl -@chapter About Jim-Tcl -@cindex Jim-Tcl -@cindex tcl - -OpenOCD uses a small ``Tcl Interpreter'' known as Jim-Tcl. -This programming language provides a simple and extensible -command interpreter. - -All commands presented in this Guide are extensions to Jim-Tcl. -You can use them as simple commands, without needing to learn -much of anything about Tcl. -Alternatively, you can write Tcl programs with them. - -You can learn more about Jim at its website, @url{http://jim.tcl.tk}. -There is an active and responsive community, get on the mailing list -if you have any questions. Jim-Tcl maintainers also lurk on the -OpenOCD mailing list. - -@itemize @bullet -@item @b{Jim vs. Tcl} -@* Jim-Tcl is a stripped down version of the well known Tcl language, -which can be found here: @url{http://www.tcl.tk}. Jim-Tcl has far -fewer features. Jim-Tcl is several dozens of .C files and .H files and -implements the basic Tcl command set. In contrast: Tcl 8.6 is a -4.2 MB .zip file containing 1540 files. - -@item @b{Missing Features} -@* Our practice has been: Add/clone the real Tcl feature if/when -needed. We welcome Jim-Tcl improvements, not bloat. Also there -are a large number of optional Jim-Tcl features that are not -enabled in OpenOCD. - -@item @b{Scripts} -@* OpenOCD configuration scripts are Jim-Tcl Scripts. OpenOCD's -command interpreter today is a mixture of (newer) -Jim-Tcl commands, and the (older) original command interpreter. - -@item @b{Commands} -@* At the OpenOCD telnet command line (or via the GDB monitor command) one -can type a Tcl for() loop, set variables, etc. -Some of the commands documented in this guide are implemented -as Tcl scripts, from a @file{startup.tcl} file internal to the server. - -@item @b{Historical Note} -@* Jim-Tcl was introduced to OpenOCD in spring 2008. Fall 2010, -before OpenOCD 0.5 release, OpenOCD switched to using Jim-Tcl -as a Git submodule, which greatly simplified upgrading Jim-Tcl -to benefit from new features and bugfixes in Jim-Tcl. - -@item @b{Need a crash course in Tcl?} -@*@xref{Tcl Crash Course}. -@end itemize - -@node Running -@chapter Running -@cindex command line options -@cindex logfile -@cindex directory search - -Properly installing OpenOCD sets up your operating system to grant it access -to the debug adapters. On Linux, this usually involves installing a file -in @file{/etc/udev/rules.d,} so OpenOCD has permissions. An example rules file -that works for many common adapters is shipped with OpenOCD in the -@file{contrib} directory. MS-Windows needs -complex and confusing driver configuration for every peripheral. Such issues -are unique to each operating system, and are not detailed in this User's Guide. - -Then later you will invoke the OpenOCD server, with various options to -tell it how each debug session should work. -The @option{--help} option shows: -@verbatim -bash$ openocd --help - ---help | -h display this help ---version | -v display OpenOCD version ---file | -f use configuration file <name> ---search | -s dir to search for config files and scripts ---debug | -d set debug level <0-3> ---log_output | -l redirect log output to file <name> ---command | -c run <command> -@end verbatim - -If you don't give any @option{-f} or @option{-c} options, -OpenOCD tries to read the configuration file @file{openocd.cfg}. -To specify one or more different -configuration files, use @option{-f} options. For example: - -@example -openocd -f config1.cfg -f config2.cfg -f config3.cfg -@end example - -Configuration files and scripts are searched for in -@enumerate -@item the current directory, -@item any search dir specified on the command line using the @option{-s} option, -@item any search dir specified using the @command{add_script_search_dir} command, -@item @file{$HOME/.openocd} (not on Windows), -@item a directory in the @env{OPENOCD_SCRIPTS} environment variable (if set), -@item the site wide script library @file{$pkgdatadir/site} and -@item the OpenOCD-supplied script library @file{$pkgdatadir/scripts}. -@end enumerate -The first found file with a matching file name will be used. - -@quotation Note -Don't try to use configuration script names or paths which -include the "#" character. That character begins Tcl comments. -@end quotation - -@section Simple setup, no customization - -In the best case, you can use two scripts from one of the script -libraries, hook up your JTAG adapter, and start the server ... and -your JTAG setup will just work "out of the box". Always try to -start by reusing those scripts, but assume you'll need more -customization even if this works. @xref{OpenOCD Project Setup}. - -If you find a script for your JTAG adapter, and for your board or -target, you may be able to hook up your JTAG adapter then start -the server with some variation of one of the following: - -@example -openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg -openocd -f interface/ftdi/ADAPTER.cfg -f board/MYBOARD.cfg -@end example - -You might also need to configure which reset signals are present, -using @option{-c 'reset_config trst_and_srst'} or something similar. -If all goes well you'll see output something like - -@example -Open On-Chip Debugger 0.4.0 (2010-01-14-15:06) -For bug reports, read - http://openocd.org/doc/doxygen/bugs.html -Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477 - (mfg: 0x23b, part: 0xba00, ver: 0x3) -@end example - -Seeing that "tap/device found" message, and no warnings, means -the JTAG communication is working. That's a key milestone, but -you'll probably need more project-specific setup. - -@section What OpenOCD does as it starts - -OpenOCD starts by processing the configuration commands provided -on the command line or, if there were no @option{-c command} or -@option{-f file.cfg} options given, in @file{openocd.cfg}. -@xref{configurationstage,,Configuration Stage}. -At the end of the configuration stage it verifies the JTAG scan -chain defined using those commands; your configuration should -ensure that this always succeeds. -Normally, OpenOCD then starts running as a daemon. -Alternatively, commands may be used to terminate the configuration -stage early, perform work (such as updating some flash memory), -and then shut down without acting as a daemon. - -Once OpenOCD starts running as a daemon, it waits for connections from -clients (Telnet, GDB, Other) and processes the commands issued through -those channels. - -If you are having problems, you can enable internal debug messages via -the @option{-d} option. - -Also it is possible to interleave Jim-Tcl commands w/config scripts using the -@option{-c} command line switch. - -To enable debug output (when reporting problems or working on OpenOCD -itself), use the @option{-d} command line switch. This sets the -@option{debug_level} to "3", outputting the most information, -including debug messages. The default setting is "2", outputting only -informational messages, warnings and errors. You can also change this -setting from within a telnet or gdb session using @command{debug_level<n>} -(@pxref{debuglevel,,debug_level}). - -You can redirect all output from the daemon to a file using the -@option{-l <logfile>} switch. - -Note! OpenOCD will launch the GDB & telnet server even if it can not -establish a connection with the target. In general, it is possible for -the JTAG controller to be unresponsive until the target is set up -correctly via e.g. GDB monitor commands in a GDB init script. - -@node OpenOCD Project Setup -@chapter OpenOCD Project Setup - -To use OpenOCD with your development projects, you need to do more than -just connect the JTAG adapter hardware (dongle) to your development board -and start the OpenOCD server. -You also need to configure your OpenOCD server so that it knows -about your adapter and board, and helps your work. -You may also want to connect OpenOCD to GDB, possibly -using Eclipse or some other GUI. - -@section Hooking up the JTAG Adapter - -Today's most common case is a dongle with a JTAG cable on one side -(such as a ribbon cable with a 10-pin or 20-pin IDC connector) -and a USB cable on the other. -Instead of USB, some cables use Ethernet; -older ones may use a PC parallel port, or even a serial port. - -@enumerate -@item @emph{Start with power to your target board turned off}, -and nothing connected to your JTAG adapter. -If you're particularly paranoid, unplug power to the board. -It's important to have the ground signal properly set up, -unless you are using a JTAG adapter which provides -galvanic isolation between the target board and the -debugging host. - -@item @emph{Be sure it's the right kind of JTAG connector.} -If your dongle has a 20-pin ARM connector, you need some kind -of adapter (or octopus, see below) to hook it up to -boards using 14-pin or 10-pin connectors ... or to 20-pin -connectors which don't use ARM's pinout. - -In the same vein, make sure the voltage levels are compatible. -Not all JTAG adapters have the level shifters needed to work -with 1.2 Volt boards. - -@item @emph{Be certain the cable is properly oriented} or you might -damage your board. In most cases there are only two possible -ways to connect the cable. -Connect the JTAG cable from your adapter to the board. -Be sure it's firmly connected. - -In the best case, the connector is keyed to physically -prevent you from inserting it wrong. -This is most often done using a slot on the board's male connector -housing, which must match a key on the JTAG cable's female connector. -If there's no housing, then you must look carefully and -make sure pin 1 on the cable hooks up to pin 1 on the board. -Ribbon cables are frequently all grey except for a wire on one -edge, which is red. The red wire is pin 1. - -Sometimes dongles provide cables where one end is an ``octopus'' of -color coded single-wire connectors, instead of a connector block. -These are great when converting from one JTAG pinout to another, -but are tedious to set up. -Use these with connector pinout diagrams to help you match up the -adapter signals to the right board pins. - -@item @emph{Connect the adapter's other end} once the JTAG cable is connected. -A USB, parallel, or serial port connector will go to the host which -you are using to run OpenOCD. -For Ethernet, consult the documentation and your network administrator. - -For USB-based JTAG adapters you have an easy sanity check at this point: -does the host operating system see the JTAG adapter? If you're running -Linux, try the @command{lsusb} command. If that host is an -MS-Windows host, you'll need to install a driver before OpenOCD works. - -@item @emph{Connect the adapter's power supply, if needed.} -This step is primarily for non-USB adapters, -but sometimes USB adapters need extra power. - -@item @emph{Power up the target board.} -Unless you just let the magic smoke escape, -you're now ready to set up the OpenOCD server -so you can use JTAG to work with that board. - -@end enumerate - -Talk with the OpenOCD server using -telnet (@code{telnet localhost 4444} on many systems) or GDB. -@xref{GDB and OpenOCD}. - -@section Project Directory - -There are many ways you can configure OpenOCD and start it up. - -A simple way to organize them all involves keeping a -single directory for your work with a given board. -When you start OpenOCD from that directory, -it searches there first for configuration files, scripts, -files accessed through semihosting, -and for code you upload to the target board. -It is also the natural place to write files, -such as log files and data you download from the board. - -@section Configuration Basics - -There are two basic ways of configuring OpenOCD, and -a variety of ways you can mix them. -Think of the difference as just being how you start the server: - -@itemize -@item Many @option{-f file} or @option{-c command} options on the command line -@item No options, but a @dfn{user config file} -in the current directory named @file{openocd.cfg} -@end itemize - -Here is an example @file{openocd.cfg} file for a setup -using a Signalyzer FT2232-based JTAG adapter to talk to -a board with an Atmel AT91SAM7X256 microcontroller: - -@example -source [find interface/signalyzer.cfg] - -# GDB can also flash my flash! -gdb_memory_map enable -gdb_flash_program enable - -source [find target/sam7x256.cfg] -@end example - -Here is the command line equivalent of that configuration: - -@example -openocd -f interface/signalyzer.cfg \ - -c "gdb_memory_map enable" \ - -c "gdb_flash_program enable" \ - -f target/sam7x256.cfg -@end example - -You could wrap such long command lines in shell scripts, -each supporting a different development task. -One might re-flash the board with a specific firmware version. -Another might set up a particular debugging or run-time environment. - -@quotation Important -At this writing (October 2009) the command line method has -problems with how it treats variables. -For example, after @option{-c "set VAR value"}, or doing the -same in a script, the variable @var{VAR} will have no value -that can be tested in a later script. -@end quotation - -Here we will focus on the simpler solution: one user config -file, including basic configuration plus any TCL procedures -to simplify your work. - -@section User Config Files -@cindex config file, user -@cindex user config file -@cindex config file, overview - -A user configuration file ties together all the parts of a project -in one place. -One of the following will match your situation best: - -@itemize -@item Ideally almost everything comes from configuration files -provided by someone else. -For example, OpenOCD distributes a @file{scripts} directory -(probably in @file{/usr/share/openocd/scripts} on Linux). -Board and tool vendors can provide these too, as can individual -user sites; the @option{-s} command line option lets you say -where to find these files. (@xref{Running}.) -The AT91SAM7X256 example above works this way. - -Three main types of non-user configuration file each have their -own subdirectory in the @file{scripts} directory: - -@enumerate -@item @b{interface} -- one for each different debug adapter; -@item @b{board} -- one for each different board -@item @b{target} -- the chips which integrate CPUs and other JTAG TAPs -@end enumerate - -Best case: include just two files, and they handle everything else. -The first is an interface config file. -The second is board-specific, and it sets up the JTAG TAPs and -their GDB targets (by deferring to some @file{target.cfg} file), -declares all flash memory, and leaves you nothing to do except -meet your deadline: - -@example -source [find interface/olimex-jtag-tiny.cfg] -source [find board/csb337.cfg] -@end example - -Boards with a single microcontroller often won't need more -than the target config file, as in the AT91SAM7X256 example. -That's because there is no external memory (flash, DDR RAM), and -the board differences are encapsulated by application code. - -@item Maybe you don't know yet what your board looks like to JTAG. -Once you know the @file{interface.cfg} file to use, you may -need help from OpenOCD to discover what's on the board. -Once you find the JTAG TAPs, you can just search for appropriate -target and board -configuration files ... or write your own, from the bottom up. -@xref{autoprobing,,Autoprobing}. - -@item You can often reuse some standard config files but -need to write a few new ones, probably a @file{board.cfg} file. -You will be using commands described later in this User's Guide, -and working with the guidelines in the next chapter. - -For example, there may be configuration files for your JTAG adapter -and target chip, but you need a new board-specific config file -giving access to your particular flash chips. -Or you might need to write another target chip configuration file -for a new chip built around the Cortex M3 core. - -@quotation Note -When you write new configuration files, please submit -them for inclusion in the next OpenOCD release. -For example, a @file{board/newboard.cfg} file will help the -next users of that board, and a @file{target/newcpu.cfg} -will help support users of any board using that chip. -@end quotation - -@item -You may may need to write some C code. -It may be as simple as supporting a new FT2232 or parport -based adapter; a bit more involved, like a NAND or NOR flash -controller driver; or a big piece of work like supporting -a new chip architecture. -@end itemize - -Reuse the existing config files when you can. -Look first in the @file{scripts/boards} area, then @file{scripts/targets}. -You may find a board configuration that's a good example to follow. - -When you write config files, separate the reusable parts -(things every user of that interface, chip, or board needs) -from ones specific to your environment and debugging approach. -@itemize - -@item -For example, a @code{gdb-attach} event handler that invokes -the @command{reset init} command will interfere with debugging -early boot code, which performs some of the same actions -that the @code{reset-init} event handler does. - -@item -Likewise, the @command{arm9 vector_catch} command (or -@cindex vector_catch -its siblings @command{xscale vector_catch} -and @command{cortex_m vector_catch}) can be a timesaver -during some debug sessions, but don't make everyone use that either. -Keep those kinds of debugging aids in your user config file, -along with messaging and tracing setup. -(@xref{softwaredebugmessagesandtracing,,Software Debug Messages and Tracing}.) - -@item -You might need to override some defaults. -For example, you might need to move, shrink, or back up the target's -work area if your application needs much SRAM. - -@item -TCP/IP port configuration is another example of something which -is environment-specific, and should only appear in -a user config file. @xref{tcpipports,,TCP/IP Ports}. -@end itemize - -@section Project-Specific Utilities - -A few project-specific utility -routines may well speed up your work. -Write them, and keep them in your project's user config file. - -For example, if you are making a boot loader work on a -board, it's nice to be able to debug the ``after it's -loaded to RAM'' parts separately from the finicky early -code which sets up the DDR RAM controller and clocks. -A script like this one, or a more GDB-aware sibling, -may help: - -@example -proc ramboot @{ @} @{ - # Reset, running the target's "reset-init" scripts - # to initialize clocks and the DDR RAM controller. - # Leave the CPU halted. - reset init - - # Load CONFIG_SKIP_LOWLEVEL_INIT version into DDR RAM. - load_image u-boot.bin 0x20000000 - - # Start running. - resume 0x20000000 -@} -@end example - -Then once that code is working you will need to make it -boot from NOR flash; a different utility would help. -Alternatively, some developers write to flash using GDB. -(You might use a similar script if you're working with a flash -based microcontroller application instead of a boot loader.) - -@example -proc newboot @{ @} @{ - # Reset, leaving the CPU halted. The "reset-init" event - # proc gives faster access to the CPU and to NOR flash; - # "reset halt" would be slower. - reset init - - # Write standard version of U-Boot into the first two - # sectors of NOR flash ... the standard version should - # do the same lowlevel init as "reset-init". - flash protect 0 0 1 off - flash erase_sector 0 0 1 - flash write_bank 0 u-boot.bin 0x0 - flash protect 0 0 1 on - - # Reboot from scratch using that new boot loader. - reset run -@} -@end example - -You may need more complicated utility procedures when booting -from NAND. -That often involves an extra bootloader stage, -running from on-chip SRAM to perform DDR RAM setup so it can load -the main bootloader code (which won't fit into that SRAM). - -Other helper scripts might be used to write production system images, -involving considerably more than just a three stage bootloader. - -@section Target Software Changes - -Sometimes you may want to make some small changes to the software -you're developing, to help make JTAG debugging work better. -For example, in C or assembly language code you might -use @code{#ifdef JTAG_DEBUG} (or its converse) around code -handling issues like: - -@itemize @bullet - -@item @b{Watchdog Timers}... -Watchog timers are typically used to automatically reset systems if -some application task doesn't periodically reset the timer. (The -assumption is that the system has locked up if the task can't run.) -When a JTAG debugger halts the system, that task won't be able to run -and reset the timer ... potentially causing resets in the middle of -your debug sessions. - -It's rarely a good idea to disable such watchdogs, since their usage -needs to be debugged just like all other parts of your firmware. -That might however be your only option. - -Look instead for chip-specific ways to stop the watchdog from counting -while the system is in a debug halt state. It may be simplest to set -that non-counting mode in your debugger startup scripts. You may however -need a different approach when, for example, a motor could be physically -damaged by firmware remaining inactive in a debug halt state. That might -involve a type of firmware mode where that "non-counting" mode is disabled -at the beginning then re-enabled at the end; a watchdog reset might fire -and complicate the debug session, but hardware (or people) would be -protected.@footnote{Note that many systems support a "monitor mode" debug -that is a somewhat cleaner way to address such issues. You can think of -it as only halting part of the system, maybe just one task, -instead of the whole thing. -At this writing, January 2010, OpenOCD based debugging does not support -monitor mode debug, only "halt mode" debug.} - -@item @b{ARM Semihosting}... -@cindex ARM semihosting -When linked with a special runtime library provided with many -toolchains@footnote{See chapter 8 "Semihosting" in -@uref{http://infocenter.arm.com/help/topic/com.arm.doc.dui0203i/DUI0203I_rvct_developer_guide.pdf, -ARM DUI 0203I}, the "RealView Compilation Tools Developer Guide". -The CodeSourcery EABI toolchain also includes a semihosting library.}, -your target code can use I/O facilities on the debug host. That library -provides a small set of system calls which are handled by OpenOCD. -It can let the debugger provide your system console and a file system, -helping with early debugging or providing a more capable environment -for sometimes-complex tasks like installing system firmware onto -NAND or SPI flash. - -@item @b{ARM Wait-For-Interrupt}... -Many ARM chips synchronize the JTAG clock using the core clock. -Low power states which stop that core clock thus prevent JTAG access. -Idle loops in tasking environments often enter those low power states -via the @code{WFI} instruction (or its coprocessor equivalent, before ARMv7). - -You may want to @emph{disable that instruction} in source code, -or otherwise prevent using that state, -to ensure you can get JTAG access at any time.@footnote{As a more -polite alternative, some processors have special debug-oriented -registers which can be used to change various features including -how the low power states are clocked while debugging. -The STM32 DBGMCU_CR register is an example; at the cost of extra -power consumption, JTAG can be used during low power states.} -For example, the OpenOCD @command{halt} command may not -work for an idle processor otherwise. - -@item @b{Delay after reset}... -Not all chips have good support for debugger access -right after reset; many LPC2xxx chips have issues here. -Similarly, applications that reconfigure pins used for -JTAG access as they start will also block debugger access. - -To work with boards like this, @emph{enable a short delay loop} -the first thing after reset, before "real" startup activities. -For example, one second's delay is usually more than enough -time for a JTAG debugger to attach, so that -early code execution can be debugged -or firmware can be replaced. - -@item @b{Debug Communications Channel (DCC)}... -Some processors include mechanisms to send messages over JTAG. -Many ARM cores support these, as do some cores from other vendors. -(OpenOCD may be able to use this DCC internally, speeding up some -operations like writing to memory.) - -Your application may want to deliver various debugging messages -over JTAG, by @emph{linking with a small library of code} -provided with OpenOCD and using the utilities there to send -various kinds of message. -@xref{softwaredebugmessagesandtracing,,Software Debug Messages and Tracing}. - -@end itemize - -@section Target Hardware Setup - -Chip vendors often provide software development boards which -are highly configurable, so that they can support all options -that product boards may require. @emph{Make sure that any -jumpers or switches match the system configuration you are -working with.} - -Common issues include: - -@itemize @bullet - -@item @b{JTAG setup} ... -Boards may support more than one JTAG configuration. -Examples include jumpers controlling pullups versus pulldowns -on the nTRST and/or nSRST signals, and choice of connectors -(e.g. which of two headers on the base board, -or one from a daughtercard). -For some Texas Instruments boards, you may need to jumper the -EMU0 and EMU1 signals (which OpenOCD won't currently control). - -@item @b{Boot Modes} ... -Complex chips often support multiple boot modes, controlled -by external jumpers. Make sure this is set up correctly. -For example many i.MX boards from NXP need to be jumpered -to "ATX mode" to start booting using the on-chip ROM, when -using second stage bootloader code stored in a NAND flash chip. - -Such explicit configuration is common, and not limited to -booting from NAND. You might also need to set jumpers to -start booting using code loaded from an MMC/SD card; external -SPI flash; Ethernet, UART, or USB links; NOR flash; OneNAND -flash; some external host; or various other sources. - - -@item @b{Memory Addressing} ... -Boards which support multiple boot modes may also have jumpers -to configure memory addressing. One board, for example, jumpers -external chipselect 0 (used for booting) to address either -a large SRAM (which must be pre-loaded via JTAG), NOR flash, -or NAND flash. When it's jumpered to address NAND flash, that -board must also be told to start booting from on-chip ROM. - -Your @file{board.cfg} file may also need to be told this jumper -configuration, so that it can know whether to declare NOR flash -using @command{flash bank} or instead declare NAND flash with -@command{nand device}; and likewise which probe to perform in -its @code{reset-init} handler. - -A closely related issue is bus width. Jumpers might need to -distinguish between 8 bit or 16 bit bus access for the flash -used to start booting. - -@item @b{Peripheral Access} ... -Development boards generally provide access to every peripheral -on the chip, sometimes in multiple modes (such as by providing -multiple audio codec chips). -This interacts with software -configuration of pin multiplexing, where for example a -given pin may be routed either to the MMC/SD controller -or the GPIO controller. It also often interacts with -configuration jumpers. One jumper may be used to route -signals to an MMC/SD card slot or an expansion bus (which -might in turn affect booting); others might control which -audio or video codecs are used. - -@end itemize - -Plus you should of course have @code{reset-init} event handlers -which set up the hardware to match that jumper configuration. -That includes in particular any oscillator or PLL used to clock -the CPU, and any memory controllers needed to access external -memory and peripherals. Without such handlers, you won't be -able to access those resources without working target firmware -which can do that setup ... this can be awkward when you're -trying to debug that target firmware. Even if there's a ROM -bootloader which handles a few issues, it rarely provides full -access to all board-specific capabilities. - - -@node Config File Guidelines -@chapter Config File Guidelines - -This chapter is aimed at any user who needs to write a config file, -including developers and integrators of OpenOCD and any user who -needs to get a new board working smoothly. -It provides guidelines for creating those files. - -You should find the following directories under -@t{$(INSTALLDIR)/scripts}, with config files maintained upstream. Use -them as-is where you can; or as models for new files. -@itemize @bullet -@item @file{interface} ... -These are for debug adapters. Files that specify configuration to use -specific JTAG, SWD and other adapters go here. -@item @file{board} ... -Think Circuit Board, PWA, PCB, they go by many names. Board files -contain initialization items that are specific to a board. - -They reuse target configuration files, since the same -microprocessor chips are used on many boards, -but support for external parts varies widely. For -example, the SDRAM initialization sequence for the board, or the type -of external flash and what address it uses. Any initialization -sequence to enable that external flash or SDRAM should be found in the -board file. Boards may also contain multiple targets: two CPUs; or -a CPU and an FPGA. -@item @file{target} ... -Think chip. The ``target'' directory represents the JTAG TAPs -on a chip -which OpenOCD should control, not a board. Two common types of targets -are ARM chips and FPGA or CPLD chips. -When a chip has multiple TAPs (maybe it has both ARM and DSP cores), -the target config file defines all of them. -@item @emph{more} ... browse for other library files which may be useful. -For example, there are various generic and CPU-specific utilities. -@end itemize - -The @file{openocd.cfg} user config -file may override features in any of the above files by -setting variables before sourcing the target file, or by adding -commands specific to their situation. - -@section Interface Config Files - -The user config file -should be able to source one of these files with a command like this: - -@example -source [find interface/FOOBAR.cfg] -@end example - -A preconfigured interface file should exist for every debug adapter -in use today with OpenOCD. -That said, perhaps some of these config files -have only been used by the developer who created it. - -A separate chapter gives information about how to set these up. -@xref{Debug Adapter Configuration}. -Read the OpenOCD source code (and Developer's Guide) -if you have a new kind of hardware interface -and need to provide a driver for it. - -@section Board Config Files -@cindex config file, board -@cindex board config file - -The user config file -should be able to source one of these files with a command like this: - -@example -source [find board/FOOBAR.cfg] -@end example - -The point of a board config file is to package everything -about a given board that user config files need to know. -In summary the board files should contain (if present) - -@enumerate -@item One or more @command{source [find target/...cfg]} statements -@item NOR flash configuration (@pxref{norconfiguration,,NOR Configuration}) -@item NAND flash configuration (@pxref{nandconfiguration,,NAND Configuration}) -@item Target @code{reset} handlers for SDRAM and I/O configuration -@item JTAG adapter reset configuration (@pxref{Reset Configuration}) -@item All things that are not ``inside a chip'' -@end enumerate - -Generic things inside target chips belong in target config files, -not board config files. So for example a @code{reset-init} event -handler should know board-specific oscillator and PLL parameters, -which it passes to target-specific utility code. - -The most complex task of a board config file is creating such a -@code{reset-init} event handler. -Define those handlers last, after you verify the rest of the board -configuration works. - -@subsection Communication Between Config files - -In addition to target-specific utility code, another way that -board and target config files communicate is by following a -convention on how to use certain variables. - -The full Tcl/Tk language supports ``namespaces'', but Jim-Tcl does not. -Thus the rule we follow in OpenOCD is this: Variables that begin with -a leading underscore are temporary in nature, and can be modified and -used at will within a target configuration file. - -Complex board config files can do the things like this, -for a board with three chips: - -@example -# Chip #1: PXA270 for network side, big endian -set CHIPNAME network -set ENDIAN big -source [find target/pxa270.cfg] -# on return: _TARGETNAME = network.cpu -# other commands can refer to the "network.cpu" target. -$_TARGETNAME configure .... events for this CPU.. - -# Chip #2: PXA270 for video side, little endian -set CHIPNAME video -set ENDIAN little -source [find target/pxa270.cfg] -# on return: _TARGETNAME = video.cpu -# other commands can refer to the "video.cpu" target. -$_TARGETNAME configure .... events for this CPU.. - -# Chip #3: Xilinx FPGA for glue logic -set CHIPNAME xilinx -unset ENDIAN -source [find target/spartan3.cfg] -@end example - -That example is oversimplified because it doesn't show any flash memory, -or the @code{reset-init} event handlers to initialize external DRAM -or (assuming it needs it) load a configuration into the FPGA. -Such features are usually needed for low-level work with many boards, -where ``low level'' implies that the board initialization software may -not be working. (That's a common reason to need JTAG tools. Another -is to enable working with microcontroller-based systems, which often -have no debugging support except a JTAG connector.) - -Target config files may also export utility functions to board and user -config files. Such functions should use name prefixes, to help avoid -naming collisions. - -Board files could also accept input variables from user config files. -For example, there might be a @code{J4_JUMPER} setting used to identify -what kind of flash memory a development board is using, or how to set -up other clocks and peripherals. - -@subsection Variable Naming Convention -@cindex variable names - -Most boards have only one instance of a chip. -However, it should be easy to create a board with more than -one such chip (as shown above). -Accordingly, we encourage these conventions for naming -variables associated with different @file{target.cfg} files, -to promote consistency and -so that board files can override target defaults. - -Inputs to target config files include: - -@itemize @bullet -@item @code{CHIPNAME} ... -This gives a name to the overall chip, and is used as part of -tap identifier dotted names. -While the default is normally provided by the chip manufacturer, -board files may need to distinguish between instances of a chip. -@item @code{ENDIAN} ... -By default @option{little} - although chips may hard-wire @option{big}. -Chips that can't change endianness don't need to use this variable. -@item @code{CPUTAPID} ... -When OpenOCD examines the JTAG chain, it can be told verify the -chips against the JTAG IDCODE register. -The target file will hold one or more defaults, but sometimes the -chip in a board will use a different ID (perhaps a newer revision). -@end itemize - -Outputs from target config files include: - -@itemize @bullet -@item @code{_TARGETNAME} ... -By convention, this variable is created by the target configuration -script. The board configuration file may make use of this variable to -configure things like a ``reset init'' script, or other things -specific to that board and that target. -If the chip has 2 targets, the names are @code{_TARGETNAME0}, -@code{_TARGETNAME1}, ... etc. -@end itemize - -@subsection The reset-init Event Handler -@cindex event, reset-init -@cindex reset-init handler - -Board config files run in the OpenOCD configuration stage; -they can't use TAPs or targets, since they haven't been -fully set up yet. -This means you can't write memory or access chip registers; -you can't even verify that a flash chip is present. -That's done later in event handlers, of which the target @code{reset-init} -handler is one of the most important. - -Except on microcontrollers, the basic job of @code{reset-init} event -handlers is setting up flash and DRAM, as normally handled by boot loaders. -Microcontrollers rarely use boot loaders; they run right out of their -on-chip flash and SRAM memory. But they may want to use one of these -handlers too, if just for developer convenience. - -@quotation Note -Because this is so very board-specific, and chip-specific, no examples -are included here. -Instead, look at the board config files distributed with OpenOCD. -If you have a boot loader, its source code will help; so will -configuration files for other JTAG tools -(@pxref{translatingconfigurationfiles,,Translating Configuration Files}). -@end quotation - -Some of this code could probably be shared between different boards. -For example, setting up a DRAM controller often doesn't differ by -much except the bus width (16 bits or 32?) and memory timings, so a -reusable TCL procedure loaded by the @file{target.cfg} file might take -those as parameters. -Similarly with oscillator, PLL, and clock setup; -and disabling the watchdog. -Structure the code cleanly, and provide comments to help -the next developer doing such work. -(@emph{You might be that next person} trying to reuse init code!) - -The last thing normally done in a @code{reset-init} handler is probing -whatever flash memory was configured. For most chips that needs to be -done while the associated target is halted, either because JTAG memory -access uses the CPU or to prevent conflicting CPU access. - -@subsection JTAG Clock Rate - -Before your @code{reset-init} handler has set up -the PLLs and clocking, you may need to run with -a low JTAG clock rate. -@xref{jtagspeed,,JTAG Speed}. -Then you'd increase that rate after your handler has -made it possible to use the faster JTAG clock. -When the initial low speed is board-specific, for example -because it depends on a board-specific oscillator speed, then -you should probably set it up in the board config file; -if it's target-specific, it belongs in the target config file. - -For most ARM-based processors the fastest JTAG clock@footnote{A FAQ -@uref{http://www.arm.com/support/faqdev/4170.html} gives details.} -is one sixth of the CPU clock; or one eighth for ARM11 cores. -Consult chip documentation to determine the peak JTAG clock rate, -which might be less than that. - -@quotation Warning -On most ARMs, JTAG clock detection is coupled to the core clock, so -software using a @option{wait for interrupt} operation blocks JTAG access. -Adaptive clocking provides a partial workaround, but a more complete -solution just avoids using that instruction with JTAG debuggers. -@end quotation - -If both the chip and the board support adaptive clocking, -use the @command{jtag_rclk} -command, in case your board is used with JTAG adapter which -also supports it. Otherwise use @command{adapter_khz}. -Set the slow rate at the beginning of the reset sequence, -and the faster rate as soon as the clocks are at full speed. - -@anchor{theinitboardprocedure} -@subsection The init_board procedure -@cindex init_board procedure - -The concept of @code{init_board} procedure is very similar to @code{init_targets} -(@xref{theinittargetsprocedure,,The init_targets procedure}.) - it's a replacement of ``linear'' -configuration scripts. This procedure is meant to be executed when OpenOCD enters run stage -(@xref{enteringtherunstage,,Entering the Run Stage},) after @code{init_targets}. The idea to have -separate @code{init_targets} and @code{init_board} procedures is to allow the first one to configure -everything target specific (internal flash, internal RAM, etc.) and the second one to configure -everything board specific (reset signals, chip frequency, reset-init event handler, external memory, etc.). -Additionally ``linear'' board config file will most likely fail when target config file uses -@code{init_targets} scheme (``linear'' script is executed before @code{init} and @code{init_targets} - after), -so separating these two configuration stages is very convenient, as the easiest way to overcome this -problem is to convert board config file to use @code{init_board} procedure. Board config scripts don't -need to override @code{init_targets} defined in target config files when they only need to add some specifics. - -Just as @code{init_targets}, the @code{init_board} procedure can be overridden by ``next level'' script (which sources -the original), allowing greater code reuse. - -@example -### board_file.cfg ### - -# source target file that does most of the config in init_targets -source [find target/target.cfg] - -proc enable_fast_clock @{@} @{ - # enables fast on-board clock source - # configures the chip to use it -@} - -# initialize only board specifics - reset, clock, adapter frequency -proc init_board @{@} @{ - reset_config trst_and_srst trst_pulls_srst - - $_TARGETNAME configure -event reset-init @{ - adapter_khz 1 - enable_fast_clock - adapter_khz 10000 - @} -@} -@end example - -@section Target Config Files -@cindex config file, target -@cindex target config file - -Board config files communicate with target config files using -naming conventions as described above, and may source one or -more target config files like this: - -@example -source [find target/FOOBAR.cfg] -@end example - -The point of a target config file is to package everything -about a given chip that board config files need to know. -In summary the target files should contain - -@enumerate -@item Set defaults -@item Add TAPs to the scan chain -@item Add CPU targets (includes GDB support) -@item CPU/Chip/CPU-Core specific features -@item On-Chip flash -@end enumerate - -As a rule of thumb, a target file sets up only one chip. -For a microcontroller, that will often include a single TAP, -which is a CPU needing a GDB target, and its on-chip flash. - -More complex chips may include multiple TAPs, and the target -config file may need to define them all before OpenOCD -can talk to the chip. -For example, some phone chips have JTAG scan chains that include -an ARM core for operating system use, a DSP, -another ARM core embedded in an image processing engine, -and other processing engines. - -@subsection Default Value Boiler Plate Code - -All target configuration files should start with code like this, -letting board config files express environment-specific -differences in how things should be set up. - -@example -# Boards may override chip names, perhaps based on role, -# but the default should match what the vendor uses -if @{ [info exists CHIPNAME] @} @{ - set _CHIPNAME $CHIPNAME -@} else @{ - set _CHIPNAME sam7x256 -@} - -# ONLY use ENDIAN with targets that can change it. -if @{ [info exists ENDIAN] @} @{ - set _ENDIAN $ENDIAN -@} else @{ - set _ENDIAN little -@} - -# TAP identifiers may change as chips mature, for example with -# new revision fields (the "3" here). Pick a good default; you -# can pass several such identifiers to the "jtag newtap" command. -if @{ [info exists CPUTAPID ] @} @{ - set _CPUTAPID $CPUTAPID -@} else @{ - set _CPUTAPID 0x3f0f0f0f -@} -@end example -@c but 0x3f0f0f0f is for an str73x part ... - -@emph{Remember:} Board config files may include multiple target -config files, or the same target file multiple times -(changing at least @code{CHIPNAME}). - -Likewise, the target configuration file should define -@code{_TARGETNAME} (or @code{_TARGETNAME0} etc) and -use it later on when defining debug targets: - -@example -set _TARGETNAME $_CHIPNAME.cpu -target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME -@end example - -@subsection Adding TAPs to the Scan Chain -After the ``defaults'' are set up, -add the TAPs on each chip to the JTAG scan chain. -@xref{TAP Declaration}, and the naming convention -for taps. - -In the simplest case the chip has only one TAP, -probably for a CPU or FPGA. -The config file for the Atmel AT91SAM7X256 -looks (in part) like this: - -@example -jtag newtap $_CHIPNAME cpu -irlen 4 -expected-id $_CPUTAPID -@end example - -A board with two such at91sam7 chips would be able -to source such a config file twice, with different -values for @code{CHIPNAME}, so -it adds a different TAP each time. - -If there are nonzero @option{-expected-id} values, -OpenOCD attempts to verify the actual tap id against those values. -It will issue error messages if there is mismatch, which -can help to pinpoint problems in OpenOCD configurations. - -@example -JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f - (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3) -ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f -ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1 -ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3 -@end example - -There are more complex examples too, with chips that have -multiple TAPs. Ones worth looking at include: - -@itemize -@item @file{target/omap3530.cfg} -- with disabled ARM and DSP, -plus a JRC to enable them -@item @file{target/str912.cfg} -- with flash, CPU, and boundary scan -@item @file{target/ti_dm355.cfg} -- with ETM, ARM, and JRC (this JRC -is not currently used) -@end itemize - -@subsection Add CPU targets - -After adding a TAP for a CPU, you should set it up so that -GDB and other commands can use it. -@xref{CPU Configuration}. -For the at91sam7 example above, the command can look like this; -note that @code{$_ENDIAN} is not needed, since OpenOCD defaults -to little endian, and this chip doesn't support changing that. - -@example -set _TARGETNAME $_CHIPNAME.cpu -target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME -@end example - -Work areas are small RAM areas associated with CPU targets. -They are used by OpenOCD to speed up downloads, -and to download small snippets of code to program flash chips. -If the chip includes a form of ``on-chip-ram'' - and many do - define -a work area if you can. -Again using the at91sam7 as an example, this can look like: - -@example -$_TARGETNAME configure -work-area-phys 0x00200000 \ - -work-area-size 0x4000 -work-area-backup 0 -@end example - -@anchor{definecputargetsworkinginsmp} -@subsection Define CPU targets working in SMP -@cindex SMP -After setting targets, you can define a list of targets working in SMP. - -@example -set _TARGETNAME_1 $_CHIPNAME.cpu1 -set _TARGETNAME_2 $_CHIPNAME.cpu2 -target create $_TARGETNAME_1 cortex_a -chain-position $_CHIPNAME.dap \ --coreid 0 -dbgbase $_DAP_DBG1 -target create $_TARGETNAME_2 cortex_a -chain-position $_CHIPNAME.dap \ --coreid 1 -dbgbase $_DAP_DBG2 -#define 2 targets working in smp. -target smp $_CHIPNAME.cpu2 $_CHIPNAME.cpu1 -@end example -In the above example on cortex_a, 2 cpus are working in SMP. -In SMP only one GDB instance is created and : -@itemize @bullet -@item a set of hardware breakpoint sets the same breakpoint on all targets in the list. -@item halt command triggers the halt of all targets in the list. -@item resume command triggers the write context and the restart of all targets in the list. -@item following a breakpoint: the target stopped by the breakpoint is displayed to the GDB session. -@item dedicated GDB serial protocol packets are implemented for switching/retrieving the target -displayed by the GDB session @pxref{usingopenocdsmpwithgdb,,Using OpenOCD SMP with GDB}. -@end itemize - -The SMP behaviour can be disabled/enabled dynamically. On cortex_a following -command have been implemented. -@itemize @bullet -@item cortex_a smp_on : enable SMP mode, behaviour is as described above. -@item cortex_a smp_off : disable SMP mode, the current target is the one -displayed in the GDB session, only this target is now controlled by GDB -session. This behaviour is useful during system boot up. -@item cortex_a smp_gdb : display/fix the core id displayed in GDB session see -following example. -@end itemize - -@example ->cortex_a smp_gdb -gdb coreid 0 -> -1 -#0 : coreid 0 is displayed to GDB , -#-> -1 : next resume triggers a real resume -> cortex_a smp_gdb 1 -gdb coreid 0 -> 1 -#0 :coreid 0 is displayed to GDB , -#->1 : next resume displays coreid 1 to GDB -> resume -> cortex_a smp_gdb -gdb coreid 1 -> 1 -#1 :coreid 1 is displayed to GDB , -#->1 : next resume displays coreid 1 to GDB -> cortex_a smp_gdb -1 -gdb coreid 1 -> -1 -#1 :coreid 1 is displayed to GDB, -#->-1 : next resume triggers a real resume -@end example - - -@subsection Chip Reset Setup - -As a rule, you should put the @command{reset_config} command -into the board file. Most things you think you know about a -chip can be tweaked by the board. - -Some chips have specific ways the TRST and SRST signals are -managed. In the unusual case that these are @emph{chip specific} -and can never be changed by board wiring, they could go here. -For example, some chips can't support JTAG debugging without -both signals. - -Provide a @code{reset-assert} event handler if you can. -Such a handler uses JTAG operations to reset the target, -letting this target config be used in systems which don't -provide the optional SRST signal, or on systems where you -don't want to reset all targets at once. -Such a handler might write to chip registers to force a reset, -use a JRC to do that (preferable -- the target may be wedged!), -or force a watchdog timer to trigger. -(For Cortex-M targets, this is not necessary. The target -driver knows how to use trigger an NVIC reset when SRST is -not available.) - -Some chips need special attention during reset handling if -they're going to be used with JTAG. -An example might be needing to send some commands right -after the target's TAP has been reset, providing a -@code{reset-deassert-post} event handler that writes a chip -register to report that JTAG debugging is being done. -Another would be reconfiguring the watchdog so that it stops -counting while the core is halted in the debugger. - -JTAG clocking constraints often change during reset, and in -some cases target config files (rather than board config files) -are the right places to handle some of those issues. -For example, immediately after reset most chips run using a -slower clock than they will use later. -That means that after reset (and potentially, as OpenOCD -first starts up) they must use a slower JTAG clock rate -than they will use later. -@xref{jtagspeed,,JTAG Speed}. - -@quotation Important -When you are debugging code that runs right after chip -reset, getting these issues right is critical. -In particular, if you see intermittent failures when -OpenOCD verifies the scan chain after reset, -look at how you are setting up JTAG clocking. -@end quotation - -@anchor{theinittargetsprocedure} -@subsection The init_targets procedure -@cindex init_targets procedure - -Target config files can either be ``linear'' (script executed line-by-line when parsed in -configuration stage, @xref{configurationstage,,Configuration Stage},) or they can contain a special -procedure called @code{init_targets}, which will be executed when entering run stage -(after parsing all config files or after @code{init} command, @xref{enteringtherunstage,,Entering the Run Stage}.) -Such procedure can be overriden by ``next level'' script (which sources the original). -This concept faciliates code reuse when basic target config files provide generic configuration -procedures and @code{init_targets} procedure, which can then be sourced and enchanced or changed in -a ``more specific'' target config file. This is not possible with ``linear'' config scripts, -because sourcing them executes every initialization commands they provide. - -@example -### generic_file.cfg ### - -proc setup_my_chip @{chip_name flash_size ram_size@} @{ - # basic initialization procedure ... -@} - -proc init_targets @{@} @{ - # initializes generic chip with 4kB of flash and 1kB of RAM - setup_my_chip MY_GENERIC_CHIP 4096 1024 -@} - -### specific_file.cfg ### - -source [find target/generic_file.cfg] - -proc init_targets @{@} @{ - # initializes specific chip with 128kB of flash and 64kB of RAM - setup_my_chip MY_CHIP_WITH_128K_FLASH_64KB_RAM 131072 65536 -@} -@end example - -The easiest way to convert ``linear'' config files to @code{init_targets} version is to -enclose every line of ``code'' (i.e. not @code{source} commands, procedures, etc.) in this procedure. - -For an example of this scheme see LPC2000 target config files. - -The @code{init_boards} procedure is a similar concept concerning board config files -(@xref{theinitboardprocedure,,The init_board procedure}.) - -@anchor{theinittargeteventsprocedure} -@subsection The init_target_events procedure -@cindex init_target_events procedure - -A special procedure called @code{init_target_events} is run just after -@code{init_targets} (@xref{theinittargetsprocedure,,The init_targets -procedure}.) and before @code{init_board} -(@xref{theinitboardprocedure,,The init_board procedure}.) It is used -to set up default target events for the targets that do not have those -events already assigned. - -@subsection ARM Core Specific Hacks - -If the chip has a DCC, enable it. If the chip is an ARM9 with some -special high speed download features - enable it. - -If present, the MMU, the MPU and the CACHE should be disabled. - -Some ARM cores are equipped with trace support, which permits -examination of the instruction and data bus activity. Trace -activity is controlled through an ``Embedded Trace Module'' (ETM) -on one of the core's scan chains. The ETM emits voluminous data -through a ``trace port''. (@xref{armhardwaretracing,,ARM Hardware Tracing}.) -If you are using an external trace port, -configure it in your board config file. -If you are using an on-chip ``Embedded Trace Buffer'' (ETB), -configure it in your target config file. - -@example -etm config $_TARGETNAME 16 normal full etb -etb config $_TARGETNAME $_CHIPNAME.etb -@end example - -@subsection Internal Flash Configuration - -This applies @b{ONLY TO MICROCONTROLLERS} that have flash built in. - -@b{Never ever} in the ``target configuration file'' define any type of -flash that is external to the chip. (For example a BOOT flash on -Chip Select 0.) Such flash information goes in a board file - not -the TARGET (chip) file. - -Examples: -@itemize @bullet -@item at91sam7x256 - has 256K flash YES enable it. -@item str912 - has flash internal YES enable it. -@item imx27 - uses boot flash on CS0 - it goes in the board file. -@item pxa270 - again - CS0 flash - it goes in the board file. -@end itemize - -@anchor{translatingconfigurationfiles} -@section Translating Configuration Files -@cindex translation -If you have a configuration file for another hardware debugger -or toolset (Abatron, BDI2000, BDI3000, CCS, -Lauterbach, SEGGER, Macraigor, etc.), translating -it into OpenOCD syntax is often quite straightforward. The most tricky -part of creating a configuration script is oftentimes the reset init -sequence where e.g. PLLs, DRAM and the like is set up. - -One trick that you can use when translating is to write small -Tcl procedures to translate the syntax into OpenOCD syntax. This -can avoid manual translation errors and make it easier to -convert other scripts later on. - -Example of transforming quirky arguments to a simple search and -replace job: - -@example -# Lauterbach syntax(?) -# -# Data.Set c15:0x042f %long 0x40000015 -# -# OpenOCD syntax when using procedure below. -# -# setc15 0x01 0x00050078 - -proc setc15 @{regs value@} @{ - global TARGETNAME - - echo [format "set p15 0x%04x, 0x%08x" $regs $value] - - arm mcr 15 [expr ($regs>>12)&0x7] \ - [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] \ - [expr ($regs>>8)&0x7] $value -@} -@end example - - - -@node Daemon Configuration -@chapter Daemon Configuration -@cindex initialization -The commands here are commonly found in the openocd.cfg file and are -used to specify what TCP/IP ports are used, and how GDB should be -supported. - -@anchor{configurationstage} -@section Configuration Stage -@cindex configuration stage -@cindex config command - -When the OpenOCD server process starts up, it enters a -@emph{configuration stage} which is the only time that -certain commands, @emph{configuration commands}, may be issued. -Normally, configuration commands are only available -inside startup scripts. - -In this manual, the definition of a configuration command is -presented as a @emph{Config Command}, not as a @emph{Command} -which may be issued interactively. -The runtime @command{help} command also highlights configuration -commands, and those which may be issued at any time. - -Those configuration commands include declaration of TAPs, -flash banks, -the interface used for JTAG communication, -and other basic setup. -The server must leave the configuration stage before it -may access or activate TAPs. -After it leaves this stage, configuration commands may no -longer be issued. - -@anchor{enteringtherunstage} -@section Entering the Run Stage - -The first thing OpenOCD does after leaving the configuration -stage is to verify that it can talk to the scan chain -(list of TAPs) which has been configured. -It will warn if it doesn't find TAPs it expects to find, -or finds TAPs that aren't supposed to be there. -You should see no errors at this point. -If you see errors, resolve them by correcting the -commands you used to configure the server. -Common errors include using an initial JTAG speed that's too -fast, and not providing the right IDCODE values for the TAPs -on the scan chain. - -Once OpenOCD has entered the run stage, a number of commands -become available. -A number of these relate to the debug targets you may have declared. -For example, the @command{mww} command will not be available until -a target has been successfuly instantiated. -If you want to use those commands, you may need to force -entry to the run stage. - -@deffn {Config Command} init -This command terminates the configuration stage and -enters the run stage. This helps when you need to have -the startup scripts manage tasks such as resetting the target, -programming flash, etc. To reset the CPU upon startup, add "init" and -"reset" at the end of the config script or at the end of the OpenOCD -command line using the @option{-c} command line switch. - -If this command does not appear in any startup/configuration file -OpenOCD executes the command for you after processing all -configuration files and/or command line options. - -@b{NOTE:} This command normally occurs at or near the end of your -openocd.cfg file to force OpenOCD to ``initialize'' and make the -targets ready. For example: If your openocd.cfg file needs to -read/write memory on your target, @command{init} must occur before -the memory read/write commands. This includes @command{nand probe}. -@end deffn - -@deffn {Overridable Procedure} jtag_init -This is invoked at server startup to verify that it can talk -to the scan chain (list of TAPs) which has been configured. - -The default implementation first tries @command{jtag arp_init}, -which uses only a lightweight JTAG reset before examining the -scan chain. -If that fails, it tries again, using a harder reset -from the overridable procedure @command{init_reset}. - -Implementations must have verified the JTAG scan chain before -they return. -This is done by calling @command{jtag arp_init} -(or @command{jtag arp_init-reset}). -@end deffn - -@anchor{tcpipports} -@section TCP/IP Ports -@cindex TCP port -@cindex server -@cindex port -@cindex security -The OpenOCD server accepts remote commands in several syntaxes. -Each syntax uses a different TCP/IP port, which you may specify -only during configuration (before those ports are opened). - -For reasons including security, you may wish to prevent remote -access using one or more of these ports. -In such cases, just specify the relevant port number as zero. -If you disable all access through TCP/IP, you will need to -use the command line @option{-pipe} option. - -@deffn {Command} gdb_port [number] -@cindex GDB server -Normally gdb listens to a TCP/IP port, but GDB can also -communicate via pipes(stdin/out or named pipes). The name -"gdb_port" stuck because it covers probably more than 90% of -the normal use cases. - -No arguments reports GDB port. "pipe" means listen to stdin -output to stdout, an integer is base port number, "disable" -disables the gdb server. - -When using "pipe", also use log_output to redirect the log -output to a file so as not to flood the stdin/out pipes. - -The -p/--pipe option is deprecated and a warning is printed -as it is equivalent to passing in -c "gdb_port pipe; log_output openocd.log". - -Any other string is interpreted as named pipe to listen to. -Output pipe is the same name as input pipe, but with 'o' appended, -e.g. /var/gdb, /var/gdbo. - -The GDB port for the first target will be the base port, the -second target will listen on gdb_port + 1, and so on. -When not specified during the configuration stage, -the port @var{number} defaults to 3333. - -Note: when using "gdb_port pipe", increasing the default remote timeout in -gdb (with 'set remotetimeout') is recommended. An insufficient timeout may -cause initialization to fail with "Unknown remote qXfer reply: OK". - -@end deffn - -@deffn {Command} tcl_port [number] -Specify or query the port used for a simplified RPC -connection that can be used by clients to issue TCL commands and get the -output from the Tcl engine. -Intended as a machine interface. -When not specified during the configuration stage, -the port @var{number} defaults to 6666. - -@end deffn - -@deffn {Command} telnet_port [number] -Specify or query the -port on which to listen for incoming telnet connections. -This port is intended for interaction with one human through TCL commands. -When not specified during the configuration stage, -the port @var{number} defaults to 4444. -When specified as zero, this port is not activated. -@end deffn - -@anchor{gdbconfiguration} -@section GDB Configuration -@cindex GDB -@cindex GDB configuration -You can reconfigure some GDB behaviors if needed. -The ones listed here are static and global. -@xref{targetconfiguration,,Target Configuration}, about configuring individual targets. -@xref{targetevents,,Target Events}, about configuring target-specific event handling. - -@anchor{gdbbreakpointoverride} -@deffn {Command} gdb_breakpoint_override [@option{hard}|@option{soft}|@option{disable}] -Force breakpoint type for gdb @command{break} commands. -This option supports GDB GUIs which don't -distinguish hard versus soft breakpoints, if the default OpenOCD and -GDB behaviour is not sufficient. GDB normally uses hardware -breakpoints if the memory map has been set up for flash regions. -@end deffn - -@anchor{gdbflashprogram} -@deffn {Config Command} gdb_flash_program (@option{enable}|@option{disable}) -Set to @option{enable} to cause OpenOCD to program the flash memory when a -vFlash packet is received. -The default behaviour is @option{enable}. -@end deffn - -@deffn {Config Command} gdb_memory_map (@option{enable}|@option{disable}) -Set to @option{enable} to cause OpenOCD to send the memory configuration to GDB when -requested. GDB will then know when to set hardware breakpoints, and program flash -using the GDB load command. @command{gdb_flash_program enable} must also be enabled -for flash programming to work. -Default behaviour is @option{enable}. -@xref{gdbflashprogram,,gdb_flash_program}. -@end deffn - -@deffn {Config Command} gdb_report_data_abort (@option{enable}|@option{disable}) -Specifies whether data aborts cause an error to be reported -by GDB memory read packets. -The default behaviour is @option{disable}; -use @option{enable} see these errors reported. -@end deffn - -@deffn {Config Command} gdb_target_description (@option{enable}|@option{disable}) -Set to @option{enable} to cause OpenOCD to send the target descriptions to gdb via qXfer:features:read packet. -The default behaviour is @option{enable}. -@end deffn - -@deffn {Command} gdb_save_tdesc -Saves the target descripton file to the local file system. - -The file name is @i{target_name}.xml. -@end deffn - -@anchor{eventpolling} -@section Event Polling - -Hardware debuggers are parts of asynchronous systems, -where significant events can happen at any time. -The OpenOCD server needs to detect some of these events, -so it can report them to through TCL command line -or to GDB. - -Examples of such events include: - -@itemize -@item One of the targets can stop running ... maybe it triggers -a code breakpoint or data watchpoint, or halts itself. -@item Messages may be sent over ``debug message'' channels ... many -targets support such messages sent over JTAG, -for receipt by the person debugging or tools. -@item Loss of power ... some adapters can detect these events. -@item Resets not issued through JTAG ... such reset sources -can include button presses or other system hardware, sometimes -including the target itself (perhaps through a watchdog). -@item Debug instrumentation sometimes supports event triggering -such as ``trace buffer full'' (so it can quickly be emptied) -or other signals (to correlate with code behavior). -@en
<TRUNCATED>