X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=c586592942052210155ebd801f6742addc14bebb;hb=3324841558e39cd3d40cf4eed96b5ad8fb2678fb;hp=304fc62acf425514632881b98dc4263167c93fa3;hpb=cc9488008a7ff914b20a2194271569bb1b5206da;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 304fc62acf..c586592942 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -23,6 +23,7 @@ of the Open On-Chip Debugger (OpenOCD). @item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk} @item Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com} @item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com} +@item Copyright @copyright{} 2009 David Brownell @end itemize @quotation @@ -62,10 +63,10 @@ Free Documentation License''. * Developers:: OpenOCD Developers * Building OpenOCD:: Building OpenOCD From SVN * JTAG Hardware Dongles:: JTAG Hardware Dongles +* About JIM-Tcl:: About JIM-Tcl * Running:: Running OpenOCD * OpenOCD Project Setup:: OpenOCD Project Setup * Config File Guidelines:: Config File Guidelines -* About JIM-Tcl:: About JIM-Tcl * Daemon Configuration:: Daemon Configuration * Interface - Dongle Configuration:: Interface - Dongle Configuration * Reset Configuration:: Reset Configuration @@ -73,6 +74,7 @@ Free Documentation License''. * CPU Configuration:: CPU Configuration * Flash Commands:: Flash Commands * NAND Flash Commands:: NAND Flash Commands +* PLD/FPGA Commands:: PLD/FPGA Commands * General Commands:: General Commands * Architecture and Core Commands:: Architecture and Core Commands * JTAG Commands:: JTAG Commands @@ -104,6 +106,8 @@ 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 @@ -126,7 +130,7 @@ debugged via the GDB protocol. @b{Flash Programing:} Flash writing is supported for external CFI compatible NOR flashes (Intel and AMD/Spansion command set) and several -internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3, and +internal flashes (LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and STM32x). Preliminary support for various NAND flash controllers (LPC3180, Orion, S3C24xx, more) controller is included. @@ -238,27 +242,11 @@ That said, the OpenOCD developers would also like you to follow a few suggestions: @enumerate -@item @b{Send patches, including config files, upstream.} -@item @b{Always build with printer ports enabled.} -@item @b{Try to use LIBFTDI + LIBUSB where possible. You cover more bases.} +@item Send patches, including config files, upstream. +@item Always build with printer ports enabled. +@item Use libftdi + libusb for FT2232 support. @end enumerate -@itemize @bullet -@item @b{Why YES to LIBFTDI + LIBUSB?} -@itemize @bullet -@item @b{LESS} work - libusb perhaps already there -@item @b{LESS} work - identical code, multiple platforms -@item @b{MORE} dongles are supported -@item @b{MORE} platforms are supported -@item @b{MORE} complete solution -@end itemize -@item @b{Why not LIBFTDI + LIBUSB} (i.e.: ftd2xx instead)? -@itemize @bullet -@item @b{LESS} speed - some say it is slower -@item @b{LESS} complex to distribute (external dependencies) -@end itemize -@end itemize - @section Building From Source You can download the current SVN version with an SVN client of your choice from the @@ -297,16 +285,21 @@ a FTDI FT2232 based interface: @itemize @bullet @item @b{ftdi2232} libftdi (@uref{http://www.intra2net.com/opensource/ftdi/}) -@item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm}) -@item When using the Amontec JTAGkey, you have to get the drivers from the Amontec -homepage (@uref{http://www.amontec.com}). The JTAGkey uses a non-standard VID/PID. +@item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm}), +or the Amontec version (from @uref{http://www.amontec.com}), +for easier support of JTAGkey's vendor and product IDs. @end itemize libftdi is supported under Windows. Do not use versions earlier than 0.14. +To use the newer FT2232H chips, supporting RTCK and USB high speed (480 Mbps), +you need libftdi version 0.16 or newer. -In general, the D2XX driver provides superior performance (several times as fast), -but has the draw-back of being binary-only - though that isn't that bad, as it isn't -a kernel module, only a user space library. +Some people say that FTDI's libftd2xx code provides better performance. +However, it is binary-only, while OpenOCD is licenced according +to GNU GPLv2 without any exceptions. +That means that @emph{distributing} copies of OpenOCD built with +the FTDI code would violate the OpenOCD licensing terms. +You may, however, build such copies for personal use. To build OpenOCD (on both Linux and Cygwin), use the following commands: @@ -354,9 +347,12 @@ should be included (among other things): @item @option{--enable-gw16012} - Enable building support for the Gateworks GW16012 JTAG programmer. @item -@option{--enable-ft2232_ftd2xx} - Numerous USB type ARM JTAG dongles use the FT2232C chip from this FTDICHIP.COM chip (closed source). +@option{--enable-ft2232_ftd2xx} - Support FT2232-family chips using +the closed-source library from FTDICHIP.COM +(result not for re-distribution). @item -@option{--enable-ft2232_libftdi} - An open source (free) alternative to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin). +@option{--enable-ft2232_libftdi} - Support FT2232-family chips using +a GPL'd ft2232 support library (result OK for re-distribution). @item @option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c driver, give the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked. @@ -364,7 +360,11 @@ give the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpack @option{--with-ftd2xx-linux-tardir=PATH} - If using FTDICHIP.COM ft2232c driver on Linux, give the directory where the Linux driver's TAR.GZ file was unpacked. @item -@option{--with-ftd2xx-lib=shared|static} - Linux only. Default: static. Specifies how the FTDICHIP.COM libftd2xx driver should be linked. Note: 'static' only works in conjunction with @option{--with-ftd2xx-linux-tardir}. The 'shared' value is supported (12/26/2008), however you must manually install the required header files and shared libraries in an appropriate place. This uses ``libusb'' internally. +@option{--with-ftd2xx-lib=shared|static} - Linux only. Default: static. +Specifies how the FTDICHIP.COM libftd2xx driver should be linked. +Note: 'static' only works in conjunction with @option{--with-ftd2xx-linux-tardir}. +The 'shared' value is supported, however you must manually install the required +header files and shared libraries in an appropriate place. @item @option{--enable-presto_libftdi} - Enable building support for ASIX Presto programmer using the libftdi driver. @item @@ -399,12 +399,16 @@ use both the @option{--enable-parport} AND the @option{--enable-parport_giveio} There are 2 methods of using the FTD2232, either (1) using the FTDICHIP.COM closed source driver, or (2) the open (and free) driver -libftdi. Some claim the (closed) FTDICHIP.COM solution is faster. +libftdi. Some claim the (closed) FTDICHIP.COM solution is faster, +which is the motivation for supporting it even though its licensing +restricts it to non-redistributable OpenOCD binaries, and it is +not available for all operating systems used with OpenOCD. The FTDICHIP drivers come as either a (win32) ZIP file, or a (Linux) TAR.GZ file. You must unpack them ``some where'' convient. As of this -writing (12/26/2008) FTDICHIP does not supply means to install these -files ``in an appropriate place'' As a result, there are two +writing FTDICHIP does not supply means to install these +files ``in an appropriate place''. +As a result, there are two ``./configure'' options that help. Below is an example build process: @@ -481,7 +485,7 @@ openocd @option{-v} is executed. @cindex zy1000 @cindex printer port @cindex USB Adapter -@cindex rtck +@cindex RTCK Defined: @b{dongle}: A small device that plugins into a computer and serves as an adapter .... [snip] @@ -523,8 +527,6 @@ See: @url{http://www.ftdichip.com} for more information. In summer 2009, USB high speed (480 Mbps) versions of these FTDI chips are starting to become available in JTAG adapters. -As of 28/Nov/2008, the following are supported: - @itemize @bullet @item @b{usbjtag} @* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html} @@ -657,13 +659,55 @@ FlashLINK JTAG programing cable for PSD and uPSD} @end itemize +@node About JIM-Tcl +@chapter About JIM-Tcl +@cindex JIM Tcl +@cindex tcl + +OpenOCD includes 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, can write Tcl programs with them. + +You can learn more about JIM at its website, @url{http://jim.berlios.de}. + +@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 a single .C file and a single .H file 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. + +@item @b{Scripts} +@* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's +command interpreter today is a mixture of (newer) +JIM-Tcl commands, and (older) the orginal command interpreter. + +@item @b{Commands} +@* At the OpenOCD telnet command line (or via the GDB mon command) one +can type a Tcl for() loop, set variables, etc. + +@item @b{Historical Note} +@* JIM-Tcl was introduced to OpenOCD in spring 2008. + +@item @b{Need a crash course in Tcl?} +@*@xref{Tcl Crash Course}. +@end itemize + @node Running @chapter Running -@cindex running OpenOCD -@cindex --configfile -@cindex --debug_level -@cindex --logfile -@cindex --search +@cindex command line options +@cindex logfile +@cindex directory search The @option{--help} option shows: @verbatim @@ -693,7 +737,7 @@ clients (Telnet, GDB, Other). If you are having problems, you can enable internal debug messages via the ``-d'' option. -Also it is possible to interleave commands w/config scripts using the +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 @@ -701,8 +745,8 @@ 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 @option{debug_level -} @xref{debug_level}. +setting from within a telnet or gdb session using @command{debug_level +} (@pxref{debug_level}). You can redirect all output from the daemon to a file using the @option{-l } switch. @@ -808,7 +852,7 @@ single directory for your work with a given board. When you start OpenOCD from that directory, it searches there first for configuration files and for code you upload to the target board. -It is also be the natural place to write files, +It is also the natural place to write files, such as log files and data you download from the board. @section Configuration Basics @@ -848,7 +892,7 @@ openocd -f interface/signalyzer.cfg \ You could wrap such long command lines in shell scripts, each supporting a different development task. -One might re-flash the board with specific firmware version. +One might re-flash the board with a specific firmware version. Another might set up a particular debugging or run-time environment. Here we will focus on the simpler solution: one user config @@ -856,8 +900,9 @@ file, including basic configuration plus any TCL procedures to simplify your work. @section User Config Files -@cindex config file +@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. @@ -867,8 +912,10 @@ One of the following will match your situation best: @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. +(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 @@ -941,6 +988,10 @@ its @command{xscale vector_catch} sibling) 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. +TCP/IP port configuration is another example of something which +is environment-specific, and should only appear in +a user config file. @xref{TCP/IP Ports}. + @section Project-Specific Utilities A few project-specific utility @@ -1008,29 +1059,26 @@ involving considerably more than just a three stage bootloader. @node Config File Guidelines @chapter Config File Guidelines -This section/chapter is aimed at developers and integrators of -OpenOCD. These are guidelines for creating new boards and new target -configurations as of 28/Nov/2008. - -However, you, the user of OpenOCD, should be somewhat familiar with -this section as it should help explain some of the internals of what -you might be looking at. +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. -The user should find the following directories under @t{$(INSTALLDIR)/lib/openocd} : +You should find the following directories under @t{$(INSTALLDIR)/scripts}: @itemize @bullet -@item @b{interface} -@*Think JTAG Dongle. Files that configure the JTAG dongle go here. -@item @b{board} -@* Think Circuit Board, PWA, PCB, they go by many names. Board files -contain initialization items that are specific to a board - for -example: The SDRAM initialization sequence for the board, or the type -of external flash and what address it is found at. Any initialization +@item @file{interface} ... +think JTAG Dongle. Files that configure JTAG 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. 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, i.e.: Two CPUs, or +board file. Boards may also contain multiple targets: two CPUs; or a CPU and an FPGA or CPLD. -@item @b{target} -@* Think chip. The ``target'' directory represents the JTAG TAPs +@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. @@ -1038,191 +1086,273 @@ When a chip has multiple TAPs (maybe it has both ARM and DSP cores), the target config file defines all of them. @end itemize -@b{If needed...} The user in their ``openocd.cfg'' file or the board -file might override a specific feature in any of the above files by -setting a variable or two before sourcing the target file. Or adding -various commands specific to their situation. +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 -@cindex config file -The user should be able to source one of these files via a command like this: +The user config file +should be able to source one of these files with a command like this: @example - source [find interface/FOOBAR.cfg] -Or: - openocd -f interface/FOOBAR.cfg +source [find interface/FOOBAR.cfg] @end example A preconfigured interface file should exist for every interface in use today, that said, perhaps some interfaces have only been used by the sole developer who created it. -Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface} +A separate chapter gives information about how to set these up. +@xref{Interface - Dongle Configuration}. +Read the OpenOCD source code if you have a new kind of hardware interface +and need to provide a driver for it. @section Board Config Files -@cindex config file - -@b{Note: BOARD directory NEW as of 28/nov/2008} +@cindex config file, board +@cindex board config file -The user should be able to source one of these files via a command like this: +The user config file +should be able to source one of these files with a command like this: @example - source [find board/FOOBAR.cfg] -Or: - openocd -f board/FOOBAR.cfg +source [find board/FOOBAR.cfg] @end example - -The board file should contain one or more @t{source [find -target/FOO.cfg]} statements along with any board specific things. - +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 External flash configuration (i.e.: NOR flash on CS0, two NANDs on CS2) -@item SDRAM configuration (size, speed, etc. -@item Board specific IO configuration (i.e.: GPIO pins might disable a 2nd flash) -@item Multiple TARGET source statements -@item Reset configuration +@item One or more @command{source [target/...cfg]} statements +@item NOR flash configuration (@pxref{NOR Configuration}) +@item NAND flash configuration (@pxref{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'' -@item Things inside a chip go in a 'target' file @end enumerate -@section Target Config Files -@cindex config file +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 user should be able to source one of these files via a command like this: +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. -@example - source [find target/FOOBAR.cfg] -Or: - openocd -f target/FOOBAR.cfg -@end example +@subsection Communication Between Config files -In summary the target files should contain +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. -@enumerate -@item Set defaults -@item Add TAPs to the scan chain -@item Add CPU targets -@item CPU/Chip/CPU-Core specific features -@item On-Chip flash -@end enumerate +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. -@subsection Important variable names +Complex board config files can do the things like this, +for a board with three chips: -By default, the end user should never need to set these -variables. However, if the user needs to override a setting they only -need to set the variable in a simple way. +@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 @b{CHIPNAME} -@* This gives a name to the overall chip, and is used as part of the -tap identifier dotted name. -@item @b{ENDIAN} -@* By default little - unless the chip or board is not normally used that way. -@item @b{CPUTAPID} -@* When OpenOCD examines the JTAG chain, it will attempt to identify -every chip. If the @t{-expected-id} is nonzero, OpenOCD attempts -to verify the tap id number verses configuration file and may issue an -error or warning like this. The hope is that this will help to pinpoint -problems in OpenOCD configurations. +@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 -@example -Info: JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f - (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3) -Error: ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, - Got: 0x3f0f0f0f -Error: ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1 -Error: ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3 -@end example +Outputs from target config files include: -@item @b{_TARGETNAME} -@* By convention, this variable is created by the target configuration +@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 -If the chip has 2 targets, use the names @b{_TARGETNAME0}, -@b{_TARGETNAME1}, ... etc. +@subsection The reset-init Event Handler +@cindex event, reset-init +@cindex reset-init handler -@b{Remember:} The ``board file'' may include multiple targets. +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. -At no time should the name ``target0'' (the default target name if -none was specified) be used. The name ``target0'' is a hard coded name -- the next target on the board will be some other number. -In the same way, avoid using target numbers even when they are -permitted; use the right target name(s) for your board. +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. -The user (or board file) should reasonably be able to: +@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 may also be useful. +@end quotation -@example - source [find target/FOO.cfg] - $_TARGETNAME configure ... FOO specific parameters +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 use +a low JTAG clock rate; then you'd increase it later. +(The rule of thumb for ARM-based processors is 1/8 the CPU clock.) +If the board supports adaptive clocking, use the @command{jtag_rclk} +command, in case your board is used with JTAG adapter which +also supports it. Otherwise use @command{jtag_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. - source [find target/BAR.cfg] - $_TARGETNAME configure ... BAR specific parameters -@end example +@section Target Config Files +@cindex config file, target +@cindex target config file -@end itemize +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: -@subsection Tcl Variables Guide Line -The Full Tcl/Tk language supports ``namespaces'' - JIM-Tcl does not. +@example +source [find target/FOOBAR.cfg] +@end example -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. +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 -@b{EXAMPLE:} The user should be able to do this: +@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 -@example - # Board has 3 chips, - # PXA270 #1 network side, big endian - # PXA270 #2 video side, little endian - # Xilinx Glue logic - set CHIPNAME network - set ENDIAN big - source [find target/pxa270.cfg] - # variable: _TARGETNAME = network.cpu - # other commands can refer to the "network.cpu" tap. - $_TARGETNAME configure .... params for this CPU.. - - set ENDIAN little - set CHIPNAME video - source [find target/pxa270.cfg] - # variable: _TARGETNAME = video.cpu - # other commands can refer to the "video.cpu" tap. - $_TARGETNAME configure .... params for this CPU.. - - unset ENDIAN - set CHIPNAME xilinx - source [find target/spartan3.cfg] - - # Since $_TARGETNAME is temporal.. - # these names still work! - network.cpu configure ... params - video.cpu configure ... params -@end example +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 this (or a modified form) +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 -# SIMPLE 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 @{ @@ -1230,6 +1360,19 @@ if @{ [info exists CPUTAPID ] @} @{ @} @end example +@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. @@ -1251,12 +1394,25 @@ to source such a config file twice, with different values for @code{CHIPNAME}, so it adds a different TAP each time. +If there are one or more 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 a disabled ARM, and a JRC -(there's a DSP too, which is not listed) +@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) @@ -1267,7 +1423,9 @@ is not currently used) 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: +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 @@ -1342,42 +1500,6 @@ Examples: @item pxa270 - again - CS0 flash - it goes in the board file. @end itemize -@node About JIM-Tcl -@chapter About JIM-Tcl -@cindex JIM Tcl -@cindex tcl - -OpenOCD includes a small ``TCL Interpreter'' known as JIM-TCL. You can -learn more about JIM here: @url{http://jim.berlios.de} - -@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 a single .C file and a single .H file and -impliments the basic Tcl command set along. 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. - -@item @b{Scripts} -@* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's -command interpreter today (28/nov/2008) is a mixture of (newer) -JIM-Tcl commands, and (older) the orginal command interpreter. - -@item @b{Commands} -@* At the OpenOCD telnet command line (or via the GDB mon command) one -can type a Tcl for() loop, set variables, etc. - -@item @b{Historical Note} -@* JIM-Tcl was introduced to OpenOCD in spring 2008. - -@item @b{Need a crash course in Tcl?} -@*@xref{Tcl Crash Course}. -@end itemize - @node Daemon Configuration @chapter Daemon Configuration @cindex initialization @@ -1418,6 +1540,7 @@ read/write memory on your target, @command{init} must occur before the memory read/write commands. This includes @command{nand probe}. @end deffn +@anchor{TCP/IP Ports} @section TCP/IP Ports @cindex TCP port @cindex server @@ -1571,6 +1694,9 @@ MMU: disabled, D-Cache: disabled, I-Cache: enabled @node Interface - Dongle Configuration @chapter Interface - Dongle Configuration +@cindex config file, interface +@cindex interface config file + JTAG Adapters/Interfaces/Dongles are normally configured through commands in an interface configuration file which is sourced by your @file{openocd.cfg} file, or @@ -2143,6 +2269,7 @@ which sets up CPUs and exports them as GDB targets, probes flash memory, performs low-level JTAG operations, and more. @section Scan Chains +@cindex scan chain TAPs are part of a hardware @dfn{scan chain}, which is daisy chain of TAPs. @@ -2237,6 +2364,7 @@ each TAP's instruction register can also change. @c (on entry to RESET state). @section TAP Names +@cindex dotted name When TAP objects are declared with @command{jtag newtap}, a @dfn{dotted.name} is created for the TAP, combining the @@ -2314,8 +2442,9 @@ A TAP may also provide optional @var{configparams}: @itemize @bullet @item @code{-disable} (or @code{-enable}) -@*Use the @code{-disable} paramater to flag a TAP which is not -linked in to the scan chain when it is declared. +@*Use the @code{-disable} parameter to flag a TAP which is not +linked in to the scan chain after a reset using either TRST +or the JTAG state machine's @sc{reset} state. You may use @code{-enable} to highlight the default state (the TAP is linked in). @xref{Enabling and Disabling TAPs}. @@ -2334,6 +2463,8 @@ ID code could appear (for example, multiple versions). @anchor{Enabling and Disabling TAPs} @section Enabling and Disabling TAPs @cindex TAP events +@cindex JTAG Route Controller +@cindex jrc In some systems, a @dfn{JTAG Route Controller} (JRC) is used to enable and/or disable specific JTAG TAPs. @@ -2426,6 +2557,8 @@ We'll start by looking at how to examine the targets you have, then look at how to add one more target and how to configure it. @section Target List +@cindex target, current +@cindex target, list All targets that have been set up are part of a list, where each member has a name. @@ -2502,6 +2635,9 @@ only relevant on boards which have more than one target. @end deffn @section Target CPU Types and Variants +@cindex target type +@cindex CPU type +@cindex CPU variant Each target has a @dfn{CPU type}, as shown in the output of the @command{targets} command. You need to specify that type @@ -2549,6 +2685,7 @@ SRST, to avoid a issue with clearing the debug registers. This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will be detected and the normal reset behaviour used. @end itemize +@item @code{fa526} -- resembles arm920 (w/o Thumb) @item @code{feroceon} -- resembles arm926 @item @code{mips_m4k} -- a MIPS core. This supports one variant: @itemize @minus @@ -2983,12 +3120,6 @@ used. (SPI flash must also be copied to memory before use.) However, the documentation also uses ``flash'' as a generic term; for example, ``Put flash configuration in board-specific files''. -@quotation Note -As of 28-nov-2008 OpenOCD does not know how to program a SPI -flash that a micro may boot from. Perhaps you, the reader, would like to -contribute support for this. -@end quotation - Flash Steps: @enumerate @item Configure via the command @command{flash bank} @@ -3005,11 +3136,12 @@ bank'', and the GDB flash features be enabled. @end enumerate Many CPUs have the ablity to ``boot'' from the first flash bank. -This means that misprograming that bank can ``brick'' a system, +This means that misprogramming that bank can ``brick'' a system, so that it can't boot. JTAG tools, like OpenOCD, are often then used to ``de-brick'' the board by (re)installing working boot firmware. +@anchor{NOR Configuration} @section Flash Configuration Commands @cindex flash configuration @@ -3242,11 +3374,68 @@ flash bank aduc702x 0 0 0 0 $_TARGETNAME @end example @end deffn +@deffn {Flash Driver} at91sam3 +@cindex at91sam3 +All members of the AT91SAM3 (cortex-M3) microcontroller family from +atmel include internal flash and use the Cortex-M3 core. The driver +currently (6/22/09) recognizes the AT91SAM3U[1/2/4][C/E] chips. Note +that the driver was orginaly developed and tested using the +AT91SAM3U4E, using a SAM3U-EK eval board. Support for other chips in +the family where cribbed from the data sheet [Note to future +readers/updaters: Please remove this worrysome comment after other +chips are confirmed]. + +The AT91SAM3U4[E/C] (256K) chips have 2 flash banks, the other chips +(3U[1/2][E/C]) have 1 flash bank, in all cases the flash banks are at +the following fixed locations. + +@example +# Flash bank 0 - all chips +flash bank at91sam3 0x000080000 0 1 1 $_TARGETNAME +# Flash bank 1 - only 256K chips +flash bank at91sam3 0x000100000 0 1 1 $_TARGETNAME +@end example + +Internally, the AT91SAM3 flash memory is organized as follows: + +@itemize +@item @var{N-Banks:} 256K chips have 2 banks, others have 1 bank. +@item @var{Bank Size:} 128K/64K Per flash bank +@item @var{Sectors:} 16 or 8 per bank +@item @var{SectorSize:} 8K Per Sector +@item @var{PageSize:} 256 bytes per page. Note that OpenOCD operates on 'sector' sizes, not page sizes. +@end itemize + +The AT91SAM3 driver adds an additional command: + +@deffn Command {at91sam3 gpnvm set|clear|show all|NUMBER} +This command allows you to set, clear, or show the state of the GPNVM bits. +@end deffn + +@deffn Command {at91sam3 info} +This command attempts to display information about the AT91SAM3 +chip. @b{First} it read the @var{CHIPID_CIDR} [address 0x400e0740, see +Section 28.2.1, page 505 of the AT91SAM3U 29/may/2009 datasheet, +document id: doc6430A] and decodes the values. @b{Second} it reads the +various clock configuration registers and attempts to display how it +believes the chip is configured. By default, the SLOWCLK is assumed to +be 32768 Hz, see the command @b{at91sam3 slowclk}. +@end deffn + +@deffn Command {at91sam3 slowclk [VALUE]} +This command shows/sets the slow clock frequency used in the +@b{at91sam3 info} command calculations above. +@end deffn + +@end deffn + @deffn {Flash Driver} at91sam7 -All members of the AT91SAM7 microcontroller family from Atmel -include internal flash and use ARM7TDMI cores. -The driver automatically recognizes a number of these chips using -the chip identification register, and autoconfigures itself. +All members of the AT91SAM7 microcontroller family from Atmel include +internal flash and use ARM7TDMI cores. The driver automatically +recognizes a number of these chips using the chip identification +register, and autoconfigures itself. +@end deffn + @example flash bank at91sam7 0 0 0 0 $_TARGETNAME @@ -3287,7 +3476,6 @@ This assumes that the first flash bank (number 0) is associated with the appropriate at91sam7 target. @end quotation @end deffn -@end deffn @deffn {Flash Driver} avr The AVR 8-bit microcontrollers from Atmel integrate flash memory. @@ -3698,6 +3886,7 @@ is larger than 0xffffffff, the largest 32-bit unsigned integer.) Some larger devices will work, since they are actually multi-chip modules with two smaller chips and individual chipselect lines. +@anchor{NAND Configuration} @section NAND Configuration Commands @cindex NAND configuration @@ -3965,6 +4154,62 @@ or @code{read_page} methods, so @command{nand raw_access} won't change any behavior. @end deffn +@node PLD/FPGA Commands +@chapter PLD/FPGA Commands +@cindex PLD +@cindex FPGA + +Programmable Logic Devices (PLDs) and the more flexible +Field Programmable Gate Arrays (FPGAs) are both types of programmable hardware. +OpenOCD can support programming them. +Although PLDs are generally restrictive (cells are less functional, and +there are no special purpose cells for memory or computational tasks), +they share the same OpenOCD infrastructure. +Accordingly, both are called PLDs here. + +@section PLD/FPGA Configuration and Commands + +As it does for JTAG TAPs, debug targets, and flash chips (both NOR and NAND), +OpenOCD maintains a list of PLDs available for use in various commands. +Also, each such PLD requires a driver. + +They are referenced by the number shown by the @command{pld devices} command, +and new PLDs are defined by @command{pld device driver_name}. + +@deffn {Config Command} {pld device} driver_name tap_name [driver_options] +Defines a new PLD device, supported by driver @var{driver_name}, +using the TAP named @var{tap_name}. +The driver may make use of any @var{driver_options} to configure its +behavior. +@end deffn + +@deffn {Command} {pld devices} +Lists the PLDs and their numbers. +@end deffn + +@deffn {Command} {pld load} num filename +Loads the file @file{filename} into the PLD identified by @var{num}. +The file format must be inferred by the driver. +@end deffn + +@section PLD/FPGA Drivers, Options, and Commands + +Drivers may support PLD-specific options to the @command{pld device} +definition command, and may also define commands usable only with +that particular type of PLD. + +@deffn {FPGA Driver} virtex2 +Virtex-II is a family of FPGAs sold by Xilinx. +It supports the IEEE 1532 standard for In-System Configuration (ISC). +No driver-specific PLD definition options are used, +and one driver-specific command is defined. + +@deffn {Command} {virtex2 read_stat} num +Reads and displays the Virtex-II status register (STAT) +for FPGA @var{num}. +@end deffn +@end deffn + @node General Commands @chapter General Commands @cindex commands @@ -4016,8 +4261,12 @@ If @var{n} (from 0..3) is provided, then set it to that level. This affects the kind of messages sent to the server log. Level 0 is error messages only; level 1 adds warnings; -level 2 (the default) adds informational messages; +level 2 adds informational messages; and level 3 adds debugging messages. +The default is level 2, but that can be overridden on +the command line along with the location of that log +file (which is normally the server's standard output). +@xref{Running}. @end deffn @deffn Command fast (@option{enable}|@option{disable}) @@ -4061,7 +4310,7 @@ the initial log output channel is stderr. In this section ``target'' refers to a CPU configured as shown earlier (@pxref{CPU Configuration}). These commands, like many, implicitly refer to -a @dfn{current target} which is used to perform the +a current target which is used to perform the various operations. The current target may be changed by using @command{targets} command with the name of the target which should become current. @@ -5079,7 +5328,7 @@ and @command{irscan} commands are: @end itemize Note that only six of those states are fully ``stable'' in the -face of TMS fixed (usually low) +face of TMS fixed (low except for @sc{reset}) and a free-running JTAG clock. For all the others, the next TCK transition changes to a new state. @@ -5747,8 +5996,8 @@ is a string} parsed, but are NOT expanded or executed. @{Curly-Braces@} are like 'single-quote' operators in BASH shell scripts, with the added feature: @{curly-braces@} can be nested, single quotes can not. @{@{@{this is -nested 3 times@}@}@} NOTE: [date] is perhaps a bad example, as of -28/nov/2008, Jim/OpenOCD does not have a date command. +nested 3 times@}@}@} NOTE: [date] is a bad example; +at this writing, Jim/OpenOCD does not have a date command. @end itemize @section Consequences of Rule 1/2/3/4 @@ -5971,7 +6220,7 @@ $VARS and [square-brackets] are expanded later, when the EVENT occurs, and the text is evaluated. In case #4, they are replaced before the ``Target Object Command'' is executed. This occurs at the same time $_TARGETNAME is replaced. In case #4 the date will never -change. @{BTW: [date] is perhaps a bad example, as of 28/nov/2008, +change. @{BTW: [date] is a bad example; at this writing, Jim/OpenOCD does not have a date command@} @end enumerate @subsection Global Variables