tcl: introduce init_target_events and use it for gdb flashing events

[openocd] / doc / openocd.texi

diff --git a/doc/openocd.texi b/doc/openocd.texi
index d4930de59fef6a2decf058b562339778847a602e..3977454bba8b7dae71b780cb222b3cf2df06e708 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -2109,6 +2109,17 @@ For an example of this scheme see LPC2000 target config files.
 The @code{init_boards} procedure is a similar concept concerning board config files
 (@xref{theinitboardprocedure,,The init_board procedure}.)
 
+@anchor{theinittargeteventsprocedure}
+@subsection The init_target_events procedure
+@cindex init_target_events procedure
+
+A special procedure called @code{init_target_events} is run just after
+@code{init_targets} (@xref{theinittargetsprocedure,,The init_targets
+procedure}.) and before @code{init_board}
+(@xref{theinitboardprocedure,,The init_board procedure}.) It is used
+to set up default target events for the targets that do not have those
+events already assigned.
+
 @subsection ARM Core Specific Hacks
 
 If the chip has a DCC, enable it. If the chip is an ARM9 with some
@@ -4577,13 +4588,14 @@ depending on whether the breakpoint is in RAM or read only memory.
 @item @b{gdb-end}
 @* When the target has halted and GDB is not doing anything (see early halt)
 @item @b{gdb-flash-erase-start}
-@* Before the GDB flash process tries to erase the flash
+@* Before the GDB flash process tries to erase the flash (default is
+@code{reset init})
 @item @b{gdb-flash-erase-end}
 @* After the GDB flash process has finished erasing the flash
 @item @b{gdb-flash-write-start}
 @* Before GDB writes to the flash
 @item @b{gdb-flash-write-end}
-@* After GDB writes to the flash
+@* After GDB writes to the flash (default is @code{reset halt})
 @item @b{gdb-start}
 @* Before the target steps, gdb is trying to start/resume the target
 @item @b{halted}
@@ -8429,7 +8441,7 @@ should be passed in to the proc in question.
 By "low-level," we mean commands that a human would typically not
 invoke directly.
 
-Low-level commands are (should be) prefixed with "ocd_"; e.g.
+Some low-level commands need to be prefixed with "ocd_"; e.g.
 @command{ocd_flash_banks}
 is the low-level API upon which @command{flash banks} is implemented.
 
@@ -8443,6 +8455,16 @@ Convert a Tcl array to memory locations and write the values
 @item @b{ocd_flash_banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...]
 
 Return information about the flash banks
+
+@item @b{capture} <@var{command}>
+
+Run <@var{command}> and return full log output that was produced during
+its execution. Example:
+
+@example
+> capture "reset init"
+@end example
+
 @end itemize
 
 OpenOCD commands can consist of two words, e.g. "flash banks". The
@@ -8477,6 +8499,24 @@ We should add support for a variable like Tcl variable
 is jim, not real tcl).
 @end quotation
 
+@section Tcl RPC server
+@cindex RPC
+
+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 @command{tcl_port}). Then it can pass any string to the
+interpreter terminating it with @code{0x1a} and wait for the return
+value (it will be terminated with @code{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
+@code{ocd_} to get the results back. Sometimes you might also need the
+@command{capture} command.
+
+See @file{contrib/rpc_examples/} for specific client implementations.
+
 @node FAQ
 @chapter FAQ
 @cindex faq