1cf673620a236505f399c63dc39cbe6cbc08088b
[openocd.git] / doc / openocd.texi
1 \input texinfo @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename openocd.info
4 @settitle OpenOCD User's Guide
5 @dircategory Development
6 @direntry
7 * OpenOCD: (openocd). OpenOCD User's Guide
8 @end direntry
9 @paragraphindent 0
10 @c %**end of header
11
12 @include version.texi
13
14 @copying
15
16 This User's Guide documents
17 release @value{VERSION},
18 dated @value{UPDATED},
19 of the Open On-Chip Debugger (OpenOCD).
20
21 @itemize @bullet
22 @item Copyright @copyright{} 2008 The OpenOCD Project
23 @item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
24 @item Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
25 @item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com}
26 @item Copyright @copyright{} 2009 David Brownell
27 @end itemize
28
29 @quotation
30 Permission is granted to copy, distribute and/or modify this document
31 under the terms of the GNU Free Documentation License, Version 1.2 or
32 any later version published by the Free Software Foundation; with no
33 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
34 Texts. A copy of the license is included in the section entitled ``GNU
35 Free Documentation License''.
36 @end quotation
37 @end copying
38
39 @titlepage
40 @titlefont{@emph{Open On-Chip Debugger:}}
41 @sp 1
42 @title OpenOCD User's Guide
43 @subtitle for release @value{VERSION}
44 @subtitle @value{UPDATED}
45
46 @page
47 @vskip 0pt plus 1filll
48 @insertcopying
49 @end titlepage
50
51 @summarycontents
52 @contents
53
54 @ifnottex
55 @node Top
56 @top OpenOCD User's Guide
57
58 @insertcopying
59 @end ifnottex
60
61 @menu
62 * About:: About OpenOCD
63 * Developers:: OpenOCD Developers
64 * JTAG Hardware Dongles:: JTAG Hardware Dongles
65 * About JIM-Tcl:: About JIM-Tcl
66 * Running:: Running OpenOCD
67 * OpenOCD Project Setup:: OpenOCD Project Setup
68 * Config File Guidelines:: Config File Guidelines
69 * Daemon Configuration:: Daemon Configuration
70 * Interface - Dongle Configuration:: Interface - Dongle Configuration
71 * Reset Configuration:: Reset Configuration
72 * TAP Declaration:: TAP Declaration
73 * CPU Configuration:: CPU Configuration
74 * Flash Commands:: Flash Commands
75 * NAND Flash Commands:: NAND Flash Commands
76 * PLD/FPGA Commands:: PLD/FPGA Commands
77 * General Commands:: General Commands
78 * Architecture and Core Commands:: Architecture and Core Commands
79 * JTAG Commands:: JTAG Commands
80 * Boundary Scan Commands:: Boundary Scan Commands
81 * TFTP:: TFTP
82 * GDB and OpenOCD:: Using GDB and OpenOCD
83 * Tcl Scripting API:: Tcl Scripting API
84 * Upgrading:: Deprecated/Removed Commands
85 * FAQ:: Frequently Asked Questions
86 * Tcl Crash Course:: Tcl Crash Course
87 * License:: GNU Free Documentation License
88
89 @comment DO NOT use the plain word ``Index'', reason: CYGWIN filename
90 @comment case issue with ``Index.html'' and ``index.html''
91 @comment Occurs when creating ``--html --no-split'' output
92 @comment This fix is based on: http://sourceware.org/ml/binutils/2006-05/msg00215.html
93 * OpenOCD Concept Index:: Concept Index
94 * Command and Driver Index:: Command and Driver Index
95 @end menu
96
97 @node About
98 @unnumbered About
99 @cindex about
100
101 OpenOCD was created by Dominic Rath as part of a diploma thesis written at the
102 University of Applied Sciences Augsburg (@uref{http://www.fh-augsburg.de}).
103 Since that time, the project has grown into an active open-source project,
104 supported by a diverse community of software and hardware developers from
105 around the world.
106
107 @section What is OpenOCD?
108 @cindex TAP
109 @cindex JTAG
110
111 The Open On-Chip Debugger (OpenOCD) aims to provide debugging,
112 in-system programming and boundary-scan testing for embedded target
113 devices.
114
115 @b{JTAG:} OpenOCD uses a ``hardware interface dongle'' to communicate
116 with the JTAG (IEEE 1149.1) compliant TAPs on your target board.
117 A @dfn{TAP} is a ``Test Access Port'', a module which processes
118 special instructions and data. TAPs are daisy-chained within and
119 between chips and boards.
120
121 @b{Dongles:} OpenOCD currently supports many types of hardware dongles: USB
122 based, parallel port based, and other standalone boxes that run
123 OpenOCD internally. @xref{JTAG Hardware Dongles}.
124
125 @b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
126 ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and
127 Cortex-M3 (Stellaris LM3 and ST STM32) based cores to be
128 debugged via the GDB protocol.
129
130 @b{Flash Programing:} Flash writing is supported for external CFI
131 compatible NOR flashes (Intel and AMD/Spansion command set) and several
132 internal flashes (LPC1700, LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and
133 STM32x). Preliminary support for various NAND flash controllers
134 (LPC3180, Orion, S3C24xx, more) controller is included.
135
136 @section OpenOCD Web Site
137
138 The OpenOCD web site provides the latest public news from the community:
139
140 @uref{http://openocd.berlios.de/web/}
141
142 @section Latest User's Guide:
143
144 The user's guide you are now reading may not be the latest one
145 available. A version for more recent code may be available.
146 Its HTML form is published irregularly at:
147
148 @uref{http://openocd.berlios.de/doc/html/index.html}
149
150 PDF form is likewise published at:
151
152 @uref{http://openocd.berlios.de/doc/pdf/openocd.pdf}
153
154 @section OpenOCD User's Forum
155
156 There is an OpenOCD forum (phpBB) hosted by SparkFun:
157
158 @uref{http://forum.sparkfun.com/viewforum.php?f=18}
159
160
161 @node Developers
162 @chapter OpenOCD Developer Resources
163 @cindex developers
164
165 If you are interested in improving the state of OpenOCD's debugging and
166 testing support, new contributions will be welcome. Motivated developers
167 can produce new target, flash or interface drivers, improve the
168 documentation, as well as more conventional bug fixes and enhancements.
169
170 The resources in this chapter are available for developers wishing to explore
171 or expand the OpenOCD source code.
172
173 @section OpenOCD Subversion Repository
174
175 You can download the current SVN version with an SVN client of your
176 choice from the following repositories:
177
178 @uref{svn://svn.berlios.de/openocd/trunk}
179
180 or
181
182 @uref{http://svn.berlios.de/svnroot/repos/openocd/trunk}
183
184 Using the SVN command line client, you can use the following command to
185 fetch the latest version (make sure there is no (non-svn) directory
186 called "openocd" in the current directory):
187
188 svn checkout svn://svn.berlios.de/openocd/trunk openocd
189
190 If you prefer GIT based tools, the @command{git-svn} package works too:
191
192 git svn clone -s svn://svn.berlios.de/openocd
193
194 The ``README'' file contains the instructions for building the project
195 from the repository.
196
197 Developers that want to contribute patches to the OpenOCD system are
198 @b{strongly} encouraged to base their work off of the most recent trunk
199 revision. Patches created against older versions may require additional
200 work from their submitter in order to be updated for newer releases.
201
202 @section Doxygen Developer Manual
203
204 During the development of the 0.2.0 release, the OpenOCD project began
205 providing a Doxygen reference manual. This document contains more
206 technical information about the software internals, development
207 processes, and similar documentation:
208
209 @uref{http://openocd.berlios.de/doc/doxygen/index.html}
210
211 This document is a work-in-progress, but contributions would be welcome
212 to fill in the gaps. All of the source files are provided in-tree,
213 listed in the Doxyfile configuration in the top of the repository trunk.
214
215 @section OpenOCD Developer Mailing List
216
217 The OpenOCD Developer Mailing List provides the primary means of
218 communication between developers:
219
220 @uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
221
222 All drivers developers are enouraged to also subscribe to the list of
223 SVN commits to keep pace with the ongoing changes:
224
225 @uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
226
227
228 @node JTAG Hardware Dongles
229 @chapter JTAG Hardware Dongles
230 @cindex dongles
231 @cindex FTDI
232 @cindex wiggler
233 @cindex zy1000
234 @cindex printer port
235 @cindex USB Adapter
236 @cindex RTCK
237
238 Defined: @b{dongle}: A small device that plugins into a computer and serves as
239 an adapter .... [snip]
240
241 In the OpenOCD case, this generally refers to @b{a small adapater} one
242 attaches to your computer via USB or the Parallel Printer Port. The
243 execption being the Zylin ZY1000 which is a small box you attach via
244 an ethernet cable. The Zylin ZY1000 has the advantage that it does not
245 require any drivers to be installed on the developer PC. It also has
246 a built in web interface. It supports RTCK/RCLK or adaptive clocking
247 and has a built in relay to power cycle targets remotely.
248
249
250 @section Choosing a Dongle
251
252 There are several things you should keep in mind when choosing a dongle.
253
254 @enumerate
255 @item @b{Voltage} What voltage is your target - 1.8, 2.8, 3.3, or 5V?
256 Does your dongle support it? You might need a level converter.
257 @item @b{Pinout} What pinout does your target board use?
258 Does your dongle support it? You may be able to use jumper
259 wires, or an "octopus" connector, to convert pinouts.
260 @item @b{Connection} Does your computer have the USB, printer, or
261 Ethernet port needed?
262 @item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking''
263 @end enumerate
264
265 @section Stand alone Systems
266
267 @b{ZY1000} See: @url{http://www.zylin.com/zy1000.html} Technically, not a
268 dongle, but a standalone box. The ZY1000 has the advantage that it does
269 not require any drivers installed on the developer PC. It also has
270 a built in web interface. It supports RTCK/RCLK or adaptive clocking
271 and has a built in relay to power cycle targets remotely.
272
273 @section USB FT2232 Based
274
275 There are many USB JTAG dongles on the market, many of them are based
276 on a chip from ``Future Technology Devices International'' (FTDI)
277 known as the FTDI FT2232; this is a USB full speed (12 Mbps) chip.
278 See: @url{http://www.ftdichip.com} for more information.
279 In summer 2009, USB high speed (480 Mbps) versions of these FTDI
280 chips are starting to become available in JTAG adapters.
281
282 @itemize @bullet
283 @item @b{usbjtag}
284 @* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
285 @item @b{jtagkey}
286 @* See: @url{http://www.amontec.com/jtagkey.shtml}
287 @item @b{jtagkey2}
288 @* See: @url{http://www.amontec.com/jtagkey2.shtml}
289 @item @b{oocdlink}
290 @* See: @url{http://www.oocdlink.com} By Joern Kaipf
291 @item @b{signalyzer}
292 @* See: @url{http://www.signalyzer.com}
293 @item @b{evb_lm3s811}
294 @* See: @url{http://www.luminarymicro.com} - The Stellaris LM3S811 eval board has an FTD2232C chip built in.
295 @item @b{luminary_icdi}
296 @* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug Interface (ICDI) Board, included in the Stellaris LM3S9B90 and LM3S9B92 Evaluation Kits.
297 @item @b{olimex-jtag}
298 @* See: @url{http://www.olimex.com}
299 @item @b{flyswatter}
300 @* See: @url{http://www.tincantools.com}
301 @item @b{turtelizer2}
302 @* See:
303 @uref{http://www.ethernut.de/en/hardware/turtelizer/index.html, Turtelizer 2}, or
304 @url{http://www.ethernut.de}
305 @item @b{comstick}
306 @* Link: @url{http://www.hitex.com/index.php?id=383}
307 @item @b{stm32stick}
308 @* Link @url{http://www.hitex.com/stm32-stick}
309 @item @b{axm0432_jtag}
310 @* Axiom AXM-0432 Link @url{http://www.axman.com}
311 @item @b{cortino}
312 @* Link @url{http://www.hitex.com/index.php?id=cortino}
313 @end itemize
314
315 @section USB JLINK based
316 There are several OEM versions of the Segger @b{JLINK} adapter. It is
317 an example of a micro controller based JTAG adapter, it uses an
318 AT91SAM764 internally.
319
320 @itemize @bullet
321 @item @b{ATMEL SAMICE} Only works with ATMEL chips!
322 @* Link: @url{http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3892}
323 @item @b{SEGGER JLINK}
324 @* Link: @url{http://www.segger.com/jlink.html}
325 @item @b{IAR J-Link}
326 @* Link: @url{http://www.iar.com/website1/1.0.1.0/369/1/index.php}
327 @end itemize
328
329 @section USB RLINK based
330 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.
331
332 @itemize @bullet
333 @item @b{Raisonance RLink}
334 @* Link: @url{http://www.raisonance.com/products/RLink.php}
335 @item @b{STM32 Primer}
336 @* Link: @url{http://www.stm32circle.com/resources/stm32primer.php}
337 @item @b{STM32 Primer2}
338 @* Link: @url{http://www.stm32circle.com/resources/stm32primer2.php}
339 @end itemize
340
341 @section USB Other
342 @itemize @bullet
343 @item @b{USBprog}
344 @* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604
345
346 @item @b{USB - Presto}
347 @* Link: @url{http://tools.asix.net/prg_presto.htm}
348
349 @item @b{Versaloon-Link}
350 @* Link: @url{http://www.simonqian.com/en/Versaloon}
351
352 @item @b{ARM-JTAG-EW}
353 @* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html}
354 @end itemize
355
356 @section IBM PC Parallel Printer Port Based
357
358 The two well known ``JTAG Parallel Ports'' cables are the Xilnx DLC5
359 and the MacGraigor Wiggler. There are many clones and variations of
360 these on the market.
361
362 Note that parallel ports are becoming much less common, so if you
363 have the choice you should probably avoid these adapters in favor
364 of USB-based ones.
365
366 @itemize @bullet
367
368 @item @b{Wiggler} - There are many clones of this.
369 @* Link: @url{http://www.macraigor.com/wiggler.htm}
370
371 @item @b{DLC5} - From XILINX - There are many clones of this
372 @* Link: Search the web for: ``XILINX DLC5'' - it is no longer
373 produced, PDF schematics are easily found and it is easy to make.
374
375 @item @b{Amontec - JTAG Accelerator}
376 @* Link: @url{http://www.amontec.com/jtag_accelerator.shtml}
377
378 @item @b{GW16402}
379 @* Link: @url{http://www.gateworks.com/products/avila_accessories/gw16042.php}
380
381 @item @b{Wiggler2}
382 @*@uref{http://www.ccac.rwth-aachen.de/@/~michaels/@/index.php/hardware/@/armjtag,
383 Improved parallel-port wiggler-style JTAG adapter}
384
385 @item @b{Wiggler_ntrst_inverted}
386 @* Yet another variation - See the source code, src/jtag/parport.c
387
388 @item @b{old_amt_wiggler}
389 @* Unknown - probably not on the market today
390
391 @item @b{arm-jtag}
392 @* Link: Most likely @url{http://www.olimex.com/dev/arm-jtag.html} [another wiggler clone]
393
394 @item @b{chameleon}
395 @* Link: @url{http://www.amontec.com/chameleon.shtml}
396
397 @item @b{Triton}
398 @* Unknown.
399
400 @item @b{Lattice}
401 @* ispDownload from Lattice Semiconductor
402 @url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf}
403
404 @item @b{flashlink}
405 @* From ST Microsystems;
406 @uref{http://www.st.com/stonline/@/products/literature/um/7889.pdf,
407 FlashLINK JTAG programing cable for PSD and uPSD}
408
409 @end itemize
410
411 @section Other...
412 @itemize @bullet
413
414 @item @b{ep93xx}
415 @* An EP93xx based Linux machine using the GPIO pins directly.
416
417 @item @b{at91rm9200}
418 @* Like the EP93xx - but an ATMEL AT91RM9200 based solution using the GPIO pins on the chip.
419
420 @end itemize
421
422 @node About JIM-Tcl
423 @chapter About JIM-Tcl
424 @cindex JIM Tcl
425 @cindex tcl
426
427 OpenOCD includes a small ``Tcl Interpreter'' known as JIM-Tcl.
428 This programming language provides a simple and extensible
429 command interpreter.
430
431 All commands presented in this Guide are extensions to JIM-Tcl.
432 You can use them as simple commands, without needing to learn
433 much of anything about Tcl.
434 Alternatively, can write Tcl programs with them.
435
436 You can learn more about JIM at its website, @url{http://jim.berlios.de}.
437
438 @itemize @bullet
439 @item @b{JIM vs. Tcl}
440 @* JIM-TCL is a stripped down version of the well known Tcl language,
441 which can be found here: @url{http://www.tcl.tk}. JIM-Tcl has far
442 fewer features. JIM-Tcl is a single .C file and a single .H file and
443 implements the basic Tcl command set. In contrast: Tcl 8.6 is a
444 4.2 MB .zip file containing 1540 files.
445
446 @item @b{Missing Features}
447 @* Our practice has been: Add/clone the real Tcl feature if/when
448 needed. We welcome JIM Tcl improvements, not bloat.
449
450 @item @b{Scripts}
451 @* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's
452 command interpreter today is a mixture of (newer)
453 JIM-Tcl commands, and (older) the orginal command interpreter.
454
455 @item @b{Commands}
456 @* At the OpenOCD telnet command line (or via the GDB mon command) one
457 can type a Tcl for() loop, set variables, etc.
458 Some of the commands documented in this guide are implemented
459 as Tcl scripts, from a @file{startup.tcl} file internal to the server.
460
461 @item @b{Historical Note}
462 @* JIM-Tcl was introduced to OpenOCD in spring 2008.
463
464 @item @b{Need a crash course in Tcl?}
465 @*@xref{Tcl Crash Course}.
466 @end itemize
467
468 @node Running
469 @chapter Running
470 @cindex command line options
471 @cindex logfile
472 @cindex directory search
473
474 The @option{--help} option shows:
475 @verbatim
476 bash$ openocd --help
477
478 --help | -h display this help
479 --version | -v display OpenOCD version
480 --file | -f use configuration file <name>
481 --search | -s dir to search for config files and scripts
482 --debug | -d set debug level <0-3>
483 --log_output | -l redirect log output to file <name>
484 --command | -c run <command>
485 --pipe | -p use pipes when talking to gdb
486 @end verbatim
487
488 By default OpenOCD reads the file configuration file @file{openocd.cfg}
489 in the current directory. To specify a different (or multiple)
490 configuration file, you can use the ``-f'' option. For example:
491
492 @example
493 openocd -f config1.cfg -f config2.cfg -f config3.cfg
494 @end example
495
496 OpenOCD starts by processing the configuration commands provided
497 on the command line or in @file{openocd.cfg}.
498 @xref{Configuration Stage}.
499 At the end of the configuration stage it verifies the JTAG scan
500 chain defined using those commands; your configuration should
501 ensure that this always succeeds.
502 Normally, OpenOCD then starts running as a daemon.
503 Alternatively, commands may be used to terminate the configuration
504 stage early, perform work (such as updating some flash memory),
505 and then shut down without acting as a daemon.
506
507 Once OpenOCD starts running as a daemon, it waits for connections from
508 clients (Telnet, GDB, Other) and processes the commands issued through
509 those channels.
510
511 If you are having problems, you can enable internal debug messages via
512 the ``-d'' option.
513
514 Also it is possible to interleave JIM-Tcl commands w/config scripts using the
515 @option{-c} command line switch.
516
517 To enable debug output (when reporting problems or working on OpenOCD
518 itself), use the @option{-d} command line switch. This sets the
519 @option{debug_level} to "3", outputting the most information,
520 including debug messages. The default setting is "2", outputting only
521 informational messages, warnings and errors. You can also change this
522 setting from within a telnet or gdb session using @command{debug_level
523 <n>} (@pxref{debug_level}).
524
525 You can redirect all output from the daemon to a file using the
526 @option{-l <logfile>} switch.
527
528 Search paths for config/script files can be added to OpenOCD by using
529 the @option{-s <search>} switch. The current directory and the OpenOCD
530 target library is in the search path by default.
531
532 For details on the @option{-p} option. @xref{Connecting to GDB}.
533
534 Note! OpenOCD will launch the GDB & telnet server even if it can not
535 establish a connection with the target. In general, it is possible for
536 the JTAG controller to be unresponsive until the target is set up
537 correctly via e.g. GDB monitor commands in a GDB init script.
538
539 @node OpenOCD Project Setup
540 @chapter OpenOCD Project Setup
541
542 To use OpenOCD with your development projects, you need to do more than
543 just connecting the JTAG adapter hardware (dongle) to your development board
544 and then starting the OpenOCD server.
545 You also need to configure that server so that it knows
546 about that adapter and board, and helps your work.
547
548 @section Hooking up the JTAG Adapter
549
550 Today's most common case is a dongle with a JTAG cable on one side
551 (such as a ribbon cable with a 10-pin or 20-pin IDC connector)
552 and a USB cable on the other.
553 Instead of USB, some cables use Ethernet;
554 older ones may use a PC parallel port, or even a serial port.
555
556 @enumerate
557 @item @emph{Start with power to your target board turned off},
558 and nothing connected to your JTAG adapter.
559 If you're particularly paranoid, unplug power to the board.
560 It's important to have the ground signal properly set up,
561 unless you are using a JTAG adapter which provides
562 galvanic isolation between the target board and the
563 debugging host.
564
565 @item @emph{Be sure it's the right kind of JTAG connector.}
566 If your dongle has a 20-pin ARM connector, you need some kind
567 of adapter (or octopus, see below) to hook it up to
568 boards using 14-pin or 10-pin connectors ... or to 20-pin
569 connectors which don't use ARM's pinout.
570
571 In the same vein, make sure the voltage levels are compatible.
572 Not all JTAG adapters have the level shifters needed to work
573 with 1.2 Volt boards.
574
575 @item @emph{Be certain the cable is properly oriented} or you might
576 damage your board. In most cases there are only two possible
577 ways to connect the cable.
578 Connect the JTAG cable from your adapter to the board.
579 Be sure it's firmly connected.
580
581 In the best case, the connector is keyed to physically
582 prevent you from inserting it wrong.
583 This is most often done using a slot on the board's male connector
584 housing, which must match a key on the JTAG cable's female connector.
585 If there's no housing, then you must look carefully and
586 make sure pin 1 on the cable hooks up to pin 1 on the board.
587 Ribbon cables are frequently all grey except for a wire on one
588 edge, which is red. The red wire is pin 1.
589
590 Sometimes dongles provide cables where one end is an ``octopus'' of
591 color coded single-wire connectors, instead of a connector block.
592 These are great when converting from one JTAG pinout to another,
593 but are tedious to set up.
594 Use these with connector pinout diagrams to help you match up the
595 adapter signals to the right board pins.
596
597 @item @emph{Connect the adapter's other end} once the JTAG cable is connected.
598 A USB, parallel, or serial port connector will go to the host which
599 you are using to run OpenOCD.
600 For Ethernet, consult the documentation and your network administrator.
601
602 For USB based JTAG adapters you have an easy sanity check at this point:
603 does the host operating system see the JTAG adapter?
604
605 @item @emph{Connect the adapter's power supply, if needed.}
606 This step is primarily for non-USB adapters,
607 but sometimes USB adapters need extra power.
608
609 @item @emph{Power up the target board.}
610 Unless you just let the magic smoke escape,
611 you're now ready to set up the OpenOCD server
612 so you can use JTAG to work with that board.
613
614 @end enumerate
615
616 Talk with the OpenOCD server using
617 telnet (@code{telnet localhost 4444} on many systems) or GDB.
618 @xref{GDB and OpenOCD}.
619
620 @section Project Directory
621
622 There are many ways you can configure OpenOCD and start it up.
623
624 A simple way to organize them all involves keeping a
625 single directory for your work with a given board.
626 When you start OpenOCD from that directory,
627 it searches there first for configuration files, scripts,
628 and for code you upload to the target board.
629 It is also the natural place to write files,
630 such as log files and data you download from the board.
631
632 @section Configuration Basics
633
634 There are two basic ways of configuring OpenOCD, and
635 a variety of ways you can mix them.
636 Think of the difference as just being how you start the server:
637
638 @itemize
639 @item Many @option{-f file} or @option{-c command} options on the command line
640 @item No options, but a @dfn{user config file}
641 in the current directory named @file{openocd.cfg}
642 @end itemize
643
644 Here is an example @file{openocd.cfg} file for a setup
645 using a Signalyzer FT2232-based JTAG adapter to talk to
646 a board with an Atmel AT91SAM7X256 microcontroller:
647
648 @example
649 source [find interface/signalyzer.cfg]
650
651 # GDB can also flash my flash!
652 gdb_memory_map enable
653 gdb_flash_program enable
654
655 source [find target/sam7x256.cfg]
656 @end example
657
658 Here is the command line equivalent of that configuration:
659
660 @example
661 openocd -f interface/signalyzer.cfg \
662 -c "gdb_memory_map enable" \
663 -c "gdb_flash_program enable" \
664 -f target/sam7x256.cfg
665 @end example
666
667 You could wrap such long command lines in shell scripts,
668 each supporting a different development task.
669 One might re-flash the board with a specific firmware version.
670 Another might set up a particular debugging or run-time environment.
671
672 @quotation Important
673 At this writing (October 2009) the command line method has
674 problems with how it treats variables.
675 For example, after @option{-c "set VAR value"}, or doing the
676 same in a script, the variable @var{VAR} will have no value
677 that can be tested in a later script.
678 @end quotation
679
680 Here we will focus on the simpler solution: one user config
681 file, including basic configuration plus any TCL procedures
682 to simplify your work.
683
684 @section User Config Files
685 @cindex config file, user
686 @cindex user config file
687 @cindex config file, overview
688
689 A user configuration file ties together all the parts of a project
690 in one place.
691 One of the following will match your situation best:
692
693 @itemize
694 @item Ideally almost everything comes from configuration files
695 provided by someone else.
696 For example, OpenOCD distributes a @file{scripts} directory
697 (probably in @file{/usr/share/openocd/scripts} on Linux).
698 Board and tool vendors can provide these too, as can individual
699 user sites; the @option{-s} command line option lets you say
700 where to find these files. (@xref{Running}.)
701 The AT91SAM7X256 example above works this way.
702
703 Three main types of non-user configuration file each have their
704 own subdirectory in the @file{scripts} directory:
705
706 @enumerate
707 @item @b{interface} -- one for each kind of JTAG adapter/dongle
708 @item @b{board} -- one for each different board
709 @item @b{target} -- the chips which integrate CPUs and other JTAG TAPs
710 @end enumerate
711
712 Best case: include just two files, and they handle everything else.
713 The first is an interface config file.
714 The second is board-specific, and it sets up the JTAG TAPs and
715 their GDB targets (by deferring to some @file{target.cfg} file),
716 declares all flash memory, and leaves you nothing to do except
717 meet your deadline:
718
719 @example
720 source [find interface/olimex-jtag-tiny.cfg]
721 source [find board/csb337.cfg]
722 @end example
723
724 Boards with a single microcontroller often won't need more
725 than the target config file, as in the AT91SAM7X256 example.
726 That's because there is no external memory (flash, DDR RAM), and
727 the board differences are encapsulated by application code.
728
729 @item You can often reuse some standard config files but
730 need to write a few new ones, probably a @file{board.cfg} file.
731 You will be using commands described later in this User's Guide,
732 and working with the guidelines in the next chapter.
733
734 For example, there may be configuration files for your JTAG adapter
735 and target chip, but you need a new board-specific config file
736 giving access to your particular flash chips.
737 Or you might need to write another target chip configuration file
738 for a new chip built around the Cortex M3 core.
739
740 @quotation Note
741 When you write new configuration files, please submit
742 them for inclusion in the next OpenOCD release.
743 For example, a @file{board/newboard.cfg} file will help the
744 next users of that board, and a @file{target/newcpu.cfg}
745 will help support users of any board using that chip.
746 @end quotation
747
748 @item
749 You may may need to write some C code.
750 It may be as simple as a supporting a new ft2232 or parport
751 based dongle; a bit more involved, like a NAND or NOR flash
752 controller driver; or a big piece of work like supporting
753 a new chip architecture.
754 @end itemize
755
756 Reuse the existing config files when you can.
757 Look first in the @file{scripts/boards} area, then @file{scripts/targets}.
758 You may find a board configuration that's a good example to follow.
759
760 When you write config files, separate the reusable parts
761 (things every user of that interface, chip, or board needs)
762 from ones specific to your environment and debugging approach.
763 @itemize
764
765 @item
766 For example, a @code{gdb-attach} event handler that invokes
767 the @command{reset init} command will interfere with debugging
768 early boot code, which performs some of the same actions
769 that the @code{reset-init} event handler does.
770
771 @item
772 Likewise, the @command{arm9tdmi vector_catch} command (or
773 @cindex vector_catch
774 its siblings @command{xscale vector_catch}
775 and @command{cortex_m3 vector_catch}) can be a timesaver
776 during some debug sessions, but don't make everyone use that either.
777 Keep those kinds of debugging aids in your user config file,
778 along with messaging and tracing setup.
779 (@xref{Software Debug Messages and Tracing}.)
780
781 @item
782 You might need to override some defaults.
783 For example, you might need to move, shrink, or back up the target's
784 work area if your application needs much SRAM.
785
786 @item
787 TCP/IP port configuration is another example of something which
788 is environment-specific, and should only appear in
789 a user config file. @xref{TCP/IP Ports}.
790 @end itemize
791
792 @section Project-Specific Utilities
793
794 A few project-specific utility
795 routines may well speed up your work.
796 Write them, and keep them in your project's user config file.
797
798 For example, if you are making a boot loader work on a
799 board, it's nice to be able to debug the ``after it's
800 loaded to RAM'' parts separately from the finicky early
801 code which sets up the DDR RAM controller and clocks.
802 A script like this one, or a more GDB-aware sibling,
803 may help:
804
805 @example
806 proc ramboot @{ @} @{
807 # Reset, running the target's "reset-init" scripts
808 # to initialize clocks and the DDR RAM controller.
809 # Leave the CPU halted.
810 reset init
811
812 # Load CONFIG_SKIP_LOWLEVEL_INIT version into DDR RAM.
813 load_image u-boot.bin 0x20000000
814
815 # Start running.
816 resume 0x20000000
817 @}
818 @end example
819
820 Then once that code is working you will need to make it
821 boot from NOR flash; a different utility would help.
822 Alternatively, some developers write to flash using GDB.
823 (You might use a similar script if you're working with a flash
824 based microcontroller application instead of a boot loader.)
825
826 @example
827 proc newboot @{ @} @{
828 # Reset, leaving the CPU halted. The "reset-init" event
829 # proc gives faster access to the CPU and to NOR flash;
830 # "reset halt" would be slower.
831 reset init
832
833 # Write standard version of U-Boot into the first two
834 # sectors of NOR flash ... the standard version should
835 # do the same lowlevel init as "reset-init".
836 flash protect 0 0 1 off
837 flash erase_sector 0 0 1
838 flash write_bank 0 u-boot.bin 0x0
839 flash protect 0 0 1 on
840
841 # Reboot from scratch using that new boot loader.
842 reset run
843 @}
844 @end example
845
846 You may need more complicated utility procedures when booting
847 from NAND.
848 That often involves an extra bootloader stage,
849 running from on-chip SRAM to perform DDR RAM setup so it can load
850 the main bootloader code (which won't fit into that SRAM).
851
852 Other helper scripts might be used to write production system images,
853 involving considerably more than just a three stage bootloader.
854
855 @section Target Software Changes
856
857 Sometimes you may want to make some small changes to the software
858 you're developing, to help make JTAG debugging work better.
859 For example, in C or assembly language code you might
860 use @code{#ifdef JTAG_DEBUG} (or its converse) around code
861 handling issues like:
862
863 @itemize @bullet
864
865 @item @b{ARM Wait-For-Interrupt}...
866 Many ARM chips synchronize the JTAG clock using the core clock.
867 Low power states which stop that core clock thus prevent JTAG access.
868 Idle loops in tasking environments often enter those low power states
869 via the @code{WFI} instruction (or its coprocessor equivalent, before ARMv7).
870
871 You may want to @emph{disable that instruction} in source code,
872 or otherwise prevent using that state,
873 to ensure you can get JTAG access at any time.
874 For example, the OpenOCD @command{halt} command may not
875 work for an idle processor otherwise.
876
877 @item @b{Delay after reset}...
878 Not all chips have good support for debugger access
879 right after reset; many LPC2xxx chips have issues here.
880 Similarly, applications that reconfigure pins used for
881 JTAG access as they start will also block debugger access.
882
883 To work with boards like this, @emph{enable a short delay loop}
884 the first thing after reset, before "real" startup activities.
885 For example, one second's delay is usually more than enough
886 time for a JTAG debugger to attach, so that
887 early code execution can be debugged
888 or firmware can be replaced.
889
890 @item @b{Debug Communications Channel (DCC)}...
891 Some processors include mechanisms to send messages over JTAG.
892 Many ARM cores support these, as do some cores from other vendors.
893 (OpenOCD may be able to use this DCC internally, speeding up some
894 operations like writing to memory.)
895
896 Your application may want to deliver various debugging messages
897 over JTAG, by @emph{linking with a small library of code}
898 provided with OpenOCD and using the utilities there to send
899 various kinds of message.
900 @xref{Software Debug Messages and Tracing}.
901
902 @end itemize
903
904 @node Config File Guidelines
905 @chapter Config File Guidelines
906
907 This chapter is aimed at any user who needs to write a config file,
908 including developers and integrators of OpenOCD and any user who
909 needs to get a new board working smoothly.
910 It provides guidelines for creating those files.
911
912 You should find the following directories under @t{$(INSTALLDIR)/scripts},
913 with files including the ones listed here.
914 Use them as-is where you can; or as models for new files.
915
916 @itemize @bullet
917 @item @file{interface} ...
918 think JTAG Dongle. Files that configure JTAG adapters go here.
919 @example
920 $ ls interface
921 arm-jtag-ew.cfg hitex_str9-comstick.cfg oocdlink.cfg
922 arm-usb-ocd.cfg icebear.cfg openocd-usb.cfg
923 at91rm9200.cfg jlink.cfg parport.cfg
924 axm0432.cfg jtagkey2.cfg parport_dlc5.cfg
925 calao-usb-a9260-c01.cfg jtagkey.cfg rlink.cfg
926 calao-usb-a9260-c02.cfg jtagkey-tiny.cfg sheevaplug.cfg
927 calao-usb-a9260.cfg luminary.cfg signalyzer.cfg
928 chameleon.cfg luminary-icdi.cfg stm32-stick.cfg
929 cortino.cfg luminary-lm3s811.cfg turtelizer2.cfg
930 dummy.cfg olimex-arm-usb-ocd.cfg usbprog.cfg
931 flyswatter.cfg olimex-jtag-tiny.cfg vsllink.cfg
932 $
933 @end example
934 @item @file{board} ...
935 think Circuit Board, PWA, PCB, they go by many names. Board files
936 contain initialization items that are specific to a board.
937 They reuse target configuration files, since the same
938 microprocessor chips are used on many boards,
939 but support for external parts varies widely. For
940 example, the SDRAM initialization sequence for the board, or the type
941 of external flash and what address it uses. Any initialization
942 sequence to enable that external flash or SDRAM should be found in the
943 board file. Boards may also contain multiple targets: two CPUs; or
944 a CPU and an FPGA.
945 @example
946 $ ls board
947 arm_evaluator7t.cfg keil_mcb1700.cfg
948 at91rm9200-dk.cfg keil_mcb2140.cfg
949 at91sam9g20-ek.cfg linksys_nslu2.cfg
950 atmel_at91sam7s-ek.cfg logicpd_imx27.cfg
951 atmel_at91sam9260-ek.cfg mini2440.cfg
952 atmel_sam3u_ek.cfg olimex_LPC2378STK.cfg
953 crossbow_tech_imote2.cfg olimex_lpc_h2148.cfg
954 csb337.cfg olimex_sam7_ex256.cfg
955 csb732.cfg olimex_sam9_l9260.cfg
956 digi_connectcore_wi-9c.cfg olimex_stm32_h103.cfg
957 dm355evm.cfg omap2420_h4.cfg
958 dm365evm.cfg osk5912.cfg
959 dm6446evm.cfg pic-p32mx.cfg
960 eir.cfg propox_mmnet1001.cfg
961 ek-lm3s1968.cfg pxa255_sst.cfg
962 ek-lm3s3748.cfg sheevaplug.cfg
963 ek-lm3s811.cfg stm3210e_eval.cfg
964 ek-lm3s9b9x.cfg stm32f10x_128k_eval.cfg
965 hammer.cfg str910-eval.cfg
966 hitex_lpc2929.cfg telo.cfg
967 hitex_stm32-performancestick.cfg ti_beagleboard.cfg
968 hitex_str9-comstick.cfg topas910.cfg
969 iar_str912_sk.cfg topasa900.cfg
970 imx27ads.cfg unknown_at91sam9260.cfg
971 imx27lnst.cfg x300t.cfg
972 imx31pdk.cfg zy1000.cfg
973 $
974 @end example
975 @item @file{target} ...
976 think chip. The ``target'' directory represents the JTAG TAPs
977 on a chip
978 which OpenOCD should control, not a board. Two common types of targets
979 are ARM chips and FPGA or CPLD chips.
980 When a chip has multiple TAPs (maybe it has both ARM and DSP cores),
981 the target config file defines all of them.
982 @example
983 $ ls target
984 aduc702x.cfg imx27.cfg pxa255.cfg
985 ar71xx.cfg imx31.cfg pxa270.cfg
986 at91eb40a.cfg imx35.cfg readme.txt
987 at91r40008.cfg is5114.cfg sam7se512.cfg
988 at91rm9200.cfg ixp42x.cfg sam7x256.cfg
989 at91sam3u1c.cfg lm3s1968.cfg samsung_s3c2410.cfg
990 at91sam3u1e.cfg lm3s3748.cfg samsung_s3c2440.cfg
991 at91sam3u2c.cfg lm3s6965.cfg samsung_s3c2450.cfg
992 at91sam3u2e.cfg lm3s811.cfg samsung_s3c4510.cfg
993 at91sam3u4c.cfg lm3s9b9x.cfg samsung_s3c6410.cfg
994 at91sam3u4e.cfg lpc1768.cfg sharp_lh79532.cfg
995 at91sam3uXX.cfg lpc2103.cfg smdk6410.cfg
996 at91sam7sx.cfg lpc2124.cfg smp8634.cfg
997 at91sam9260.cfg lpc2129.cfg stm32.cfg
998 c100.cfg lpc2148.cfg str710.cfg
999 c100config.tcl lpc2294.cfg str730.cfg
1000 c100helper.tcl lpc2378.cfg str750.cfg
1001 c100regs.tcl lpc2478.cfg str912.cfg
1002 cs351x.cfg lpc2900.cfg telo.cfg
1003 davinci.cfg mega128.cfg ti_dm355.cfg
1004 dragonite.cfg netx500.cfg ti_dm365.cfg
1005 epc9301.cfg omap2420.cfg ti_dm6446.cfg
1006 feroceon.cfg omap3530.cfg tmpa900.cfg
1007 icepick.cfg omap5912.cfg tmpa910.cfg
1008 imx21.cfg pic32mx.cfg xba_revA3.cfg
1009 $
1010 @end example
1011 @item @emph{more} ... browse for other library files which may be useful.
1012 For example, there are various generic and CPU-specific utilities.
1013 @end itemize
1014
1015 The @file{openocd.cfg} user config
1016 file may override features in any of the above files by
1017 setting variables before sourcing the target file, or by adding
1018 commands specific to their situation.
1019
1020 @section Interface Config Files
1021
1022 The user config file
1023 should be able to source one of these files with a command like this:
1024
1025 @example
1026 source [find interface/FOOBAR.cfg]
1027 @end example
1028
1029 A preconfigured interface file should exist for every interface in use
1030 today, that said, perhaps some interfaces have only been used by the
1031 sole developer who created it.
1032
1033 A separate chapter gives information about how to set these up.
1034 @xref{Interface - Dongle Configuration}.
1035 Read the OpenOCD source code if you have a new kind of hardware interface
1036 and need to provide a driver for it.
1037
1038 @section Board Config Files
1039 @cindex config file, board
1040 @cindex board config file
1041
1042 The user config file
1043 should be able to source one of these files with a command like this:
1044
1045 @example
1046 source [find board/FOOBAR.cfg]
1047 @end example
1048
1049 The point of a board config file is to package everything
1050 about a given board that user config files need to know.
1051 In summary the board files should contain (if present)
1052
1053 @enumerate
1054 @item One or more @command{source [target/...cfg]} statements
1055 @item NOR flash configuration (@pxref{NOR Configuration})
1056 @item NAND flash configuration (@pxref{NAND Configuration})
1057 @item Target @code{reset} handlers for SDRAM and I/O configuration
1058 @item JTAG adapter reset configuration (@pxref{Reset Configuration})
1059 @item All things that are not ``inside a chip''
1060 @end enumerate
1061
1062 Generic things inside target chips belong in target config files,
1063 not board config files. So for example a @code{reset-init} event
1064 handler should know board-specific oscillator and PLL parameters,
1065 which it passes to target-specific utility code.
1066
1067 The most complex task of a board config file is creating such a
1068 @code{reset-init} event handler.
1069 Define those handlers last, after you verify the rest of the board
1070 configuration works.
1071
1072 @subsection Communication Between Config files
1073
1074 In addition to target-specific utility code, another way that
1075 board and target config files communicate is by following a
1076 convention on how to use certain variables.
1077
1078 The full Tcl/Tk language supports ``namespaces'', but JIM-Tcl does not.
1079 Thus the rule we follow in OpenOCD is this: Variables that begin with
1080 a leading underscore are temporary in nature, and can be modified and
1081 used at will within a target configuration file.
1082
1083 Complex board config files can do the things like this,
1084 for a board with three chips:
1085
1086 @example
1087 # Chip #1: PXA270 for network side, big endian
1088 set CHIPNAME network
1089 set ENDIAN big
1090 source [find target/pxa270.cfg]
1091 # on return: _TARGETNAME = network.cpu
1092 # other commands can refer to the "network.cpu" target.
1093 $_TARGETNAME configure .... events for this CPU..
1094
1095 # Chip #2: PXA270 for video side, little endian
1096 set CHIPNAME video
1097 set ENDIAN little
1098 source [find target/pxa270.cfg]
1099 # on return: _TARGETNAME = video.cpu
1100 # other commands can refer to the "video.cpu" target.
1101 $_TARGETNAME configure .... events for this CPU..
1102
1103 # Chip #3: Xilinx FPGA for glue logic
1104 set CHIPNAME xilinx
1105 unset ENDIAN
1106 source [find target/spartan3.cfg]
1107 @end example
1108
1109 That example is oversimplified because it doesn't show any flash memory,
1110 or the @code{reset-init} event handlers to initialize external DRAM
1111 or (assuming it needs it) load a configuration into the FPGA.
1112 Such features are usually needed for low-level work with many boards,
1113 where ``low level'' implies that the board initialization software may
1114 not be working. (That's a common reason to need JTAG tools. Another
1115 is to enable working with microcontroller-based systems, which often
1116 have no debugging support except a JTAG connector.)
1117
1118 Target config files may also export utility functions to board and user
1119 config files. Such functions should use name prefixes, to help avoid
1120 naming collisions.
1121
1122 Board files could also accept input variables from user config files.
1123 For example, there might be a @code{J4_JUMPER} setting used to identify
1124 what kind of flash memory a development board is using, or how to set
1125 up other clocks and peripherals.
1126
1127 @subsection Variable Naming Convention
1128 @cindex variable names
1129
1130 Most boards have only one instance of a chip.
1131 However, it should be easy to create a board with more than
1132 one such chip (as shown above).
1133 Accordingly, we encourage these conventions for naming
1134 variables associated with different @file{target.cfg} files,
1135 to promote consistency and
1136 so that board files can override target defaults.
1137
1138 Inputs to target config files include:
1139
1140 @itemize @bullet
1141 @item @code{CHIPNAME} ...
1142 This gives a name to the overall chip, and is used as part of
1143 tap identifier dotted names.
1144 While the default is normally provided by the chip manufacturer,
1145 board files may need to distinguish between instances of a chip.
1146 @item @code{ENDIAN} ...
1147 By default @option{little} - although chips may hard-wire @option{big}.
1148 Chips that can't change endianness don't need to use this variable.
1149 @item @code{CPUTAPID} ...
1150 When OpenOCD examines the JTAG chain, it can be told verify the
1151 chips against the JTAG IDCODE register.
1152 The target file will hold one or more defaults, but sometimes the
1153 chip in a board will use a different ID (perhaps a newer revision).
1154 @end itemize
1155
1156 Outputs from target config files include:
1157
1158 @itemize @bullet
1159 @item @code{_TARGETNAME} ...
1160 By convention, this variable is created by the target configuration
1161 script. The board configuration file may make use of this variable to
1162 configure things like a ``reset init'' script, or other things
1163 specific to that board and that target.
1164 If the chip has 2 targets, the names are @code{_TARGETNAME0},
1165 @code{_TARGETNAME1}, ... etc.
1166 @end itemize
1167
1168 @subsection The reset-init Event Handler
1169 @cindex event, reset-init
1170 @cindex reset-init handler
1171
1172 Board config files run in the OpenOCD configuration stage;
1173 they can't use TAPs or targets, since they haven't been
1174 fully set up yet.
1175 This means you can't write memory or access chip registers;
1176 you can't even verify that a flash chip is present.
1177 That's done later in event handlers, of which the target @code{reset-init}
1178 handler is one of the most important.
1179
1180 Except on microcontrollers, the basic job of @code{reset-init} event
1181 handlers is setting up flash and DRAM, as normally handled by boot loaders.
1182 Microcontrollers rarely use boot loaders; they run right out of their
1183 on-chip flash and SRAM memory. But they may want to use one of these
1184 handlers too, if just for developer convenience.
1185
1186 @quotation Note
1187 Because this is so very board-specific, and chip-specific, no examples
1188 are included here.
1189 Instead, look at the board config files distributed with OpenOCD.
1190 If you have a boot loader, its source code may also be useful.
1191 @end quotation
1192
1193 Some of this code could probably be shared between different boards.
1194 For example, setting up a DRAM controller often doesn't differ by
1195 much except the bus width (16 bits or 32?) and memory timings, so a
1196 reusable TCL procedure loaded by the @file{target.cfg} file might take
1197 those as parameters.
1198 Similarly with oscillator, PLL, and clock setup;
1199 and disabling the watchdog.
1200 Structure the code cleanly, and provide comments to help
1201 the next developer doing such work.
1202 (@emph{You might be that next person} trying to reuse init code!)
1203
1204 The last thing normally done in a @code{reset-init} handler is probing
1205 whatever flash memory was configured. For most chips that needs to be
1206 done while the associated target is halted, either because JTAG memory
1207 access uses the CPU or to prevent conflicting CPU access.
1208
1209 @subsection JTAG Clock Rate
1210
1211 Before your @code{reset-init} handler has set up
1212 the PLLs and clocking, you may need to run with
1213 a low JTAG clock rate.
1214 @xref{JTAG Speed}.
1215 Then you'd increase that rate after your handler has
1216 made it possible to use the faster JTAG clock.
1217 When the initial low speed is board-specific, for example
1218 because it depends on a board-specific oscillator speed, then
1219 you should probably set it up in the board config file;
1220 if it's target-specific, it belongs in the target config file.
1221
1222 For most ARM-based processors the fastest JTAG clock@footnote{A FAQ
1223 @uref{http://www.arm.com/support/faqdev/4170.html} gives details.}
1224 is one sixth of the CPU clock; or one eighth for ARM11 cores.
1225 Consult chip documentation to determine the peak JTAG clock rate,
1226 which might be less than that.
1227
1228 @quotation Warning
1229 On most ARMs, JTAG clock detection is coupled to the core clock, so
1230 software using a @option{wait for interrupt} operation blocks JTAG access.
1231 Adaptive clocking provides a partial workaround, but a more complete
1232 solution just avoids using that instruction with JTAG debuggers.
1233 @end quotation
1234
1235 If the board supports adaptive clocking, use the @command{jtag_rclk}
1236 command, in case your board is used with JTAG adapter which
1237 also supports it. Otherwise use @command{jtag_khz}.
1238 Set the slow rate at the beginning of the reset sequence,
1239 and the faster rate as soon as the clocks are at full speed.
1240
1241 @section Target Config Files
1242 @cindex config file, target
1243 @cindex target config file
1244
1245 Board config files communicate with target config files using
1246 naming conventions as described above, and may source one or
1247 more target config files like this:
1248
1249 @example
1250 source [find target/FOOBAR.cfg]
1251 @end example
1252
1253 The point of a target config file is to package everything
1254 about a given chip that board config files need to know.
1255 In summary the target files should contain
1256
1257 @enumerate
1258 @item Set defaults
1259 @item Add TAPs to the scan chain
1260 @item Add CPU targets (includes GDB support)
1261 @item CPU/Chip/CPU-Core specific features
1262 @item On-Chip flash
1263 @end enumerate
1264
1265 As a rule of thumb, a target file sets up only one chip.
1266 For a microcontroller, that will often include a single TAP,
1267 which is a CPU needing a GDB target, and its on-chip flash.
1268
1269 More complex chips may include multiple TAPs, and the target
1270 config file may need to define them all before OpenOCD
1271 can talk to the chip.
1272 For example, some phone chips have JTAG scan chains that include
1273 an ARM core for operating system use, a DSP,
1274 another ARM core embedded in an image processing engine,
1275 and other processing engines.
1276
1277 @subsection Default Value Boiler Plate Code
1278
1279 All target configuration files should start with code like this,
1280 letting board config files express environment-specific
1281 differences in how things should be set up.
1282
1283 @example
1284 # Boards may override chip names, perhaps based on role,
1285 # but the default should match what the vendor uses
1286 if @{ [info exists CHIPNAME] @} @{
1287 set _CHIPNAME $CHIPNAME
1288 @} else @{
1289 set _CHIPNAME sam7x256
1290 @}
1291
1292 # ONLY use ENDIAN with targets that can change it.
1293 if @{ [info exists ENDIAN] @} @{
1294 set _ENDIAN $ENDIAN
1295 @} else @{
1296 set _ENDIAN little
1297 @}
1298
1299 # TAP identifiers may change as chips mature, for example with
1300 # new revision fields (the "3" here). Pick a good default; you
1301 # can pass several such identifiers to the "jtag newtap" command.
1302 if @{ [info exists CPUTAPID ] @} @{
1303 set _CPUTAPID $CPUTAPID
1304 @} else @{
1305 set _CPUTAPID 0x3f0f0f0f
1306 @}
1307 @end example
1308 @c but 0x3f0f0f0f is for an str73x part ...
1309
1310 @emph{Remember:} Board config files may include multiple target
1311 config files, or the same target file multiple times
1312 (changing at least @code{CHIPNAME}).
1313
1314 Likewise, the target configuration file should define
1315 @code{_TARGETNAME} (or @code{_TARGETNAME0} etc) and
1316 use it later on when defining debug targets:
1317
1318 @example
1319 set _TARGETNAME $_CHIPNAME.cpu
1320 target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
1321 @end example
1322
1323 @subsection Adding TAPs to the Scan Chain
1324 After the ``defaults'' are set up,
1325 add the TAPs on each chip to the JTAG scan chain.
1326 @xref{TAP Declaration}, and the naming convention
1327 for taps.
1328
1329 In the simplest case the chip has only one TAP,
1330 probably for a CPU or FPGA.
1331 The config file for the Atmel AT91SAM7X256
1332 looks (in part) like this:
1333
1334 @example
1335 jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf \
1336 -expected-id $_CPUTAPID
1337 @end example
1338
1339 A board with two such at91sam7 chips would be able
1340 to source such a config file twice, with different
1341 values for @code{CHIPNAME}, so
1342 it adds a different TAP each time.
1343
1344 If there are nonzero @option{-expected-id} values,
1345 OpenOCD attempts to verify the actual tap id against those values.
1346 It will issue error messages if there is mismatch, which
1347 can help to pinpoint problems in OpenOCD configurations.
1348
1349 @example
1350 JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f
1351 (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
1352 ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f
1353 ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
1354 ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3
1355 @end example
1356
1357 There are more complex examples too, with chips that have
1358 multiple TAPs. Ones worth looking at include:
1359
1360 @itemize
1361 @item @file{target/omap3530.cfg} -- with disabled ARM and DSP,
1362 plus a JRC to enable them
1363 @item @file{target/str912.cfg} -- with flash, CPU, and boundary scan
1364 @item @file{target/ti_dm355.cfg} -- with ETM, ARM, and JRC (this JRC
1365 is not currently used)
1366 @end itemize
1367
1368 @subsection Add CPU targets
1369
1370 After adding a TAP for a CPU, you should set it up so that
1371 GDB and other commands can use it.
1372 @xref{CPU Configuration}.
1373 For the at91sam7 example above, the command can look like this;
1374 note that @code{$_ENDIAN} is not needed, since OpenOCD defaults
1375 to little endian, and this chip doesn't support changing that.
1376
1377 @example
1378 set _TARGETNAME $_CHIPNAME.cpu
1379 target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
1380 @end example
1381
1382 Work areas are small RAM areas associated with CPU targets.
1383 They are used by OpenOCD to speed up downloads,
1384 and to download small snippets of code to program flash chips.
1385 If the chip includes a form of ``on-chip-ram'' - and many do - define
1386 a work area if you can.
1387 Again using the at91sam7 as an example, this can look like:
1388
1389 @example
1390 $_TARGETNAME configure -work-area-phys 0x00200000 \
1391 -work-area-size 0x4000 -work-area-backup 0
1392 @end example
1393
1394 @subsection Chip Reset Setup
1395
1396 As a rule, you should put the @command{reset_config} command
1397 into the board file. Most things you think you know about a
1398 chip can be tweaked by the board.
1399
1400 Some chips have specific ways the TRST and SRST signals are
1401 managed. In the unusual case that these are @emph{chip specific}
1402 and can never be changed by board wiring, they could go here.
1403
1404 Some chips need special attention during reset handling if
1405 they're going to be used with JTAG.
1406 An example might be needing to send some commands right
1407 after the target's TAP has been reset, providing a
1408 @code{reset-deassert-post} event handler that writes a chip
1409 register to report that JTAG debugging is being done.
1410
1411 JTAG clocking constraints often change during reset, and in
1412 some cases target config files (rather than board config files)
1413 are the right places to handle some of those issues.
1414 For example, immediately after reset most chips run using a
1415 slower clock than they will use later.
1416 That means that after reset (and potentially, as OpenOCD
1417 first starts up) they must use a slower JTAG clock rate
1418 than they will use later.
1419 @xref{JTAG Speed}.
1420
1421 @quotation Important
1422 When you are debugging code that runs right after chip
1423 reset, getting these issues right is critical.
1424 In particular, if you see intermittent failures when
1425 OpenOCD verifies the scan chain after reset,
1426 look at how you are setting up JTAG clocking.
1427 @end quotation
1428
1429 @subsection ARM Core Specific Hacks
1430
1431 If the chip has a DCC, enable it. If the chip is an ARM9 with some
1432 special high speed download features - enable it.
1433
1434 If present, the MMU, the MPU and the CACHE should be disabled.
1435
1436 Some ARM cores are equipped with trace support, which permits
1437 examination of the instruction and data bus activity. Trace
1438 activity is controlled through an ``Embedded Trace Module'' (ETM)
1439 on one of the core's scan chains. The ETM emits voluminous data
1440 through a ``trace port''. (@xref{ARM Hardware Tracing}.)
1441 If you are using an external trace port,
1442 configure it in your board config file.
1443 If you are using an on-chip ``Embedded Trace Buffer'' (ETB),
1444 configure it in your target config file.
1445
1446 @example
1447 etm config $_TARGETNAME 16 normal full etb
1448 etb config $_TARGETNAME $_CHIPNAME.etb
1449 @end example
1450
1451 @subsection Internal Flash Configuration
1452
1453 This applies @b{ONLY TO MICROCONTROLLERS} that have flash built in.
1454
1455 @b{Never ever} in the ``target configuration file'' define any type of
1456 flash that is external to the chip. (For example a BOOT flash on
1457 Chip Select 0.) Such flash information goes in a board file - not
1458 the TARGET (chip) file.
1459
1460 Examples:
1461 @itemize @bullet
1462 @item at91sam7x256 - has 256K flash YES enable it.
1463 @item str912 - has flash internal YES enable it.
1464 @item imx27 - uses boot flash on CS0 - it goes in the board file.
1465 @item pxa270 - again - CS0 flash - it goes in the board file.
1466 @end itemize
1467
1468 @node Daemon Configuration
1469 @chapter Daemon Configuration
1470 @cindex initialization
1471 The commands here are commonly found in the openocd.cfg file and are
1472 used to specify what TCP/IP ports are used, and how GDB should be
1473 supported.
1474
1475 @anchor{Configuration Stage}
1476 @section Configuration Stage
1477 @cindex configuration stage
1478 @cindex config command
1479
1480 When the OpenOCD server process starts up, it enters a
1481 @emph{configuration stage} which is the only time that
1482 certain commands, @emph{configuration commands}, may be issued.
1483 In this manual, the definition of a configuration command is
1484 presented as a @emph{Config Command}, not as a @emph{Command}
1485 which may be issued interactively.
1486
1487 Those configuration commands include declaration of TAPs,
1488 flash banks,
1489 the interface used for JTAG communication,
1490 and other basic setup.
1491 The server must leave the configuration stage before it
1492 may access or activate TAPs.
1493 After it leaves this stage, configuration commands may no
1494 longer be issued.
1495
1496 The first thing OpenOCD does after leaving the configuration
1497 stage is to verify that it can talk to the scan chain
1498 (list of TAPs) which has been configured.
1499 It will warn if it doesn't find TAPs it expects to find,
1500 or finds TAPs that aren't supposed to be there.
1501 You should see no errors at this point.
1502 If you see errors, resolve them by correcting the
1503 commands you used to configure the server.
1504 Common errors include using an initial JTAG speed that's too
1505 fast, and not providing the right IDCODE values for the TAPs
1506 on the scan chain.
1507
1508 @deffn {Config Command} init
1509 This command terminates the configuration stage and
1510 enters the normal command mode. This can be useful to add commands to
1511 the startup scripts and commands such as resetting the target,
1512 programming flash, etc. To reset the CPU upon startup, add "init" and
1513 "reset" at the end of the config script or at the end of the OpenOCD
1514 command line using the @option{-c} command line switch.
1515
1516 If this command does not appear in any startup/configuration file
1517 OpenOCD executes the command for you after processing all
1518 configuration files and/or command line options.
1519
1520 @b{NOTE:} This command normally occurs at or near the end of your
1521 openocd.cfg file to force OpenOCD to ``initialize'' and make the
1522 targets ready. For example: If your openocd.cfg file needs to
1523 read/write memory on your target, @command{init} must occur before
1524 the memory read/write commands. This includes @command{nand probe}.
1525 @end deffn
1526
1527 @anchor{TCP/IP Ports}
1528 @section TCP/IP Ports
1529 @cindex TCP port
1530 @cindex server
1531 @cindex port
1532 @cindex security
1533 The OpenOCD server accepts remote commands in several syntaxes.
1534 Each syntax uses a different TCP/IP port, which you may specify
1535 only during configuration (before those ports are opened).
1536
1537 For reasons including security, you may wish to prevent remote
1538 access using one or more of these ports.
1539 In such cases, just specify the relevant port number as zero.
1540 If you disable all access through TCP/IP, you will need to
1541 use the command line @option{-pipe} option.
1542
1543 @deffn {Command} gdb_port (number)
1544 @cindex GDB server
1545 Specify or query the first port used for incoming GDB connections.
1546 The GDB port for the
1547 first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
1548 When not specified during the configuration stage,
1549 the port @var{number} defaults to 3333.
1550 When specified as zero, this port is not activated.
1551 @end deffn
1552
1553 @deffn {Command} tcl_port (number)
1554 Specify or query the port used for a simplified RPC
1555 connection that can be used by clients to issue TCL commands and get the
1556 output from the Tcl engine.
1557 Intended as a machine interface.
1558 When not specified during the configuration stage,
1559 the port @var{number} defaults to 6666.
1560 When specified as zero, this port is not activated.
1561 @end deffn
1562
1563 @deffn {Command} telnet_port (number)
1564 Specify or query the
1565 port on which to listen for incoming telnet connections.
1566 This port is intended for interaction with one human through TCL commands.
1567 When not specified during the configuration stage,
1568 the port @var{number} defaults to 4444.
1569 When specified as zero, this port is not activated.
1570 @end deffn
1571
1572 @anchor{GDB Configuration}
1573 @section GDB Configuration
1574 @cindex GDB
1575 @cindex GDB configuration
1576 You can reconfigure some GDB behaviors if needed.
1577 The ones listed here are static and global.
1578 @xref{Target Configuration}, about configuring individual targets.
1579 @xref{Target Events}, about configuring target-specific event handling.
1580
1581 @anchor{gdb_breakpoint_override}
1582 @deffn {Command} gdb_breakpoint_override [@option{hard}|@option{soft}|@option{disable}]
1583 Force breakpoint type for gdb @command{break} commands.
1584 This option supports GDB GUIs which don't
1585 distinguish hard versus soft breakpoints, if the default OpenOCD and
1586 GDB behaviour is not sufficient. GDB normally uses hardware
1587 breakpoints if the memory map has been set up for flash regions.
1588 @end deffn
1589
1590 @deffn {Config Command} gdb_detach (@option{resume}|@option{reset}|@option{halt}|@option{nothing})
1591 Configures what OpenOCD will do when GDB detaches from the daemon.
1592 Default behaviour is @option{resume}.
1593 @end deffn
1594
1595 @anchor{gdb_flash_program}
1596 @deffn {Config Command} gdb_flash_program (@option{enable}|@option{disable})
1597 Set to @option{enable} to cause OpenOCD to program the flash memory when a
1598 vFlash packet is received.
1599 The default behaviour is @option{enable}.
1600 @end deffn
1601
1602 @deffn {Config Command} gdb_memory_map (@option{enable}|@option{disable})
1603 Set to @option{enable} to cause OpenOCD to send the memory configuration to GDB when
1604 requested. GDB will then know when to set hardware breakpoints, and program flash
1605 using the GDB load command. @command{gdb_flash_program enable} must also be enabled
1606 for flash programming to work.
1607 Default behaviour is @option{enable}.
1608 @xref{gdb_flash_program}.
1609 @end deffn
1610
1611 @deffn {Config Command} gdb_report_data_abort (@option{enable}|@option{disable})
1612 Specifies whether data aborts cause an error to be reported
1613 by GDB memory read packets.
1614 The default behaviour is @option{disable};
1615 use @option{enable} see these errors reported.
1616 @end deffn
1617
1618 @anchor{Event Polling}
1619 @section Event Polling
1620
1621 Hardware debuggers are parts of asynchronous systems,
1622 where significant events can happen at any time.
1623 The OpenOCD server needs to detect some of these events,
1624 so it can report them to through TCL command line
1625 or to GDB.
1626
1627 Examples of such events include:
1628
1629 @itemize
1630 @item One of the targets can stop running ... maybe it triggers
1631 a code breakpoint or data watchpoint, or halts itself.
1632 @item Messages may be sent over ``debug message'' channels ... many
1633 targets support such messages sent over JTAG,
1634 for receipt by the person debugging or tools.
1635 @item Loss of power ... some adapters can detect these events.
1636 @item Resets not issued through JTAG ... such reset sources
1637 can include button presses or other system hardware, sometimes
1638 including the target itself (perhaps through a watchdog).
1639 @item Debug instrumentation sometimes supports event triggering
1640 such as ``trace buffer full'' (so it can quickly be emptied)
1641 or other signals (to correlate with code behavior).
1642 @end itemize
1643
1644 None of those events are signaled through standard JTAG signals.
1645 However, most conventions for JTAG connectors include voltage
1646 level and system reset (SRST) signal detection.
1647 Some connectors also include instrumentation signals, which
1648 can imply events when those signals are inputs.
1649
1650 In general, OpenOCD needs to periodically check for those events,
1651 either by looking at the status of signals on the JTAG connector
1652 or by sending synchronous ``tell me your status'' JTAG requests
1653 to the various active targets.
1654 There is a command to manage and monitor that polling,
1655 which is normally done in the background.
1656
1657 @deffn Command poll [@option{on}|@option{off}]
1658 Poll the current target for its current state.
1659 (Also, @pxref{target curstate}.)
1660 If that target is in debug mode, architecture
1661 specific information about the current state is printed.
1662 An optional parameter
1663 allows background polling to be enabled and disabled.
1664
1665 You could use this from the TCL command shell, or
1666 from GDB using @command{monitor poll} command.
1667 @example
1668 > poll
1669 background polling: on
1670 target state: halted
1671 target halted in ARM state due to debug-request, \
1672 current mode: Supervisor
1673 cpsr: 0x800000d3 pc: 0x11081bfc
1674 MMU: disabled, D-Cache: disabled, I-Cache: enabled
1675 >
1676 @end example
1677 @end deffn
1678
1679 @node Interface - Dongle Configuration
1680 @chapter Interface - Dongle Configuration
1681 @cindex config file, interface
1682 @cindex interface config file
1683
1684 JTAG Adapters/Interfaces/Dongles are normally configured
1685 through commands in an interface configuration
1686 file which is sourced by your @file{openocd.cfg} file, or
1687 through a command line @option{-f interface/....cfg} option.
1688
1689 @example
1690 source [find interface/olimex-jtag-tiny.cfg]
1691 @end example
1692
1693 These commands tell
1694 OpenOCD what type of JTAG adapter you have, and how to talk to it.
1695 A few cases are so simple that you only need to say what driver to use:
1696
1697 @example
1698 # jlink interface
1699 interface jlink
1700 @end example
1701
1702 Most adapters need a bit more configuration than that.
1703
1704
1705 @section Interface Configuration
1706
1707 The interface command tells OpenOCD what type of JTAG dongle you are
1708 using. Depending on the type of dongle, you may need to have one or
1709 more additional commands.
1710
1711 @deffn {Config Command} {interface} name
1712 Use the interface driver @var{name} to connect to the
1713 target.
1714 @end deffn
1715
1716 @deffn Command {interface_list}
1717 List the interface drivers that have been built into
1718 the running copy of OpenOCD.
1719 @end deffn
1720
1721 @deffn Command {jtag interface}
1722 Returns the name of the interface driver being used.
1723 @end deffn
1724
1725 @section Interface Drivers
1726
1727 Each of the interface drivers listed here must be explicitly
1728 enabled when OpenOCD is configured, in order to be made
1729 available at run time.
1730
1731 @deffn {Interface Driver} {amt_jtagaccel}
1732 Amontec Chameleon in its JTAG Accelerator configuration,
1733 connected to a PC's EPP mode parallel port.
1734 This defines some driver-specific commands:
1735
1736 @deffn {Config Command} {parport_port} number
1737 Specifies either the address of the I/O port (default: 0x378 for LPT1) or
1738 the number of the @file{/dev/parport} device.
1739 @end deffn
1740
1741 @deffn {Config Command} rtck [@option{enable}|@option{disable}]
1742 Displays status of RTCK option.
1743 Optionally sets that option first.
1744 @end deffn
1745 @end deffn
1746
1747 @deffn {Interface Driver} {arm-jtag-ew}
1748 Olimex ARM-JTAG-EW USB adapter
1749 This has one driver-specific command:
1750
1751 @deffn Command {armjtagew_info}
1752 Logs some status
1753 @end deffn
1754 @end deffn
1755
1756 @deffn {Interface Driver} {at91rm9200}
1757 Supports bitbanged JTAG from the local system,
1758 presuming that system is an Atmel AT91rm9200
1759 and a specific set of GPIOs is used.
1760 @c command: at91rm9200_device NAME
1761 @c chooses among list of bit configs ... only one option
1762 @end deffn
1763
1764 @deffn {Interface Driver} {dummy}
1765 A dummy software-only driver for debugging.
1766 @end deffn
1767
1768 @deffn {Interface Driver} {ep93xx}
1769 Cirrus Logic EP93xx based single-board computer bit-banging (in development)
1770 @end deffn
1771
1772 @deffn {Interface Driver} {ft2232}
1773 FTDI FT2232 (USB) based devices over one of the userspace libraries.
1774 These interfaces have several commands, used to configure the driver
1775 before initializing the JTAG scan chain:
1776
1777 @deffn {Config Command} {ft2232_device_desc} description
1778 Provides the USB device description (the @emph{iProduct string})
1779 of the FTDI FT2232 device. If not
1780 specified, the FTDI default value is used. This setting is only valid
1781 if compiled with FTD2XX support.
1782 @end deffn
1783
1784 @deffn {Config Command} {ft2232_serial} serial-number
1785 Specifies the @var{serial-number} of the FTDI FT2232 device to use,
1786 in case the vendor provides unique IDs and more than one FT2232 device
1787 is connected to the host.
1788 If not specified, serial numbers are not considered.
1789 (Note that USB serial numbers can be arbitrary Unicode strings,
1790 and are not restricted to containing only decimal digits.)
1791 @end deffn
1792
1793 @deffn {Config Command} {ft2232_layout} name
1794 Each vendor's FT2232 device can use different GPIO signals
1795 to control output-enables, reset signals, and LEDs.
1796 Currently valid layout @var{name} values include:
1797 @itemize @minus
1798 @item @b{axm0432_jtag} Axiom AXM-0432
1799 @item @b{comstick} Hitex STR9 comstick
1800 @item @b{cortino} Hitex Cortino JTAG interface
1801 @item @b{evb_lm3s811} Luminary Micro EVB_LM3S811 as a JTAG interface,
1802 either for the local Cortex-M3 (SRST only)
1803 or in a passthrough mode (neither SRST nor TRST)
1804 @item @b{luminary_icdi} Luminary In-Circuit Debug Interface (ICDI) Board
1805 @item @b{flyswatter} Tin Can Tools Flyswatter
1806 @item @b{icebear} ICEbear JTAG adapter from Section 5
1807 @item @b{jtagkey} Amontec JTAGkey and JTAGkey-Tiny (and compatibles)
1808 @item @b{jtagkey2} Amontec JTAGkey2 (and compatibles)
1809 @item @b{m5960} American Microsystems M5960
1810 @item @b{olimex-jtag} Olimex ARM-USB-OCD and ARM-USB-Tiny
1811 @item @b{oocdlink} OOCDLink
1812 @c oocdlink ~= jtagkey_prototype_v1
1813 @item @b{sheevaplug} Marvell Sheevaplug development kit
1814 @item @b{signalyzer} Xverve Signalyzer
1815 @item @b{stm32stick} Hitex STM32 Performance Stick
1816 @item @b{turtelizer2} egnite Software turtelizer2
1817 @item @b{usbjtag} "USBJTAG-1" layout described in the OpenOCD diploma thesis
1818 @end itemize
1819 @end deffn
1820
1821 @deffn {Config Command} {ft2232_vid_pid} [vid pid]+
1822 The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI
1823 default values are used.
1824 Currently, up to eight [@var{vid}, @var{pid}] pairs may be given, e.g.
1825 @example
1826 ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003
1827 @end example
1828 @end deffn
1829
1830 @deffn {Config Command} {ft2232_latency} ms
1831 On some systems using FT2232 based JTAG interfaces the FT_Read function call in
1832 ft2232_read() fails to return the expected number of bytes. This can be caused by
1833 USB communication delays and has proved hard to reproduce and debug. Setting the
1834 FT2232 latency timer to a larger value increases delays for short USB packets but it
1835 also reduces the risk of timeouts before receiving the expected number of bytes.
1836 The OpenOCD default value is 2 and for some systems a value of 10 has proved useful.
1837 @end deffn
1838
1839 For example, the interface config file for a
1840 Turtelizer JTAG Adapter looks something like this:
1841
1842 @example
1843 interface ft2232
1844 ft2232_device_desc "Turtelizer JTAG/RS232 Adapter"
1845 ft2232_layout turtelizer2
1846 ft2232_vid_pid 0x0403 0xbdc8
1847 @end example
1848 @end deffn
1849
1850 @deffn {Interface Driver} {gw16012}
1851 Gateworks GW16012 JTAG programmer.
1852 This has one driver-specific command:
1853
1854 @deffn {Config Command} {parport_port} number
1855 Specifies either the address of the I/O port (default: 0x378 for LPT1) or
1856 the number of the @file{/dev/parport} device.
1857 @end deffn
1858 @end deffn
1859
1860 @deffn {Interface Driver} {jlink}
1861 Segger jlink USB adapter
1862 @c command: jlink_info
1863 @c dumps status
1864 @c command: jlink_hw_jtag (2|3)
1865 @c sets version 2 or 3
1866 @end deffn
1867
1868 @deffn {Interface Driver} {parport}
1869 Supports PC parallel port bit-banging cables:
1870 Wigglers, PLD download cable, and more.
1871 These interfaces have several commands, used to configure the driver
1872 before initializing the JTAG scan chain:
1873
1874 @deffn {Config Command} {parport_cable} name
1875 The layout of the parallel port cable used to connect to the target.
1876 Currently valid cable @var{name} values include:
1877
1878 @itemize @minus
1879 @item @b{altium} Altium Universal JTAG cable.
1880 @item @b{arm-jtag} Same as original wiggler except SRST and
1881 TRST connections reversed and TRST is also inverted.
1882 @item @b{chameleon} The Amontec Chameleon's CPLD when operated
1883 in configuration mode. This is only used to
1884 program the Chameleon itself, not a connected target.
1885 @item @b{dlc5} The Xilinx Parallel cable III.
1886 @item @b{flashlink} The ST Parallel cable.
1887 @item @b{lattice} Lattice ispDOWNLOAD Cable
1888 @item @b{old_amt_wiggler} The Wiggler configuration that comes with
1889 some versions of
1890 Amontec's Chameleon Programmer. The new version available from
1891 the website uses the original Wiggler layout ('@var{wiggler}')
1892 @item @b{triton} The parallel port adapter found on the
1893 ``Karo Triton 1 Development Board''.
1894 This is also the layout used by the HollyGates design
1895 (see @uref{http://www.lartmaker.nl/projects/jtag/}).
1896 @item @b{wiggler} The original Wiggler layout, also supported by
1897 several clones, such as the Olimex ARM-JTAG
1898 @item @b{wiggler2} Same as original wiggler except an led is fitted on D5.
1899 @item @b{wiggler_ntrst_inverted} Same as original wiggler except TRST is inverted.
1900 @end itemize
1901 @end deffn
1902
1903 @deffn {Config Command} {parport_port} number
1904 Either the address of the I/O port (default: 0x378 for LPT1) or the number of
1905 the @file{/dev/parport} device
1906
1907 When using PPDEV to access the parallel port, use the number of the parallel port:
1908 @option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
1909 you may encounter a problem.
1910 @end deffn
1911
1912 @deffn {Config Command} {parport_write_on_exit} (on|off)
1913 This will configure the parallel driver to write a known
1914 cable-specific value to the parallel interface on exiting OpenOCD
1915 @end deffn
1916
1917 For example, the interface configuration file for a
1918 classic ``Wiggler'' cable might look something like this:
1919
1920 @example
1921 interface parport
1922 parport_port 0xc8b8
1923 parport_cable wiggler
1924 @end example
1925 @end deffn
1926
1927 @deffn {Interface Driver} {presto}
1928 ASIX PRESTO USB JTAG programmer.
1929 @c command: presto_serial str
1930 @c sets serial number
1931 @end deffn
1932
1933 @deffn {Interface Driver} {rlink}
1934 Raisonance RLink USB adapter
1935 @end deffn
1936
1937 @deffn {Interface Driver} {usbprog}
1938 usbprog is a freely programmable USB adapter.
1939 @end deffn
1940
1941 @deffn {Interface Driver} {vsllink}
1942 vsllink is part of Versaloon which is a versatile USB programmer.
1943
1944 @quotation Note
1945 This defines quite a few driver-specific commands,
1946 which are not currently documented here.
1947 @end quotation
1948 @end deffn
1949
1950 @deffn {Interface Driver} {ZY1000}
1951 This is the Zylin ZY1000 JTAG debugger.
1952
1953 @quotation Note
1954 This defines some driver-specific commands,
1955 which are not currently documented here.
1956 @end quotation
1957
1958 @deffn Command power [@option{on}|@option{off}]
1959 Turn power switch to target on/off.
1960 No arguments: print status.
1961 @end deffn
1962
1963 @end deffn
1964
1965 @anchor{JTAG Speed}
1966 @section JTAG Speed
1967 JTAG clock setup is part of system setup.
1968 It @emph{does not belong with interface setup} since any interface
1969 only knows a few of the constraints for the JTAG clock speed.
1970 Sometimes the JTAG speed is
1971 changed during the target initialization process: (1) slow at
1972 reset, (2) program the CPU clocks, (3) run fast.
1973 Both the "slow" and "fast" clock rates are functions of the
1974 oscillators used, the chip, the board design, and sometimes
1975 power management software that may be active.
1976
1977 The speed used during reset, and the scan chain verification which
1978 follows reset, can be adjusted using a @code{reset-start}
1979 target event handler.
1980 It can then be reconfigured to a faster speed by a
1981 @code{reset-init} target event handler after it reprograms those
1982 CPU clocks, or manually (if something else, such as a boot loader,
1983 sets up those clocks).
1984 @xref{Target Events}.
1985 When the initial low JTAG speed is a chip characteristic, perhaps
1986 because of a required oscillator speed, provide such a handler
1987 in the target config file.
1988 When that speed is a function of a board-specific characteristic
1989 such as which speed oscillator is used, it belongs in the board
1990 config file instead.
1991 In both cases it's safest to also set the initial JTAG clock rate
1992 to that same slow speed, so that OpenOCD never starts up using a
1993 clock speed that's faster than the scan chain can support.
1994
1995 @example
1996 jtag_rclk 3000
1997 $_TARGET.cpu configure -event reset-start @{ jtag_rclk 3000 @}
1998 @end example
1999
2000 If your system supports adaptive clocking (RTCK), configuring
2001 JTAG to use that is probably the most robust approach.
2002 However, it introduces delays to synchronize clocks; so it
2003 may not be the fastest solution.
2004
2005 @b{NOTE:} Script writers should consider using @command{jtag_rclk}
2006 instead of @command{jtag_khz}.
2007
2008 @deffn {Command} jtag_khz max_speed_kHz
2009 A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
2010 JTAG interfaces usually support a limited number of
2011 speeds. The speed actually used won't be faster
2012 than the speed specified.
2013
2014 Chip data sheets generally include a top JTAG clock rate.
2015 The actual rate is often a function of a CPU core clock,
2016 and is normally less than that peak rate.
2017 For example, most ARM cores accept at most one sixth of the CPU clock.
2018
2019 Speed 0 (khz) selects RTCK method.
2020 @xref{FAQ RTCK}.
2021 If your system uses RTCK, you won't need to change the
2022 JTAG clocking after setup.
2023 Not all interfaces, boards, or targets support ``rtck''.
2024 If the interface device can not
2025 support it, an error is returned when you try to use RTCK.
2026 @end deffn
2027
2028 @defun jtag_rclk fallback_speed_kHz
2029 @cindex adaptive clocking
2030 @cindex RTCK
2031 This Tcl proc (defined in @file{startup.tcl}) attempts to enable RTCK/RCLK.
2032 If that fails (maybe the interface, board, or target doesn't
2033 support it), falls back to the specified frequency.
2034 @example
2035 # Fall back to 3mhz if RTCK is not supported
2036 jtag_rclk 3000
2037 @end example
2038 @end defun
2039
2040 @node Reset Configuration
2041 @chapter Reset Configuration
2042 @cindex Reset Configuration
2043
2044 Every system configuration may require a different reset
2045 configuration. This can also be quite confusing.
2046 Resets also interact with @var{reset-init} event handlers,
2047 which do things like setting up clocks and DRAM, and
2048 JTAG clock rates. (@xref{JTAG Speed}.)
2049 They can also interact with JTAG routers.
2050 Please see the various board files for examples.
2051
2052 @quotation Note
2053 To maintainers and integrators:
2054 Reset configuration touches several things at once.
2055 Normally the board configuration file
2056 should define it and assume that the JTAG adapter supports
2057 everything that's wired up to the board's JTAG connector.
2058
2059 However, the target configuration file could also make note
2060 of something the silicon vendor has done inside the chip,
2061 which will be true for most (or all) boards using that chip.
2062 And when the JTAG adapter doesn't support everything, the
2063 user configuration file will need to override parts of
2064 the reset configuration provided by other files.
2065 @end quotation
2066
2067 @section Types of Reset
2068
2069 There are many kinds of reset possible through JTAG, but
2070 they may not all work with a given board and adapter.
2071 That's part of why reset configuration can be error prone.
2072
2073 @itemize @bullet
2074 @item
2075 @emph{System Reset} ... the @emph{SRST} hardware signal
2076 resets all chips connected to the JTAG adapter, such as processors,
2077 power management chips, and I/O controllers. Normally resets triggered
2078 with this signal behave exactly like pressing a RESET button.
2079 @item
2080 @emph{JTAG TAP Reset} ... the @emph{TRST} hardware signal resets
2081 just the TAP controllers connected to the JTAG adapter.
2082 Such resets should not be visible to the rest of the system; resetting a
2083 device's the TAP controller just puts that controller into a known state.
2084 @item
2085 @emph{Emulation Reset} ... many devices can be reset through JTAG
2086 commands. These resets are often distinguishable from system
2087 resets, either explicitly (a "reset reason" register says so)
2088 or implicitly (not all parts of the chip get reset).
2089 @item
2090 @emph{Other Resets} ... system-on-chip devices often support
2091 several other types of reset.
2092 You may need to arrange that a watchdog timer stops
2093 while debugging, preventing a watchdog reset.
2094 There may be individual module resets.
2095 @end itemize
2096
2097 In the best case, OpenOCD can hold SRST, then reset
2098 the TAPs via TRST and send commands through JTAG to halt the
2099 CPU at the reset vector before the 1st instruction is executed.
2100 Then when it finally releases the SRST signal, the system is
2101 halted under debugger control before any code has executed.
2102 This is the behavior required to support the @command{reset halt}
2103 and @command{reset init} commands; after @command{reset init} a
2104 board-specific script might do things like setting up DRAM.
2105 (@xref{Reset Command}.)
2106
2107 @anchor{SRST and TRST Issues}
2108 @section SRST and TRST Issues
2109
2110 Because SRST and TRST are hardware signals, they can have a
2111 variety of system-specific constraints. Some of the most
2112 common issues are:
2113
2114 @itemize @bullet
2115
2116 @item @emph{Signal not available} ... Some boards don't wire
2117 SRST or TRST to the JTAG connector. Some JTAG adapters don't
2118 support such signals even if they are wired up.
2119 Use the @command{reset_config} @var{signals} options to say
2120 when either of those signals is not connected.
2121 When SRST is not available, your code might not be able to rely
2122 on controllers having been fully reset during code startup.
2123 Missing TRST is not a problem, since JTAG level resets can
2124 be triggered using with TMS signaling.
2125
2126 @item @emph{Signals shorted} ... Sometimes a chip, board, or
2127 adapter will connect SRST to TRST, instead of keeping them separate.
2128 Use the @command{reset_config} @var{combination} options to say
2129 when those signals aren't properly independent.
2130
2131 @item @emph{Timing} ... Reset circuitry like a resistor/capacitor
2132 delay circuit, reset supervisor, or on-chip features can extend
2133 the effect of a JTAG adapter's reset for some time after the adapter
2134 stops issuing the reset. For example, there may be chip or board
2135 requirements that all reset pulses last for at least a
2136 certain amount of time; and reset buttons commonly have
2137 hardware debouncing.
2138 Use the @command{jtag_nsrst_delay} and @command{jtag_ntrst_delay}
2139 commands to say when extra delays are needed.
2140
2141 @item @emph{Drive type} ... Reset lines often have a pullup
2142 resistor, letting the JTAG interface treat them as open-drain
2143 signals. But that's not a requirement, so the adapter may need
2144 to use push/pull output drivers.
2145 Also, with weak pullups it may be advisable to drive
2146 signals to both levels (push/pull) to minimize rise times.
2147 Use the @command{reset_config} @var{trst_type} and
2148 @var{srst_type} parameters to say how to drive reset signals.
2149
2150 @item @emph{Special initialization} ... Targets sometimes need
2151 special JTAG initialization sequences to handle chip-specific
2152 issues (not limited to errata).
2153 For example, certain JTAG commands might need to be issued while
2154 the system as a whole is in a reset state (SRST active)
2155 but the JTAG scan chain is usable (TRST inactive).
2156 (@xref{JTAG Commands}, where the @command{jtag_reset}
2157 command is presented.)
2158 @end itemize
2159
2160 There can also be other issues.
2161 Some devices don't fully conform to the JTAG specifications.
2162 Trivial system-specific differences are common, such as
2163 SRST and TRST using slightly different names.
2164 There are also vendors who distribute key JTAG documentation for
2165 their chips only to developers who have signed a Non-Disclosure
2166 Agreement (NDA).
2167
2168 Sometimes there are chip-specific extensions like a requirement to use
2169 the normally-optional TRST signal (precluding use of JTAG adapters which
2170 don't pass TRST through), or needing extra steps to complete a TAP reset.
2171
2172 In short, SRST and especially TRST handling may be very finicky,
2173 needing to cope with both architecture and board specific constraints.
2174
2175 @section Commands for Handling Resets
2176
2177 @deffn {Command} jtag_nsrst_delay milliseconds
2178 How long (in milliseconds) OpenOCD should wait after deasserting
2179 nSRST (active-low system reset) before starting new JTAG operations.
2180 When a board has a reset button connected to SRST line it will
2181 probably have hardware debouncing, implying you should use this.
2182 @end deffn
2183
2184 @deffn {Command} jtag_ntrst_delay milliseconds
2185 How long (in milliseconds) OpenOCD should wait after deasserting
2186 nTRST (active-low JTAG TAP reset) before starting new JTAG operations.
2187 @end deffn
2188
2189 @deffn {Command} reset_config mode_flag ...
2190 This command displays or modifies the reset configuration
2191 of your combination of JTAG board and target in target
2192 configuration scripts.
2193
2194 Information earlier in this section describes the kind of problems
2195 the command is intended to address (@pxref{SRST and TRST Issues}).
2196 As a rule this command belongs only in board config files,
2197 describing issues like @emph{board doesn't connect TRST};
2198 or in user config files, addressing limitations derived
2199 from a particular combination of interface and board.
2200 (An unlikely example would be using a TRST-only adapter
2201 with a board that only wires up SRST.)
2202
2203 The @var{mode_flag} options can be specified in any order, but only one
2204 of each type -- @var{signals}, @var{combination},
2205 @var{gates},
2206 @var{trst_type},
2207 and @var{srst_type} -- may be specified at a time.
2208 If you don't provide a new value for a given type, its previous
2209 value (perhaps the default) is unchanged.
2210 For example, this means that you don't need to say anything at all about
2211 TRST just to declare that if the JTAG adapter should want to drive SRST,
2212 it must explicitly be driven high (@option{srst_push_pull}).
2213
2214 @itemize
2215 @item
2216 @var{signals} can specify which of the reset signals are connected.
2217 For example, If the JTAG interface provides SRST, but the board doesn't
2218 connect that signal properly, then OpenOCD can't use it.
2219 Possible values are @option{none} (the default), @option{trst_only},
2220 @option{srst_only} and @option{trst_and_srst}.
2221
2222 @quotation Tip
2223 If your board provides SRST and/or TRST through the JTAG connector,
2224 you must declare that or else those signals will not be used.
2225 @end quotation
2226
2227 @item
2228 The @var{combination} is an optional value specifying broken reset
2229 signal implementations.
2230 The default behaviour if no option given is @option{separate},
2231 indicating everything behaves normally.
2232 @option{srst_pulls_trst} states that the
2233 test logic is reset together with the reset of the system (e.g. Philips
2234 LPC2000, "broken" board layout), @option{trst_pulls_srst} says that
2235 the system is reset together with the test logic (only hypothetical, I
2236 haven't seen hardware with such a bug, and can be worked around).
2237 @option{combined} implies both @option{srst_pulls_trst} and
2238 @option{trst_pulls_srst}.
2239
2240 @item
2241 The @var{gates} tokens control flags that describe some cases where
2242 JTAG may be unvailable during reset.
2243 @option{srst_gates_jtag} (default)
2244 indicates that asserting SRST gates the
2245 JTAG clock. This means that no communication can happen on JTAG
2246 while SRST is asserted.
2247 Its converse is @option{srst_nogate}, indicating that JTAG commands
2248 can safely be issued while SRST is active.
2249 @end itemize
2250
2251 The optional @var{trst_type} and @var{srst_type} parameters allow the
2252 driver mode of each reset line to be specified. These values only affect
2253 JTAG interfaces with support for different driver modes, like the Amontec
2254 JTAGkey and JTAG Accelerator. Also, they are necessarily ignored if the
2255 relevant signal (TRST or SRST) is not connected.
2256
2257 @itemize
2258 @item
2259 Possible @var{trst_type} driver modes for the test reset signal (TRST)
2260 are the default @option{trst_push_pull}, and @option{trst_open_drain}.
2261 Most boards connect this signal to a pulldown, so the JTAG TAPs
2262 never leave reset unless they are hooked up to a JTAG adapter.
2263
2264 @item
2265 Possible @var{srst_type} driver modes for the system reset signal (SRST)
2266 are the default @option{srst_open_drain}, and @option{srst_push_pull}.
2267 Most boards connect this signal to a pullup, and allow the
2268 signal to be pulled low by various events including system
2269 powerup and pressing a reset button.
2270 @end itemize
2271 @end deffn
2272
2273
2274 @node TAP Declaration
2275 @chapter TAP Declaration
2276 @cindex TAP declaration
2277 @cindex TAP configuration
2278
2279 @emph{Test Access Ports} (TAPs) are the core of JTAG.
2280 TAPs serve many roles, including:
2281
2282 @itemize @bullet
2283 @item @b{Debug Target} A CPU TAP can be used as a GDB debug target
2284 @item @b{Flash Programing} Some chips program the flash directly via JTAG.
2285 Others do it indirectly, making a CPU do it.
2286 @item @b{Program Download} Using the same CPU support GDB uses,
2287 you can initialize a DRAM controller, download code to DRAM, and then
2288 start running that code.
2289 @item @b{Boundary Scan} Most chips support boundary scan, which
2290 helps test for board assembly problems like solder bridges
2291 and missing connections
2292 @end itemize
2293
2294 OpenOCD must know about the active TAPs on your board(s).
2295 Setting up the TAPs is the core task of your configuration files.
2296 Once those TAPs are set up, you can pass their names to code
2297 which sets up CPUs and exports them as GDB targets,
2298 probes flash memory, performs low-level JTAG operations, and more.
2299
2300 @section Scan Chains
2301 @cindex scan chain
2302
2303 TAPs are part of a hardware @dfn{scan chain},
2304 which is daisy chain of TAPs.
2305 They also need to be added to
2306 OpenOCD's software mirror of that hardware list,
2307 giving each member a name and associating other data with it.
2308 Simple scan chains, with a single TAP, are common in
2309 systems with a single microcontroller or microprocessor.
2310 More complex chips may have several TAPs internally.
2311 Very complex scan chains might have a dozen or more TAPs:
2312 several in one chip, more in the next, and connecting
2313 to other boards with their own chips and TAPs.
2314
2315 You can display the list with the @command{scan_chain} command.
2316 (Don't confuse this with the list displayed by the @command{targets}
2317 command, presented in the next chapter.
2318 That only displays TAPs for CPUs which are configured as
2319 debugging targets.)
2320 Here's what the scan chain might look like for a chip more than one TAP:
2321
2322 @verbatim
2323 TapName Enabled IdCode Expected IrLen IrCap IrMask Instr
2324 -- ------------------ ------- ---------- ---------- ----- ----- ------ -----
2325 0 omap5912.dsp Y 0x03df1d81 0x03df1d81 38 0 0 0x...
2326 1 omap5912.arm Y 0x0692602f 0x0692602f 4 0x1 0 0xc
2327 2 omap5912.unknown Y 0x00000000 0x00000000 8 0 0 0xff
2328 @end verbatim
2329
2330 Unfortunately those TAPs can't always be autoconfigured,
2331 because not all devices provide good support for that.
2332 JTAG doesn't require supporting IDCODE instructions, and
2333 chips with JTAG routers may not link TAPs into the chain
2334 until they are told to do so.
2335
2336 The configuration mechanism currently supported by OpenOCD
2337 requires explicit configuration of all TAP devices using
2338 @command{jtag newtap} commands, as detailed later in this chapter.
2339 A command like this would declare one tap and name it @code{chip1.cpu}:
2340
2341 @example
2342 jtag newtap chip1 cpu -irlen 7 -ircapture 0x01 -irmask 0x55
2343 @end example
2344
2345 Each target configuration file lists the TAPs provided
2346 by a given chip.
2347 Board configuration files combine all the targets on a board,
2348 and so forth.
2349 Note that @emph{the order in which TAPs are declared is very important.}
2350 It must match the order in the JTAG scan chain, both inside
2351 a single chip and between them.
2352 @xref{FAQ TAP Order}.
2353
2354 For example, the ST Microsystems STR912 chip has
2355 three separate TAPs@footnote{See the ST
2356 document titled: @emph{STR91xFAxxx, Section 3.15 Jtag Interface, Page:
2357 28/102, Figure 3: JTAG chaining inside the STR91xFA}.
2358 @url{http://eu.st.com/stonline/products/literature/ds/13495.pdf}}.
2359 To configure those taps, @file{target/str912.cfg}
2360 includes commands something like this:
2361
2362 @example
2363 jtag newtap str912 flash ... params ...
2364 jtag newtap str912 cpu ... params ...
2365 jtag newtap str912 bs ... params ...
2366 @end example
2367
2368 Actual config files use a variable instead of literals like
2369 @option{str912}, to support more than one chip of each type.
2370 @xref{Config File Guidelines}.
2371
2372 @deffn Command {jtag names}
2373 Returns the names of all current TAPs in the scan chain.
2374 Use @command{jtag cget} or @command{jtag tapisenabled}
2375 to examine attributes and state of each TAP.
2376 @example
2377 foreach t [jtag names] @{
2378 puts [format "TAP: %s\n" $t]
2379 @}
2380 @end example
2381 @end deffn
2382
2383 @deffn Command {scan_chain}
2384 Displays the TAPs in the scan chain configuration,
2385 and their status.
2386 The set of TAPs listed by this command is fixed by
2387 exiting the OpenOCD configuration stage,
2388 but systems with a JTAG router can
2389 enable or disable TAPs dynamically.
2390 In addition to the enable/disable status, the contents of
2391 each TAP's instruction register can also change.
2392 @end deffn
2393
2394 @c FIXME! "jtag cget" should be able to return all TAP
2395 @c attributes, like "$target_name cget" does for targets.
2396
2397 @c Probably want "jtag eventlist", and a "tap-reset" event
2398 @c (on entry to RESET state).
2399
2400 @section TAP Names
2401 @cindex dotted name
2402
2403 When TAP objects are declared with @command{jtag newtap},
2404 a @dfn{dotted.name} is created for the TAP, combining the
2405 name of a module (usually a chip) and a label for the TAP.
2406 For example: @code{xilinx.tap}, @code{str912.flash},
2407 @code{omap3530.jrc}, @code{dm6446.dsp}, or @code{stm32.cpu}.
2408 Many other commands use that dotted.name to manipulate or
2409 refer to the TAP. For example, CPU configuration uses the
2410 name, as does declaration of NAND or NOR flash banks.
2411
2412 The components of a dotted name should follow ``C'' symbol
2413 name rules: start with an alphabetic character, then numbers
2414 and underscores are OK; while others (including dots!) are not.
2415
2416 @quotation Tip
2417 In older code, JTAG TAPs were numbered from 0..N.
2418 This feature is still present.
2419 However its use is highly discouraged, and
2420 should not be relied on; it will be removed by mid-2010.
2421 Update all of your scripts to use TAP names rather than numbers,
2422 by paying attention to the runtime warnings they trigger.
2423 Using TAP numbers in target configuration scripts prevents
2424 reusing those scripts on boards with multiple targets.
2425 @end quotation
2426
2427 @section TAP Declaration Commands
2428
2429 @c shouldn't this be(come) a {Config Command}?
2430 @anchor{jtag newtap}
2431 @deffn Command {jtag newtap} chipname tapname configparams...
2432 Declares a new TAP with the dotted name @var{chipname}.@var{tapname},
2433 and configured according to the various @var{configparams}.
2434
2435 The @var{chipname} is a symbolic name for the chip.
2436 Conventionally target config files use @code{$_CHIPNAME},
2437 defaulting to the model name given by the chip vendor but
2438 overridable.
2439
2440 @cindex TAP naming convention
2441 The @var{tapname} reflects the role of that TAP,
2442 and should follow this convention:
2443
2444 @itemize @bullet
2445 @item @code{bs} -- For boundary scan if this is a seperate TAP;
2446 @item @code{cpu} -- The main CPU of the chip, alternatively
2447 @code{arm} and @code{dsp} on chips with both ARM and DSP CPUs,
2448 @code{arm1} and @code{arm2} on chips two ARMs, and so forth;
2449 @item @code{etb} -- For an embedded trace buffer (example: an ARM ETB11);
2450 @item @code{flash} -- If the chip has a flash TAP, like the str912;
2451 @item @code{jrc} -- For JTAG route controller (example: the ICEpick modules
2452 on many Texas Instruments chips, like the OMAP3530 on Beagleboards);
2453 @item @code{tap} -- Should be used only FPGA or CPLD like devices
2454 with a single TAP;
2455 @item @code{unknownN} -- If you have no idea what the TAP is for (N is a number);
2456 @item @emph{when in doubt} -- Use the chip maker's name in their data sheet.
2457 For example, the Freescale IMX31 has a SDMA (Smart DMA) with
2458 a JTAG TAP; that TAP should be named @code{sdma}.
2459 @end itemize
2460
2461 Every TAP requires at least the following @var{configparams}:
2462
2463 @itemize @bullet
2464 @item @code{-irlen} @var{NUMBER}
2465 @*The length in bits of the
2466 instruction register, such as 4 or 5 bits.
2467 @end itemize
2468
2469 A TAP may also provide optional @var{configparams}:
2470
2471 @itemize @bullet
2472 @item @code{-disable} (or @code{-enable})
2473 @*Use the @code{-disable} parameter to flag a TAP which is not
2474 linked in to the scan chain after a reset using either TRST
2475 or the JTAG state machine's @sc{reset} state.
2476 You may use @code{-enable} to highlight the default state
2477 (the TAP is linked in).
2478 @xref{Enabling and Disabling TAPs}.
2479 @item @code{-expected-id} @var{number}
2480 @*A non-zero @var{number} represents a 32-bit IDCODE
2481 which you expect to find when the scan chain is examined.
2482 These codes are not required by all JTAG devices.
2483 @emph{Repeat the option} as many times as required if more than one
2484 ID code could appear (for example, multiple versions).
2485 Specify @var{number} as zero to suppress warnings about IDCODE
2486 values that were found but not included in the list.
2487 @item @code{-ircapture} @var{NUMBER}
2488 @*The bit pattern loaded by the TAP into the JTAG shift register
2489 on entry to the @sc{ircapture} state, such as 0x01.
2490 JTAG requires the two LSBs of this value to be 01.
2491 By default, @code{-ircapture} and @code{-irmask} are set
2492 up to verify that two-bit value; but you may provide
2493 additional bits, if you know them.
2494 @item @code{-irmask} @var{NUMBER}
2495 @*A mask used with @code{-ircapture}
2496 to verify that instruction scans work correctly.
2497 Such scans are not used by OpenOCD except to verify that
2498 there seems to be no problems with JTAG scan chain operations.
2499 @end itemize
2500 @end deffn
2501
2502 @section Other TAP commands
2503
2504 @c @deffn Command {jtag arp_init-reset}
2505 @c ... more or less "toggle TRST ... and SRST too, what the heck"
2506
2507 @deffn Command {jtag cget} dotted.name @option{-event} name
2508 @deffnx Command {jtag configure} dotted.name @option{-event} name string
2509 At this writing this TAP attribute
2510 mechanism is used only for event handling.
2511 (It is not a direct analogue of the @code{cget}/@code{configure}
2512 mechanism for debugger targets.)
2513 See the next section for information about the available events.
2514
2515 The @code{configure} subcommand assigns an event handler,
2516 a TCL string which is evaluated when the event is triggered.
2517 The @code{cget} subcommand returns that handler.
2518 @end deffn
2519
2520 @anchor{TAP Events}
2521 @section TAP Events
2522 @cindex events
2523 @cindex TAP events
2524
2525 OpenOCD includes two event mechanisms.
2526 The one presented here applies to all JTAG TAPs.
2527 The other applies to debugger targets,
2528 which are associated with certain TAPs.
2529
2530 The TAP events currently defined are:
2531
2532 @itemize @bullet
2533 @item @b{post-reset}
2534 @* The TAP has just completed a JTAG reset.
2535 The tap may still be in the JTAG @sc{reset} state.
2536 Handlers for these events might perform initialization sequences
2537 such as issuing TCK cycles, TMS sequences to ensure
2538 exit from the ARM SWD mode, and more.
2539
2540 Because the scan chain has not yet been verified, handlers for these events
2541 @emph{should not issue commands which scan the JTAG IR or DR registers}
2542 of any particular target.
2543 @b{NOTE:} As this is written (September 2009), nothing prevents such access.
2544 @item @b{setup}
2545 @* The scan chain has been reset and verified.
2546 This handler may enable TAPs as needed.
2547 @item @b{tap-disable}
2548 @* The TAP needs to be disabled. This handler should
2549 implement @command{jtag tapdisable}
2550 by issuing the relevant JTAG commands.
2551 @item @b{tap-enable}
2552 @* The TAP needs to be enabled. This handler should
2553 implement @command{jtag tapenable}
2554 by issuing the relevant JTAG commands.
2555 @end itemize
2556
2557 If you need some action after each JTAG reset, which isn't actually
2558 specific to any TAP (since you can't yet trust the scan chain's
2559 contents to be accurate), you might:
2560
2561 @example
2562 jtag configure CHIP.jrc -event post-reset @{
2563 echo "JTAG Reset done"
2564 ... non-scan jtag operations to be done after reset
2565 @}
2566 @end example
2567
2568
2569 @anchor{Enabling and Disabling TAPs}
2570 @section Enabling and Disabling TAPs
2571 @cindex JTAG Route Controller
2572 @cindex jrc
2573
2574 In some systems, a @dfn{JTAG Route Controller} (JRC)
2575 is used to enable and/or disable specific JTAG TAPs.
2576 Many ARM based chips from Texas Instruments include
2577 an ``ICEpick'' module, which is a JRC.
2578 Such chips include DaVinci and OMAP3 processors.
2579
2580 A given TAP may not be visible until the JRC has been
2581 told to link it into the scan chain; and if the JRC
2582 has been told to unlink that TAP, it will no longer
2583 be visible.
2584 Such routers address problems that JTAG ``bypass mode''
2585 ignores, such as:
2586
2587 @itemize
2588 @item The scan chain can only go as fast as its slowest TAP.
2589 @item Having many TAPs slows instruction scans, since all
2590 TAPs receive new instructions.
2591 @item TAPs in the scan chain must be powered up, which wastes
2592 power and prevents debugging some power management mechanisms.
2593 @end itemize
2594
2595 The IEEE 1149.1 JTAG standard has no concept of a ``disabled'' tap,
2596 as implied by the existence of JTAG routers.
2597 However, the upcoming IEEE 1149.7 framework (layered on top of JTAG)
2598 does include a kind of JTAG router functionality.
2599
2600 @c (a) currently the event handlers don't seem to be able to
2601 @c fail in a way that could lead to no-change-of-state.
2602
2603 In OpenOCD, tap enabling/disabling is invoked by the Tcl commands
2604 shown below, and is implemented using TAP event handlers.
2605 So for example, when defining a TAP for a CPU connected to
2606 a JTAG router, your @file{target.cfg} file
2607 should define TAP event handlers using
2608 code that looks something like this:
2609
2610 @example
2611 jtag configure CHIP.cpu -event tap-enable @{
2612 ... jtag operations using CHIP.jrc
2613 @}
2614 jtag configure CHIP.cpu -event tap-disable @{
2615 ... jtag operations using CHIP.jrc
2616 @}
2617 @end example
2618
2619 Then you might want that CPU's TAP enabled almost all the time:
2620
2621 @example
2622 jtag configure $CHIP.jrc -event setup "jtag tapenable $CHIP.cpu"
2623 @end example
2624
2625 Note how that particular setup event handler declaration
2626 uses quotes to evaluate @code{$CHIP} when the event is configured.
2627 Using brackets @{ @} would cause it to be evaluated later,
2628 at runtime, when it might have a different value.
2629
2630 @deffn Command {jtag tapdisable} dotted.name
2631 If necessary, disables the tap
2632 by sending it a @option{tap-disable} event.
2633 Returns the string "1" if the tap
2634 specified by @var{dotted.name} is enabled,
2635 and "0" if it is disabled.
2636 @end deffn
2637
2638 @deffn Command {jtag tapenable} dotted.name
2639 If necessary, enables the tap
2640 by sending it a @option{tap-enable} event.
2641 Returns the string "1" if the tap
2642 specified by @var{dotted.name} is enabled,
2643 and "0" if it is disabled.
2644 @end deffn
2645
2646 @deffn Command {jtag tapisenabled} dotted.name
2647 Returns the string "1" if the tap
2648 specified by @var{dotted.name} is enabled,
2649 and "0" if it is disabled.
2650
2651 @quotation Note
2652 Humans will find the @command{scan_chain} command more helpful
2653 for querying the state of the JTAG taps.
2654 @end quotation
2655 @end deffn
2656
2657 @node CPU Configuration
2658 @chapter CPU Configuration
2659 @cindex GDB target
2660
2661 This chapter discusses how to set up GDB debug targets for CPUs.
2662 You can also access these targets without GDB
2663 (@pxref{Architecture and Core Commands},
2664 and @ref{Target State handling}) and
2665 through various kinds of NAND and NOR flash commands.
2666 If you have multiple CPUs you can have multiple such targets.
2667
2668 We'll start by looking at how to examine the targets you have,
2669 then look at how to add one more target and how to configure it.
2670
2671 @section Target List
2672 @cindex target, current
2673 @cindex target, list
2674
2675 All targets that have been set up are part of a list,
2676 where each member has a name.
2677 That name should normally be the same as the TAP name.
2678 You can display the list with the @command{targets}
2679 (plural!) command.
2680 This display often has only one CPU; here's what it might
2681 look like with more than one:
2682 @verbatim
2683 TargetName Type Endian TapName State
2684 -- ------------------ ---------- ------ ------------------ ------------
2685 0* at91rm9200.cpu arm920t little at91rm9200.cpu running
2686 1 MyTarget cortex_m3 little mychip.foo tap-disabled
2687 @end verbatim
2688
2689 One member of that list is the @dfn{current target}, which
2690 is implicitly referenced by many commands.
2691 It's the one marked with a @code{*} near the target name.
2692 In particular, memory addresses often refer to the address
2693 space seen by that current target.
2694 Commands like @command{mdw} (memory display words)
2695 and @command{flash erase_address} (erase NOR flash blocks)
2696 are examples; and there are many more.
2697
2698 Several commands let you examine the list of targets:
2699
2700 @deffn Command {target count}
2701 @emph{Note: target numbers are deprecated; don't use them.
2702 They will be removed shortly after August 2010, including this command.
2703 Iterate target using @command{target names}, not by counting.}
2704
2705 Returns the number of targets, @math{N}.
2706 The highest numbered target is @math{N - 1}.
2707 @example
2708 set c [target count]
2709 for @{ set x 0 @} @{ $x < $c @} @{ incr x @} @{
2710 # Assuming you have created this function
2711 print_target_details $x
2712 @}
2713 @end example
2714 @end deffn
2715
2716 @deffn Command {target current}
2717 Returns the name of the current target.
2718 @end deffn
2719
2720 @deffn Command {target names}
2721 Lists the names of all current targets in the list.
2722 @example
2723 foreach t [target names] @{
2724 puts [format "Target: %s\n" $t]
2725 @}
2726 @end example
2727 @end deffn
2728
2729 @deffn Command {target number} number
2730 @emph{Note: target numbers are deprecated; don't use them.
2731 They will be removed shortly after August 2010, including this command.}
2732
2733 The list of targets is numbered starting at zero.
2734 This command returns the name of the target at index @var{number}.
2735 @example
2736 set thename [target number $x]
2737 puts [format "Target %d is: %s\n" $x $thename]
2738 @end example
2739 @end deffn
2740
2741 @c yep, "target list" would have been better.
2742 @c plus maybe "target setdefault".
2743
2744 @deffn Command targets [name]
2745 @emph{Note: the name of this command is plural. Other target
2746 command names are singular.}
2747
2748 With no parameter, this command displays a table of all known
2749 targets in a user friendly form.
2750
2751 With a parameter, this command sets the current target to
2752 the given target with the given @var{name}; this is
2753 only relevant on boards which have more than one target.
2754 @end deffn
2755
2756 @section Target CPU Types and Variants
2757 @cindex target type
2758 @cindex CPU type
2759 @cindex CPU variant
2760
2761 Each target has a @dfn{CPU type}, as shown in the output of
2762 the @command{targets} command. You need to specify that type
2763 when calling @command{target create}.
2764 The CPU type indicates more than just the instruction set.
2765 It also indicates how that instruction set is implemented,
2766 what kind of debug support it integrates,
2767 whether it has an MMU (and if so, what kind),
2768 what core-specific commands may be available
2769 (@pxref{Architecture and Core Commands}),
2770 and more.
2771
2772 For some CPU types, OpenOCD also defines @dfn{variants} which
2773 indicate differences that affect their handling.
2774 For example, a particular implementation bug might need to be
2775 worked around in some chip versions.
2776
2777 It's easy to see what target types are supported,
2778 since there's a command to list them.
2779 However, there is currently no way to list what target variants
2780 are supported (other than by reading the OpenOCD source code).
2781
2782 @anchor{target types}
2783 @deffn Command {target types}
2784 Lists all supported target types.
2785 At this writing, the supported CPU types and variants are:
2786
2787 @itemize @bullet
2788 @item @code{arm11} -- this is a generation of ARMv6 cores
2789 @item @code{arm720t} -- this is an ARMv4 core
2790 @item @code{arm7tdmi} -- this is an ARMv4 core
2791 @item @code{arm920t} -- this is an ARMv5 core
2792 @item @code{arm926ejs} -- this is an ARMv5 core
2793 @item @code{arm966e} -- this is an ARMv5 core
2794 @item @code{arm9tdmi} -- this is an ARMv4 core
2795 @item @code{avr} -- implements Atmel's 8-bit AVR instruction set.
2796 (Support for this is preliminary and incomplete.)
2797 @item @code{cortex_a8} -- this is an ARMv7 core
2798 @item @code{cortex_m3} -- this is an ARMv7 core, supporting only the
2799 compact Thumb2 instruction set. It supports one variant:
2800 @itemize @minus
2801 @item @code{lm3s} ... Use this when debugging older Stellaris LM3S targets.
2802 This will cause OpenOCD to use a software reset rather than asserting
2803 SRST, to avoid a issue with clearing the debug registers.
2804 This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will
2805 be detected and the normal reset behaviour used.
2806 @end itemize
2807 @item @code{fa526} -- resembles arm920 (w/o Thumb)
2808 @item @code{feroceon} -- resembles arm926
2809 @item @code{mips_m4k} -- a MIPS core. This supports one variant:
2810 @itemize @minus
2811 @item @code{ejtag_srst} ... Use this when debugging targets that do not
2812 provide a functional SRST line on the EJTAG connector. This causes
2813 OpenOCD to instead use an EJTAG software reset command to reset the
2814 processor.
2815 You still need to enable @option{srst} on the @command{reset_config}
2816 command to enable OpenOCD hardware reset functionality.
2817 @end itemize
2818 @item @code{xscale} -- this is actually an architecture,
2819 not a CPU type. It is based on the ARMv5 architecture.
2820 There are several variants defined:
2821 @itemize @minus
2822 @item @code{ixp42x}, @code{ixp45x}, @code{ixp46x},
2823 @code{pxa27x} ... instruction register length is 7 bits
2824 @item @code{pxa250}, @code{pxa255},
2825 @code{pxa26x} ... instruction register length is 5 bits
2826 @end itemize
2827 @end itemize
2828 @end deffn
2829
2830 To avoid being confused by the variety of ARM based cores, remember
2831 this key point: @emph{ARM is a technology licencing company}.
2832 (See: @url{http://www.arm.com}.)
2833 The CPU name used by OpenOCD will reflect the CPU design that was
2834 licenced, not a vendor brand which incorporates that design.
2835 Name prefixes like arm7, arm9, arm11, and cortex
2836 reflect design generations;
2837 while names like ARMv4, ARMv5, ARMv6, and ARMv7
2838 reflect an architecture version implemented by a CPU design.
2839
2840 @anchor{Target Configuration}
2841 @section Target Configuration
2842
2843 Before creating a ``target'', you must have added its TAP to the scan chain.
2844 When you've added that TAP, you will have a @code{dotted.name}
2845 which is used to set up the CPU support.
2846 The chip-specific configuration file will normally configure its CPU(s)
2847 right after it adds all of the chip's TAPs to the scan chain.
2848
2849 Although you can set up a target in one step, it's often clearer if you
2850 use shorter commands and do it in two steps: create it, then configure
2851 optional parts.
2852 All operations on the target after it's created will use a new
2853 command, created as part of target creation.
2854
2855 The two main things to configure after target creation are
2856 a work area, which usually has target-specific defaults even
2857 if the board setup code overrides them later;
2858 and event handlers (@pxref{Target Events}), which tend
2859 to be much more board-specific.
2860 The key steps you use might look something like this
2861
2862 @example
2863 target create MyTarget cortex_m3 -chain-position mychip.cpu
2864 $MyTarget configure -work-area-phys 0x08000 -work-area-size 8096
2865 $MyTarget configure -event reset-deassert-pre @{ jtag_rclk 5 @}
2866 $MyTarget configure -event reset-init @{ myboard_reinit @}
2867 @end example
2868
2869 You should specify a working area if you can; typically it uses some
2870 on-chip SRAM.
2871 Such a working area can speed up many things, including bulk
2872 writes to target memory;
2873 flash operations like checking to see if memory needs to be erased;
2874 GDB memory checksumming;
2875 and more.
2876
2877 @quotation Warning
2878 On more complex chips, the work area can become
2879 inaccessible when application code
2880 (such as an operating system)
2881 enables or disables the MMU.
2882 For example, the particular MMU context used to acess the virtual
2883 address will probably matter ... and that context might not have
2884 easy access to other addresses needed.
2885 At this writing, OpenOCD doesn't have much MMU intelligence.
2886 @end quotation
2887
2888 It's often very useful to define a @code{reset-init} event handler.
2889 For systems that are normally used with a boot loader,
2890 common tasks include updating clocks and initializing memory
2891 controllers.
2892 That may be needed to let you write the boot loader into flash,
2893 in order to ``de-brick'' your board; or to load programs into
2894 external DDR memory without having run the boot loader.
2895
2896 @deffn Command {target create} target_name type configparams...
2897 This command creates a GDB debug target that refers to a specific JTAG tap.
2898 It enters that target into a list, and creates a new
2899 command (@command{@var{target_name}}) which is used for various
2900 purposes including additional configuration.
2901
2902 @itemize @bullet
2903 @item @var{target_name} ... is the name of the debug target.
2904 By convention this should be the same as the @emph{dotted.name}
2905 of the TAP associated with this target, which must be specified here
2906 using the @code{-chain-position @var{dotted.name}} configparam.
2907
2908 This name is also used to create the target object command,
2909 referred to here as @command{$target_name},
2910 and in other places the target needs to be identified.
2911 @item @var{type} ... specifies the target type. @xref{target types}.
2912 @item @var{configparams} ... all parameters accepted by
2913 @command{$target_name configure} are permitted.
2914 If the target is big-endian, set it here with @code{-endian big}.
2915 If the variant matters, set it here with @code{-variant}.
2916
2917 You @emph{must} set the @code{-chain-position @var{dotted.name}} here.
2918 @end itemize
2919 @end deffn
2920
2921 @deffn Command {$target_name configure} configparams...
2922 The options accepted by this command may also be
2923 specified as parameters to @command{target create}.
2924 Their values can later be queried one at a time by
2925 using the @command{$target_name cget} command.
2926
2927 @emph{Warning:} changing some of these after setup is dangerous.
2928 For example, moving a target from one TAP to another;
2929 and changing its endianness or variant.
2930
2931 @itemize @bullet
2932
2933 @item @code{-chain-position} @var{dotted.name} -- names the TAP
2934 used to access this target.
2935
2936 @item @code{-endian} (@option{big}|@option{little}) -- specifies
2937 whether the CPU uses big or little endian conventions
2938
2939 @item @code{-event} @var{event_name} @var{event_body} --
2940 @xref{Target Events}.
2941 Note that this updates a list of named event handlers.
2942 Calling this twice with two different event names assigns
2943 two different handlers, but calling it twice with the
2944 same event name assigns only one handler.
2945
2946 @item @code{-variant} @var{name} -- specifies a variant of the target,
2947 which OpenOCD needs to know about.
2948
2949 @item @code{-work-area-backup} (@option{0}|@option{1}) -- says
2950 whether the work area gets backed up; by default,
2951 @emph{it is not backed up.}
2952 When possible, use a working_area that doesn't need to be backed up,
2953 since performing a backup slows down operations.
2954 For example, the beginning of an SRAM block is likely to
2955 be used by most build systems, but the end is often unused.
2956
2957 @item @code{-work-area-size} @var{size} -- specify/set the work area
2958
2959 @item @code{-work-area-phys} @var{address} -- set the work area
2960 base @var{address} to be used when no MMU is active.
2961
2962 @item @code{-work-area-virt} @var{address} -- set the work area
2963 base @var{address} to be used when an MMU is active.
2964
2965 @end itemize
2966 @end deffn
2967
2968 @section Other $target_name Commands
2969 @cindex object command
2970
2971 The Tcl/Tk language has the concept of object commands,
2972 and OpenOCD adopts that same model for targets.
2973
2974 A good Tk example is a on screen button.
2975 Once a button is created a button
2976 has a name (a path in Tk terms) and that name is useable as a first
2977 class command. For example in Tk, one can create a button and later
2978 configure it like this:
2979
2980 @example
2981 # Create
2982 button .foobar -background red -command @{ foo @}
2983 # Modify
2984 .foobar configure -foreground blue
2985 # Query
2986 set x [.foobar cget -background]
2987 # Report
2988 puts [format "The button is %s" $x]
2989 @end example
2990
2991 In OpenOCD's terms, the ``target'' is an object just like a Tcl/Tk
2992 button, and its object commands are invoked the same way.
2993
2994 @example
2995 str912.cpu mww 0x1234 0x42
2996 omap3530.cpu mww 0x5555 123
2997 @end example
2998
2999 The commands supported by OpenOCD target objects are:
3000
3001 @deffn Command {$target_name arp_examine}
3002 @deffnx Command {$target_name arp_halt}
3003 @deffnx Command {$target_name arp_poll}
3004 @deffnx Command {$target_name arp_reset}
3005 @deffnx Command {$target_name arp_waitstate}
3006 Internal OpenOCD scripts (most notably @file{startup.tcl})
3007 use these to deal with specific reset cases.
3008 They are not otherwise documented here.
3009 @end deffn
3010
3011 @deffn Command {$target_name array2mem} arrayname width address count
3012 @deffnx Command {$target_name mem2array} arrayname width address count
3013 These provide an efficient script-oriented interface to memory.
3014 The @code{array2mem} primitive writes bytes, halfwords, or words;
3015 while @code{mem2array} reads them.
3016 In both cases, the TCL side uses an array, and
3017 the target side uses raw memory.
3018
3019 The efficiency comes from enabling the use of
3020 bulk JTAG data transfer operations.
3021 The script orientation comes from working with data
3022 values that are packaged for use by TCL scripts;
3023 @command{mdw} type primitives only print data they retrieve,
3024 and neither store nor return those values.
3025
3026 @itemize
3027 @item @var{arrayname} ... is the name of an array variable
3028 @item @var{width} ... is 8/16/32 - indicating the memory access size
3029 @item @var{address} ... is the target memory address
3030 @item @var{count} ... is the number of elements to process
3031 @end itemize
3032 @end deffn
3033
3034 @deffn Command {$target_name cget} queryparm
3035 Each configuration parameter accepted by
3036 @command{$target_name configure}
3037 can be individually queried, to return its current value.
3038 The @var{queryparm} is a parameter name
3039 accepted by that command, such as @code{-work-area-phys}.
3040 There are a few special cases:
3041
3042 @itemize @bullet
3043 @item @code{-event} @var{event_name} -- returns the handler for the
3044 event named @var{event_name}.
3045 This is a special case because setting a handler requires
3046 two parameters.
3047 @item @code{-type} -- returns the target type.
3048 This is a special case because this is set using
3049 @command{target create} and can't be changed
3050 using @command{$target_name configure}.
3051 @end itemize
3052
3053 For example, if you wanted to summarize information about
3054 all the targets you might use something like this:
3055
3056 @example
3057 foreach name [target names] @{
3058 set y [$name cget -endian]
3059 set z [$name cget -type]
3060 puts [format "Chip %d is %s, Endian: %s, type: %s" \
3061 $x $name $y $z]
3062 @}
3063 @end example
3064 @end deffn
3065
3066 @anchor{target curstate}
3067 @deffn Command {$target_name curstate}
3068 Displays the current target state:
3069 @code{debug-running},
3070 @code{halted},
3071 @code{reset},
3072 @code{running}, or @code{unknown}.
3073 (Also, @pxref{Event Polling}.)
3074 @end deffn
3075
3076 @deffn Command {$target_name eventlist}
3077 Displays a table listing all event handlers
3078 currently associated with this target.
3079 @xref{Target Events}.
3080 @end deffn
3081
3082 @deffn Command {$target_name invoke-event} event_name
3083 Invokes the handler for the event named @var{event_name}.
3084 (This is primarily intended for use by OpenOCD framework
3085 code, for example by the reset code in @file{startup.tcl}.)
3086 @end deffn
3087
3088 @deffn Command {$target_name mdw} addr [count]
3089 @deffnx Command {$target_name mdh} addr [count]
3090 @deffnx Command {$target_name mdb} addr [count]
3091 Display contents of address @var{addr}, as
3092 32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}),
3093 or 8-bit bytes (@command{mdb}).
3094 If @var{count} is specified, displays that many units.
3095 (If you want to manipulate the data instead of displaying it,
3096 see the @code{mem2array} primitives.)
3097 @end deffn
3098
3099 @deffn Command {$target_name mww} addr word
3100 @deffnx Command {$target_name mwh} addr halfword
3101 @deffnx Command {$target_name mwb} addr byte
3102 Writes the specified @var{word} (32 bits),
3103 @var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
3104 at the specified address @var{addr}.
3105 @end deffn
3106
3107 @anchor{Target Events}
3108 @section Target Events
3109 @cindex target events
3110 @cindex events
3111 At various times, certain things can happen, or you want them to happen.
3112 For example:
3113 @itemize @bullet
3114 @item What should happen when GDB connects? Should your target reset?
3115 @item When GDB tries to flash the target, do you need to enable the flash via a special command?
3116 @item During reset, do you need to write to certain memory locations
3117 to set up system clocks or
3118 to reconfigure the SDRAM?
3119 @end itemize
3120
3121 All of the above items can be addressed by target event handlers.
3122 These are set up by @command{$target_name configure -event} or
3123 @command{target create ... -event}.
3124
3125 The programmer's model matches the @code{-command} option used in Tcl/Tk
3126 buttons and events. The two examples below act the same, but one creates
3127 and invokes a small procedure while the other inlines it.
3128
3129 @example
3130 proc my_attach_proc @{ @} @{
3131 echo "Reset..."
3132 reset halt
3133 @}
3134 mychip.cpu configure -event gdb-attach my_attach_proc
3135 mychip.cpu configure -event gdb-attach @{
3136 echo "Reset..."
3137 reset halt
3138 @}
3139 @end example
3140
3141 The following target events are defined:
3142
3143 @itemize @bullet
3144 @item @b{debug-halted}
3145 @* The target has halted for debug reasons (i.e.: breakpoint)
3146 @item @b{debug-resumed}
3147 @* The target has resumed (i.e.: gdb said run)
3148 @item @b{early-halted}
3149 @* Occurs early in the halt process
3150 @ignore
3151 @item @b{examine-end}
3152 @* Currently not used (goal: when JTAG examine completes)
3153 @item @b{examine-start}
3154 @* Currently not used (goal: when JTAG examine starts)
3155 @end ignore
3156 @item @b{gdb-attach}
3157 @* When GDB connects
3158 @item @b{gdb-detach}
3159 @* When GDB disconnects
3160 @item @b{gdb-end}
3161 @* When the target has halted and GDB is not doing anything (see early halt)
3162 @item @b{gdb-flash-erase-start}
3163 @* Before the GDB flash process tries to erase the flash
3164 @item @b{gdb-flash-erase-end}
3165 @* After the GDB flash process has finished erasing the flash
3166 @item @b{gdb-flash-write-start}
3167 @* Before GDB writes to the flash
3168 @item @b{gdb-flash-write-end}
3169 @* After GDB writes to the flash
3170 @item @b{gdb-start}
3171 @* Before the target steps, gdb is trying to start/resume the target
3172 @item @b{halted}
3173 @* The target has halted
3174 @ignore
3175 @item @b{old-gdb_program_config}
3176 @* DO NOT USE THIS: Used internally
3177 @item @b{old-pre_resume}
3178 @* DO NOT USE THIS: Used internally
3179 @end ignore
3180 @item @b{reset-assert-pre}
3181 @* Issued as part of @command{reset} processing
3182 after SRST and/or TRST were activated and deactivated,
3183 but before SRST alone is re-asserted on the tap.
3184 @item @b{reset-assert-post}
3185 @* Issued as part of @command{reset} processing
3186 when SRST is asserted on the tap.
3187 @item @b{reset-deassert-pre}
3188 @* Issued as part of @command{reset} processing
3189 when SRST is about to be released on the tap.
3190 @item @b{reset-deassert-post}
3191 @* Issued as part of @command{reset} processing
3192 when SRST has been released on the tap.
3193 @item @b{reset-end}
3194 @* Issued as the final step in @command{reset} processing.
3195 @ignore
3196 @item @b{reset-halt-post}
3197 @* Currently not used
3198 @item @b{reset-halt-pre}
3199 @* Currently not used
3200 @end ignore
3201 @item @b{reset-init}
3202 @* Used by @b{reset init} command for board-specific initialization.
3203 This event fires after @emph{reset-deassert-post}.
3204
3205 This is where you would configure PLLs and clocking, set up DRAM so
3206 you can download programs that don't fit in on-chip SRAM, set up pin
3207 multiplexing, and so on.
3208 (You may be able to switch to a fast JTAG clock rate here, after
3209 the target clocks are fully set up.)
3210 @item @b{reset-start}
3211 @* Issued as part of @command{reset} processing
3212 before either SRST or TRST are activated.
3213
3214 This is the most robust place to switch to a low JTAG clock rate, if
3215 SRST disables PLLs needed to use a fast clock.
3216 @ignore
3217 @item @b{reset-wait-pos}
3218 @* Currently not used
3219 @item @b{reset-wait-pre}
3220 @* Currently not used
3221 @end ignore
3222 @item @b{resume-start}
3223 @* Before any target is resumed
3224 @item @b{resume-end}
3225 @* After all targets have resumed
3226 @item @b{resume-ok}
3227 @* Success
3228 @item @b{resumed}
3229 @* Target has resumed
3230 @end itemize
3231
3232
3233 @node Flash Commands
3234 @chapter Flash Commands
3235
3236 OpenOCD has different commands for NOR and NAND flash;
3237 the ``flash'' command works with NOR flash, while
3238 the ``nand'' command works with NAND flash.
3239 This partially reflects different hardware technologies:
3240 NOR flash usually supports direct CPU instruction and data bus access,
3241 while data from a NAND flash must be copied to memory before it can be
3242 used. (SPI flash must also be copied to memory before use.)
3243 However, the documentation also uses ``flash'' as a generic term;
3244 for example, ``Put flash configuration in board-specific files''.
3245
3246 Flash Steps:
3247 @enumerate
3248 @item Configure via the command @command{flash bank}
3249 @* Do this in a board-specific configuration file,
3250 passing parameters as needed by the driver.
3251 @item Operate on the flash via @command{flash subcommand}
3252 @* Often commands to manipulate the flash are typed by a human, or run
3253 via a script in some automated way. Common tasks include writing a
3254 boot loader, operating system, or other data.
3255 @item GDB Flashing
3256 @* Flashing via GDB requires the flash be configured via ``flash
3257 bank'', and the GDB flash features be enabled.
3258 @xref{GDB Configuration}.
3259 @end enumerate
3260
3261 Many CPUs have the ablity to ``boot'' from the first flash bank.
3262 This means that misprogramming that bank can ``brick'' a system,
3263 so that it can't boot.
3264 JTAG tools, like OpenOCD, are often then used to ``de-brick'' the
3265 board by (re)installing working boot firmware.
3266
3267 @anchor{NOR Configuration}
3268 @section Flash Configuration Commands
3269 @cindex flash configuration
3270
3271 @deffn {Config Command} {flash bank} driver base size chip_width bus_width target [driver_options]
3272 Configures a flash bank which provides persistent storage
3273 for addresses from @math{base} to @math{base + size - 1}.
3274 These banks will often be visible to GDB through the target's memory map.
3275 In some cases, configuring a flash bank will activate extra commands;
3276 see the driver-specific documentation.
3277
3278 @itemize @bullet
3279 @item @var{driver} ... identifies the controller driver
3280 associated with the flash bank being declared.
3281 This is usually @code{cfi} for external flash, or else
3282 the name of a microcontroller with embedded flash memory.
3283 @xref{Flash Driver List}.
3284 @item @var{base} ... Base address of the flash chip.
3285 @item @var{size} ... Size of the chip, in bytes.
3286 For some drivers, this value is detected from the hardware.
3287 @item @var{chip_width} ... Width of the flash chip, in bytes;
3288 ignored for most microcontroller drivers.
3289 @item @var{bus_width} ... Width of the data bus used to access the
3290 chip, in bytes; ignored for most microcontroller drivers.
3291 @item @var{target} ... Names the target used to issue
3292 commands to the flash controller.
3293 @comment Actually, it's currently a controller-specific parameter...
3294 @item @var{driver_options} ... drivers may support, or require,
3295 additional parameters. See the driver-specific documentation
3296 for more information.
3297 @end itemize
3298 @quotation Note
3299 This command is not available after OpenOCD initialization has completed.
3300 Use it in board specific configuration files, not interactively.
3301 @end quotation
3302 @end deffn
3303
3304 @comment the REAL name for this command is "ocd_flash_banks"
3305 @comment less confusing would be: "flash list" (like "nand list")
3306 @deffn Command {flash banks}
3307 Prints a one-line summary of each device declared
3308 using @command{flash bank}, numbered from zero.
3309 Note that this is the @emph{plural} form;
3310 the @emph{singular} form is a very different command.
3311 @end deffn
3312
3313 @deffn Command {flash probe} num
3314 Identify the flash, or validate the parameters of the configured flash. Operation
3315 depends on the flash type.
3316 The @var{num} parameter is a value shown by @command{flash banks}.
3317 Most flash commands will implicitly @emph{autoprobe} the bank;
3318 flash drivers can distinguish between probing and autoprobing,
3319 but most don't bother.
3320 @end deffn
3321
3322 @section Erasing, Reading, Writing to Flash
3323 @cindex flash erasing
3324 @cindex flash reading
3325 @cindex flash writing
3326 @cindex flash programming
3327
3328 One feature distinguishing NOR flash from NAND or serial flash technologies
3329 is that for read access, it acts exactly like any other addressible memory.
3330 This means you can use normal memory read commands like @command{mdw} or
3331 @command{dump_image} with it, with no special @command{flash} subcommands.
3332 @xref{Memory access}, and @ref{Image access}.
3333
3334 Write access works differently. Flash memory normally needs to be erased
3335 before it's written. Erasing a sector turns all of its bits to ones, and
3336 writing can turn ones into zeroes. This is why there are special commands
3337 for interactive erasing and writing, and why GDB needs to know which parts
3338 of the address space hold NOR flash memory.
3339
3340 @quotation Note
3341 Most of these erase and write commands leverage the fact that NOR flash
3342 chips consume target address space. They implicitly refer to the current
3343 JTAG target, and map from an address in that target's address space
3344 back to a flash bank.
3345 @comment In May 2009, those mappings may fail if any bank associated
3346 @comment with that target doesn't succesfuly autoprobe ... bug worth fixing?
3347 A few commands use abstract addressing based on bank and sector numbers,
3348 and don't depend on searching the current target and its address space.
3349 Avoid confusing the two command models.
3350 @end quotation
3351
3352 Some flash chips implement software protection against accidental writes,
3353 since such buggy writes could in some cases ``brick'' a system.
3354 For such systems, erasing and writing may require sector protection to be
3355 disabled first.
3356 Examples include CFI flash such as ``Intel Advanced Bootblock flash'',
3357 and AT91SAM7 on-chip flash.
3358 @xref{flash protect}.
3359
3360 @anchor{flash erase_sector}
3361 @deffn Command {flash erase_sector} num first last
3362 Erase sectors in bank @var{num}, starting at sector @var{first}
3363 up to and including @var{last}.
3364 Sector numbering starts at 0.
3365 Providing a @var{last} sector of @option{last}
3366 specifies "to the end of the flash bank".
3367 The @var{num} parameter is a value shown by @command{flash banks}.
3368 @end deffn
3369
3370 @deffn Command {flash erase_address} address length
3371 Erase sectors starting at @var{address} for @var{length} bytes.
3372 The flash bank to use is inferred from the @var{address}, and
3373 the specified length must stay within that bank.
3374 As a special case, when @var{length} is zero and @var{address} is
3375 the start of the bank, the whole flash is erased.
3376 @end deffn
3377
3378 @deffn Command {flash fillw} address word length
3379 @deffnx Command {flash fillh} address halfword length
3380 @deffnx Command {flash fillb} address byte length
3381 Fills flash memory with the specified @var{word} (32 bits),
3382 @var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
3383 starting at @var{address} and continuing
3384 for @var{length} units (word/halfword/byte).
3385 No erasure is done before writing; when needed, that must be done
3386 before issuing this command.
3387 Writes are done in blocks of up to 1024 bytes, and each write is
3388 verified by reading back the data and comparing it to what was written.
3389 The flash bank to use is inferred from the @var{address} of
3390 each block, and the specified length must stay within that bank.
3391 @end deffn
3392 @comment no current checks for errors if fill blocks touch multiple banks!
3393
3394 @anchor{flash write_bank}
3395 @deffn Command {flash write_bank} num filename offset
3396 Write the binary @file{filename} to flash bank @var{num},
3397 starting at @var{offset} bytes from the beginning of the bank.
3398 The @var{num} parameter is a value shown by @command{flash banks}.
3399 @end deffn
3400
3401 @anchor{flash write_image}
3402 @deffn Command {flash write_image} [erase] filename [offset] [type]
3403 Write the image @file{filename} to the current target's flash bank(s).
3404 A relocation @var{offset} may be specified, in which case it is added
3405 to the base address for each section in the image.
3406 The file [@var{type}] can be specified
3407 explicitly as @option{bin} (binary), @option{ihex} (Intel hex),
3408 @option{elf} (ELF file), @option{s19} (Motorola s19).
3409 @option{mem}, or @option{builder}.
3410 The relevant flash sectors will be erased prior to programming
3411 if the @option{erase} parameter is given.
3412 The flash bank to use is inferred from the @var{address} of
3413 each image segment.
3414 @end deffn
3415
3416 @section Other Flash commands
3417 @cindex flash protection
3418
3419 @deffn Command {flash erase_check} num
3420 Check erase state of sectors in flash bank @var{num},
3421 and display that status.
3422 The @var{num} parameter is a value shown by @command{flash banks}.
3423 This is the only operation that
3424 updates the erase state information displayed by @option{flash info}. That means you have
3425 to issue a @command{flash erase_check} command after erasing or programming the device
3426 to get updated information.
3427 (Code execution may have invalidated any state records kept by OpenOCD.)
3428 @end deffn
3429
3430 @deffn Command {flash info} num
3431 Print info about flash bank @var{num}
3432 The @var{num} parameter is a value shown by @command{flash banks}.
3433 The information includes per-sector protect status.
3434 @end deffn
3435
3436 @anchor{flash protect}
3437 @deffn Command {flash protect} num first last (@option{on}|@option{off})
3438 Enable (@option{on}) or disable (@option{off}) protection of flash sectors
3439 in flash bank @var{num}, starting at sector @var{first}
3440 and continuing up to and including @var{last}.
3441 Providing a @var{last} sector of @option{last}
3442 specifies "to the end of the flash bank".
3443 The @var{num} parameter is a value shown by @command{flash banks}.
3444 @end deffn
3445
3446 @deffn Command {flash protect_check} num
3447 Check protection state of sectors in flash bank @var{num}.
3448 The @var{num} parameter is a value shown by @command{flash banks}.
3449 @comment @option{flash erase_sector} using the same syntax.
3450 @end deffn
3451
3452 @anchor{Flash Driver List}
3453 @section Flash Drivers, Options, and Commands
3454 As noted above, the @command{flash bank} command requires a driver name,
3455 and allows driver-specific options and behaviors.
3456 Some drivers also activate driver-specific commands.
3457
3458 @subsection External Flash
3459
3460 @deffn {Flash Driver} cfi
3461 @cindex Common Flash Interface
3462 @cindex CFI
3463 The ``Common Flash Interface'' (CFI) is the main standard for
3464 external NOR flash chips, each of which connects to a
3465 specific external chip select on the CPU.
3466 Frequently the first such chip is used to boot the system.
3467 Your board's @code{reset-init} handler might need to
3468 configure additional chip selects using other commands (like: @command{mww} to
3469 configure a bus and its timings) , or
3470 perhaps configure a GPIO pin that controls the ``write protect'' pin
3471 on the flash chip.
3472 The CFI driver can use a target-specific working area to significantly
3473 speed up operation.
3474
3475 The CFI driver can accept the following optional parameters, in any order:
3476
3477 @itemize
3478 @item @var{jedec_probe} ... is used to detect certain non-CFI flash ROMs,
3479 like AM29LV010 and similar types.
3480 @item @var{x16_as_x8} ... when a 16-bit flash is hooked up to an 8-bit bus.
3481 @end itemize
3482
3483 To configure two adjacent banks of 16 MBytes each, both sixteen bits (two bytes)
3484 wide on a sixteen bit bus:
3485
3486 @example
3487 flash bank cfi 0x00000000 0x01000000 2 2 $_TARGETNAME
3488 flash bank cfi 0x01000000 0x01000000 2 2 $_TARGETNAME
3489 @end example
3490 @c "cfi part_id" disabled
3491 @end deffn
3492
3493 @subsection Internal Flash (Microcontrollers)
3494
3495 @deffn {Flash Driver} aduc702x
3496 The ADUC702x analog microcontrollers from Analog Devices
3497 include internal flash and use ARM7TDMI cores.
3498 The aduc702x flash driver works with models ADUC7019 through ADUC7028.
3499 The setup command only requires the @var{target} argument
3500 since all devices in this family have the same memory layout.
3501
3502 @example
3503 flash bank aduc702x 0 0 0 0 $_TARGETNAME
3504 @end example
3505 @end deffn
3506
3507 @deffn {Flash Driver} at91sam3
3508 @cindex at91sam3
3509 All members of the AT91SAM3 microcontroller family from
3510 Atmel include internal flash and use ARM's Cortex-M3 core. The driver
3511 currently (6/22/09) recognizes the AT91SAM3U[1/2/4][C/E] chips. Note
3512 that the driver was orginaly developed and tested using the
3513 AT91SAM3U4E, using a SAM3U-EK eval board. Support for other chips in
3514 the family was cribbed from the data sheet. @emph{Note to future
3515 readers/updaters: Please remove this worrysome comment after other
3516 chips are confirmed.}
3517
3518 The AT91SAM3U4[E/C] (256K) chips have two flash banks; most other chips
3519 have one flash bank. In all cases the flash banks are at
3520 the following fixed locations:
3521
3522 @example
3523 # Flash bank 0 - all chips
3524 flash bank at91sam3 0x00080000 0 1 1 $_TARGETNAME
3525 # Flash bank 1 - only 256K chips
3526 flash bank at91sam3 0x00100000 0 1 1 $_TARGETNAME
3527 @end example
3528
3529 Internally, the AT91SAM3 flash memory is organized as follows.
3530 Unlike the AT91SAM7 chips, these are not used as parameters
3531 to the @command{flash bank} command:
3532
3533 @itemize
3534 @item @emph{N-Banks:} 256K chips have 2 banks, others have 1 bank.
3535 @item @emph{Bank Size:} 128K/64K Per flash bank
3536 @item @emph{Sectors:} 16 or 8 per bank
3537 @item @emph{SectorSize:} 8K Per Sector
3538 @item @emph{PageSize:} 256 bytes per page. Note that OpenOCD operates on 'sector' sizes, not page sizes.
3539 @end itemize
3540
3541 The AT91SAM3 driver adds some additional commands:
3542
3543 @deffn Command {at91sam3 gpnvm}
3544 @deffnx Command {at91sam3 gpnvm clear} number
3545 @deffnx Command {at91sam3 gpnvm set} number
3546 @deffnx Command {at91sam3 gpnvm show} [@option{all}|number]
3547 With no parameters, @command{show} or @command{show all},
3548 shows the status of all GPNVM bits.
3549 With @command{show} @var{number}, displays that bit.
3550
3551 With @command{set} @var{number} or @command{clear} @var{number},
3552 modifies that GPNVM bit.
3553 @end deffn
3554
3555 @deffn Command {at91sam3 info}
3556 This command attempts to display information about the AT91SAM3
3557 chip. @emph{First} it read the @code{CHIPID_CIDR} [address 0x400e0740, see
3558 Section 28.2.1, page 505 of the AT91SAM3U 29/may/2009 datasheet,
3559 document id: doc6430A] and decodes the values. @emph{Second} it reads the
3560 various clock configuration registers and attempts to display how it
3561 believes the chip is configured. By default, the SLOWCLK is assumed to
3562 be 32768 Hz, see the command @command{at91sam3 slowclk}.
3563 @end deffn
3564
3565 @deffn Command {at91sam3 slowclk} [value]
3566 This command shows/sets the slow clock frequency used in the
3567 @command{at91sam3 info} command calculations above.
3568 @end deffn
3569 @end deffn
3570
3571 @deffn {Flash Driver} at91sam7
3572 All members of the AT91SAM7 microcontroller family from Atmel include
3573 internal flash and use ARM7TDMI cores. The driver automatically
3574 recognizes a number of these chips using the chip identification
3575 register, and autoconfigures itself.
3576
3577 @example
3578 flash bank at91sam7 0 0 0 0 $_TARGETNAME
3579 @end example
3580
3581 For chips which are not recognized by the controller driver, you must
3582 provide additional parameters in the following order:
3583
3584 @itemize
3585 @item @var{chip_model} ... label used with @command{flash info}
3586 @item @var{banks}
3587 @item @var{sectors_per_bank}
3588 @item @var{pages_per_sector}
3589 @item @var{pages_size}
3590 @item @var{num_nvm_bits}
3591 @item @var{freq_khz} ... required if an external clock is provided,
3592 optional (but recommended) when the oscillator frequency is known
3593 @end itemize
3594
3595 It is recommended that you provide zeroes for all of those values
3596 except the clock frequency, so that everything except that frequency
3597 will be autoconfigured.
3598 Knowing the frequency helps ensure correct timings for flash access.
3599
3600 The flash controller handles erases automatically on a page (128/256 byte)
3601 basis, so explicit erase commands are not necessary for flash programming.
3602 However, there is an ``EraseAll`` command that can erase an entire flash
3603 plane (of up to 256KB), and it will be used automatically when you issue
3604 @command{flash erase_sector} or @command{flash erase_address} commands.
3605
3606 @deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
3607 Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
3608 bit for the processor. Each processor has a number of such bits,
3609 used for controlling features such as brownout detection (so they
3610 are not truly general purpose).
3611 @quotation Note
3612 This assumes that the first flash bank (number 0) is associated with
3613 the appropriate at91sam7 target.
3614 @end quotation
3615 @end deffn
3616 @end deffn
3617
3618 @deffn {Flash Driver} avr
3619 The AVR 8-bit microcontrollers from Atmel integrate flash memory.
3620 @emph{The current implementation is incomplete.}
3621 @comment - defines mass_erase ... pointless given flash_erase_address
3622 @end deffn
3623
3624 @deffn {Flash Driver} ecosflash
3625 @emph{No idea what this is...}
3626 The @var{ecosflash} driver defines one mandatory parameter,
3627 the name of a modules of target code which is downloaded
3628 and executed.
3629 @end deffn
3630
3631 @deffn {Flash Driver} lpc2000
3632 Most members of the LPC1700 and LPC2000 microcontroller families from NXP
3633 include internal flash and use Cortex-M3 (LPC1700) or ARM7TDMI (LPC2000) cores.
3634
3635 @quotation Note
3636 There are LPC2000 devices which are not supported by the @var{lpc2000}
3637 driver:
3638 The LPC2888 is supported by the @var{lpc288x} driver.
3639 The LPC29xx family is supported by the @var{lpc2900} driver.
3640 @end quotation
3641
3642 The @var{lpc2000} driver defines two mandatory and one optional parameters,
3643 which must appear in the following order:
3644
3645 @itemize
3646 @item @var{variant} ... required, may be
3647 @var{lpc2000_v1} (older LPC21xx and LPC22xx)
3648 @var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx)
3649 or @var{lpc1700} (LPC175x and LPC176x)
3650 @item @var{clock_kHz} ... the frequency, in kiloHertz,
3651 at which the core is running
3652 @item @var{calc_checksum} ... optional (but you probably want to provide this!),
3653 telling the driver to calculate a valid checksum for the exception vector table.
3654 @end itemize
3655
3656 LPC flashes don't require the chip and bus width to be specified.
3657
3658 @example
3659 flash bank lpc2000 0x0 0x7d000 0 0 $_TARGETNAME \
3660 lpc2000_v2 14765 calc_checksum
3661 @end example
3662
3663 @deffn {Command} {lpc2000 part_id} bank
3664 Displays the four byte part identifier associated with
3665 the specified flash @var{bank}.
3666 @end deffn
3667 @end deffn
3668
3669 @deffn {Flash Driver} lpc288x
3670 The LPC2888 microcontroller from NXP needs slightly different flash
3671 support from its lpc2000 siblings.
3672 The @var{lpc288x} driver defines one mandatory parameter,
3673 the programming clock rate in Hz.
3674 LPC flashes don't require the chip and bus width to be specified.
3675
3676 @example
3677 flash bank lpc288x 0 0 0 0 $_TARGETNAME 12000000
3678 @end example
3679 @end deffn
3680
3681 @deffn {Flash Driver} lpc2900
3682 This driver supports the LPC29xx ARM968E based microcontroller family
3683 from NXP.
3684
3685 The predefined parameters @var{base}, @var{size}, @var{chip_width} and
3686 @var{bus_width} of the @code{flash bank} command are ignored. Flash size and
3687 sector layout are auto-configured by the driver.
3688 The driver has one additional mandatory parameter: The CPU clock rate
3689 (in kHz) at the time the flash operations will take place. Most of the time this
3690 will not be the crystal frequency, but a higher PLL frequency. The
3691 @code{reset-init} event handler in the board script is usually the place where
3692 you start the PLL.
3693
3694 The driver rejects flashless devices (currently the LPC2930).
3695
3696 The EEPROM in LPC2900 devices is not mapped directly into the address space.
3697 It must be handled much more like NAND flash memory, and will therefore be
3698 handled by a separate @code{lpc2900_eeprom} driver (not yet available).
3699
3700 Sector protection in terms of the LPC2900 is handled transparently. Every time a
3701 sector needs to be erased or programmed, it is automatically unprotected.
3702 What is shown as protection status in the @code{flash info} command, is
3703 actually the LPC2900 @emph{sector security}. This is a mechanism to prevent a
3704 sector from ever being erased or programmed again. As this is an irreversible
3705 mechanism, it is handled by a special command (@code{lpc2900 secure_sector}),
3706 and not by the standard @code{flash protect} command.
3707
3708 Example for a 125 MHz clock frequency:
3709 @example
3710 flash bank lpc2900 0 0 0 0 $_TARGETNAME 125000
3711 @end example
3712
3713 Some @code{lpc2900}-specific commands are defined. In the following command list,
3714 the @var{bank} parameter is the bank number as obtained by the
3715 @code{flash banks} command.
3716
3717 @deffn Command {lpc2900 signature} bank
3718 Calculates a 128-bit hash value, the @emph{signature}, from the whole flash
3719 content. This is a hardware feature of the flash block, hence the calculation is
3720 very fast. You may use this to verify the content of a programmed device against
3721 a known signature.
3722 Example:
3723 @example
3724 lpc2900 signature 0
3725 signature: 0x5f40cdc8:0xc64e592e:0x10490f89:0x32a0f317
3726 @end example
3727 @end deffn
3728
3729 @deffn Command {lpc2900 read_custom} bank filename
3730 Reads the 912 bytes of customer information from the flash index sector, and
3731 saves it to a file in binary format.
3732 Example:
3733 @example
3734 lpc2900 read_custom 0 /path_to/customer_info.bin
3735 @end example
3736 @end deffn
3737
3738 The index sector of the flash is a @emph{write-only} sector. It cannot be
3739 erased! In order to guard against unintentional write access, all following
3740 commands need to be preceeded by a successful call to the @code{password}
3741 command:
3742
3743 @deffn Command {lpc2900 password} bank password
3744 You need to use this command right before each of the following commands:
3745 @code{lpc2900 write_custom}, @code{lpc2900 secure_sector},
3746 @code{lpc2900 secure_jtag}.
3747
3748 The password string is fixed to "I_know_what_I_am_doing".
3749 Example:
3750 @example
3751 lpc2900 password 0 I_know_what_I_am_doing
3752 Potentially dangerous operation allowed in next command!
3753 @end example
3754 @end deffn
3755
3756 @deffn Command {lpc2900 write_custom} bank filename type
3757 Writes the content of the file into the customer info space of the flash index
3758 sector. The filetype can be specified with the @var{type} field. Possible values
3759 for @var{type} are: @var{bin} (binary), @var{ihex} (Intel hex format),
3760 @var{elf} (ELF binary) or @var{s19} (Motorola S-records). The file must
3761 contain a single section, and the contained data length must be exactly
3762 912 bytes.
3763 @quotation Attention
3764 This cannot be reverted! Be careful!
3765 @end quotation
3766 Example:
3767 @example
3768 lpc2900 write_custom 0 /path_to/customer_info.bin bin
3769 @end example
3770 @end deffn
3771
3772 @deffn Command {lpc2900 secure_sector} bank first last
3773 Secures the sector range from @var{first} to @var{last} (including) against
3774 further program and erase operations. The sector security will be effective
3775 after the next power cycle.
3776 @quotation Attention
3777 This cannot be reverted! Be careful!
3778 @end quotation
3779 Secured sectors appear as @emph{protected} in the @code{flash info} command.
3780 Example:
3781 @example
3782 lpc2900 secure_sector 0 1 1
3783 flash info 0
3784 #0 : lpc2900 at 0x20000000, size 0x000c0000, (...)
3785 # 0: 0x00000000 (0x2000 8kB) not protected
3786 # 1: 0x00002000 (0x2000 8kB) protected
3787 # 2: 0x00004000 (0x2000 8kB) not protected
3788 @end example
3789 @end deffn
3790
3791 @deffn Command {lpc2900 secure_jtag} bank
3792 Irreversibly disable the JTAG port. The new JTAG security setting will be
3793 effective after the next power cycle.
3794 @quotation Attention
3795 This cannot be reverted! Be careful!
3796 @end quotation
3797 Examples:
3798 @example
3799 lpc2900 secure_jtag 0
3800 @end example
3801 @end deffn
3802 @end deffn
3803
3804 @deffn {Flash Driver} ocl
3805 @emph{No idea what this is, other than using some arm7/arm9 core.}
3806
3807 @example
3808 flash bank ocl 0 0 0 0 $_TARGETNAME
3809 @end example
3810 @end deffn
3811
3812 @deffn {Flash Driver} pic32mx
3813 The PIC32MX microcontrollers are based on the MIPS 4K cores,
3814 and integrate flash memory.
3815 @emph{The current implementation is incomplete.}
3816
3817 @example
3818 flash bank pix32mx 0 0 0 0 $_TARGETNAME
3819 @end example
3820
3821 @comment numerous *disabled* commands are defined:
3822 @comment - chip_erase ... pointless given flash_erase_address
3823 @comment - lock, unlock ... pointless given protect on/off (yes?)
3824 @comment - pgm_word ... shouldn't bank be deduced from address??
3825 Some pic32mx-specific commands are defined:
3826 @deffn Command {pic32mx pgm_word} address value bank
3827 Programs the specified 32-bit @var{value} at the given @var{address}
3828 in the specified chip @var{bank}.
3829 @end deffn
3830 @end deffn
3831
3832 @deffn {Flash Driver} stellaris
3833 All members of the Stellaris LM3Sxxx microcontroller family from
3834 Texas Instruments
3835 include internal flash and use ARM Cortex M3 cores.
3836 The driver automatically recognizes a number of these chips using
3837 the chip identification register, and autoconfigures itself.
3838 @footnote{Currently there is a @command{stellaris mass_erase} command.
3839 That seems pointless since the same effect can be had using the
3840 standard @command{flash erase_address} command.}
3841
3842 @example
3843 flash bank stellaris 0 0 0 0 $_TARGETNAME
3844 @end example
3845 @end deffn
3846
3847 @deffn {Flash Driver} stm32x
3848 All members of the STM32 microcontroller family from ST Microelectronics
3849 include internal flash and use ARM Cortex M3 cores.
3850 The driver automatically recognizes a number of these chips using
3851 the chip identification register, and autoconfigures itself.
3852
3853 @example
3854 flash bank stm32x 0 0 0 0 $_TARGETNAME
3855 @end example
3856
3857 Some stm32x-specific commands
3858 @footnote{Currently there is a @command{stm32x mass_erase} command.
3859 That seems pointless since the same effect can be had using the
3860 standard @command{flash erase_address} command.}
3861 are defined:
3862
3863 @deffn Command {stm32x lock} num
3864 Locks the entire stm32 device.
3865 The @var{num} parameter is a value shown by @command{flash banks}.
3866 @end deffn
3867
3868 @deffn Command {stm32x unlock} num
3869 Unlocks the entire stm32 device.
3870 The @var{num} parameter is a value shown by @command{flash banks}.
3871 @end deffn
3872
3873 @deffn Command {stm32x options_read} num
3874 Read and display the stm32 option bytes written by
3875 the @command{stm32x options_write} command.
3876 The @var{num} parameter is a value shown by @command{flash banks}.
3877 @end deffn
3878
3879 @deffn Command {stm32x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP})
3880 Writes the stm32 option byte with the specified values.
3881 The @var{num} parameter is a value shown by @command{flash banks}.
3882 @end deffn
3883 @end deffn
3884
3885 @deffn {Flash Driver} str7x
3886 All members of the STR7 microcontroller family from ST Microelectronics
3887 include internal flash and use ARM7TDMI cores.
3888 The @var{str7x} driver defines one mandatory parameter, @var{variant},
3889 which is either @code{STR71x}, @code{STR73x} or @code{STR75x}.
3890
3891 @example
3892 flash bank str7x 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x
3893 @end example
3894
3895 @deffn Command {str7x disable_jtag} bank
3896 Activate the Debug/Readout protection mechanism
3897 for the specified flash bank.
3898 @end deffn
3899 @end deffn
3900
3901 @deffn {Flash Driver} str9x
3902 Most members of the STR9 microcontroller family from ST Microelectronics
3903 include internal flash and use ARM966E cores.
3904 The str9 needs the flash controller to be configured using
3905 the @command{str9x flash_config} command prior to Flash programming.
3906
3907 @example
3908 flash bank str9x 0x40000000 0x00040000 0 0 $_TARGETNAME
3909 str9x flash_config 0 4 2 0 0x80000
3910 @end example
3911
3912 @deffn Command {str9x flash_config} num bbsr nbbsr bbadr nbbadr
3913 Configures the str9 flash controller.
3914 The @var{num} parameter is a value shown by @command{flash banks}.
3915
3916 @itemize @bullet
3917 @item @var{bbsr} - Boot Bank Size register
3918 @item @var{nbbsr} - Non Boot Bank Size register
3919 @item @var{bbadr} - Boot Bank Start Address register
3920 @item @var{nbbadr} - Boot Bank Start Address register
3921 @end itemize
3922 @end deffn
3923
3924 @end deffn
3925
3926 @deffn {Flash Driver} tms470
3927 Most members of the TMS470 microcontroller family from Texas Instruments
3928 include internal flash and use ARM7TDMI cores.
3929 This driver doesn't require the chip and bus width to be specified.
3930
3931 Some tms470-specific commands are defined:
3932
3933 @deffn Command {tms470 flash_keyset} key0 key1 key2 key3
3934 Saves programming keys in a register, to enable flash erase and write commands.
3935 @end deffn
3936
3937 @deffn Command {tms470 osc_mhz} clock_mhz
3938 Reports the clock speed, which is used to calculate timings.
3939 @end deffn
3940
3941 @deffn Command {tms470 plldis} (0|1)
3942 Disables (@var{1}) or enables (@var{0}) use of the PLL to speed up
3943 the flash clock.
3944 @end deffn
3945 @end deffn
3946
3947 @subsection str9xpec driver
3948 @cindex str9xpec
3949
3950 Here is some background info to help
3951 you better understand how this driver works. OpenOCD has two flash drivers for
3952 the str9:
3953 @enumerate
3954 @item
3955 Standard driver @option{str9x} programmed via the str9 core. Normally used for
3956 flash programming as it is faster than the @option{str9xpec} driver.
3957 @item
3958 Direct programming @option{str9xpec} using the flash controller. This is an
3959 ISC compilant (IEEE 1532) tap connected in series with the str9 core. The str9
3960 core does not need to be running to program using this flash driver. Typical use
3961 for this driver is locking/unlocking the target and programming the option bytes.
3962 @end enumerate
3963
3964 Before we run any commands using the @option{str9xpec} driver we must first disable
3965 the str9 core. This example assumes the @option{str9xpec} driver has been
3966 configured for flash bank 0.
3967 @example
3968 # assert srst, we do not want core running
3969 # while accessing str9xpec flash driver
3970 jtag_reset 0 1
3971 # turn off target polling
3972 poll off
3973 # disable str9 core
3974 str9xpec enable_turbo 0
3975 # read option bytes
3976 str9xpec options_read 0
3977 # re-enable str9 core
3978 str9xpec disable_turbo 0
3979 poll on
3980 reset halt
3981 @end example
3982 The above example will read the str9 option bytes.
3983 When performing a unlock remember that you will not be able to halt the str9 - it
3984 has been locked. Halting the core is not required for the @option{str9xpec} driver
3985 as mentioned above, just issue the commands above manually or from a telnet prompt.
3986
3987 @deffn {Flash Driver} str9xpec
3988 Only use this driver for locking/unlocking the device or configuring the option bytes.
3989 Use the standard str9 driver for programming.
3990 Before using the flash commands the turbo mode must be enabled using the
3991 @command{str9xpec enable_turbo} command.
3992
3993 Several str9xpec-specific commands are defined:
3994
3995 @deffn Command {str9xpec disable_turbo} num
3996 Restore the str9 into JTAG chain.
3997 @end deffn
3998
3999 @deffn Command {str9xpec enable_turbo} num
4000 Enable turbo mode, will simply remove the str9 from the chain and talk
4001 directly to the embedded flash controller.
4002 @end deffn
4003
4004 @deffn Command {str9xpec lock} num
4005 Lock str9 device. The str9 will only respond to an unlock command that will
4006 erase the device.
4007 @end deffn
4008
4009 @deffn Command {str9xpec part_id} num
4010 Prints the part identifier for bank @var{num}.
4011 @end deffn
4012
4013 @deffn Command {str9xpec options_cmap} num (@option{bank0}|@option{bank1})
4014 Configure str9 boot bank.
4015 @end deffn
4016
4017 @deffn Command {str9xpec options_lvdsel} num (@option{vdd}|@option{vdd_vddq})
4018 Configure str9 lvd source.
4019 @end deffn
4020
4021 @deffn Command {str9xpec options_lvdthd} num (@option{2.4v}|@option{2.7v})
4022 Configure str9 lvd threshold.
4023 @end deffn
4024
4025 @deffn Command {str9xpec options_lvdwarn} bank (@option{vdd}|@option{vdd_vddq})
4026 Configure str9 lvd reset warning source.
4027 @end deffn
4028
4029 @deffn Command {str9xpec options_read} num
4030 Read str9 option bytes.
4031 @end deffn
4032
4033 @deffn Command {str9xpec options_write} num
4034 Write str9 option bytes.
4035 @end deffn
4036
4037 @deffn Command {str9xpec unlock} num
4038 unlock str9 device.
4039 @end deffn
4040
4041 @end deffn
4042
4043
4044 @section mFlash
4045
4046 @subsection mFlash Configuration
4047 @cindex mFlash Configuration
4048
4049 @deffn {Config Command} {mflash bank} soc base RST_pin target
4050 Configures a mflash for @var{soc} host bank at
4051 address @var{base}.
4052 The pin number format depends on the host GPIO naming convention.
4053 Currently, the mflash driver supports s3c2440 and pxa270.
4054
4055 Example for s3c2440 mflash where @var{RST pin} is GPIO B1:
4056
4057 @example
4058 mflash bank s3c2440 0x10000000 1b 0
4059 @end example
4060
4061 Example for pxa270 mflash where @var{RST pin} is GPIO 43:
4062
4063 @example
4064 mflash bank pxa270 0x08000000 43 0
4065 @end example
4066 @end deffn
4067
4068 @subsection mFlash commands
4069 @cindex mFlash commands
4070
4071 @deffn Command {mflash config pll} frequency
4072 Configure mflash PLL.
4073 The @var{frequency} is the mflash input frequency, in Hz.
4074 Issuing this command will erase mflash's whole internal nand and write new pll.
4075 After this command, mflash needs power-on-reset for normal operation.
4076 If pll was newly configured, storage and boot(optional) info also need to be update.
4077 @end deffn
4078
4079 @deffn Command {mflash config boot}
4080 Configure bootable option.
4081 If bootable option is set, mflash offer the first 8 sectors
4082 (4kB) for boot.
4083 @end deffn
4084
4085 @deffn Command {mflash config storage}
4086 Configure storage information.
4087 For the normal storage operation, this information must be
4088 written.
4089 @end deffn
4090
4091 @deffn Command {mflash dump} num filename offset size
4092 Dump @var{size} bytes, starting at @var{offset} bytes from the
4093 beginning of the bank @var{num}, to the file named @var{filename}.
4094 @end deffn
4095
4096 @deffn Command {mflash probe}
4097 Probe mflash.
4098 @end deffn
4099
4100 @deffn Command {mflash write} num filename offset
4101 Write the binary file @var{filename} to mflash bank @var{num}, starting at
4102 @var{offset} bytes from the beginning of the bank.
4103 @end deffn
4104
4105 @node NAND Flash Commands
4106 @chapter NAND Flash Commands
4107 @cindex NAND
4108
4109 Compared to NOR or SPI flash, NAND devices are inexpensive
4110 and high density. Today's NAND chips, and multi-chip modules,
4111 commonly hold multiple GigaBytes of data.
4112
4113 NAND chips consist of a number of ``erase blocks'' of a given
4114 size (such as 128 KBytes), each of which is divided into a
4115 number of pages (of perhaps 512 or 2048 bytes each). Each
4116 page of a NAND flash has an ``out of band'' (OOB) area to hold
4117 Error Correcting Code (ECC) and other metadata, usually 16 bytes
4118 of OOB for every 512 bytes of page data.
4119
4120 One key characteristic of NAND flash is that its error rate
4121 is higher than that of NOR flash. In normal operation, that
4122 ECC is used to correct and detect errors. However, NAND
4123 blocks can also wear out and become unusable; those blocks
4124 are then marked "bad". NAND chips are even shipped from the
4125 manufacturer with a few bad blocks. The highest density chips
4126 use a technology (MLC) that wears out more quickly, so ECC
4127 support is increasingly important as a way to detect blocks
4128 that have begun to fail, and help to preserve data integrity
4129 with techniques such as wear leveling.
4130
4131 Software is used to manage the ECC. Some controllers don't
4132 support ECC directly; in those cases, software ECC is used.
4133 Other controllers speed up the ECC calculations with hardware.
4134 Single-bit error correction hardware is routine. Controllers
4135 geared for newer MLC chips may correct 4 or more errors for
4136 every 512 bytes of data.
4137
4138 You will need to make sure that any data you write using
4139 OpenOCD includes the apppropriate kind of ECC. For example,
4140 that may mean passing the @code{oob_softecc} flag when
4141 writing NAND data, or ensuring that the correct hardware
4142 ECC mode is used.
4143
4144 The basic steps for using NAND devices include:
4145 @enumerate
4146 @item Declare via the command @command{nand device}
4147 @* Do this in a board-specific configuration file,
4148 passing parameters as needed by the controller.
4149 @item Configure each device using @command{nand probe}.
4150 @* Do this only after the associated target is set up,
4151 such as in its reset-init script or in procures defined
4152 to access that device.
4153 @item Operate on the flash via @command{nand subcommand}
4154 @* Often commands to manipulate the flash are typed by a human, or run
4155 via a script in some automated way. Common task include writing a
4156 boot loader, operating system, or other data needed to initialize or
4157 de-brick a board.
4158 @end enumerate
4159
4160 @b{NOTE:} At the time this text was written, the largest NAND
4161 flash fully supported by OpenOCD is 2 GiBytes (16 GiBits).
4162 This is because the variables used to hold offsets and lengths
4163 are only 32 bits wide.
4164 (Larger chips may work in some cases, unless an offset or length
4165 is larger than 0xffffffff, the largest 32-bit unsigned integer.)
4166 Some larger devices will work, since they are actually multi-chip
4167 modules with two smaller chips and individual chipselect lines.
4168
4169 @anchor{NAND Configuration}
4170 @section NAND Configuration Commands
4171 @cindex NAND configuration
4172
4173 NAND chips must be declared in configuration scripts,
4174 plus some additional configuration that's done after
4175 OpenOCD has initialized.
4176
4177 @deffn {Config Command} {nand device} controller target [configparams...]
4178 Declares a NAND device, which can be read and written to
4179 after it has been configured through @command{nand probe}.
4180 In OpenOCD, devices are single chips; this is unlike some
4181 operating systems, which may manage multiple chips as if
4182 they were a single (larger) device.
4183 In some cases, configuring a device will activate extra
4184 commands; see the controller-specific documentation.
4185
4186 @b{NOTE:} This command is not available after OpenOCD
4187 initialization has completed. Use it in board specific
4188 configuration files, not interactively.
4189
4190 @itemize @bullet
4191 @item @var{controller} ... identifies the controller driver
4192 associated with the NAND device being declared.
4193 @xref{NAND Driver List}.
4194 @item @var{target} ... names the target used when issuing
4195 commands to the NAND controller.
4196 @comment Actually, it's currently a controller-specific parameter...
4197 @item @var{configparams} ... controllers may support, or require,
4198 additional parameters. See the controller-specific documentation
4199 for more information.
4200 @end itemize
4201 @end deffn
4202
4203 @deffn Command {nand list}
4204 Prints a summary of each device declared
4205 using @command{nand device}, numbered from zero.
4206 Note that un-probed devices show no details.
4207 @example
4208 > nand list
4209 #0: NAND 1GiB 3,3V 8-bit (Micron) pagesize: 2048, buswidth: 8,
4210 blocksize: 131072, blocks: 8192
4211 #1: NAND 1GiB 3,3V 8-bit (Micron) pagesize: 2048, buswidth: 8,
4212 blocksize: 131072, blocks: 8192
4213 >
4214 @end example
4215 @end deffn
4216
4217 @deffn Command {nand probe} num
4218 Probes the specified device to determine key characteristics
4219 like its page and block sizes, and how many blocks it has.
4220 The @var{num} parameter is the value shown by @command{nand list}.
4221 You must (successfully) probe a device before you can use
4222 it with most other NAND commands.
4223 @end deffn
4224
4225 @section Erasing, Reading, Writing to NAND Flash
4226
4227 @deffn Command {nand dump} num filename offset length [oob_option]
4228 @cindex NAND reading
4229 Reads binary data from the NAND device and writes it to the file,
4230 starting at the specified offset.
4231 The @var{num} parameter is the value shown by @command{nand list}.
4232
4233 Use a complete path name for @var{filename}, so you don't depend
4234 on the directory used to start the OpenOCD server.
4235
4236 The @var{offset} and @var{length} must be exact multiples of the
4237 device's page size. They describe a data region; the OOB data
4238 associated with each such page may also be accessed.
4239
4240 @b{NOTE:} At the time this text was written, no error correction
4241 was done on the data that's read, unless raw access was disabled
4242 and the underlying NAND controller driver had a @code{read_page}
4243 method which handled that error correction.
4244
4245 By default, only page data is saved to the specified file.
4246 Use an @var{oob_option} parameter to save OOB data:
4247 @itemize @bullet
4248 @item no oob_* parameter
4249 @*Output file holds only page data; OOB is discarded.
4250 @item @code{oob_raw}
4251 @*Output file interleaves page data and OOB data;
4252 the file will be longer than "length" by the size of the
4253 spare areas associated with each data page.
4254 Note that this kind of "raw" access is different from
4255 what's implied by @command{nand raw_access}, which just
4256 controls whether a hardware-aware access method is used.
4257 @item @code{oob_only}
4258 @*Output file has only raw OOB data, and will
4259 be smaller than "length" since it will contain only the
4260 spare areas associated with each data page.
4261 @end itemize
4262 @end deffn
4263
4264 @deffn Command {nand erase} num [offset length]
4265 @cindex NAND erasing
4266 @cindex NAND programming
4267 Erases blocks on the specified NAND device, starting at the
4268 specified @var{offset} and continuing for @var{length} bytes.
4269 Both of those values must be exact multiples of the device's
4270 block size, and the region they specify must fit entirely in the chip.
4271 If those parameters are not specified,
4272 the whole NAND chip will be erased.
4273 The @var{num} parameter is the value shown by @command{nand list}.
4274
4275 @b{NOTE:} This command will try to erase bad blocks, when told
4276 to do so, which will probably invalidate the manufacturer's bad
4277 block marker.
4278 For the remainder of the current server session, @command{nand info}
4279 will still report that the block ``is'' bad.
4280 @end deffn
4281
4282 @deffn Command {nand write} num filename offset [option...]
4283 @cindex NAND writing
4284 @cindex NAND programming
4285 Writes binary data from the file into the specified NAND device,
4286 starting at the specified offset. Those pages should already
4287 have been erased; you can't change zero bits to one bits.
4288 The @var{num} parameter is the value shown by @command{nand list}.
4289
4290 Use a complete path name for @var{filename}, so you don't depend
4291 on the directory used to start the OpenOCD server.
4292
4293 The @var{offset} must be an exact multiple of the device's page size.
4294 All data in the file will be written, assuming it doesn't run
4295 past the end of the device.
4296 Only full pages are written, and any extra space in the last
4297 page will be filled with 0xff bytes. (That includes OOB data,
4298 if that's being written.)
4299
4300 @b{NOTE:} At the time this text was written, bad blocks are
4301 ignored. That is, this routine will not skip bad blocks,
4302 but will instead try to write them. This can cause problems.
4303
4304 Provide at most one @var{option} parameter. With some
4305 NAND drivers, the meanings of these parameters may change
4306 if @command{nand raw_access} was used to disable hardware ECC.
4307 @itemize @bullet
4308 @item no oob_* parameter
4309 @*File has only page data, which is written.
4310 If raw acccess is in use, the OOB area will not be written.
4311 Otherwise, if the underlying NAND controller driver has
4312 a @code{write_page} routine, that routine may write the OOB
4313 with hardware-computed ECC data.
4314 @item @code{oob_only}
4315 @*File has only raw OOB data, which is written to the OOB area.
4316 Each page's data area stays untouched. @i{This can be a dangerous
4317 option}, since it can invalidate the ECC data.
4318 You may need to force raw access to use this mode.
4319 @item @code{oob_raw}
4320 @*File interleaves data and OOB data, both of which are written
4321 If raw access is enabled, the data is written first, then the
4322 un-altered OOB.
4323 Otherwise, if the underlying NAND controller driver has
4324 a @code{write_page} routine, that routine may modify the OOB
4325 before it's written, to include hardware-computed ECC data.
4326 @item @code{oob_softecc}
4327 @*File has only page data, which is written.
4328 The OOB area is filled with 0xff, except for a standard 1-bit
4329 software ECC code stored in conventional locations.
4330 You might need to force raw access to use this mode, to prevent
4331 the underlying driver from applying hardware ECC.
4332 @item @code{oob_softecc_kw}
4333 @*File has only page data, which is written.
4334 The OOB area is filled with 0xff, except for a 4-bit software ECC
4335 specific to the boot ROM in Marvell Kirkwood SoCs.
4336 You might need to force raw access to use this mode, to prevent
4337 the underlying driver from applying hardware ECC.
4338 @end itemize
4339 @end deffn
4340
4341 @section Other NAND commands
4342 @cindex NAND other commands
4343
4344 @deffn Command {nand check_bad_blocks} [offset length]
4345 Checks for manufacturer bad block markers on the specified NAND
4346 device. If no parameters are provided, checks the whole
4347 device; otherwise, starts at the specified @var{offset} and
4348 continues for @var{length} bytes.
4349 Both of those values must be exact multiples of the device's
4350 block size, and the region they specify must fit entirely in the chip.
4351 The @var{num} parameter is the value shown by @command{nand list}.
4352
4353 @b{NOTE:} Before using this command you should force raw access
4354 with @command{nand raw_access enable} to ensure that the underlying
4355 driver will not try to apply hardware ECC.
4356 @end deffn
4357
4358 @deffn Command {nand info} num
4359 The @var{num} parameter is the value shown by @command{nand list}.
4360 This prints the one-line summary from "nand list", plus for
4361 devices which have been probed this also prints any known
4362 status for each block.
4363 @end deffn
4364
4365 @deffn Command {nand raw_access} num (@option{enable}|@option{disable})
4366 Sets or clears an flag affecting how page I/O is done.
4367 The @var{num} parameter is the value shown by @command{nand list}.
4368
4369 This flag is cleared (disabled) by default, but changing that
4370 value won't affect all NAND devices. The key factor is whether
4371 the underlying driver provides @code{read_page} or @code{write_page}
4372 methods. If it doesn't provide those methods, the setting of
4373 this flag is irrelevant; all access is effectively ``raw''.
4374
4375 When those methods exist, they are normally used when reading
4376 data (@command{nand dump} or reading bad block markers) or
4377 writing it (@command{nand write}). However, enabling
4378 raw access (setting the flag) prevents use of those methods,
4379 bypassing hardware ECC logic.
4380 @i{This can be a dangerous option}, since writing blocks
4381 with the wrong ECC data can cause them to be marked as bad.
4382 @end deffn
4383
4384 @anchor{NAND Driver List}
4385 @section NAND Drivers, Options, and Commands
4386 As noted above, the @command{nand device} command allows
4387 driver-specific options and behaviors.
4388 Some controllers also activate controller-specific commands.
4389
4390 @deffn {NAND Driver} davinci
4391 This driver handles the NAND controllers found on DaVinci family
4392 chips from Texas Instruments.
4393 It takes three extra parameters:
4394 address of the NAND chip;
4395 hardware ECC mode to use (@option{hwecc1},
4396 @option{hwecc4}, @option{hwecc4_infix});
4397 address of the AEMIF controller on this processor.
4398 @example
4399 nand device davinci dm355.arm 0x02000000 hwecc4 0x01e10000
4400 @end example
4401 All DaVinci processors support the single-bit ECC hardware,
4402 and newer ones also support the four-bit ECC hardware.
4403 The @code{write_page} and @code{read_page} methods are used
4404 to implement those ECC modes, unless they are disabled using
4405 the @command{nand raw_access} command.
4406 @end deffn
4407
4408 @deffn {NAND Driver} lpc3180
4409 These controllers require an extra @command{nand device}
4410 parameter: the clock rate used by the controller.
4411 @deffn Command {lpc3180 select} num [mlc|slc]
4412 Configures use of the MLC or SLC controller mode.
4413 MLC implies use of hardware ECC.
4414 The @var{num} parameter is the value shown by @command{nand list}.
4415 @end deffn
4416
4417 At this writing, this driver includes @code{write_page}
4418 and @code{read_page} methods. Using @command{nand raw_access}
4419 to disable those methods will prevent use of hardware ECC
4420 in the MLC controller mode, but won't change SLC behavior.
4421 @end deffn
4422 @comment current lpc3180 code won't issue 5-byte address cycles
4423
4424 @deffn {NAND Driver} orion
4425 These controllers require an extra @command{nand device}
4426 parameter: the address of the controller.
4427 @example
4428 nand device orion 0xd8000000
4429 @end example
4430 These controllers don't define any specialized commands.
4431 At this writing, their drivers don't include @code{write_page}
4432 or @code{read_page} methods, so @command{nand raw_access} won't
4433 change any behavior.
4434 @end deffn
4435
4436 @deffn {NAND Driver} s3c2410
4437 @deffnx {NAND Driver} s3c2412
4438 @deffnx {NAND Driver} s3c2440
4439 @deffnx {NAND Driver} s3c2443
4440 These S3C24xx family controllers don't have any special
4441 @command{nand device} options, and don't define any
4442 specialized commands.
4443 At this writing, their drivers don't include @code{write_page}
4444 or @code{read_page} methods, so @command{nand raw_access} won't
4445 change any behavior.
4446 @end deffn
4447
4448 @node PLD/FPGA Commands
4449 @chapter PLD/FPGA Commands
4450 @cindex PLD
4451 @cindex FPGA
4452
4453 Programmable Logic Devices (PLDs) and the more flexible
4454 Field Programmable Gate Arrays (FPGAs) are both types of programmable hardware.
4455 OpenOCD can support programming them.
4456 Although PLDs are generally restrictive (cells are less functional, and
4457 there are no special purpose cells for memory or computational tasks),
4458 they share the same OpenOCD infrastructure.
4459 Accordingly, both are called PLDs here.
4460
4461 @section PLD/FPGA Configuration and Commands
4462
4463 As it does for JTAG TAPs, debug targets, and flash chips (both NOR and NAND),
4464 OpenOCD maintains a list of PLDs available for use in various commands.
4465 Also, each such PLD requires a driver.
4466
4467 They are referenced by the number shown by the @command{pld devices} command,
4468 and new PLDs are defined by @command{pld device driver_name}.
4469
4470 @deffn {Config Command} {pld device} driver_name tap_name [driver_options]
4471 Defines a new PLD device, supported by driver @var{driver_name},
4472 using the TAP named @var{tap_name}.
4473 The driver may make use of any @var{driver_options} to configure its
4474 behavior.
4475 @end deffn
4476
4477 @deffn {Command} {pld devices}
4478 Lists the PLDs and their numbers.
4479 @end deffn
4480
4481 @deffn {Command} {pld load} num filename
4482 Loads the file @file{filename} into the PLD identified by @var{num}.
4483 The file format must be inferred by the driver.
4484 @end deffn
4485
4486 @section PLD/FPGA Drivers, Options, and Commands
4487
4488 Drivers may support PLD-specific options to the @command{pld device}
4489 definition command, and may also define commands usable only with
4490 that particular type of PLD.
4491
4492 @deffn {FPGA Driver} virtex2
4493 Virtex-II is a family of FPGAs sold by Xilinx.
4494 It supports the IEEE 1532 standard for In-System Configuration (ISC).
4495 No driver-specific PLD definition options are used,
4496 and one driver-specific command is defined.
4497
4498 @deffn {Command} {virtex2 read_stat} num
4499 Reads and displays the Virtex-II status register (STAT)
4500 for FPGA @var{num}.
4501 @end deffn
4502 @end deffn
4503
4504 @node General Commands
4505 @chapter General Commands
4506 @cindex commands
4507
4508 The commands documented in this chapter here are common commands that
4509 you, as a human, may want to type and see the output of. Configuration type
4510 commands are documented elsewhere.
4511
4512 Intent:
4513 @itemize @bullet
4514 @item @b{Source Of Commands}
4515 @* OpenOCD commands can occur in a configuration script (discussed
4516 elsewhere) or typed manually by a human or supplied programatically,
4517 or via one of several TCP/IP Ports.
4518
4519 @item @b{From the human}
4520 @* A human should interact with the telnet interface (default port: 4444)
4521 or via GDB (default port 3333).
4522
4523 To issue commands from within a GDB session, use the @option{monitor}
4524 command, e.g. use @option{monitor poll} to issue the @option{poll}
4525 command. All output is relayed through the GDB session.
4526
4527 @item @b{Machine Interface}
4528 The Tcl interface's intent is to be a machine interface. The default Tcl
4529 port is 5555.
4530 @end itemize
4531
4532
4533 @section Daemon Commands
4534
4535 @deffn {Command} exit
4536 Exits the current telnet session.
4537 @end deffn
4538
4539 @c note EXTREMELY ANNOYING word wrap at column 75
4540 @c even when lines are e.g. 100+ columns ...
4541 @c coded in startup.tcl
4542 @deffn {Command} help [string]
4543 With no parameters, prints help text for all commands.
4544 Otherwise, prints each helptext containing @var{string}.
4545 Not every command provides helptext.
4546 @end deffn
4547
4548 @deffn Command sleep msec [@option{busy}]
4549 Wait for at least @var{msec} milliseconds before resuming.
4550 If @option{busy} is passed, busy-wait instead of sleeping.
4551 (This option is strongly discouraged.)
4552 Useful in connection with script files
4553 (@command{script} command and @command{target_name} configuration).
4554 @end deffn
4555
4556 @deffn Command shutdown
4557 Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
4558 @end deffn
4559
4560 @anchor{debug_level}
4561 @deffn Command debug_level [n]
4562 @cindex message level
4563 Display debug level.
4564 If @var{n} (from 0..3) is provided, then set it to that level.
4565 This affects the kind of messages sent to the server log.
4566 Level 0 is error messages only;
4567 level 1 adds warnings;
4568 level 2 adds informational messages;
4569 and level 3 adds debugging messages.
4570 The default is level 2, but that can be overridden on
4571 the command line along with the location of that log
4572 file (which is normally the server's standard output).
4573 @xref{Running}.
4574 @end deffn
4575
4576 @deffn Command fast (@option{enable}|@option{disable})
4577 Default disabled.
4578 Set default behaviour of OpenOCD to be "fast and dangerous".
4579
4580 At this writing, this only affects the defaults for two ARM7/ARM9 parameters:
4581 fast memory access, and DCC downloads. Those parameters may still be
4582 individually overridden.
4583
4584 The target specific "dangerous" optimisation tweaking options may come and go
4585 as more robust and user friendly ways are found to ensure maximum throughput
4586 and robustness with a minimum of configuration.
4587
4588 Typically the "fast enable" is specified first on the command line:
4589
4590 @example
4591 openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg
4592 @end example
4593 @end deffn
4594
4595 @deffn Command echo message
4596 Logs a message at "user" priority.
4597 Output @var{message} to stdout.
4598 @example
4599 echo "Downloading kernel -- please wait"
4600 @end example
4601 @end deffn
4602
4603 @deffn Command log_output [filename]
4604 Redirect logging to @var{filename};
4605 the initial log output channel is stderr.
4606 @end deffn
4607
4608 @anchor{Target State handling}
4609 @section Target State handling
4610 @cindex reset
4611 @cindex halt
4612 @cindex target initialization
4613
4614 In this section ``target'' refers to a CPU configured as
4615 shown earlier (@pxref{CPU Configuration}).
4616 These commands, like many, implicitly refer to
4617 a current target which is used to perform the
4618 various operations. The current target may be changed
4619 by using @command{targets} command with the name of the
4620 target which should become current.
4621
4622 @deffn Command reg [(number|name) [value]]
4623 Access a single register by @var{number} or by its @var{name}.
4624
4625 @emph{With no arguments}:
4626 list all available registers for the current target,
4627 showing number, name, size, value, and cache status.
4628
4629 @emph{With number/name}: display that register's value.
4630
4631 @emph{With both number/name and value}: set register's value.
4632
4633 Cores may have surprisingly many registers in their
4634 Debug and trace infrastructure:
4635
4636 @example
4637 > reg
4638 (0) r0 (/32): 0x0000D3C2 (dirty: 1, valid: 1)
4639 (1) r1 (/32): 0xFD61F31C (dirty: 0, valid: 1)
4640 (2) r2 (/32): 0x00022551 (dirty: 0, valid: 1)
4641 ...
4642 (164) ETM_CONTEXTID_COMPARATOR_MASK (/32): \
4643 0x00000000 (dirty: 0, valid: 0)
4644 >
4645 @end example
4646 @end deffn
4647
4648 @deffn Command halt [ms]
4649 @deffnx Command wait_halt [ms]
4650 The @command{halt} command first sends a halt request to the target,
4651 which @command{wait_halt} doesn't.
4652 Otherwise these behave the same: wait up to @var{ms} milliseconds,
4653 or 5 seconds if there is no parameter, for the target to halt
4654 (and enter debug mode).
4655 Using 0 as the @var{ms} parameter prevents OpenOCD from waiting.
4656
4657 @quotation Warning
4658 On ARM cores, software using the @emph{wait for interrupt} operation
4659 often blocks the JTAG access needed by a @command{halt} command.
4660 This is because that operation also puts the core into a low
4661 power mode by gating the core clock;
4662 but the core clock is needed to detect JTAG clock transitions.
4663
4664 One partial workaround uses adaptive clocking: when the core is
4665 interrupted the operation completes, then JTAG clocks are accepted
4666 at least until the interrupt handler completes.
4667 However, this workaround is often unusable since the processor, board,
4668 and JTAG adapter must all support adaptive JTAG clocking.
4669 Also, it can't work until an interrupt is issued.
4670
4671 A more complete workaround is to not use that operation while you
4672 work with a JTAG debugger.
4673 Tasking environments generaly have idle loops where the body is the
4674 @emph{wait for interrupt} operation.
4675 (On older cores, it is a coprocessor action;
4676 newer cores have a @option{wfi} instruction.)
4677 Such loops can just remove that operation, at the cost of higher
4678 power consumption (because the CPU is needlessly clocked).
4679 @end quotation
4680
4681 @end deffn
4682
4683 @deffn Command resume [address]
4684 Resume the target at its current code position,
4685 or the optional @var{address} if it is provided.
4686 OpenOCD will wait 5 seconds for the target to resume.
4687 @end deffn
4688
4689 @deffn Command step [address]
4690 Single-step the target at its current code position,
4691 or the optional @var{address} if it is provided.
4692 @end deffn
4693
4694 @anchor{Reset Command}
4695 @deffn Command reset
4696 @deffnx Command {reset run}
4697 @deffnx Command {reset halt}
4698 @deffnx Command {reset init}
4699 Perform as hard a reset as possible, using SRST if possible.
4700 @emph{All defined targets will be reset, and target
4701 events will fire during the reset sequence.}
4702
4703 The optional parameter specifies what should
4704 happen after the reset.
4705 If there is no parameter, a @command{reset run} is executed.
4706 The other options will not work on all systems.
4707 @xref{Reset Configuration}.
4708
4709 @itemize @minus
4710 @item @b{run} Let the target run
4711 @item @b{halt} Immediately halt the target
4712 @item @b{init} Immediately halt the target, and execute the reset-init script
4713 @end itemize
4714 @end deffn
4715
4716 @deffn Command soft_reset_halt
4717 Requesting target halt and executing a soft reset. This is often used
4718 when a target cannot be reset and halted. The target, after reset is
4719 released begins to execute code. OpenOCD attempts to stop the CPU and
4720 then sets the program counter back to the reset vector. Unfortunately
4721 the code that was executed may have left the hardware in an unknown
4722 state.
4723 @end deffn
4724
4725 @section I/O Utilities
4726
4727 These commands are available when
4728 OpenOCD is built with @option{--enable-ioutil}.
4729 They are mainly useful on embedded targets,
4730 notably the ZY1000.
4731 Hosts with operating systems have complementary tools.
4732
4733 @emph{Note:} there are several more such commands.
4734
4735 @deffn Command append_file filename [string]*
4736 Appends the @var{string} parameters to
4737 the text file @file{filename}.
4738 Each string except the last one is followed by one space.
4739 The last string is followed by a newline.
4740 @end deffn
4741
4742 @deffn Command cat filename
4743 Reads and displays the text file @file{filename}.
4744 @end deffn
4745
4746 @deffn Command cp src_filename dest_filename
4747 Copies contents from the file @file{src_filename}
4748 into @file{dest_filename}.
4749 @end deffn
4750
4751 @deffn Command ip
4752 @emph{No description provided.}
4753 @end deffn
4754
4755 @deffn Command ls
4756 @emph{No description provided.}
4757 @end deffn
4758
4759 @deffn Command mac
4760 @emph{No description provided.}
4761 @end deffn
4762
4763 @deffn Command meminfo
4764 Display available RAM memory on OpenOCD host.
4765 Used in OpenOCD regression testing scripts.
4766 @end deffn
4767
4768 @deffn Command peek
4769 @emph{No description provided.}
4770 @end deffn
4771
4772 @deffn Command poke
4773 @emph{No description provided.}
4774 @end deffn
4775
4776 @deffn Command rm filename
4777 @c "rm" has both normal and Jim-level versions??
4778 Unlinks the file @file{filename}.
4779 @end deffn
4780
4781 @deffn Command trunc filename
4782 Removes all data in the file @file{filename}.
4783 @end deffn
4784
4785 @anchor{Memory access}
4786 @section Memory access commands
4787 @cindex memory access
4788
4789 These commands allow accesses of a specific size to the memory
4790 system. Often these are used to configure the current target in some
4791 special way. For example - one may need to write certain values to the
4792 SDRAM controller to enable SDRAM.
4793
4794 @enumerate
4795 @item Use the @command{targets} (plural) command
4796 to change the current target.
4797 @item In system level scripts these commands are deprecated.
4798 Please use their TARGET object siblings to avoid making assumptions
4799 about what TAP is the current target, or about MMU configuration.
4800 @end enumerate
4801
4802 @deffn Command mdw addr [count]
4803 @deffnx Command mdh addr [count]
4804 @deffnx Command mdb addr [count]
4805 Display contents of address @var{addr}, as
4806 32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}),
4807 or 8-bit bytes (@command{mdb}).
4808 If @var{count} is specified, displays that many units.
4809 (If you want to manipulate the data instead of displaying it,
4810 see the @code{mem2array} primitives.)
4811 @end deffn
4812
4813 @deffn Command mww addr word
4814 @deffnx Command mwh addr halfword
4815 @deffnx Command mwb addr byte
4816 Writes the specified @var{word} (32 bits),
4817 @var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
4818 at the specified address @var{addr}.
4819 @end deffn
4820
4821
4822 @anchor{Image access}
4823 @section Image loading commands
4824 @cindex image loading
4825 @cindex image dumping
4826
4827 @anchor{dump_image}
4828 @deffn Command {dump_image} filename address size
4829 Dump @var{size} bytes of target memory starting at @var{address} to the
4830 binary file named @var{filename}.
4831 @end deffn
4832
4833 @deffn Command {fast_load}
4834 Loads an image stored in memory by @command{fast_load_image} to the
4835 current target. Must be preceeded by fast_load_image.
4836 @end deffn
4837
4838 @deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
4839 Normally you should be using @command{load_image} or GDB load. However, for
4840 testing purposes or when I/O overhead is significant(OpenOCD running on an embedded
4841 host), storing the image in memory and uploading the image to the target
4842 can be a way to upload e.g. multiple debug sessions when the binary does not change.
4843 Arguments are the same as @command{load_image}, but the image is stored in OpenOCD host
4844 memory, i.e. does not affect target. This approach is also useful when profiling
4845 target programming performance as I/O and target programming can easily be profiled
4846 separately.
4847 @end deffn
4848
4849 @anchor{load_image}
4850 @deffn Command {load_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
4851 Load image from file @var{filename} to target memory at @var{address}.
4852 The file format may optionally be specified
4853 (@option{bin}, @option{ihex}, or @option{elf})
4854 @end deffn
4855
4856 @deffn Command {test_image} filename [address [@option{bin}|@option{ihex}|@option{elf}]]
4857 Displays image section sizes and addresses
4858 as if @var{filename} were loaded into target memory
4859 starting at @var{address} (defaults to zero).
4860 The file format may optionally be specified
4861 (@option{bin}, @option{ihex}, or @option{elf})
4862 @end deffn
4863
4864 @deffn Command {verify_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
4865 Verify @var{filename} against target memory starting at @var{address}.
4866 The file format may optionally be specified
4867 (@option{bin}, @option{ihex}, or @option{elf})
4868 This will first attempt a comparison using a CRC checksum, if this fails it will try a binary compare.
4869 @end deffn
4870
4871
4872 @section Breakpoint and Watchpoint commands
4873 @cindex breakpoint
4874 @cindex watchpoint
4875
4876 CPUs often make debug modules accessible through JTAG, with
4877 hardware support for a handful of code breakpoints and data
4878 watchpoints.
4879 In addition, CPUs almost always support software breakpoints.
4880
4881 @deffn Command {bp} [address len [@option{hw}]]
4882 With no parameters, lists all active breakpoints.
4883 Else sets a breakpoint on code execution starting
4884 at @var{address} for @var{length} bytes.
4885 This is a software breakpoint, unless @option{hw} is specified
4886 in which case it will be a hardware breakpoint.
4887
4888 (@xref{arm9tdmi vector_catch}, or @pxref{xscale vector_catch},
4889 for similar mechanisms that do not consume hardware breakpoints.)
4890 @end deffn
4891
4892 @deffn Command {rbp} address
4893 Remove the breakpoint at @var{address}.
4894 @end deffn
4895
4896 @deffn Command {rwp} address
4897 Remove data watchpoint on @var{address}
4898 @end deffn
4899
4900 @deffn Command {wp} [address len [(@option{r}|@option{w}|@option{a}) [value [mask]]]]
4901 With no parameters, lists all active watchpoints.
4902 Else sets a data watchpoint on data from @var{address} for @var{length} bytes.
4903 The watch point is an "access" watchpoint unless
4904 the @option{r} or @option{w} parameter is provided,
4905 defining it as respectively a read or write watchpoint.
4906 If a @var{value} is provided, that value is used when determining if
4907 the watchpoint should trigger. The value may be first be masked
4908 using @var{mask} to mark ``don't care'' fields.
4909 @end deffn
4910
4911 @section Misc Commands
4912
4913 @cindex profiling
4914 @deffn Command {profile} seconds filename
4915 Profiling samples the CPU's program counter as quickly as possible,
4916 which is useful for non-intrusive stochastic profiling.
4917 Saves up to 10000 sampines in @file{filename} using ``gmon.out'' format.
4918 @end deffn
4919
4920 @deffn Command {version}
4921 Displays a string identifying the version of this OpenOCD server.
4922 @end deffn
4923
4924 @deffn Command {virt2phys} virtual_address
4925 Requests the current target to map the specified @var{virtual_address}
4926 to its corresponding physical address, and displays the result.
4927 @end deffn
4928
4929 @node Architecture and Core Commands
4930 @chapter Architecture and Core Commands
4931 @cindex Architecture Specific Commands
4932 @cindex Core Specific Commands
4933
4934 Most CPUs have specialized JTAG operations to support debugging.
4935 OpenOCD packages most such operations in its standard command framework.
4936 Some of those operations don't fit well in that framework, so they are
4937 exposed here as architecture or implementation (core) specific commands.
4938
4939 @anchor{ARM Hardware Tracing}
4940 @section ARM Hardware Tracing
4941 @cindex tracing
4942 @cindex ETM
4943 @cindex ETB
4944
4945 CPUs based on ARM cores may include standard tracing interfaces,
4946 based on an ``Embedded Trace Module'' (ETM) which sends voluminous
4947 address and data bus trace records to a ``Trace Port''.
4948
4949 @itemize
4950 @item
4951 Development-oriented boards will sometimes provide a high speed
4952 trace connector for collecting that data, when the particular CPU
4953 supports such an interface.
4954 (The standard connector is a 38-pin Mictor, with both JTAG
4955 and trace port support.)
4956 Those trace connectors are supported by higher end JTAG adapters
4957 and some logic analyzer modules; frequently those modules can
4958 buffer several megabytes of trace data.
4959 Configuring an ETM coupled to such an external trace port belongs
4960 in the board-specific configuration file.
4961 @item
4962 If the CPU doesn't provide an external interface, it probably
4963 has an ``Embedded Trace Buffer'' (ETB) on the chip, which is a
4964 dedicated SRAM. 4KBytes is one common ETB size.
4965 Configuring an ETM coupled only to an ETB belongs in the CPU-specific
4966 (target) configuration file, since it works the same on all boards.
4967 @end itemize
4968
4969 ETM support in OpenOCD doesn't seem to be widely used yet.
4970
4971 @quotation Issues
4972 ETM support may be buggy, and at least some @command{etm config}
4973 parameters should be detected by asking the ETM for them.
4974 It seems like a GDB hookup should be possible,
4975 as well as triggering trace on specific events
4976 (perhaps @emph{handling IRQ 23} or @emph{calls foo()}).
4977 There should be GUI tools to manipulate saved trace data and help
4978 analyse it in conjunction with the source code.
4979 It's unclear how much of a common interface is shared
4980 with the current XScale trace support, or should be
4981 shared with eventual Nexus-style trace module support.
4982 At this writing (September 2009) only ARM7 and ARM9 support
4983 for ETM modules is available. The code should be able to
4984 work with some newer cores; but not all of them support
4985 this original style of JTAG access.
4986 @end quotation
4987
4988 @subsection ETM Configuration
4989 ETM setup is coupled with the trace port driver configuration.
4990
4991 @deffn {Config Command} {etm config} target width mode clocking driver
4992 Declares the ETM associated with @var{target}, and associates it
4993 with a given trace port @var{driver}. @xref{Trace Port Drivers}.
4994
4995 Several of the parameters must reflect the trace port configuration.
4996 The @var{width} must be either 4, 8, or 16.
4997 The @var{mode} must be @option{normal}, @option{multiplexted},
4998 or @option{demultiplexted}.
4999 The @var{clocking} must be @option{half} or @option{full}.
5000
5001 @quotation Note
5002 You can see the ETM registers using the @command{reg} command.
5003 Not all possible registers are present in every ETM.
5004 Most of the registers are write-only, and are used to configure
5005 what CPU activities are traced.
5006 @end quotation
5007 @end deffn
5008
5009 @deffn Command {etm info}
5010 Displays information about the current target's ETM.
5011 @end deffn
5012
5013 @deffn Command {etm status}
5014 Displays status of the current target's ETM and trace port driver:
5015 is the ETM idle, or is it collecting data?
5016 Did trace data overflow?
5017 Was it triggered?
5018 @end deffn
5019
5020 @deffn Command {etm tracemode} [type context_id_bits cycle_accurate branch_output]
5021 Displays what data that ETM will collect.
5022 If arguments are provided, first configures that data.
5023 When the configuration changes, tracing is stopped
5024 and any buffered trace data is invalidated.
5025
5026 @itemize
5027 @item @var{type} ... describing how data accesses are traced,
5028 when they pass any ViewData filtering that that was set up.
5029 The value is one of
5030 @option{none} (save nothing),
5031 @option{data} (save data),
5032 @option{address} (save addresses),
5033 @option{all} (save data and addresses)
5034 @item @var{context_id_bits} ... 0, 8, 16, or 32
5035 @item @var{cycle_accurate} ... @option{enable} or @option{disable}
5036 cycle-accurate instruction tracing.
5037 Before ETMv3, enabling this causes much extra data to be recorded.
5038 @item @var{branch_output} ... @option{enable} or @option{disable}.
5039 Disable this unless you need to try reconstructing the instruction
5040 trace stream without an image of the code.
5041 @end itemize
5042 @end deffn
5043
5044 @deffn Command {etm trigger_percent} [percent]
5045 This displays, or optionally changes, the trace port driver's
5046 behavior after the ETM's configured @emph{trigger} event fires.
5047 It controls how much more trace data is saved after the (single)
5048 trace trigger becomes active.
5049
5050 @itemize
5051 @item The default corresponds to @emph{trace around} usage,
5052 recording 50 percent data before the event and the rest
5053 afterwards.
5054 @item The minimum value of @var{percent} is 2 percent,
5055 recording almost exclusively data before the trigger.
5056 Such extreme @emph{trace before} usage can help figure out
5057 what caused that event to happen.
5058 @item The maximum value of @var{percent} is 100 percent,
5059 recording data almost exclusively after the event.
5060 This extreme @emph{trace after} usage might help sort out
5061 how the event caused trouble.
5062 @end itemize
5063 @c REVISIT allow "break" too -- enter debug mode.
5064 @end deffn
5065
5066 @subsection ETM Trace Operation
5067
5068 After setting up the ETM, you can use it to collect data.
5069 That data can be exported to files for later analysis.
5070 It can also be parsed with OpenOCD, for basic sanity checking.
5071
5072 To configure what is being traced, you will need to write
5073 various trace registers using @command{reg ETM_*} commands.
5074 For the definitions of these registers, read ARM publication
5075 @emph{IHI 0014, ``Embedded Trace Macrocell, Architecture Specification''}.
5076 Be aware that most of the relevant registers are write-only,
5077 and that ETM resources are limited. There are only a handful
5078 of address comparators, data comparators, counters, and so on.
5079
5080 Examples of scenarios you might arrange to trace include:
5081
5082 @itemize
5083 @item Code flow within a function, @emph{excluding} subroutines
5084 it calls. Use address range comparators to enable tracing
5085 for instruction access within that function's body.
5086 @item Code flow within a function, @emph{including} subroutines
5087 it calls. Use the sequencer and address comparators to activate
5088 tracing on an ``entered function'' state, then deactivate it by
5089 exiting that state when the function's exit code is invoked.
5090 @item Code flow starting at the fifth invocation of a function,
5091 combining one of the above models with a counter.
5092 @item CPU data accesses to the registers for a particular device,
5093 using address range comparators and the ViewData logic.
5094 @item Such data accesses only during IRQ handling, combining the above
5095 model with sequencer triggers which on entry and exit to the IRQ handler.
5096 @item @emph{... more}
5097 @end itemize
5098
5099 At this writing, September 2009, there are no Tcl utility
5100 procedures to help set up any common tracing scenarios.
5101
5102 @deffn Command {etm analyze}
5103 Reads trace data into memory, if it wasn't already present.
5104 Decodes and prints the data that was collected.
5105 @end deffn
5106
5107 @deffn Command {etm dump} filename
5108 Stores the captured trace data in @file{filename}.
5109 @end deffn
5110
5111 @deffn Command {etm image} filename [base_address] [type]
5112 Opens an image file.
5113 @end deffn
5114
5115 @deffn Command {etm load} filename
5116 Loads captured trace data from @file{filename}.
5117 @end deffn