+@node TCL Crash Course
+@chapter TCL Crash Course
+@cindex TCL
+
+Not everyone knows TCL - this is not intended to be a replacement for
+learning TCL, the intent of this chapter is to give you some idea of
+how the TCL Scripts work.
+
+This chapter is written with two audiences in mind. (1) OpenOCD users
+who need to understand a bit more of how JIM-Tcl works so they can do
+something useful, and (2) those that want to add a new command to
+OpenOCD.
+
+@section TCL Rule #1
+There is a famous joke, it goes like this:
+@enumerate
+@item Rule #1: The wife is aways correct
+@item Rule #2: If you think otherwise, See Rule #1
+@end enumerate
+
+The TCL equal is this:
+
+@enumerate
+@item Rule #1: Everything is a string
+@item Rule #2: If you think otherwise, See Rule #1
+@end enumerate
+
+As in the famous joke, the consiquences of Rule #1 are profound. Once
+you understand Rule #1, you will understand TCL.
+
+@section TCL Rule #1b
+There is a second pair of rules.
+@enumerate
+@item Rule #1: Control flow does not exist. Only commands
+@* For example: the classic FOR loop or IF statement is not a control
+flow item, they are commands, there is no such thing as control flow
+in TCL.
+@item Rule #2: If you think otherwise, See Rule #1
+@* Actually what happens is this: There are commands that by
+convention, act like control flow key words in other languages. One of
+those commands is the word ``for'', another command is ``if''.
+@end enumerate
+
+@section Per Rule #1 - All Results are strings
+Every TCL command results in a string. The word ``result'' is used
+deliberatly. No result is just an empty string. Remember: @i{Rule #1 -
+Everything is a string}
+
+@section TCL Quoting Operators
+In life of a TCL script, there are two important periods of time, the
+difference is subtle.
+@enumerate
+@item Parse Time
+@item Evaluation Time
+@end enumerate
+
+The two key items here are how ``quoted things'' work in TCL. TCL has
+three primary quoting constructs, the [square-brackets] the
+@{curly-braces@} and ``double-quotes''
+
+By now you should know $VARIABLES always start with a $DOLLAR
+sign. BTW, to set a variable, you actually use the command ``set'', as
+in ``set VARNAME VALUE'' much like the ancient BASIC langauge ``let x
+= 1'' statement, but without the equal sign.
+
+@itemize @bullet
+@item @b{[square-brackets]}
+@* @b{[square-brackets]} are command subsitution. It operates much
+like Unix Shell `back-ticks`. The result of a [square-bracket]
+operation is exactly 1 string. @i{Remember Rule #1 - Everything is a
+string}. These two statments are roughly identical.
+@example
+ # bash example
+ X=`date`
+ echo "The Date is: $X"
+ # TCL example
+ set X [date]
+ puts "The Date is: $X"
+@end example
+@item @b{``double-quoted-things''}
+@* @b{``double-quoted-things''} are just simply quoted
+text. $VARIABLES and [square-brackets] are expanded in place - the
+result however is exactly 1 string. @i{Remember Rule #1 - Everything
+is a string}
+@example
+ set x "Dinner"
+ puts "It is now \"[date]\", $x is in 1 hour"
+@end example
+@item @b{@{Curly-Braces@}}
+@*@b{@{Curly-Braces@}} are magic: $VARIABLES and [square-brackets] are
+parsed, but are NOT expanded or executed. @{Curly-Braces@} are like
+'single-quote' operators in BASH shell scripts, with the added
+feature: @{curly-braces@} nest, single quotes can not. @{@{@{this is
+nested 3 times@}@}@} NOTE: [date] is perhaps a bad example, as of
+28/nov/2008, Jim/OpenOCD does not have a date command.
+@end itemize
+
+@section Consiquences of Rule 1/2/3/4
+
+The consiquences of Rule 1 is profound.
+
+@subsection Tokenizing & Execution.
+
+Of course, whitespace, blank lines and #comment lines are handled in
+the normal way.
+
+As a script is parsed, each (multi) line in the script file is
+tokenized and according to the quoting rules. After tokenizing, that
+line is immedatly executed.
+
+Multi line statements end with one or more ``still-open''
+@{curly-braces@} which - eventually - a few lines later closes.
+
+@subsection Command Execution
+
+Remember earlier: There is no such thing as ``control flow''
+statements in TCL. Instead there are COMMANDS that simpily act like
+control flow operators.
+
+Commands are executed like this:
+
+@enumerate
+@item Parse the next line into (argc) and (argv[]).
+@item Look up (argv[0]) in a table and call its function.
+@item Repeat until End Of File.
+@end enumerate
+
+It sort of works like this:
+@example
+ for(;;)@{
+ ReadAndParse( &argc, &argv );
+
+ cmdPtr = LookupCommand( argv[0] );
+
+ (*cmdPtr->Execute)( argc, argv );
+ @}
+@end example
+
+When the command ``proc'' is parsed (which creates a procedure
+function) it gets 3 parameters on the command line. @b{1} the name of
+the proc (function), @b{2} the list of parameters, and @b{3} the body
+of the function. Not the choice of words: LIST and BODY. The PROC
+command stores these items in a table somewhere so it can be found by
+``LookupCommand()''
+
+@subsection The FOR Command
+
+The most interesting command to look at is the FOR command. In TCL,
+the FOR command is normally implimented in C. Remember, FOR is a
+command just like any other command.
+
+When the ascii text containing the FOR command is parsed, the parser
+produces 5 parameter strings, @i{(If in doubt: Refer to Rule #1)} they
+are:
+
+@enumerate 0
+@item The ascii text 'for'
+@item The start text
+@item The test expression
+@item The next text
+@item The body text
+@end enumerate
+
+Sort of reminds you of ``main( int argc, char **argv )'' does it not?
+Remember @i{Rule #1 - Everything is a string.} The key point is this:
+Often many of those parameters are in @{curly-braces@} - thus the
+variables inside are not expanded or replaced until later.
+
+Remember that every TCL command looks like the classic ``main( argc,
+argv )'' function in C. In JimTCL - they actually look like this:
+
+@example
+int
+MyCommand( Jim_Interp *interp,
+ int *argc,
+ Jim_Obj * const *argvs );
+@end example
+
+Real TCL is nearly identical. Although the newer versions have
+introduced a byte-code parser and intepreter, but at the core, it
+still operates in the same basic way.
+
+@subsection FOR Command Implimentation
+
+To understand TCL it is perhaps most helpful to see the FOR
+command. Remember, it is a COMMAND not a control flow structure.
+
+In TCL there are two underying C helper functions.
+
+Remember Rule #1 - You are a string.
+
+The @b{first} helper parses and executes commands found in an ascii
+string. Commands can be seperated by semi-colons, or newlines. While
+parsing, variables are expanded per the quoting rules
+
+The @b{second} helper evaluates an ascii string as a numerical
+expression and returns a value.
+
+Here is an example of how the @b{FOR} command could be
+implimented. The pseudo code below does not show error handling.
+@example
+void Execute_AsciiString( void *interp, const char *string );
+
+int Evaluate_AsciiExpression( void *interp, const char *string );
+
+int
+MyForCommand( void *interp,
+ int argc,
+ char **argv )
+@{
+ if( argc != 5 )@{
+ SetResult( interp, "WRONG number of parameters");
+ return ERROR;
+ @}
+
+ // argv[0] = the ascii string just like C
+
+ // Execute the start statement.
+ Execute_AsciiString( interp, argv[1] );
+
+ // Top of loop test
+ for(;;)@{
+ i = Evaluate_AsciiExpression(interp, argv[2]);
+ if( i == 0 )
+ break;
+
+ // Execute the body
+ Execute_AsciiString( interp, argv[3] );
+
+ // Execute the LOOP part
+ Execute_AsciiString( interp, argv[4] );
+ @}
+
+ // Return no error
+ SetResult( interp, "" );
+ return SUCCESS;
+@}
+@end example
+
+Every other command IF, WHILE, FORMAT, PUTS, EXPR, everything works
+in the same basic way.
+
+@section OpenOCD TCL Usage
+
+@subsection source and find commands
+@b{Where:} In many configuration files
+@* Example: @b{ source [find FILENAME] }
+@*Remember the parsing rules
+@enumerate
+@item The FIND command is in square brackets.
+@* The FIND command is executed with the parameter FILENAME. It should
+find the full path to the named file. The RESULT is a string, which is
+subsituted on the orginal command line.
+@item The command source is executed with the resulting filename.
+@* SOURCE reads a file and executes as a script.
+@end enumerate
+@subsection format command
+@b{Where:} Generally occurs in numerous places.
+@* TCL no command like @b{printf()}, intead it has @b{format}, which is really more like
+@b{sprintf()}.
+@b{Example}
+@example
+ set x 6
+ set y 7
+ puts [format "The answer: %d" [expr $x * $y]]
+@end example
+@enumerate
+@item The SET command creates 2 variables, X and Y.
+@item The double [nested] EXPR command performs math
+@* The EXPR command produces numerical result as a string.
+@* Refer to Rule #1
+@item The format command is executed, producing a single string
+@* Refer to Rule #1.
+@item The PUTS command outputs the text.
+@end enumerate
+@subsection Body Or Inlined Text
+@b{Where:} Various TARGET scripts.
+@example
+#1 Good
+ proc someproc @{@} @{
+ ... multiple lines of stuff ...
+ @}
+ $_TARGETNAME configure -event FOO someproc
+#2 Good - no variables
+ $_TARGETNAME confgure -event foo "this ; that;"
+#3 Good Curly Braces
+ $_TARGETNAME configure -event FOO @{
+ puts "Time: [date]"
+ @}
+#4 DANGER DANGER DANGER
+ $_TARGETNAME configure -event foo "puts \"Time: [date]\""
+@end example
+@enumerate
+@item The $_TARGETNAME is an OpenOCD variable convention.
+@*@b{$_TARGETNAME} represents the last target created, the value changes
+each time a new target is created. Remember the parsing rules. When
+the ascii text is parsed, the @b{$_TARGETNAME} becomes a simple string,
+the name of the target which happens to be a TARGET (object)
+command.
+@item The 2nd parameter to the @option{-event} parameter is a TCBODY
+@*There are 4 examples:
+@enumerate
+@item The TCLBODY is a simple string that happens to be a proc name
+@item The TCLBODY is several simple commands semi-colon seperated
+@item The TCLBODY is a multi-line @{curly-brace@} quoted string
+@item The TCLBODY is a string with variables that get expanded.
+@end enumerate
+
+In the end, when the target event FOO occurs the TCLBODY is
+evaluated. Method @b{#1} and @b{#2} are functionally identical. For
+Method @b{#3} and @b{#4} it is more interesting. What is the TCLBODY?
+
+Remember the parsing rules. In case #3, @{curly-braces@} mean the
+$VARS and [square-brackets] are expanded later, when the EVENT occurs,
+and the text is evaluated. In case #4, they are replaced before the
+``Target Object Command'' is executed. This occurs at the same time
+$_TARGETNAME is replaced. In case #4 the date will never
+change. @{BTW: [date] is perhaps a bad example, as of 28/nov/2008,
+Jim/OpenOCD does not have a date command@}
+@end enumerate
+@subsection Global Variables
+@b{Where:} You might discover this when writing your own procs @* In
+simple terms: Inside a PROC, if you need to access a global variable
+you must say so. Also see ``upvar''. Example:
+@example
+proc myproc @{ @} @{
+ set y 0 #Local variable Y
+ global x #Global variable X
+ puts [format "X=%d, Y=%d" $x $y]
+@}
+@end example
+@section Other Tcl Hacks
+@b{Dynamic Variable Creation}
+@example
+# Dynamically create a bunch of variables.
+for @{ set x 0 @} @{ $x < 32 @} @{ set x [expr $x + 1]@} @{
+ # Create var name
+ set vn [format "BIT%d" $x]
+ # Make it a global
+ global $vn
+ # Set it.
+ set $vn [expr (1 << $x)]
+@}
+@end example
+@b{Dynamic Proc/Command Creation}
+@example
+# One "X" function - 5 uart functions.
+foreach who @{A B C D E@}
+ proc [format "show_uart%c" $who] @{ @} "show_UARTx $who"
+@}
+@end example
+
+@node Target library
+@chapter Target library
+@cindex Target library
+
+OpenOCD comes with a target configuration script library. These scripts can be
+used as-is or serve as a starting point.
+
+The target library is published together with the openocd executable and
+the path to the target library is in the OpenOCD script search path.
+Similarly there are example scripts for configuring the JTAG interface.
+
+The command line below uses the example parport configuration scripts
+that ship with OpenOCD, then configures the str710.cfg target and
+finally issues the init and reset command. The communication speed
+is set to 10kHz for reset and 8MHz for post reset.
+
+
+@example
+openocd -f interface/parport.cfg -f target/str710.cfg -c "init" -c "reset"
+@end example
+
+
+To list the target scripts available:
+
+@example
+$ ls /usr/local/lib/openocd/target
+
+arm7_fast.cfg lm3s6965.cfg pxa255.cfg stm32.cfg xba_revA3.cfg
+at91eb40a.cfg lpc2148.cfg pxa255_sst.cfg str710.cfg zy1000.cfg
+at91r40008.cfg lpc2294.cfg sam7s256.cfg str912.cfg
+at91sam9260.cfg nslu2.cfg sam7x256.cfg wi-9c.cfg
+@end example
+
+
+