forked from hikob/openocd
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathopenocd.texi
8250 lines (6919 loc) · 306 KB
/
openocd.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename openocd.info
@settitle OpenOCD User's Guide
@dircategory Development
@direntry
* OpenOCD: (openocd). OpenOCD User's Guide
@end direntry
@paragraphindent 0
@c %**end of header
@include version.texi
@copying
This User's Guide documents
release @value{VERSION},
dated @value{UPDATED},
of the Open On-Chip Debugger (OpenOCD).
@itemize @bullet
@item Copyright @copyright{} 2008 The OpenOCD Project
@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
@item Copyright @copyright{} 2008-2010 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
@item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com}
@item Copyright @copyright{} 2009-2010 David Brownell
@end itemize
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end quotation
@end copying
@titlepage
@titlefont{@emph{Open On-Chip Debugger:}}
@sp 1
@title OpenOCD User's Guide
@subtitle for release @value{VERSION}
@subtitle @value{UPDATED}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@summarycontents
@contents
@ifnottex
@node Top
@top OpenOCD User's Guide
@insertcopying
@end ifnottex
@menu
* About:: About OpenOCD
* Developers:: OpenOCD Developer Resources
* Debug Adapter Hardware:: Debug Adapter Hardware
* About Jim-Tcl:: About Jim-Tcl
* Running:: Running OpenOCD
* OpenOCD Project Setup:: OpenOCD Project Setup
* Config File Guidelines:: Config File Guidelines
* Daemon Configuration:: Daemon Configuration
* Debug Adapter Configuration:: Debug Adapter Configuration
* Reset Configuration:: Reset Configuration
* TAP Declaration:: TAP Declaration
* CPU Configuration:: CPU Configuration
* Flash Commands:: Flash Commands
* NAND Flash Commands:: NAND Flash Commands
* PLD/FPGA Commands:: PLD/FPGA Commands
* General Commands:: General Commands
* Architecture and Core Commands:: Architecture and Core Commands
* JTAG Commands:: JTAG Commands
* Boundary Scan Commands:: Boundary Scan Commands
* TFTP:: TFTP
* GDB and OpenOCD:: Using GDB and OpenOCD
* Tcl Scripting API:: Tcl Scripting API
* FAQ:: Frequently Asked Questions
* Tcl Crash Course:: Tcl Crash Course
* License:: GNU Free Documentation License
@comment DO NOT use the plain word ``Index'', reason: CYGWIN filename
@comment case issue with ``Index.html'' and ``index.html''
@comment Occurs when creating ``--html --no-split'' output
@comment This fix is based on: http://sourceware.org/ml/binutils/2006-05/msg00215.html
* OpenOCD Concept Index:: Concept Index
* Command and Driver Index:: Command and Driver Index
@end menu
@node About
@unnumbered About
@cindex about
OpenOCD was created by Dominic Rath as part of a diploma thesis written at the
University of Applied Sciences Augsburg (@uref{http://www.fh-augsburg.de}).
Since that time, the project has grown into an active open-source project,
supported by a diverse community of software and hardware developers from
around the world.
@section What is OpenOCD?
@cindex TAP
@cindex JTAG
The Open On-Chip Debugger (OpenOCD) aims to provide debugging,
in-system programming and boundary-scan testing for embedded target
devices.
It does so with the assistance of a @dfn{debug adapter}, which is
a small hardware module which helps provide the right kind of
electrical signaling to the target being debugged. These are
required since the debug host (on which OpenOCD runs) won't
usually have native support for such signaling, or the connector
needed to hook up to the target.
Such debug adapters support one or more @dfn{transport} protocols,
each of which involves different electrical signaling (and uses
different messaging protocols on top of that signaling). There
are many types of debug adapter, and little uniformity in what
they are called. (There are also product naming differences.)
These adapters are sometimes packaged as discrete dongles, which
may generically be called @dfn{hardware interface dongles}.
Some development boards also integrate them directly, which may
let the development board can be directly connected to the debug
host over USB (and sometimes also to power it over USB).
For example, a @dfn{JTAG Adapter} supports JTAG
signaling, and is used to communicate
with JTAG (IEEE 1149.1) compliant TAPs on your target board.
A @dfn{TAP} is a ``Test Access Port'', a module which processes
special instructions and data. TAPs are daisy-chained within and
between chips and boards. JTAG supports debugging and boundary
scan operations.
There are also @dfn{SWD Adapters} that support Serial Wire Debug (SWD)
signaling to communicate with some newer ARM cores, as well as debug
adapters which support both JTAG and SWD transports. SWD only supports
debugging, whereas JTAG also supports boundary scan operations.
For some chips, there are also @dfn{Programming Adapters} supporting
special transports used only to write code to flash memory, without
support for on-chip debugging or boundary scan.
(At this writing, OpenOCD does not support such non-debug adapters.)
@b{Dongles:} OpenOCD currently supports many types of hardware dongles: USB
based, parallel port based, and other standalone boxes that run
OpenOCD internally. @xref{Debug Adapter Hardware}.
@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and
Cortex-M3 (Stellaris LM3 and ST STM32) based cores to be
debugged via the GDB protocol.
@b{Flash Programing:} Flash writing is supported for external CFI
compatible NOR flashes (Intel and AMD/Spansion command set) and several
internal flashes (LPC1700, LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and
STM32x). Preliminary support for various NAND flash controllers
(LPC3180, Orion, S3C24xx, more) controller is included.
@section OpenOCD Web Site
The OpenOCD web site provides the latest public news from the community:
@uref{http://openocd.sourceforge.net/}
@section Latest User's Guide:
The user's guide you are now reading may not be the latest one
available. A version for more recent code may be available.
Its HTML form is published irregularly at:
@uref{http://openocd.sourceforge.net/doc/html/index.html}
PDF form is likewise published at:
@uref{http://openocd.sourceforge.net/doc/pdf/openocd.pdf}
@section OpenOCD User's Forum
There is an OpenOCD forum (phpBB) hosted by SparkFun,
which might be helpful to you. Note that if you want
anything to come to the attention of developers, you
should post it to the OpenOCD Developer Mailing List
instead of this forum.
@uref{http://forum.sparkfun.com/viewforum.php?f=18}
@node Developers
@chapter OpenOCD Developer Resources
@cindex developers
If you are interested in improving the state of OpenOCD's debugging and
testing support, new contributions will be welcome. Motivated developers
can produce new target, flash or interface drivers, improve the
documentation, as well as more conventional bug fixes and enhancements.
The resources in this chapter are available for developers wishing to explore
or expand the OpenOCD source code.
@section OpenOCD GIT Repository
During the 0.3.x release cycle, OpenOCD switched from Subversion to
a GIT repository hosted at SourceForge. The repository URL is:
@uref{git://openocd.git.sourceforge.net/gitroot/openocd/openocd}
You may prefer to use a mirror and the HTTP protocol:
@uref{http://repo.or.cz/r/openocd.git}
With standard GIT tools, use @command{git clone} to initialize
a local repository, and @command{git pull} to update it.
There are also gitweb pages letting you browse the repository
with a web browser, or download arbitrary snapshots without
needing a GIT client:
@uref{http://openocd.git.sourceforge.net/git/gitweb.cgi?p=openocd/openocd}
@uref{http://repo.or.cz/w/openocd.git}
The @file{README} file contains the instructions for building the project
from the repository or a snapshot.
Developers that want to contribute patches to the OpenOCD system are
@b{strongly} encouraged to work against mainline.
Patches created against older versions may require additional
work from their submitter in order to be updated for newer releases.
@section Doxygen Developer Manual
During the 0.2.x release cycle, the OpenOCD project began
providing a Doxygen reference manual. This document contains more
technical information about the software internals, development
processes, and similar documentation:
@uref{http://openocd.sourceforge.net/doc/doxygen/html/index.html}
This document is a work-in-progress, but contributions would be welcome
to fill in the gaps. All of the source files are provided in-tree,
listed in the Doxyfile configuration in the top of the source tree.
@section OpenOCD Developer Mailing List
The OpenOCD Developer Mailing List provides the primary means of
communication between developers:
@uref{https://lists.sourceforge.net/mailman/listinfo/openocd-devel}
Discuss and submit patches to this list.
The @file{PATCHES.txt} file contains basic information about how
to prepare patches.
@section OpenOCD Bug Database
During the 0.4.x release cycle the OpenOCD project team began
using Trac for its bug database:
@uref{https://sourceforge.net/apps/trac/openocd}
@node Debug Adapter Hardware
@chapter Debug Adapter Hardware
@cindex dongles
@cindex FTDI
@cindex wiggler
@cindex zy1000
@cindex printer port
@cindex USB Adapter
@cindex RTCK
Defined: @b{dongle}: A small device that plugins into a computer and serves as
an adapter .... [snip]
In the OpenOCD case, this generally refers to @b{a small adapter} that
attaches to your computer via USB or the Parallel Printer Port. One
exception is the Zylin ZY1000, packaged as a small box you attach via
an ethernet cable. The Zylin ZY1000 has the advantage that it does not
require any drivers to be installed on the developer PC. It also has
a built in web interface. It supports RTCK/RCLK or adaptive clocking
and has a built in relay to power cycle targets remotely.
@section Choosing a Dongle
There are several things you should keep in mind when choosing a dongle.
@enumerate
@item @b{Transport} Does it support the kind of communication that you need?
OpenOCD focusses mostly on JTAG. Your version may also support
other ways to communicate with target devices.
@item @b{Voltage} What voltage is your target - 1.8, 2.8, 3.3, or 5V?
Does your dongle support it? You might need a level converter.
@item @b{Pinout} What pinout does your target board use?
Does your dongle support it? You may be able to use jumper
wires, or an "octopus" connector, to convert pinouts.
@item @b{Connection} Does your computer have the USB, printer, or
Ethernet port needed?
@item @b{RTCK} Do you expect to use it with ARM chips and boards with
RTCK support? Also known as ``adaptive clocking''
@end enumerate
@section Stand alone Systems
@b{ZY1000} See: @url{http://www.zylin.com/zy1000.html} Technically, not a
dongle, but a standalone box. The ZY1000 has the advantage that it does
not require any drivers installed on the developer PC. It also has
a built in web interface. It supports RTCK/RCLK or adaptive clocking
and has a built in relay to power cycle targets remotely.
@section USB FT2232 Based
There are many USB JTAG dongles on the market, many of them are based
on a chip from ``Future Technology Devices International'' (FTDI)
known as the FTDI FT2232; this is a USB full speed (12 Mbps) chip.
See: @url{http://www.ftdichip.com} for more information.
In summer 2009, USB high speed (480 Mbps) versions of these FTDI
chips are starting to become available in JTAG adapters. (Adapters
using those high speed FT2232H chips may support adaptive clocking.)
The FT2232 chips are flexible enough to support some other
transport options, such as SWD or the SPI variants used to
program some chips. They have two communications channels,
and one can be used for a UART adapter at the same time the
other one is used to provide a debug adapter.
Also, some development boards integrate an FT2232 chip to serve as
a built-in low cost debug adapter and usb-to-serial solution.
@itemize @bullet
@item @b{usbjtag}
@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
@item @b{jtagkey}
@* See: @url{http://www.amontec.com/jtagkey.shtml}
@item @b{jtagkey2}
@* See: @url{http://www.amontec.com/jtagkey2.shtml}
@item @b{oocdlink}
@* See: @url{http://www.oocdlink.com} By Joern Kaipf
@item @b{signalyzer}
@* See: @url{http://www.signalyzer.com}
@item @b{Stellaris Eval Boards}
@* See: @url{http://www.luminarymicro.com} - The Stellaris eval boards
bundle FT2232-based JTAG and SWD support, which can be used to debug
the Stellaris chips. Using separate JTAG adapters is optional.
These boards can also be used in a "pass through" mode as JTAG adapters
to other target boards, disabling the Stellaris chip.
@item @b{Luminary ICDI}
@* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug
Interface (ICDI) Boards are included in Stellaris LM3S9B9x
Evaluation Kits. Like the non-detachable FT2232 support on the other
Stellaris eval boards, they can be used to debug other target boards.
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
@item @b{flyswatter}
@* See: @url{http://www.tincantools.com}
@item @b{turtelizer2}
@* See:
@uref{http://www.ethernut.de/en/hardware/turtelizer/index.html, Turtelizer 2}, or
@url{http://www.ethernut.de}
@item @b{comstick}
@* Link: @url{http://www.hitex.com/index.php?id=383}
@item @b{stm32stick}
@* Link @url{http://www.hitex.com/stm32-stick}
@item @b{axm0432_jtag}
@* Axiom AXM-0432 Link @url{http://www.axman.com}
@item @b{cortino}
@* Link @url{http://www.hitex.com/index.php?id=cortino}
@item @b{dlp-usb1232h}
@* Link @url{http://www.dlpdesign.com/usb/usb1232h.shtml}
@end itemize
@section USB-JTAG / Altera USB-Blaster compatibles
These devices also show up as FTDI devices, but are not
protocol-compatible with the FT2232 devices. They are, however,
protocol-compatible among themselves. USB-JTAG devices typically consist
of a FT245 followed by a CPLD that understands a particular protocol,
or emulate this protocol using some other hardware.
They may appear under different USB VID/PID depending on the particular
product. The driver can be configured to search for any VID/PID pair
(see the section on driver commands).
@itemize
@item @b{USB-JTAG} Kolja Waschk's USB Blaster-compatible adapter
@* Link: @url{http://www.ixo.de/info/usb_jtag/}
@item @b{Altera USB-Blaster}
@* Link: @url{http://www.altera.com/literature/ug/ug_usb_blstr.pdf}
@end itemize
@section USB JLINK based
There are several OEM versions of the Segger @b{JLINK} adapter. It is
an example of a micro controller based JTAG adapter, it uses an
AT91SAM764 internally.
@itemize @bullet
@item @b{ATMEL SAMICE} Only works with ATMEL chips!
@* Link: @url{http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3892}
@item @b{SEGGER JLINK}
@* Link: @url{http://www.segger.com/jlink.html}
@item @b{IAR J-Link}
@* Link: @url{http://www.iar.com/website1/1.0.1.0/369/1/index.php}
@end itemize
@section USB RLINK based
Raisonance has an adapter called @b{RLink}. It exists in a stripped-down form on the STM32 Primer, permanently attached to the JTAG lines. It also exists on the STM32 Primer2, but that is wired for SWD and not JTAG, thus not supported.
@itemize @bullet
@item @b{Raisonance RLink}
@* Link: @url{http://www.raisonance.com/products/RLink.php}
@item @b{STM32 Primer}
@* Link: @url{http://www.stm32circle.com/resources/stm32primer.php}
@item @b{STM32 Primer2}
@* Link: @url{http://www.stm32circle.com/resources/stm32primer2.php}
@end itemize
@section USB ST-LINK based
ST Micro has an adapter called @b{ST-LINK}.
They only works with ST Micro chips, notably STM32 and STM8.
@itemize @bullet
@item @b{ST-LINK}
@* This is available standalone and as part of some kits, eg. STM32VLDISCOVERY.
@* Link: @url{http://www.st.com/internet/evalboard/product/219866.jsp}
@item @b{ST-LINK/V2}
@* This is available standalone and as part of some kits, eg. STM32F4DISCOVERY.
@* Link: @url{http://www.st.com/internet/evalboard/product/251168.jsp}
@end itemize
@section USB Other
@itemize @bullet
@item @b{USBprog}
@* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604
@item @b{USB - Presto}
@* Link: @url{http://tools.asix.net/prg_presto.htm}
@item @b{Versaloon-Link}
@* Link: @url{http://www.simonqian.com/en/Versaloon}
@item @b{ARM-JTAG-EW}
@* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html}
@item @b{Buspirate}
@* Link: @url{http://dangerousprototypes.com/bus-pirate-manual/}
@end itemize
@section IBM PC Parallel Printer Port Based
The two well known ``JTAG Parallel Ports'' cables are the Xilnx DLC5
and the MacGraigor Wiggler. There are many clones and variations of
these on the market.
Note that parallel ports are becoming much less common, so if you
have the choice you should probably avoid these adapters in favor
of USB-based ones.
@itemize @bullet
@item @b{Wiggler} - There are many clones of this.
@* Link: @url{http://www.macraigor.com/wiggler.htm}
@item @b{DLC5} - From XILINX - There are many clones of this
@* Link: Search the web for: ``XILINX DLC5'' - it is no longer
produced, PDF schematics are easily found and it is easy to make.
@item @b{Amontec - JTAG Accelerator}
@* Link: @url{http://www.amontec.com/jtag_accelerator.shtml}
@item @b{GW16402}
@* Link: @url{http://www.gateworks.com/products/avila_accessories/gw16042.php}
@item @b{Wiggler2}
@*@uref{http://www.ccac.rwth-aachen.de/@/~michaels/@/index.php/hardware/@/armjtag,
Improved parallel-port wiggler-style JTAG adapter}
@item @b{Wiggler_ntrst_inverted}
@* Yet another variation - See the source code, src/jtag/parport.c
@item @b{old_amt_wiggler}
@* Unknown - probably not on the market today
@item @b{arm-jtag}
@* Link: Most likely @url{http://www.olimex.com/dev/arm-jtag.html} [another wiggler clone]
@item @b{chameleon}
@* Link: @url{http://www.amontec.com/chameleon.shtml}
@item @b{Triton}
@* Unknown.
@item @b{Lattice}
@* ispDownload from Lattice Semiconductor
@url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf}
@item @b{flashlink}
@* From ST Microsystems;
@uref{http://www.st.com/stonline/@/products/literature/um/7889.pdf,
FlashLINK JTAG programing cable for PSD and uPSD}
@end itemize
@section Other...
@itemize @bullet
@item @b{ep93xx}
@* An EP93xx based Linux machine using the GPIO pins directly.
@item @b{at91rm9200}
@* Like the EP93xx - but an ATMEL AT91RM9200 based solution using the GPIO pins on the chip.
@end itemize
@node About Jim-Tcl
@chapter About Jim-Tcl
@cindex Jim-Tcl
@cindex tcl
OpenOCD uses a small ``Tcl Interpreter'' known as Jim-Tcl.
This programming language provides a simple and extensible
command interpreter.
All commands presented in this Guide are extensions to Jim-Tcl.
You can use them as simple commands, without needing to learn
much of anything about Tcl.
Alternatively, can write Tcl programs with them.
You can learn more about Jim at its website, @url{http://jim.berlios.de}.
There is an active and responsive community, get on the mailing list
if you have any questions. Jim-Tcl maintainers also lurk on the
OpenOCD mailing list.
@itemize @bullet
@item @b{Jim vs. Tcl}
@* Jim-Tcl is a stripped down version of the well known Tcl language,
which can be found here: @url{http://www.tcl.tk}. Jim-Tcl has far
fewer features. Jim-Tcl is several dozens of .C files and .H files and
implements the basic Tcl command set. In contrast: Tcl 8.6 is a
4.2 MB .zip file containing 1540 files.
@item @b{Missing Features}
@* Our practice has been: Add/clone the real Tcl feature if/when
needed. We welcome Jim-Tcl improvements, not bloat. Also there
are a large number of optional Jim-Tcl features that are not
enabled in OpenOCD.
@item @b{Scripts}
@* OpenOCD configuration scripts are Jim-Tcl Scripts. OpenOCD's
command interpreter today is a mixture of (newer)
Jim-Tcl commands, and (older) the orginal command interpreter.
@item @b{Commands}
@* At the OpenOCD telnet command line (or via the GDB monitor command) one
can type a Tcl for() loop, set variables, etc.
Some of the commands documented in this guide are implemented
as Tcl scripts, from a @file{startup.tcl} file internal to the server.
@item @b{Historical Note}
@* Jim-Tcl was introduced to OpenOCD in spring 2008. Fall 2010,
before OpenOCD 0.5 release OpenOCD switched to using Jim Tcl
as a git submodule, which greatly simplified upgrading Jim Tcl
to benefit from new features and bugfixes in Jim Tcl.
@item @b{Need a crash course in Tcl?}
@*@xref{Tcl Crash Course}.
@end itemize
@node Running
@chapter Running
@cindex command line options
@cindex logfile
@cindex directory search
Properly installing OpenOCD sets up your operating system to grant it access
to the debug adapters. On Linux, this usually involves installing a file
in @file{/etc/udev/rules.d,} so OpenOCD has permissions. MS-Windows needs
complex and confusing driver configuration for every peripheral. Such issues
are unique to each operating system, and are not detailed in this User's Guide.
Then later you will invoke the OpenOCD server, with various options to
tell it how each debug session should work.
The @option{--help} option shows:
@verbatim
bash$ openocd --help
--help | -h display this help
--version | -v display OpenOCD version
--file | -f use configuration file <name>
--search | -s dir to search for config files and scripts
--debug | -d set debug level <0-3>
--log_output | -l redirect log output to file <name>
--command | -c run <command>
@end verbatim
If you don't give any @option{-f} or @option{-c} options,
OpenOCD tries to read the configuration file @file{openocd.cfg}.
To specify one or more different
configuration files, use @option{-f} options. For example:
@example
openocd -f config1.cfg -f config2.cfg -f config3.cfg
@end example
Configuration files and scripts are searched for in
@enumerate
@item the current directory,
@item any search dir specified on the command line using the @option{-s} option,
@item any search dir specified using the @command{add_script_search_dir} command,
@item @file{$HOME/.openocd} (not on Windows),
@item the site wide script library @file{$pkgdatadir/site} and
@item the OpenOCD-supplied script library @file{$pkgdatadir/scripts}.
@end enumerate
The first found file with a matching file name will be used.
@quotation Note
Don't try to use configuration script names or paths which
include the "#" character. That character begins Tcl comments.
@end quotation
@section Simple setup, no customization
In the best case, you can use two scripts from one of the script
libraries, hook up your JTAG adapter, and start the server ... and
your JTAG setup will just work "out of the box". Always try to
start by reusing those scripts, but assume you'll need more
customization even if this works. @xref{OpenOCD Project Setup}.
If you find a script for your JTAG adapter, and for your board or
target, you may be able to hook up your JTAG adapter then start
the server like:
@example
openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg
@end example
You might also need to configure which reset signals are present,
using @option{-c 'reset_config trst_and_srst'} or something similar.
If all goes well you'll see output something like
@example
Open On-Chip Debugger 0.4.0 (2010-01-14-15:06)
For bug reports, read
http://openocd.sourceforge.net/doc/doxygen/bugs.html
Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477
(mfg: 0x23b, part: 0xba00, ver: 0x3)
@end example
Seeing that "tap/device found" message, and no warnings, means
the JTAG communication is working. That's a key milestone, but
you'll probably need more project-specific setup.
@section What OpenOCD does as it starts
OpenOCD starts by processing the configuration commands provided
on the command line or, if there were no @option{-c command} or
@option{-f file.cfg} options given, in @file{openocd.cfg}.
@xref{Configuration Stage}.
At the end of the configuration stage it verifies the JTAG scan
chain defined using those commands; your configuration should
ensure that this always succeeds.
Normally, OpenOCD then starts running as a daemon.
Alternatively, commands may be used to terminate the configuration
stage early, perform work (such as updating some flash memory),
and then shut down without acting as a daemon.
Once OpenOCD starts running as a daemon, it waits for connections from
clients (Telnet, GDB, Other) and processes the commands issued through
those channels.
If you are having problems, you can enable internal debug messages via
the @option{-d} option.
Also it is possible to interleave Jim-Tcl commands w/config scripts using the
@option{-c} command line switch.
To enable debug output (when reporting problems or working on OpenOCD
itself), use the @option{-d} command line switch. This sets the
@option{debug_level} to "3", outputting the most information,
including debug messages. The default setting is "2", outputting only
informational messages, warnings and errors. You can also change this
setting from within a telnet or gdb session using @command{debug_level
<n>} (@pxref{debug_level}).
You can redirect all output from the daemon to a file using the
@option{-l <logfile>} switch.
Note! OpenOCD will launch the GDB & telnet server even if it can not
establish a connection with the target. In general, it is possible for
the JTAG controller to be unresponsive until the target is set up
correctly via e.g. GDB monitor commands in a GDB init script.
@node OpenOCD Project Setup
@chapter OpenOCD Project Setup
To use OpenOCD with your development projects, you need to do more than
just connecting the JTAG adapter hardware (dongle) to your development board
and then starting the OpenOCD server.
You also need to configure that server so that it knows
about that adapter and board, and helps your work.
You may also want to connect OpenOCD to GDB, possibly
using Eclipse or some other GUI.
@section Hooking up the JTAG Adapter
Today's most common case is a dongle with a JTAG cable on one side
(such as a ribbon cable with a 10-pin or 20-pin IDC connector)
and a USB cable on the other.
Instead of USB, some cables use Ethernet;
older ones may use a PC parallel port, or even a serial port.
@enumerate
@item @emph{Start with power to your target board turned off},
and nothing connected to your JTAG adapter.
If you're particularly paranoid, unplug power to the board.
It's important to have the ground signal properly set up,
unless you are using a JTAG adapter which provides
galvanic isolation between the target board and the
debugging host.
@item @emph{Be sure it's the right kind of JTAG connector.}
If your dongle has a 20-pin ARM connector, you need some kind
of adapter (or octopus, see below) to hook it up to
boards using 14-pin or 10-pin connectors ... or to 20-pin
connectors which don't use ARM's pinout.
In the same vein, make sure the voltage levels are compatible.
Not all JTAG adapters have the level shifters needed to work
with 1.2 Volt boards.
@item @emph{Be certain the cable is properly oriented} or you might
damage your board. In most cases there are only two possible
ways to connect the cable.
Connect the JTAG cable from your adapter to the board.
Be sure it's firmly connected.
In the best case, the connector is keyed to physically
prevent you from inserting it wrong.
This is most often done using a slot on the board's male connector
housing, which must match a key on the JTAG cable's female connector.
If there's no housing, then you must look carefully and
make sure pin 1 on the cable hooks up to pin 1 on the board.
Ribbon cables are frequently all grey except for a wire on one
edge, which is red. The red wire is pin 1.
Sometimes dongles provide cables where one end is an ``octopus'' of
color coded single-wire connectors, instead of a connector block.
These are great when converting from one JTAG pinout to another,
but are tedious to set up.
Use these with connector pinout diagrams to help you match up the
adapter signals to the right board pins.
@item @emph{Connect the adapter's other end} once the JTAG cable is connected.
A USB, parallel, or serial port connector will go to the host which
you are using to run OpenOCD.
For Ethernet, consult the documentation and your network administrator.
For USB based JTAG adapters you have an easy sanity check at this point:
does the host operating system see the JTAG adapter? If that host is an
MS-Windows host, you'll need to install a driver before OpenOCD works.
@item @emph{Connect the adapter's power supply, if needed.}
This step is primarily for non-USB adapters,
but sometimes USB adapters need extra power.
@item @emph{Power up the target board.}
Unless you just let the magic smoke escape,
you're now ready to set up the OpenOCD server
so you can use JTAG to work with that board.
@end enumerate
Talk with the OpenOCD server using
telnet (@code{telnet localhost 4444} on many systems) or GDB.
@xref{GDB and OpenOCD}.
@section Project Directory
There are many ways you can configure OpenOCD and start it up.
A simple way to organize them all involves keeping a
single directory for your work with a given board.
When you start OpenOCD from that directory,
it searches there first for configuration files, scripts,
files accessed through semihosting,
and for code you upload to the target board.
It is also the natural place to write files,
such as log files and data you download from the board.
@section Configuration Basics
There are two basic ways of configuring OpenOCD, and
a variety of ways you can mix them.
Think of the difference as just being how you start the server:
@itemize
@item Many @option{-f file} or @option{-c command} options on the command line
@item No options, but a @dfn{user config file}
in the current directory named @file{openocd.cfg}
@end itemize
Here is an example @file{openocd.cfg} file for a setup
using a Signalyzer FT2232-based JTAG adapter to talk to
a board with an Atmel AT91SAM7X256 microcontroller:
@example
source [find interface/signalyzer.cfg]
# GDB can also flash my flash!
gdb_memory_map enable
gdb_flash_program enable
source [find target/sam7x256.cfg]
@end example
Here is the command line equivalent of that configuration:
@example
openocd -f interface/signalyzer.cfg \
-c "gdb_memory_map enable" \
-c "gdb_flash_program enable" \
-f target/sam7x256.cfg
@end example
You could wrap such long command lines in shell scripts,
each supporting a different development task.
One might re-flash the board with a specific firmware version.
Another might set up a particular debugging or run-time environment.
@quotation Important
At this writing (October 2009) the command line method has
problems with how it treats variables.
For example, after @option{-c "set VAR value"}, or doing the
same in a script, the variable @var{VAR} will have no value
that can be tested in a later script.
@end quotation
Here we will focus on the simpler solution: one user config
file, including basic configuration plus any TCL procedures
to simplify your work.
@section User Config Files
@cindex config file, user
@cindex user config file
@cindex config file, overview
A user configuration file ties together all the parts of a project
in one place.
One of the following will match your situation best:
@itemize
@item Ideally almost everything comes from configuration files
provided by someone else.
For example, OpenOCD distributes a @file{scripts} directory
(probably in @file{/usr/share/openocd/scripts} on Linux).
Board and tool vendors can provide these too, as can individual
user sites; the @option{-s} command line option lets you say
where to find these files. (@xref{Running}.)
The AT91SAM7X256 example above works this way.
Three main types of non-user configuration file each have their
own subdirectory in the @file{scripts} directory:
@enumerate
@item @b{interface} -- one for each different debug adapter;
@item @b{board} -- one for each different board
@item @b{target} -- the chips which integrate CPUs and other JTAG TAPs
@end enumerate
Best case: include just two files, and they handle everything else.
The first is an interface config file.
The second is board-specific, and it sets up the JTAG TAPs and
their GDB targets (by deferring to some @file{target.cfg} file),
declares all flash memory, and leaves you nothing to do except
meet your deadline:
@example
source [find interface/olimex-jtag-tiny.cfg]
source [find board/csb337.cfg]
@end example
Boards with a single microcontroller often won't need more
than the target config file, as in the AT91SAM7X256 example.
That's because there is no external memory (flash, DDR RAM), and
the board differences are encapsulated by application code.
@item Maybe you don't know yet what your board looks like to JTAG.
Once you know the @file{interface.cfg} file to use, you may
need help from OpenOCD to discover what's on the board.
Once you find the JTAG TAPs, you can just search for appropriate
target and board
configuration files ... or write your own, from the bottom up.
@xref{Autoprobing}.
@item You can often reuse some standard config files but
need to write a few new ones, probably a @file{board.cfg} file.
You will be using commands described later in this User's Guide,
and working with the guidelines in the next chapter.
For example, there may be configuration files for your JTAG adapter
and target chip, but you need a new board-specific config file
giving access to your particular flash chips.
Or you might need to write another target chip configuration file
for a new chip built around the Cortex M3 core.
@quotation Note
When you write new configuration files, please submit
them for inclusion in the next OpenOCD release.
For example, a @file{board/newboard.cfg} file will help the
next users of that board, and a @file{target/newcpu.cfg}
will help support users of any board using that chip.
@end quotation
@item
You may may need to write some C code.
It may be as simple as a supporting a new ft2232 or parport
based adapter; a bit more involved, like a NAND or NOR flash
controller driver; or a big piece of work like supporting
a new chip architecture.
@end itemize
Reuse the existing config files when you can.
Look first in the @file{scripts/boards} area, then @file{scripts/targets}.
You may find a board configuration that's a good example to follow.
When you write config files, separate the reusable parts
(things every user of that interface, chip, or board needs)
from ones specific to your environment and debugging approach.
@itemize
@item
For example, a @code{gdb-attach} event handler that invokes
the @command{reset init} command will interfere with debugging
early boot code, which performs some of the same actions
that the @code{reset-init} event handler does.
@item
Likewise, the @command{arm9 vector_catch} command (or
@cindex vector_catch
its siblings @command{xscale vector_catch}
and @command{cortex_m3 vector_catch}) can be a timesaver
during some debug sessions, but don't make everyone use that either.
Keep those kinds of debugging aids in your user config file,
along with messaging and tracing setup.
(@xref{Software Debug Messages and Tracing}.)
@item
You might need to override some defaults.
For example, you might need to move, shrink, or back up the target's
work area if your application needs much SRAM.
@item
TCP/IP port configuration is another example of something which
is environment-specific, and should only appear in
a user config file. @xref{TCP/IP Ports}.
@end itemize
@section Project-Specific Utilities
A few project-specific utility
routines may well speed up your work.
Write them, and keep them in your project's user config file.
For example, if you are making a boot loader work on a
board, it's nice to be able to debug the ``after it's
loaded to RAM'' parts separately from the finicky early
code which sets up the DDR RAM controller and clocks.
A script like this one, or a more GDB-aware sibling,
may help:
@example
proc ramboot @{ @} @{
# Reset, running the target's "reset-init" scripts
# to initialize clocks and the DDR RAM controller.
# Leave the CPU halted.
reset init
# Load CONFIG_SKIP_LOWLEVEL_INIT version into DDR RAM.
load_image u-boot.bin 0x20000000
# Start running.
resume 0x20000000
@}
@end example
Then once that code is working you will need to make it
boot from NOR flash; a different utility would help.
Alternatively, some developers write to flash using GDB.
(You might use a similar script if you're working with a flash
based microcontroller application instead of a boot loader.)
@example
proc newboot @{ @} @{
# Reset, leaving the CPU halted. The "reset-init" event