@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
+The @file{HACKING} file contains basic information about how
to prepare patches.
@section OpenOCD Bug Database
@section Stand alone Systems
-@b{ZY1000} See: @url{http://www.zylin.com/zy1000.html} Technically, not a
+@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/33-zylin-zy1000-jtag-probe} 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
@itemize @bullet
@item @b{usbjtag}
-@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
+@* Link @url{http://elk.informatik.fh-augsburg.de/hhweb/doc/openocd/usbjtag/usbjtag.html}
@item @b{jtagkey}
@* See: @url{http://www.amontec.com/jtagkey.shtml}
@item @b{jtagkey2}
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}
+@item @b{Flyswatter/Flyswatter2}
@* See: @url{http://www.tincantools.com}
@item @b{turtelizer2}
@* See:
@item @b{stm32stick}
@* Link @url{http://www.hitex.com/stm32-stick}
@item @b{axm0432_jtag}
-@* Axiom AXM-0432 Link @url{http://www.axman.com}
+@* Axiom AXM-0432 Link @url{http://www.axman.com} - NOTE: This JTAG does not appear
+to be available anymore as of April 2012.
@item @b{cortino}
@* Link @url{http://www.hitex.com/index.php?id=cortino}
@item @b{dlp-usb1232h}
@* Link @url{http://www.dlpdesign.com/usb/usb1232h.shtml}
+@item @b{digilent-hs1}
+@* Link @url{http://www.digilentinc.com/Products/Detail.cfm?Prod=JTAG-HS1}
@end itemize
@section USB-JTAG / Altera USB-Blaster compatibles
@itemize
@item @b{USB-JTAG} Kolja Waschk's USB Blaster-compatible adapter
-@* Link: @url{http://www.ixo.de/info/usb_jtag/}
+@* Link: @url{http://ixo-jtag.sourceforge.net/}
@item @b{Altera USB-Blaster}
@* Link: @url{http://www.altera.com/literature/ug/ug_usb_blstr.pdf}
@end itemize
@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}
+@* Link: @url{http://www.iar.com/en/products/hardware-debug-probes/iar-j-link/}
@end itemize
@section USB RLINK based
@itemize @bullet
@item @b{Raisonance RLink}
-@* Link: @url{http://www.raisonance.com/products/RLink.php}
+@* Link: @url{http://www.mcu-raisonance.com/~rlink-debugger-programmer__microcontrollers__tool~tool__T018:4cn9ziz4bnx6.html}
@item @b{STM32 Primer}
@* Link: @url{http://www.stm32circle.com/resources/stm32primer.php}
@item @b{STM32 Primer2}
@* Link: @url{http://www.stm32circle.com/resources/stm32primer2.php}
@end itemize
+@section USB ST-LINK based
+ST Micro has an adapter called @b{ST-LINK}.
+They only work with ST Micro chips, notably STM32 and STM8.
+
+@itemize @bullet
+@item @b{ST-LINK}
+@* This is available standalone and as part of some kits, eg. STM32VLDISCOVERY.
+@* Link: @url{http://www.st.com/internet/evalboard/product/219866.jsp}
+@item @b{ST-LINK/V2}
+@* This is available standalone and as part of some kits, eg. STM32F4DISCOVERY.
+@* Link: @url{http://www.st.com/internet/evalboard/product/251168.jsp}
+@end itemize
+
+For info the original ST-LINK enumerates using the mass storage usb class, however
+it's implementation is completely broken. The result is this causes issues under linux.
+The simplest solution is to get linux to ignore the ST-LINK using one of the following methods:
+@itemize @bullet
+@item modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i
+@item add "options usb-storage quirks=483:3744:i" to /etc/modprobe.conf
+@end itemize
+
@section USB Other
@itemize @bullet
@item @b{USBprog}
@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
+and the Macraigor Wiggler. There are many clones and variations of
these on the market.
Note that parallel ports are becoming much less common, so if you
@* 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}
+@* 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{flashlink}
@* From ST Microsystems;
-@uref{http://www.st.com/stonline/@/products/literature/um/7889.pdf,
-FlashLINK JTAG programing cable for PSD and uPSD}
+@* Link: @url{http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATA_BRIEF/DM00039500.pdf}
@end itemize
A separate chapter gives information about how to set these up.
@xref{Debug Adapter Configuration}.
-Read the OpenOCD source code (and Developer's GUide)
+Read the OpenOCD source code (and Developer's Guide)
if you have a new kind of hardware interface
and need to provide a driver for it.
Set the slow rate at the beginning of the reset sequence,
and the faster rate as soon as the clocks are at full speed.
+@anchor{The init_board procedure}
+@subsection The init_board procedure
+@cindex init_board procedure
+
+The concept of @code{init_board} procedure is very similar to @code{init_targets} (@xref{The init_targets procedure}.)
+- it's a replacement of ``linear'' configuration scripts. This procedure is meant to be executed when OpenOCD enters run
+stage (@xref{Entering the Run Stage},) after @code{init_targets}. The idea to have spearate @code{init_targets} and
+@code{init_board} procedures is to allow the first one to configure everything target specific (internal flash,
+internal RAM, etc.) and the second one to configure everything board specific (reset signals, chip frequency,
+reset-init event handler, external memory, etc.). Additionally ``linear'' board config file will most likely fail when
+target config file uses @code{init_targets} scheme (``linear'' script is executed before @code{init} and
+@code{init_targets} - after), so separating these two configuration stages is very convenient, as the easiest way to
+overcome this problem is to convert board config file to use @code{init_board} procedure. Board config scripts don't
+need to override @code{init_targets} defined in target config files when they only need to to add some specifics.
+
+Just as @code{init_targets}, the @code{init_board} procedure can be overriden by ``next level'' script (which sources
+the original), allowing greater code reuse.
+
+@example
+### board_file.cfg ###
+
+# source target file that does most of the config in init_targets
+source [find target/target.cfg]
+
+proc enable_fast_clock @{@} @{
+ # enables fast on-board clock source
+ # configures the chip to use it
+@}
+
+# initialize only board specifics - reset, clock, adapter frequency
+proc init_board @{@} @{
+ reset_config trst_and_srst trst_pulls_srst
+
+ $_TARGETNAME configure -event reset-init @{
+ adapter_khz 1
+ enable_fast_clock
+ adapter_khz 10000
+ @}
+@}
+@end example
+
@section Target Config Files
@cindex config file, target
@cindex target config file
look at how you are setting up JTAG clocking.
@end quotation
+@anchor{The init_targets procedure}
+@subsection The init_targets procedure
+@cindex init_targets procedure
+
+Target config files can either be ``linear'' (script executed line-by-line when parsed in configuration stage,
+@xref{Configuration Stage},) or they can contain a special procedure called @code{init_targets}, which will be executed
+when entering run stage (after parsing all config files or after @code{init} command, @xref{Entering the Run Stage}.)
+Such procedure can be overriden by ``next level'' script (which sources the original). This concept faciliates code
+reuse when basic target config files provide generic configuration procedures and @code{init_targets} procedure, which
+can then be sourced and enchanced or changed in a ``more specific'' target config file. This is not possible with
+``linear'' config scripts, because sourcing them executes every initialization commands they provide.
+
+@example
+### generic_file.cfg ###
+
+proc setup_my_chip @{chip_name flash_size ram_size@} @{
+ # basic initialization procedure ...
+@}
+
+proc init_targets @{@} @{
+ # initializes generic chip with 4kB of flash and 1kB of RAM
+ setup_my_chip MY_GENERIC_CHIP 4096 1024
+@}
+
+### specific_file.cfg ###
+
+source [find target/generic_file.cfg]
+
+proc init_targets @{@} @{
+ # initializes specific chip with 128kB of flash and 64kB of RAM
+ setup_my_chip MY_CHIP_WITH_128K_FLASH_64KB_RAM 131072 65536
+@}
+@end example
+
+The easiest way to convert ``linear'' config files to @code{init_targets} version is to enclose every line of ``code''
+(i.e. not @code{source} commands, procedures, etc.) in this procedure.
+
+For an example of this scheme see LPC2000 target config files.
+
+The @code{init_boards} procedure is a similar concept concerning board config files (@xref{The init_board procedure}.)
+
@subsection ARM Core Specific Hacks
If the chip has a DCC, enable it. If the chip is an ARM9 with some
After it leaves this stage, configuration commands may no
longer be issued.
+@anchor{Entering the Run Stage}
@section Entering the Run Stage
The first thing OpenOCD does after leaving the configuration
@end quotation
@end deffn
+@deffn {Interface Driver} {stlink}
+ST Micro ST-LINK adapter.
+@end deffn
+
@deffn {Interface Driver} {ZY1000}
This is the Zylin ZY1000 JTAG debugger.
@end deffn
option. When vendors put out multiple versions of a chip, or use the same
JTAG-level ID for several largely-compatible chips, it may be more practical
to ignore the version field than to update config files to handle all of
-the various chip IDs.
+the various chip IDs. The version field is defined as bit 28-31 of the IDCODE.
@item @code{-ircapture} @var{NUMBER}
@*The bit pattern loaded by the TAP into the JTAG shift register
on entry to the @sc{ircapture} state, such as 0x01.
@comment - defines mass_erase ... pointless given flash_erase_address
@end deffn
-@deffn {Flash Driver} ecosflash
-@emph{No idea what this is...}
-The @var{ecosflash} driver defines one mandatory parameter,
-the name of a modules of target code which is downloaded
-and executed.
-@end deffn
-
@deffn {Flash Driver} lpc2000
Most members of the LPC1700 and LPC2000 microcontroller families from NXP
include internal flash and use Cortex-M3 (LPC1700) or ARM7TDMI (LPC2000) cores.
flash bank $_FLASHNAME stm32f1x 0 0 0 0 $_TARGETNAME
@end example
+If you have a target with dual flash banks then define the second bank
+as per the following example.
+@example
+flash bank $_FLASHNAME stm32f1x 0x08080000 0 0 0 $_TARGETNAME
+@end example
+
Some stm32f1x-specific commands
@footnote{Currently there is a @command{stm32f1x mass_erase} command.
That seems pointless since the same effect can be had using the
Code Review / openocd.git / blobdiff