21 Tcl Scripting API

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

21.2 Internal low-level Commands

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

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

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

It is not needed anymore to prefix the OpenOCD commands with ocd_ to get the results back. But sometimes you might need the capture command.

See contrib/rpc_examples/ for specific client implementations.

21.4 Tcl RPC server notifications

Notifications are sent asynchronously to other commands being executed over the RPC server, so the port must be polled continuously.

Target event, state and reset notifications are emitted as Tcl associative arrays in the following format.

type target_event event [event-name]
type target_state state [state-name]
type target_reset mode [reset-mode]

Command: tcl_notifications [on/off]

Toggle output of target notifications to the current Tcl RPC server. Only available from the Tcl RPC server. Defaults to off.

21.5 Tcl RPC server trace output

Trace data is sent asynchronously to other commands being executed over the RPC server, so the port must be polled continuously.

Target trace data is emitted as a Tcl associative array in the following format.

type target_trace data [trace-data-hex-encoded]

Command: tcl_trace [on/off]

Toggle output of target trace data to the current Tcl RPC server. Only available from the Tcl RPC server. Defaults to off.

See an example application here: https://github.com/apmorton/OpenOcdTraceUtil [OpenOcdTraceUtil]