aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorFreddie Chopin <freddie.chopin@gmail.com>2012-02-09 17:50:42 +0100
committerPeter Stuge <peter@stuge.se>2012-02-09 18:07:22 +0000
commit394dcc8e34dd4aa8864cce1d42e29d99d0640740 (patch)
tree45ca657f0a6c9e4fbe86ebdd8d21e4bffc52b457
parentf86986a9ef9ca863bad3bec5ffbdea748d011b40 (diff)
downloadriscv-openocd-394dcc8e34dd4aa8864cce1d42e29d99d0640740.zip
riscv-openocd-394dcc8e34dd4aa8864cce1d42e29d99d0640740.tar.gz
riscv-openocd-394dcc8e34dd4aa8864cce1d42e29d99d0640740.tar.bz2
Add missing init_targets documentation
Add init_targets procedure documentation to OpenOCD manual explaining the concept. Change-Id: I82933ed90397cbcdc5c72801182573ca69b1d265 Signed-off-by: Freddie Chopin <freddie.chopin@gmail.com> Reviewed-on: http://openocd.zylin.com/439 Reviewed-by: Chris Morgan <chmorgan@gmail.com> Tested-by: jenkins Reviewed-by: Peter Stuge <peter@stuge.se>
-rw-r--r--doc/openocd.texi40
1 files changed, 40 insertions, 0 deletions
diff --git a/doc/openocd.texi b/doc/openocd.texi
index 7bfad9b..3519222 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -1810,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
@@ -1922,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