Add missing init_targets documentation

[fw/openocd] / doc / openocd.texi

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 233da0ef8f2429f4cc9d11f39a316dbe9c157e78..3519222b5cd68bf8ea155a5fc3e81a0845f5869e 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -255,7 +255,7 @@ 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
+The @file{HACKING} file contains basic information about how
 to prepare patches.
 
 @section OpenOCD Bug Database
@@ -421,6 +421,27 @@ Raisonance has an adapter called @b{RLink}.  It exists in a stripped-down form o
 @* 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
+
+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 method's:
+@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}
@@ -1789,6 +1810,45 @@ OpenOCD verifies the scan chain after reset,
 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.
+
 @subsection ARM Core Specific Hacks
 
 If the chip has a DCC, enable it. If the chip is an ARM9 with some
@@ -1901,6 +1961,7 @@ may access or activate TAPs.
 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
@@ -2564,6 +2625,10 @@ which are not currently documented here.
 @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