* Commands:: OpenOCD Commands
* Sample Scripts:: Sample Target Scripts
* GDB and OpenOCD:: Using GDB and OpenOCD
+* TCL and OpenOCD:: Using TCL and OpenOCD
+* TCL scripting API:: Tcl scripting API
* Upgrading:: Deprecated/Removed Commands
* FAQ:: Frequently Asked Questions
* License:: GNU Free Documentation License
@option{--enable-presto_libftdi}
@item
@option{--enable-presto_ftd2xx}
+@item
+@option{--enable-jlink}
@end itemize
If you want to access the parallel port using the PPDEV interface you have to specify
@cindex --debug_level
@cindex --logfile
@cindex --search
-OpenOCD runs as a daemon, waiting for connections from clients (Telnet or GDB).
+OpenOCD runs as a daemon, waiting for connections from clients (Telnet, GDB, Other).
Run with @option{--help} or @option{-h} to view the available command line switches.
It reads its configuration by default from the file openocd.cfg located in the current
requested. gdb will then know when to set hardware breakpoints, and program flash
using the gdb load command. @option{gdb_flash_program enable} will also need enabling
for flash programming to work.
-Default behaviour is <@var{disable}>
+Default behaviour is <@var{enable}>
@item @b{gdb_flash_program} <@var{enable|disable}>
@cindex gdb_flash_program
Set to <@var{enable}> to cause OpenOCD to program the flash memory when a
vFlash packet is received.
Default behaviour is <@var{enable}>
-@item @b{daemon_startup} <@var{mode}>
-@cindex daemon_startup
-@option{mode} can either @option{attach} or @option{reset}
-This is equivalent to adding "init" and "reset" to the end of the config script.
-
-It is available as a command mainly for backwards compatibility.
+ at item @b{tcl_port} <@var{number}>
+ at cindex tcl_port
+Port on which to listen for incoming TCL syntax. This port is intended as
+a simplified RPC connection that can be used by clients to issue commands
+and get the output from the TCL engine.
@end itemize
@section JTAG interface configuration
@item @b{gw16012}
Gateworks GW16012 JTAG programmer.
@end itemize
+@itemize @minus
+@item @b{jlink}
+Segger jlink usb adapter
+@end itemize
@end itemize
@itemize @bullet
@item wiggler: maximum speed / @var{number}
@item ft2232: 6MHz / (@var{number}+1)
@item amt jtagaccel: 8 / 2**@var{number}
+@item jlink: maximum speed in kHz (0-12000), 0 will use RTCK
@end itemize
Note: Make sure the jtag clock is no more than @math{1/6th × CPU-Clock}. This is
@section Target configuration
@itemize @bullet
-@item @b{target} <@var{type}> <@var{endianess}> <@var{reset_mode}> <@var{JTAG pos}>
+@item @b{target} <@var{type}> <@var{endianess}> <@var{JTAG pos}>
<@var{variant}>
@cindex target
Defines a target that should be debugged. Currently supported types are:
Endianess may be @option{little} or @option{big}.
-The reset_mode specifies what should happen to the target when a reset occurs:
-@itemize @minus
-@item @b{reset_halt}
-@cindex reset_halt
-Immediately request a target halt after reset. This allows targets to be debugged
-from the very first instruction. This is only possible with targets and JTAG
-interfaces that correctly implement the reset signals.
-@item @b{reset_init}
-@cindex reset_init
-Similar to @option{reset_halt}, but executes the script file defined to handle the
-'reset' event for the target. Like @option{reset_halt} this only works with
-correct reset implementations.
-@item @b{reset_run}
-@cindex reset_run
-Simply let the target run after a reset.
-@item @b{run_and_halt}
-@cindex run_and_halt
-Let the target run for some time (default: 1s), and then request halt.
-@item @b{run_and_init}
-@cindex run_and_init
-A combination of @option{reset_init} and @option{run_and_halt}. The target is allowed
-to run for some time, then halted, and the @option{reset} event script is executed.
-@end itemize
On JTAG interfaces / targets where system reset and test-logic reset can't be driven
completely independent (like the LPC2000 series), or where the JTAG interface is
@item @b{target_script} <@var{target#}> <@var{event}> <@var{script_file}>
@cindex target_script
-Event is either @option{reset}, @option{post_halt}, @option{pre_resume} or @option{gdb_program_config}
+Event is one of the following:
+@option{pre_reset}, @option{reset}, @option{post_reset}, @option{post_halt},
+@option{pre_resume} or @option{gdb_program_config}.
+@option{post_reset} and @option{reset} will produce the same results.
-TODO: describe exact semantic of events
@item @b{run_and_halt_time} <@var{target#}> <@var{time_in_ms}>
@cindex run_and_halt_time
The amount of time the debugger should wait after releasing reset before it asserts
@subsection arm7tdmi options
@cindex arm7tdmi options
-target arm7tdmi <@var{endianess}> <@var{reset_mode}> <@var{jtag#}>
+target arm7tdmi <@var{endianess}> <@var{jtag#}>
The arm7tdmi target definition requires at least one additional argument, specifying
the position of the target in the JTAG daisy-chain. The first JTAG device is number 0.
The optional [@var{variant}] parameter has been removed in recent versions.
@chapter Commands
@cindex commands
-OpenOCD allows user interaction through a telnet interface
-(default: port 4444) and a GDB server (default: port 3333). The command line interpreter
+OpenOCD allows user interaction through a GDB server (default: port 3333),
+a telnet interface (default: port 4444), and a TCL interface (default: port 5555). The command line interpreter
is available from both the telnet interface and a GDB session. To issue commands to the
interpreter from within a GDB session, use the @option{monitor} command, e.g. use
@option{monitor poll} to issue the @option{poll} command. All output is relayed through the
GDB session.
+The TCL interface is used as a simplified RPC mechanism that feeds all the
+input into the TCL interpreter and returns the output from the evaluation of
+the commands.
+
@section Daemon
@itemize @bullet
@item @b{shutdown}
@cindex shutdown
-Close the OpenOCD daemon, disconnecting all clients (GDB, Telnet).
+Close the OpenOCD daemon, disconnecting all clients (GDB, Telnet, Other).
@item @b{debug_level} [@var{n}]
@cindex debug_level
Perform a hard-reset. The optional parameter specifies what should happen after the reset.
This optional parameter overrides the setting specified in the configuration file,
making the new behaviour the default for the @option{reset} command.
+
+With no arguments a "reset run" is executed
@itemize @minus
@item @b{run}
@cindex reset run
mass erase flash memory.
@end itemize
+@subsection Stellaris specific commands
+@cindex Stellaris specific commands
+
+These are flash specific commands when using the Stellaris driver.
+@itemize @bullet
+@item @b{stellaris mass_erase} <@var{num}>
+@cindex stellaris mass_erase
+mass erase flash memory.
+@end itemize
+
@page
@section Architecture Specific Commands
@cindex Architecture Specific Commands
To verify any flash programming the gdb command @option{compare-sections}
can be used.
+@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".
+
+
@node Upgrading
@chapter Deprecated/Removed Commands
@cindex Deprecated/Removed Commands
Code Review / openocd.git / blobdiff