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.