forked from openocd-org/openocd
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathopenocd.texi
4468 lines (3750 loc) · 161 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 Open On-Chip Debugger (OpenOCD)
@dircategory Development
@direntry
@paragraphindent 0
* OpenOCD: (openocd). Open On-Chip Debugger.
@end direntry
@c %**end of header
@include version.texi
@copying
@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 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
@item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com}
@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
@title Open On-Chip Debugger (OpenOCD)
@subtitle Edition @value{EDITION} for OpenOCD version @value{VERSION}
@subtitle @value{UPDATED}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@summarycontents
@contents
@node Top, About, , (dir)
@top OpenOCD
This manual documents edition @value{EDITION} of the Open On-Chip Debugger
(OpenOCD) version @value{VERSION}, @value{UPDATED}.
@insertcopying
@menu
* About:: About OpenOCD
* Developers:: OpenOCD Developers
* Building OpenOCD:: Building OpenOCD From SVN
* JTAG Hardware Dongles:: JTAG Hardware Dongles
* Running:: Running OpenOCD
* Simple Configuration Files:: Simple Configuration Files
* Config File Guidelines:: Config File Guidelines
* About JIM-Tcl:: About JIM-Tcl
* Daemon Configuration:: Daemon Configuration
* Interface - Dongle Configuration:: Interface - Dongle Configuration
* Reset Configuration:: Reset Configuration
* Tap Creation:: Tap Creation
* Target Configuration:: Target Configuration
* Flash Configuration:: Flash Configuration
* NAND Flash Commands:: NAND Flash Commands
* General Commands:: General Commands
* JTAG Commands:: JTAG Commands
* Sample Scripts:: Sample Target Scripts
* TFTP:: TFTP
* GDB and OpenOCD:: Using GDB and OpenOCD
* Tcl Scripting API:: Tcl Scripting API
* Upgrading:: Deprecated/Removed Commands
* Target Library:: Target Library
* 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
* OpenOCD Command Index:: Command 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?
The Open On-Chip Debugger (OpenOCD) aims to provide debugging,
in-system programming and boundary-scan testing for embedded target
devices.
@b{JTAG:} OpenOCD uses a ``hardware interface dongle'' to communicate
with the JTAG (IEEE 1149.1) compliant taps on your target board.
@b{Dongles:} OpenOCD currently supports many types of hardware dongles: USB
based, parallel port based, and other standalone boxes that run
OpenOCD internally. @xref{JTAG Hardware Dongles}.
@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and
Cortex-M3 (Luminary 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 (LPC2000, AT91SAM7, 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.berlios.de/web/}
@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 Subversion Repository
The ``Building From Source'' section provides instructions to retrieve
and and build the latest version of the OpenOCD source code.
@xref{Building OpenOCD}.
Developers that want to contribute patches to the OpenOCD system are
@b{strongly} encouraged to base their work off of the most recent trunk
revision. 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 development of the 0.2.0 release, 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.berlios.de/doc/doxygen/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 repository trunk.
@section OpenOCD Developer Mailing List
The OpenOCD Developer Mailing List provides the primary means of
communication between developers:
@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
All drivers developers are enouraged to also subscribe to the list of
SVN commits to keep pace with the ongoing changes:
@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
@node Building OpenOCD
@chapter Building OpenOCD
@cindex building
@section Pre-Built Tools
If you are interested in getting actual work done rather than building
OpenOCD, then check if your interface supplier provides binaries for
you. Chances are that that binary is from some SVN version that is more
stable than SVN trunk where bleeding edge development takes place.
@section Packagers Please Read!
You are a @b{PACKAGER} of OpenOCD if you
@enumerate
@item @b{Sell dongles} and include pre-built binaries
@item @b{Supply tools} i.e.: A complete development solution
@item @b{Supply IDEs} like Eclipse, or RHIDE, etc.
@item @b{Build packages} i.e.: RPM files, or DEB files for a Linux Distro
@end enumerate
As a @b{PACKAGER}, you will experience first reports of most issues.
When you fix those problems for your users, your solution may help
prevent hundreds (if not thousands) of other questions from other users.
If something does not work for you, please work to inform the OpenOCD
developers know how to improve the system or documentation to avoid
future problems, and follow-up to help us ensure the issue will be fully
resolved in our future releases.
That said, the OpenOCD developers would also like you to follow a few
suggestions:
@enumerate
@item @b{Always build with printer ports enabled.}
@item @b{Try to use LIBFTDI + LIBUSB where possible. You cover more bases.}
@end enumerate
@itemize @bullet
@item @b{Why YES to LIBFTDI + LIBUSB?}
@itemize @bullet
@item @b{LESS} work - libusb perhaps already there
@item @b{LESS} work - identical code, multiple platforms
@item @b{MORE} dongles are supported
@item @b{MORE} platforms are supported
@item @b{MORE} complete solution
@end itemize
@item @b{Why not LIBFTDI + LIBUSB} (i.e.: ftd2xx instead)?
@itemize @bullet
@item @b{LESS} speed - some say it is slower
@item @b{LESS} complex to distribute (external dependencies)
@end itemize
@end itemize
@section Building From Source
You can download the current SVN version with an SVN client of your choice from the
following repositories:
@uref{svn://svn.berlios.de/openocd/trunk}
or
@uref{http://svn.berlios.de/svnroot/repos/openocd/trunk}
Using the SVN command line client, you can use the following command to fetch the
latest version (make sure there is no (non-svn) directory called "openocd" in the
current directory):
@example
svn checkout svn://svn.berlios.de/openocd/trunk openocd
@end example
Building OpenOCD requires a recent version of the GNU autotools (autoconf >= 2.59 and automake >= 1.9).
For building on Windows,
you have to use Cygwin. Make sure that your @env{PATH} environment variable contains no
other locations with Unix utils (like UnxUtils) - these can't handle the Cygwin
paths, resulting in obscure dependency errors (This is an observation I've gathered
from the logs of one user - correct me if I'm wrong).
You further need the appropriate driver files, if you want to build support for
a FTDI FT2232 based interface:
@itemize @bullet
@item @b{ftdi2232} libftdi (@uref{http://www.intra2net.com/opensource/ftdi/})
@item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm})
@item When using the Amontec JTAGkey, you have to get the drivers from the Amontec
homepage (@uref{http://www.amontec.com}), as the JTAGkey uses a non-standard VID/PID.
@end itemize
libftdi is supported under Windows. Do not use versions earlier than 0.14.
In general, the D2XX driver provides superior performance (several times as fast),
but has the draw-back of being binary-only - though that isn't that bad, as it isn't
a kernel module, only a user space library.
To build OpenOCD (on both Linux and Cygwin), use the following commands:
@example
./bootstrap
@end example
Bootstrap generates the configure script, and prepares building on your system.
@example
./configure [options, see below]
@end example
Configure generates the Makefiles used to build OpenOCD.
@example
make
make install
@end example
Make builds OpenOCD, and places the final executable in ./src/, the last step, ``make install'' is optional.
The configure script takes several options, specifying which JTAG interfaces
should be included (among other things):
@itemize @bullet
@item
@option{--enable-parport} - Enable building the PC parallel port driver.
@item
@option{--enable-parport_ppdev} - Enable use of ppdev (/dev/parportN) for parport.
@item
@option{--enable-parport_giveio} - Enable use of giveio for parport instead of ioperm.
@item
@option{--enable-amtjtagaccel} - Enable building the Amontec JTAG-Accelerator driver.
@item
@option{--enable-ecosboard} - Enable building support for eCosBoard based JTAG debugger.
@item
@option{--enable-ioutil} - Enable ioutil functions - useful for standalone OpenOCD implementations.
@item
@option{--enable-httpd} - Enable builtin httpd server - useful for standalone OpenOCD implementations.
@item
@option{--enable-ep93xx} - Enable building support for EP93xx based SBCs.
@item
@option{--enable-at91rm9200} - Enable building support for AT91RM9200 based SBCs.
@item
@option{--enable-gw16012} - Enable building support for the Gateworks GW16012 JTAG programmer.
@item
@option{--enable-ft2232_ftd2xx} - Numerous USB type ARM JTAG dongles use the FT2232C chip from this FTDICHIP.COM chip (closed source).
@item
@option{--enable-ft2232_libftdi} - An open source (free) alternative to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin).
@item
@option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c, point at the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
@item
@option{--with-ftd2xx-linux-tardir=PATH} - Linux only. Equivalent of @option{--with-ftd2xx-win32-zipdir}, where you unpacked the TAR.GZ file.
@item
@option{--with-ftd2xx-lib=shared|static} - Linux only. Default: static. Specifies how the FTDICHIP.COM libftd2xx driver should be linked. Note: 'static' only works in conjunction with @option{--with-ftd2xx-linux-tardir}. The 'shared' value is supported (12/26/2008), however you must manually install the required header files and shared libraries in an appropriate place. This uses ``libusb'' internally.
@item
@option{--enable-presto_libftdi} - Enable building support for ASIX Presto programmer using the libftdi driver.
@item
@option{--enable-presto_ftd2xx} - Enable building support for ASIX Presto programmer using the FTD2XX driver.
@item
@option{--enable-usbprog} - Enable building support for the USBprog JTAG programmer.
@item
@option{--enable-oocd_trace} - Enable building support for the OpenOCD+trace ETM capture device.
@item
@option{--enable-jlink} - Enable building support for the Segger J-Link JTAG programmer.
@item
@option{--enable-vsllink} - Enable building support for the Versaloon-Link JTAG programmer.
@item
@option{--enable-rlink} - Enable building support for the Raisonance RLink JTAG programmer.
@item
@option{--enable-arm-jtag-ew} - Enable building support for the Olimex ARM-JTAG-EW programmer.
@item
@option{--enable-dummy} - Enable building the dummy port driver.
@end itemize
@section Parallel Port Dongles
If you want to access the parallel port using the PPDEV interface you have to specify
both the @option{--enable-parport} AND the @option{--enable-parport_ppdev} option since
the @option{--enable-parport_ppdev} option actually is an option to the parport driver
(see @uref{http://forum.sparkfun.com/viewtopic.php?t=3795} for more info).
The same is true for the @option{--enable-parport_giveio} option, you have to
use both the @option{--enable-parport} AND the @option{--enable-parport_giveio} option if you want to use giveio instead of ioperm parallel port access method.
@section FT2232C Based USB Dongles
There are 2 methods of using the FTD2232, either (1) using the
FTDICHIP.COM closed source driver, or (2) the open (and free) driver
libftdi. Some claim the (closed) FTDICHIP.COM solution is faster.
The FTDICHIP drivers come as either a (win32) ZIP file, or a (Linux)
TAR.GZ file. You must unpack them ``some where'' convient. As of this
writing (12/26/2008) FTDICHIP does not supply means to install these
files ``in an appropriate place'' As a result, there are two
``./configure'' options that help.
Below is an example build process:
1) Check out the latest version of ``openocd'' from SVN.
2) Download & unpack either the Windows or Linux FTD2xx drivers
(@uref{http://www.ftdichip.com/Drivers/D2XX.htm}).
@example
/home/duane/ftd2xx.win32 => the Cygwin/Win32 ZIP file contents.
/home/duane/libftd2xx0.4.16 => the Linux TAR.GZ file contents.
@end example
3) Configure with these options:
@example
Cygwin FTDICHIP solution:
./configure --prefix=/home/duane/mytools \
--enable-ft2232_ftd2xx \
--with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32
Linux FTDICHIP solution:
./configure --prefix=/home/duane/mytools \
--enable-ft2232_ftd2xx \
--with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
Cygwin/Linux LIBFTDI solution:
Assumes:
1a) For Windows: The Windows port of LIBUSB is in place.
1b) For Linux: libusb has been built/installed and is in place.
2) And libftdi has been built and installed
Note: libftdi - relies upon libusb.
./configure --prefix=/home/duane/mytools \
--enable-ft2232_libftdi
@end example
4) Then just type ``make'', and perhaps ``make install''.
@section Miscellaneous Configure Options
@itemize @bullet
@item
@option{--disable-option-checking} - Ignore unrecognized @option{--enable} and @option{--with} options.
@item
@option{--enable-gccwarnings} - Enable extra gcc warnings during build.
Default is enabled.
@item
@option{--enable-release} - Enable building of an OpenOCD release, generally
this is for developers. It simply omits the svn version string when the
openocd @option{-v} is executed.
@end itemize
@node JTAG Hardware Dongles
@chapter JTAG Hardware Dongles
@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 adapater} one
attaches to your computer via USB or the Parallel Printer Port. The
execption being the Zylin ZY1000 which is 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 three things you should keep in mind when choosing a dongle.
@enumerate
@item @b{Voltage} What voltage is your target? 1.8, 2.8, 3.3, or 5V? Does your dongle support it?
@item @b{Connection} Printer Ports - Does your computer have one?
@item @b{Connection} Is that long printer bit-bang cable practical?
@item @b{RTCK} Do you require RTCK? 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.
See: @url{http://www.ftdichip.com} or @url{http://www.ftdichip.com/Products/FT2232H.htm}
As of 28/Nov/2008, the following are supported:
@itemize @bullet
@item @b{usbjtag}
@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
@item @b{jtagkey}
@* See: @url{http://www.amontec.com/jtagkey.shtml}
@item @b{oocdlink}
@* See: @url{http://www.oocdlink.com} By Joern Kaipf
@item @b{signalyzer}
@* See: @url{http://www.signalyzer.com}
@item @b{evb_lm3s811}
@* See: @url{http://www.luminarymicro.com} - The Luminary Micro Stellaris LM3S811 eval board has an FTD2232C chip built in.
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
@item @b{flyswatter}
@* See: @url{http://www.tincantools.com}
@item @b{turtelizer2}
@* See: @url{http://www.ethernut.de}, or @url{http://www.ethernut.de/en/hardware/turtelizer/index.html}
@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}
@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 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}
@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.
@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}
@* Link: @url{http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag}
@item @b{Wiggler_ntrst_inverted}
@* Yet another variation - See the source code, src/jtag/parport.c
@item @b{old_amt_wiggler}
@* Unknown - probably not on the market today
@item @b{arm-jtag}
@* Link: Most likely @url{http://www.olimex.com/dev/arm-jtag.html} [another wiggler clone]
@item @b{chameleon}
@* Link: @url{http://www.amontec.com/chameleon.shtml}
@item @b{Triton}
@* Unknown.
@item @b{Lattice}
@* ispDownload from Lattice Semiconductor @url{http://www.latticesemi.com/lit/docs/devtools/dlcable.pdf}
@item @b{flashlink}
@* From ST Microsystems, link:
@url{http://www.st.com/stonline/products/literature/um/7889.pdf}
Title: 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 Running
@chapter Running
@cindex running OpenOCD
@cindex --configfile
@cindex --debug_level
@cindex --logfile
@cindex --search
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>
--pipe | -p use pipes when talking to gdb
@end verbatim
By default OpenOCD reads the file configuration file ``openocd.cfg''
in the current directory. To specify a different (or multiple)
configuration file, you can use the ``-f'' option. For example:
@example
openocd -f config1.cfg -f config2.cfg -f config3.cfg
@end example
Once started, OpenOCD runs as a daemon, waiting for connections from
clients (Telnet, GDB, Other).
If you are having problems, you can enable internal debug messages via
the ``-d'' option.
Also it is possible to interleave commands w/config scripts using the
@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 @option{debug_level
<n>} @xref{debug_level}.
You can redirect all output from the daemon to a file using the
@option{-l <logfile>} switch.
Search paths for config/script files can be added to OpenOCD by using
the @option{-s <search>} switch. The current directory and the OpenOCD
target library is in the search path by default.
For details on the @option{-p} option. @xref{Connecting to GDB}.
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 Simple Configuration Files
@chapter Simple Configuration Files
@cindex configuration
@section Outline
There are 4 basic ways of ``configurating'' OpenOCD to run, they are:
@enumerate
@item A small openocd.cfg file which ``sources'' other configuration files
@item A monolithic openocd.cfg file
@item Many -f filename options on the command line
@item Your Mixed Solution
@end enumerate
@section Small configuration file method
This is the preferred method. It is simple and works well for many
people. The developers of OpenOCD would encourage you to use this
method. If you create a new configuration please email new
configurations to the development list.
Here is an example of an openocd.cfg file for an ATMEL at91sam7x256
@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
There are many example configuration scripts you can work with. You
should look in the directory: @t{$(INSTALLDIR)/lib/openocd}. You
should find:
@enumerate
@item @b{board} - eval board level configurations
@item @b{interface} - specific dongle configurations
@item @b{target} - the target chips
@item @b{tcl} - helper scripts
@item @b{xscale} - things specific to the xscale.
@end enumerate
Look first in the ``boards'' area, then the ``targets'' area. Often a board
configuration is a good example to work from.
@section Many -f filename options
Some believe this is a wonderful solution, others find it painful.
You can use a series of ``-f filename'' options on the command line,
OpenOCD will read each filename in sequence, for example:
@example
openocd -f file1.cfg -f file2.cfg -f file2.cfg
@end example
You can also intermix various commands with the ``-c'' command line
option.
@section Monolithic file
The ``Monolithic File'' dispenses with all ``source'' statements and
puts everything in one self contained (monolithic) file. This is not
encouraged.
Please try to ``source'' various files or use the multiple -f
technique.
@section Advice for you
Often, one uses a ``mixed approach''. Where possible, please try to
``source'' common things, and if needed cut/paste parts of the
standard distribution configuration files as needed.
@b{REMEMBER:} The ``important parts'' of your configuration file are:
@enumerate
@item @b{Interface} - Defines the dongle
@item @b{Taps} - Defines the JTAG Taps
@item @b{GDB Targets} - What GDB talks to
@item @b{Flash Programing} - Very Helpful
@end enumerate
Some key things you should look at and understand are:
@enumerate
@item The reset configuration of your debug environment as a whole
@item Is there a ``work area'' that OpenOCD can use?
@* For ARM - work areas mean up to 10x faster downloads.
@item For MMU/MPU based ARM chips (i.e.: ARM9 and later) will that work area still be available?
@item For complex targets (multiple chips) the JTAG SPEED becomes an issue.
@end enumerate
@node Config File Guidelines
@chapter Config File Guidelines
This section/chapter is aimed at developers and integrators of
OpenOCD. These are guidelines for creating new boards and new target
configurations as of 28/Nov/2008.
However, you, the user of OpenOCD, should be somewhat familiar with
this section as it should help explain some of the internals of what
you might be looking at.
The user should find the following directories under @t{$(INSTALLDIR)/lib/openocd} :
@itemize @bullet
@item @b{interface}
@*Think JTAG Dongle. Files that configure the JTAG dongle go here.
@item @b{board}
@* Think Circuit Board, PWA, PCB, they go by many names. Board files
contain initialization items that are specific to a board - for
example: The SDRAM initialization sequence for the board, or the type
of external flash and what address it is found at. Any initialization
sequence to enable that external flash or SDRAM should be found in the
board file. Boards may also contain multiple targets, i.e.: Two CPUs, or
a CPU and an FPGA or CPLD.
@item @b{target}
@* Think chip. The ``target'' directory represents a JTAG tap (or
chip) OpenOCD should control, not a board. Two common types of targets
are ARM chips and FPGA or CPLD chips.
@end itemize
@b{If needed...} The user in their ``openocd.cfg'' file or the board
file might override a specific feature in any of the above files by
setting a variable or two before sourcing the target file. Or adding
various commands specific to their situation.
@section Interface Config Files
The user should be able to source one of these files via a command like this:
@example
source [find interface/FOOBAR.cfg]
Or:
openocd -f interface/FOOBAR.cfg
@end example
A preconfigured interface file should exist for every interface in use
today, that said, perhaps some interfaces have only been used by the
sole developer who created it.
@b{FIXME/NOTE:} We need to add support for a variable like Tcl variable
tcl_platform(platform), it should be called jim_platform (because it
is jim, not real tcl) and it should contain 1 of 3 words: ``linux'',
``cygwin'' or ``mingw''
Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
@section Board Config Files
@b{Note: BOARD directory NEW as of 28/nov/2008}
The user should be able to source one of these files via a command like this:
@example
source [find board/FOOBAR.cfg]
Or:
openocd -f board/FOOBAR.cfg
@end example
The board file should contain one or more @t{source [find
target/FOO.cfg]} statements along with any board specific things.
In summary the board files should contain (if present)
@enumerate
@item External flash configuration (i.e.: NOR flash on CS0, two NANDs on CS2)
@item SDRAM configuration (size, speed, etc.
@item Board specific IO configuration (i.e.: GPIO pins might disable a 2nd flash)
@item Multiple TARGET source statements
@item All things that are not ``inside a chip''
@item Things inside a chip go in a 'target' file
@end enumerate
@section Target Config Files
The user should be able to source one of these files via a command like this:
@example
source [find target/FOOBAR.cfg]
Or:
openocd -f target/FOOBAR.cfg
@end example
In summary the target files should contain
@enumerate
@item Set defaults
@item Create taps
@item Reset configuration
@item Work areas
@item CPU/Chip/CPU-Core specific features
@item On-Chip flash
@end enumerate
@subsection Important variable names
By default, the end user should never need to set these
variables. However, if the user needs to override a setting they only
need to set the variable in a simple way.
@itemize @bullet
@item @b{CHIPNAME}
@* This gives a name to the overall chip, and is used as part of the
tap identifier dotted name.
@item @b{ENDIAN}
@* By default little - unless the chip or board is not normally used that way.
@item @b{CPUTAPID}
@* When OpenOCD examines the JTAG chain, it will attempt to identify
every chip. If the @t{-expected-id} is nonzero, OpenOCD attempts
to verify the tap id number verses configuration file and may issue an
error or warning like this. The hope is that this will help to pinpoint
problems in OpenOCD configurations.
@example
Info: JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
Error: ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f
Error: ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
Error: ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3
@end example
@item @b{_TARGETNAME}
@* By convention, this variable is created by the target configuration
script. The board configuration file may make use of this variable to
configure things like a ``reset init'' script, or other things
specific to that board and that target.
If the chip has 2 targets, use the names @b{_TARGETNAME0},
@b{_TARGETNAME1}, ... etc.
@b{Remember:} The ``board file'' may include multiple targets.
At no time should the name ``target0'' (the default target name if
none was specified) be used. The name ``target0'' is a hard coded name
- the next target on the board will be some other number.
In the same way, avoid using target numbers even when they are
permitted; use the right target name(s) for your board.
The user (or board file) should reasonably be able to:
@example
source [find target/FOO.cfg]
$_TARGETNAME configure ... FOO specific parameters
source [find target/BAR.cfg]
$_TARGETNAME configure ... BAR specific parameters
@end example
@end itemize
@subsection Tcl Variables Guide Line
The Full Tcl/Tk language supports ``namespaces'' - JIM-Tcl does not.
Thus the rule we follow in OpenOCD is this: Variables that begin with
a leading underscore are temporary in nature, and can be modified and
used at will within a ?TARGET? configuration file.
@b{EXAMPLE:} The user should be able to do this:
@example
# Board has 3 chips,
# PXA270 #1 network side, big endian
# PXA270 #2 video side, little endian
# Xilinx Glue logic
set CHIPNAME network
set ENDIAN big
source [find target/pxa270.cfg]
# variable: _TARGETNAME = network.cpu
# other commands can refer to the "network.cpu" tap.
$_TARGETNAME configure .... params for this CPU..
set ENDIAN little
set CHIPNAME video
source [find target/pxa270.cfg]
# variable: _TARGETNAME = video.cpu
# other commands can refer to the "video.cpu" tap.
$_TARGETNAME configure .... params for this CPU..
unset ENDIAN
set CHIPNAME xilinx
source [find target/spartan3.cfg]
# Since $_TARGETNAME is temporal..
# these names still work!
network.cpu configure ... params
video.cpu configure ... params
@end example
@subsection Default Value Boiler Plate Code
All target configuration files should start with this (or a modified form)
@example
# SIMPLE example
if @{ [info exists CHIPNAME] @} @{
set _CHIPNAME $CHIPNAME
@} else @{
set _CHIPNAME sam7x256
@}
if @{ [info exists ENDIAN] @} @{
set _ENDIAN $ENDIAN
@} else @{
set _ENDIAN little
@}
if @{ [info exists CPUTAPID ] @} @{
set _CPUTAPID $CPUTAPID
@} else @{
set _CPUTAPID 0x3f0f0f0f
@}
@end example
@subsection Creating Taps
After the ``defaults'' are choosen [see above] the taps are created.
@b{SIMPLE example:} such as an Atmel AT91SAM7X256
@example
# for an ARM7TDMI.
set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf -expected-id $_CPUTAPID
@end example
@b{COMPLEX example:}
This is an SNIP/example for an STR912 - which has 3 internal taps. Key features shown:
@enumerate
@item @b{Unform tap names} - See: Tap Naming Convention
@item @b{_TARGETNAME} is created at the end where used.
@end enumerate