+@node TCL and OpenOCD
+@chapter TCL and OpenOCD
+@cindex TCL and OpenOCD
+OpenOCD embeds a TCL interpreter (see JIM) for command parsing and scripting
+support.
+
+The TCL interpreter can be invoked from the interactive command line, files, and a network port.
+
+The command and file interfaces are fairly straightforward, while the network
+port is geared toward intergration with external clients. A small example
+of an external TCL script that can connect to openocd is shown below.
+
+@verbatim
+# Simple tcl client to connect to openocd
+puts "Use empty line to exit"
+set fo [socket 127.0.0.1 6666]
+puts -nonewline stdout "> "
+flush stdout
+while {[gets stdin line] >= 0} {
+ if {$line eq {}} break
+ puts $fo $line
+ flush $fo
+ gets $fo line
+ puts $line
+ puts -nonewline stdout "> "
+ flush stdout
+}
+close $fo
+@end verbatim
+
+This script can easily be modified to front various GUIs or be a sub
+component of a larger framework for control and interaction.
+
+
+@node TCL scripting API
+@chapter TCL scripting API
+@cindex TCL scripting API
+API rules
+
+The commands are stateless. E.g. the telnet command line has a concept
+of currently active target, the Tcl API proc's take this sort of state
+information as an argument to each proc.
+
+There are three main types of return values: single value, name value
+pair list and lists.
+
+Name value pair. The proc 'foo' below returns a name/value pair
+list.
+
+@verbatim
+
+ > set foo(me) Duane
+ > set foo(you) Oyvind
+ > set foo(mouse) Micky
+ > set foo(duck) Donald
+
+If one does this:
+
+ > set foo
+
+The result is:
+
+ me Duane you Oyvind mouse Micky duck Donald
+
+Thus, to get the names of the associative array is easy:
+
+ foreach { name value } [set foo] {
+ puts "Name: $name, Value: $value"
+ }
+@end verbatim
+
+Lists returned must be relatively small. Otherwise a range
+should be passed in to the proc in question.
+
+Low level commands are prefixed with "openocd_", e.g. openocd_flash_banks
+is the low level API upon which "flash banks" is implemented.
+
+OpenOCD commands can consist of two words, e.g. "flash banks". The
+startup.tcl "unknown" proc will translate this into a tcl proc
+called "flash_banks".
+
+