Added tip in documentation on how to translate quirky syntax

1 files changed, 41 insertions, 1 deletions

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 11bd7e0a..daa94609 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -66,6 +66,7 @@ Free Documentation License''.
 * Running::                          Running OpenOCD
 * OpenOCD Project Setup::            OpenOCD Project Setup
 * Config File Guidelines::           Config File Guidelines
+* Translating Configuration Files::  Translating Configuration Files
 * Daemon Configuration::             Daemon Configuration
 * Interface - Dongle Configuration:: Interface - Dongle Configuration
 * Reset Configuration::              Reset Configuration
@@ -911,7 +912,6 @@ It provides guidelines for creating those files.
 You should find the following directories under @t{$(INSTALLDIR)/scripts},
 with files including the ones listed here.
 Use them as-is where you can; or as models for new files.
-
 @itemize @bullet
 @item @file{interface} ...
 think JTAG Dongle. Files that configure JTAG adapters go here.
@@ -1464,6 +1464,46 @@ Examples:
 @item pxa270 - again - CS0 flash - it goes in the board file.
 @end itemize
 
+@node Translating Configuration Files
+@chapter Translating Configuration Files
+@cindex translation
+If you have a configuration file for another hardware debugger(Abatron,
+BDI2000, BDI3000, Lauterbach, Segger, MacRaigor, etc.), translating
+it into OpenOCD syntax is often quite straightforward. The most tricky
+part of creating a configuration script is oftentimes the reset init
+sequence where e.g. PLLs, DRAM and the like is set up.
+
+One trick that you can use when translating is to write small
+Tcl proc's to translate the syntax into OpenOCD syntax. This
+can avoid manual translation errors and make it easier to
+convert other scripts later on.
+
+Example of transforming quirky arguments to a simple search and
+replace job:
+
+@example
+# rewrite commands of the form below to arm11 mcr...
+#
+#   Lauterbach syntax(?)
+#
+#	Data.Set c15:0x042f %long 0x40000015
+#
+#   OpenOCD syntax when using procedure below.
+#
+#   setc15 0x01 0x00050078
+#
+#
+proc setc15 @{regs value@} @{
+	global TARGETNAME 
+
+	echo [format "set p15 0x%04x, 0x%08x" $regs $value] 
+
+	arm11 mcr $TARGETNAME 15 [expr ($regs>>12)&0x7] [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] [expr ($regs>>8)&0x7] $value 
+@}
+@end example
+
+
+
 @node Daemon Configuration
 @chapter Daemon Configuration
 @cindex initialization