## 23 Tcl Scripting API

### 23.1 API rules

Tcl commands are stateless; e.g. the `telnet` command 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 should be relatively small. Otherwise, a range should be passed in to the proc in question.

### 23.2 Internal low-level Commands

By "low-level," we mean commands that a human would typically not invoke directly.

Some low-level commands need to 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

- capture <command>

  Run <command> and return full log output that was produced during its execution. Example:

      > capture "reset init"

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

### 23.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
- openbsd Running under OpenBSD
- netbsd Running under NetBSD
- linux Linux is the underlying operating sytem
- mingw32 Running under MingW32
- winxx Built using Microsoft Visual Studio
- ecos Running under eCos
- 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).

### 23.4 Tcl RPC server

OpenOCD provides a simple RPC server that allows to run arbitrary Tcl commands and receive the results.

To access it, your application needs to connect to a configured TCP port (see `tcl_port`). Then it can pass any string to the interpreter terminating it with `0x1a` and wait for the return value (it will be terminated with `0x1a` as well). This can be repeated as many times as desired without reopening the connection.

Remember that most of the OpenOCD commands need to be prefixed with `ocd_` to get the results back. Sometimes you might also need the `capture` command.

See `contrib/rpc_examples/` for specific client implementations.