You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/06/16 21:41:50 UTC
[42/51] [partial] incubator-mynewt-site git commit: remove untarred
files for openocd
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>