## 21 Tcl Scripting API

### 21.1 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.

     >  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"
         }

Lists returned must be relatively small. Otherwise a range should be passed in to the proc in question.

### 21.2 Internal low-level Commands

By low-level, the intent is a human would not directly use these commands.

Low-level commands are (should be) prefixed with "ocd_", e.g. `ocd_flash_banks` is the low level API upon which `flash banks` is implemented.

- mem2array <varname> <width> <addr> <nelems>

  Read memory and return as a Tcl array for script processing

- array2mem <varname> <width> <addr> <nelems>

  Convert a Tcl array to memory locations and write the values

- ocd_flash_banks <driver> <base> <size> <chip_width> <bus_width> <target> [`driver options` ...]

  Return information about the flash banks

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".

### 21.3 OpenOCD specific Global Variables

Real Tcl has ::tcl_platform(), and platform::identify, and many other variables. JimTCL, as implemented in OpenOCD creates $ocd_HOSTOS which holds one of the following values:

- cygwin Running under Cygwin
- darwin Darwin (Mac-OS) is the underlying operating sytem.
- freebsd Running under FreeBSD
- linux Linux is the underlying operating sytem
- mingw32 Running under MingW32
- winxx Built using Microsoft Visual Studio
- other Unknown, none of the above.

Note: 'winxx' was choosen because today (March-2009) no distinction is made between Win32 and Win64.

> Note: We should add support for a variable like Tcl variable `tcl_platform(platform)`, it should be called `jim_platform` (because it is jim, not real tcl).