tcl: introduce init_target_events and use it for gdb flashing events

[openocd.git] / doc / openocd.texi

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 76e335b8f23c2466606b37baaa65a18b4b759223..3977454bba8b7dae71b780cb222b3cf2df06e708 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -666,7 +666,9 @@ to benefit from new features and bugfixes in Jim-Tcl.
 
 Properly installing OpenOCD sets up your operating system to grant it access
 to the debug adapters. On Linux, this usually involves installing a file
-in @file{/etc/udev/rules.d,} so OpenOCD has permissions. MS-Windows needs
+in @file{/etc/udev/rules.d,} so OpenOCD has permissions. An example rules file
+that works for many common adapters is shipped with OpenOCD in the
+@file{contrib} directory. MS-Windows needs
 complex and confusing driver configuration for every peripheral. Such issues
 are unique to each operating system, and are not detailed in this User's Guide.
 
@@ -2107,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
@@ -4575,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}
@@ -5687,6 +5701,23 @@ unlock str9 device.
 
 @end deffn
 
+@deffn {Flash Driver} nrf51
+All members of the nRF51 microcontroller families from Nordic Semiconductor
+include internal flash and use ARM Cortex-M0 core.
+
+@example
+flash bank $_FLASHNAME nrf51 0 0x00000000 0 0 $_TARGETNAME
+@end example
+
+Some nrf51-specific commands are defined:
+
+@deffn Command {nrf51 mass_erase}
+Erases the contents of the code memory and user information
+configuration registers as well. It must be noted that this command
+works only for chips that do not have factory pre-programmed region 0
+code.
+@end deffn
+@end deffn
 
 @section mFlash
 
@@ -8410,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.
 
@@ -8424,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
@@ -8458,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