Laurentiu Cocanu - integrated new tcl target command docs

git-svn-id: svn://svn.berlios.de/openocd/trunk@1073 b42882b7-edfa-0310-969c-e2dbd0fdcd60

2 files changed, 443 insertions, 427 deletions

diff --git a/doc/README_TARGET_COMMAND.txt b/doc/README_TARGET_COMMAND.txt
deleted file mode 100644
index b02e4881..00000000
--- a/doc/README_TARGET_COMMAND.txt
+++ /dev/null
@@ -1,427 +0,0 @@
-To be incorporated in openocd.texi...
-
-
-==
-Current as of Aug 30, 2008 - Duane Ellis
-==
-
-===================================================
-Overview - History
-
-  Pre "tcl" - many commands in openocd where implimented as C
-  functions.  Post "tcl" (Jim-Tcl to be more exact, June 2008 ...) TCL
-  became a bigger part of OpenOCD.
-
-One of the biggest changes is the introduction of 'target specific'
-commands. When every you create a target, a special command name is
-created specifically for that target.
-
-	For example - in Tcl/Tk - if you create a button (or any other
-	screen object) you can specify various "button configuration
-	parameters". One of those parameters is the "object cmd/name"
-	[ In TK - this is refered to as the object path ]. Later you
-	can use that 'path' as a command to modify the button, for
-	example to make it "grey", or change the color.
-
-In effect, the "path" function is an 'object oriented command'
-
-The TCL change in OpenOCD follows the same principle, you create a
-target, and a specific "targetname" command is created.
-
-There are two methods of creating a target.
-
-  (1) Depricated: Using the old syntax Target names are autogenerated
-      as: "target0", "target1" etc..
-
-  (2) Using the new syntax, you can specify the name of the target.
-
-As most users will have a single JTAG target, and by default the
-command name will probably default to "target0", thus for reasons of
-simplicity the instructions below use the name 'target0'
-
-Overview - History *END*
-==================================================
-
-OpenOCD has the following 'target' or 'target-like' commands.
-
-(1) targets -(plural) lists all known targets and a little bit of
-    information about each target, most importantly the target
-    *COMMAND*NAME* (it also lists the target number)
-
-(2) target -(singular) used to create, configure list, etc the targets
-
-(3) target0 - the command object for the first target.
-    Unless you specified another name.
-
-===================================================
-
-The "targets" (plural, 1 above) command has 2 functions.
-
-With a parameter, you can change the current command line target.
-
-     NOTE: "with a parameter" is really only useful with 'multiple
-     jtag targets' not something you normally encounter (ie: If you
-     had 2 arm chips - sharing the same JTAG chain)
-
-     # using a target name..
-    (gdb) mon targets target0
-     # or a target by number.
-    (gdb) mon targets 3
-
-Or - plain, without any parameter lists targets, for example:
-
-    (gdb) mon targets
-    	      CmdName    Type       Endian     ChainPos State     
-	  --  ---------- ---------- ---------- -------- ----------
-	   0: target0    arm7tdmi   little     0        halted
-
-This shows:
-   (a) in this example, a single target
-   (b) target number 0 (1st column)
-   (c) the 'object name' is target0 (the default name)
-   (d) it is an arm7tdmi
-   (e) little endian 
-   (f) The position in the JTAG chain
-   (g) and is currently halted.
-
-====================================================
-
-The "target" (singular, 2 above) command has the following options:
-
-    target create CMDNAME TYPE  ... config options ...
-    	  argv[0] = 'target'
-	  argv[1] = 'create'
-	  argv[2] = the 'object command'
-                  (normally, target0, see (3) above)
-	  argv[3] = the target type, ie: arm7tdmi
-	  argv[4..N] = configuration parameters
-    
-    target types
-    	   Lists all supported target types.
-	   ie: arm7tdmi, xscale, fericon, cortex-m3
-	   
-	   The result TCL List of all known target types (and is human
-	   readable)
- 
-    target names
-
-    	   Returns a TCL list of all known target commands (and is
-	   human readable)
-
-	   Example:
-		foreach t [target names] {
-		    puts [format "Target: %s\n" $t]
-		}
-
-
-    target current
-
-    	   Returns the TCL command name of the current target.
-
-	   Example:
-		set ct [target current]
-		set t  [$ct cget -type]
-		
-		puts "Current target name is: $ct, and is a: $t"
-
-
-    target number <VALUE>
-
-    	   Returns the TCL command name of the specified target.
-	   For example 
-
-	       set thename [target number $x]
-	       puts [format "Target %d is: %s\n" $x $thename]
-
-	   For instance, assuming the defaults
-
-	       target number 0
-
-	   Would return 'target0' (or whatever you called it)
-
-    target count
-
-    	   Returns the larget+1 target number.
-	   For example:
-
-	       set c [target count]
-	       for { set x 0 } { $x < $c } { incr x } {
-	       	   # Assuming you have this function..
-	       	   print_target_details $x
-	       }
-
-====================================================
-
-"target0" - (#3 above) the "Target Object" command.
-
-  Once a target is 'created' a command object by that targets name is
-  created, for example
-
-  target create BiGRed arm7tdmi -endian little -chain-position 3
-
-Would create a [case sensative] "command" BiGRed
-
-If you use the old [deprecated] syntax, the name is automatically
-generated and is in the form:
-
-	  target0, target1, target2, target3, .... etc.
-
-====================================================
-
-** Target CREATE, CONFIGURE and CGET options **
-
-The commands:
-    
-    target create CMDNAME TYPE  [configure-options]
-    CMDNAME configure [configure-options]
-    CMDNAME cget      [configure-options]
-
-In the 'create' case, one is creating the target and can specify any
-number of configuration parameters.
-
-In the 'CMDNAME cget' case, the goal is to query the target for a
-specific configuration option.
-
-In the 'CMDNAME configure' case, one can change the setting.
-[Not all things can, or should be changed]
-
-In the above, the "default" name target0 is 'target0'
-
-Example:
-
-   From the (gdb) prompt, one can type this:
-
-       (gdb) mon target0 configure -endian big
-
-   And change target0 to 'big-endian'.  This is a contrived example,
-   specifically for this document - don't expect changing endian
-   'mid-operation' to work you should set the endian at creation.
-
-Known options [30/august/2008] are:
-
-[Manditory 'create' Options]
-       -type arm7tdmi|arm720|etc ...
-       -chain-position NUMBER
-       -endian ENDIAN
-
-Optional
-
-       -event EVENTNAME  "tcl-action"
-       -reset RESETACTION
-       -work-area-virt ADDR
-       -work-area-phys ADDR
-       -work-area-size ADDR
-       -work-area-backup BOOLEAN
-
-[Hint: To get a list of avaialable options, try this]
-
-       (gdb) mon target0 cget -BLAHBLAHBLAH
-
-    the abov causes an error - and a helpful list of valid options.
-
-==================================================
-** Example Target Configure Query **
-
-One can query any of the above options at run time, for example:
-
- (gdb) mon target0 cget -OPTION [param]
-
-Example TCL script
-
-    # For all targets...
-    set c [target count]
-    for { set x 0 } { $x < $c } { incr x ] {
-      set n [target number $x]
-      set t [$n cget -type]
-      set e [$n cget -endian]
-      puts [format "%d: %s, %s, endian: %s\n" $x $n $t $n]
-   }
-
-Might produce:
-      0: pic32chip, mips_m4k, endain: little
-      1: arm7, arm7tdmi, endian: big
-      2: blackfin, bf534, endian: little
-
-Notice the above example is not target0, target1, target2 Why? Because
-in this contrived multi-target example - more human understandable
-target names might be helpful. 
-
-For example these two are the same:
-
-   (gdb) mon blackfin configure -event FOO {puts "Hi mom"}
-
-or:
-   (gdb) mon [target number 2] configure -event FOO {puts "Hi mom"}
-
-In the second case, we use [] to get the command name of target #2, in
-this contrived example - it is "blackfin"
-
-====================================================
-** TWO Important Configure Options Are: **
-
-Two important configuration options are:
-
-    "-event" and "-reset"
-
-The "-reset" option specifies what should happen when the chip is
-reset, for example should it 'halt', 're-init', or what.
-
-The "-event" option less you specifiy a TCL command to occur when a
-specific event occurs.
-
-====================================================
-** Target Events * Overview **
-
-At various points in time - certian 'target' events happen.  You can
-create a custom event action to occur at that time.
-
-For example - after reset, the PLLs and CLOCKs may need to be
-reconfigured, or perhaps the SDRAM needs to be re-initialized
-
-Often the easiest way to do that is to create a simple script file
-containing the series of (mww [poke memory]) commands you would type
-by hand, to reconfigure the target clocks. You could specify the
-"event action" like this:
-
-   (gdb) mon target0 configure -event reset-init "script cfg.clocks"
-
-In the above example, when the event "reset-init" occurs, the
-"action-string" will be evaluated as if you typed it at the console
-
-Option1 - 
-
-	The simple approach (above) is to create a script file with
-	lots of "mww" (memory write word) commands to configure your
-	targets clocks and/or external memory.
-
-Option2 -
-
-	You can instead create a fancy Tcl procedure and invoke that
-	procedure instead of sourcing a file.
-
-	[Infact, "script" is a TCL procedure that loads a file]
-
-==================================================
-
-** Target Events * Details **
-
-There are many events one could use, to get a current list of events
-type the following invalid command, you'll get a helpful "runtime
-error" message, see below: [list valid as of 30/august/2008]
-
-   (gdb) mon target0 cget -event FAFA
-
-Runtime error, file "../../../openocd23/src/helper/command.c", line 433:
-    -event: Unknown: FAFA, try one of: old-pre_reset, 
-    old-gdb_program_config, old-post_reset, halted, 
-    resumed, resume-start, resume-end, reset-start, 
-    reset-assert-pre, reset-assert-post, 
-    reset-deassert-pre, reset-deassert-post, 
-    reset-halt-pre, reset-halt-post, reset-wait-pre, 
-    reset-wait-post, reset-init, reset-end, 
-    examine-start, examine-end, debug-halted, 
-    debug-resumed, gdb-attach, gdb-detach, 
-    gdb-flash-write-start, gdb-flash-write-end, 
-    gdb-flash-erase-start, gdb-flash-erase-end, 
-    resume-start, resume-ok, or resume-end
-
-NOTE:
-
-    The event-names "old-*" are deprecated and exist only to help old
-    scripts continue to function, and the old "target_script" command
-    to work. Please do not rely on them.
-
-These are some other important names.
-
-    gdb-flash-erase-start
-    gdb-flash-erase-end
-    gdb-flash-write-start
-    gdb-flash-write-end
-
-    These occur when GDB/OpenOCD attempts to erase & program the FLASH
-    chip via GDB.
-
-    For example - some PCBs may have a simple GPIO pin that acts like
-    a "flash write protect" you might need to write a script that
-    disables "write protect"
-
-==================================================
-
-** How to get a list of current event actions **
-
-To get a list of current 'event actions', type the following command:
-
-   (gdb) mon target0 eventlist
-
-    Event actions for target (0) target0
-
-    Event                     | Body
-    ------------------------- | ----------------------------------------
-    old-post_reset            | script event/sam7x256_reset.script
-    ***END***
-
-Here is a simple example for all targets:
-
-   (gdb)  mon foreach x [target names] { $x eventlist }
-
-The above uses some TCL tricks:
-
-   (a) foreach VARIABLE  LIST  BODY
-
-   (b) to generate the list, we use [target names]
-   
-   (c) the BODY, contains $x - the loop variable
-       and expands to the target specific name
-
-====================================================
-
-Recalling the earlier discussion - the "object command" there are 
-other things you can do besides "configure" the target.
-
-Note: Many of these commands exist as "global" commands, and they also
-exist as target specific commands.
-
-For example, the "mww" (memory write word) operates on the current target
-if you have more then 1 target, you must switch
-
-In contrast to the normal commands, these commands operate on the
-specific target. For example, the command "mww" writes data to the
-*current* command line target. 
-
-Often, you have only a single target - but if you have multiple
-targets (ie: a PIC32 and an at91sam7 - your reset-init scripts might
-get a bit more complicated, ie: you must specify which of the two
-chips you want to write to. Writing 'pic32' clock configuration to an
-at91sam7 does not work)
-
-The commands are: [as of 30/august/2008]
-
-    TNAME  mww ADDRESS VALUE
-    TNAME  mwh ADDRESS VALUE
-    TNAME  mwb ADDRESS VALUE
-    	   Write(poke): 32, 16, 8bit values to memory.
-
-    TNAME  mdw ADDRESS VALUE
-    TNAME  mdh ADDRESS VALUE
-    TNAME  mdb ADDRESS VALUE
-    	   Human 'hexdump' with ascii 32, 16, 8bit values
-
-    TNAME  mem2array  [see mem2array command]
-    TNAME  array2mem  [see array2mem command]
-
-    TNAME  curstate
-    	  Returns the current state of the target.
-
-
-    TNAME examine
-    	  See 'advanced target reset'
-    TNAME poll
-    	  See 'advanced target reset'
-    TNAME reset assert
-    	  See 'advanced target reset'
-    TNAME reset deassert
-    	  See 'advanced target reset'
-    TNAME halt
-    	  See 'advanced target reset'
-    TNAME waitstate STATENAME
-    	  See 'advanced target reset'
diff --git a/doc/openocd.texi b/doc/openocd.texi
index 472bd895..8c8be259 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -981,6 +981,449 @@ to a <@var{file}>.
 @end itemize
 
 @page
+@section Target Commands
+@cindex Target Commands
+
+@subsection Overview
+@cindex Overview
+Pre "TCL" - many commands in OpenOCD where implemented as C functions. Post "TCL" 
+(Jim-Tcl to be more exact, June 2008) TCL became a bigger part of OpenOCD.
+
+One of the biggest changes is the introduction of 'target specific'
+commands. When every time you create a target, a special command name is
+created specifically for that target.
+For example - in TCL/TK - if you create a button (or any other screen object) you 
+can specify various "button configuration parameters". One of those parameters is 
+the "object cmd/name" [ In TK - this is referred to as the object path ]. Later 
+you	can use that 'path' as a command to modify the button, for example to make it 
+"grey", or change the color. In effect, the "path" function is an 'object 
+oriented command'. The TCL change in OpenOCD follows the same principle, you create 
+a target, and a specific "targetname" command is created.
+
+There are two methods of creating a target:
+
+@enumerate
+@item
+Using the old syntax (deprecated). Target names are autogenerated as: 
+  "target0", "target1", etc.;
+@cindex old syntax
+@item
+Using the new syntax, you can specify the name of the target.
+@cindex new syntax
+@end enumerate
+
+As most users will have a single JTAG target, and by default the command name will 
+probably default to "target0", thus for reasons of simplicity the instructions below 
+use the name "target0".
+
+@subsection Commands
+@cindex Commands
+OpenOCD has the following 'target' or 'target-like' commands:
+
+@enumerate
+@item
+@b{targets (plural)} - lists all known targets and a little bit of information about each 
+	target, most importantly the target *COMMAND*NAME* (it also lists the target number);
+@cindex targets
+@item
+@b{target (singular)} - used to create, configure list, etc the targets;
+@cindex target
+@item
+@b{target0} - the command object for the first target. Unless you specified another name.
+@cindex target0
+@end enumerate
+
+@subsubsection Targets Command
+@cindex Targets Command
+The "targets" command has 2 functions:
+
+@itemize
+@item
+With a parameter, you can change the current command line target.
+
+NOTE: "with a parameter" is really only useful with 'multiple JTAG targets' not something 
+you normally encounter (ie: If you had 2 arm chips - sharing the same JTAG chain).
+@verbatim
+# using a target name.
+(gdb) mon targets target0
+# or a target by number.
+(gdb) mon targets 3
+@end verbatim
+@cindex with a parameter
+@item
+Plain, without any parameter lists targets, for example:
+
+@verbatim
+(gdb) mon targets
+      CmdName     Type     Endian    ChainPos   State     
+--  ---------- ---------- ---------- -------- ----------
+    0: target0  arm7tdmi   little        0      halted
+@end verbatim
+
+This shows:
+@enumerate a
+@item
+in this example, a single target;
+@item
+target number 0 (1st column);
+@item
+the 'object name' is target0 (the default name);
+@item
+it is an arm7tdmi;
+@item
+little endian;
+@item
+the position in the JTAG chain;
+@item 
+and is currently halted.
+@end enumerate
+@cindex without any parameter
+@end itemize
+
+@subsubsection Target Command
+@cindex Target Command
+
+The "target" command has the following options:
+@itemize
+@item
+target create
+
+@verbatim
+	target create CMDNAME TYPE  ... config options ...
+		argv[0] = 'target'
+		argv[1] = 'create'
+		argv[2] = the 'object command'
+	               (normally, target0, see (3) above)
+		argv[3] = the target type, ie: arm7tdmi
+		argv[4..N] = configuration parameters
+@end verbatim
+@item
+target types
+
+  	Lists all supported target types; ie: arm7tdmi, xscale, fericon, cortex-m3.
+	The result TCL list of all known target types (and is human readable).
+@item
+target names
+
+	Returns a TCL list of all known target commands (and is human readable).
+
+	Example:
+@verbatim  
+	foreach t [target names] {
+	    puts [format "Target: %s\n" $t]
+	}
+@end verbatim
+@item   
+target current
+
+    Returns the TCL command name of the current target.
+
+	Example:
+@verbatim 
+	set ct [target current]
+	set t  [$ct cget -type]
+		
+	puts "Current target name is: $ct, and is a: $t"
+@end verbatim
+@item
+target number <VALUE>
+
+ 	Returns the TCL command name of the specified target.
+	   
+	Example 
+@verbatim
+    set thename [target number $x]
+    puts [format "Target %d is: %s\n" $x $thename]
+@end verbatim
+	For instance, assuming the defaults
+@verbatim
+    target number 0
+@end verbatim
+	Would return 'target0' (or whatever you called it)
+@item
+target count
+
+ 	Returns the larget+1 target number.
+	
+	Example:
+@verbatim
+    set c [target count]
+    for { set x 0 } { $x < $c } { incr x } {
+       	# Assuming you have this function..
+       	print_target_details $x
+    }
+@end verbatim
+@end itemize
+
+@subsubsection Target0 Command
+@cindex Target0 Command
+The "target0" command (the "Target Object" command):
+
+Once a target is 'created' a command object by that targets name is created, for example
+@verbatim
+	target create BiGRed arm7tdmi -endian little -chain-position 3
+@end verbatim
+
+Would create a [case sensitive] "command" BiGRed
+
+If you use the old [deprecated] syntax, the name is automatically
+generated and is in the form:
+@verbatim
+	target0, target1, target2, target3, ... etc.
+@end verbatim
+
+@subsubsection Target CREATE, CONFIGURE and CGET Options Command
+@cindex Target CREATE, CONFIGURE and CGET Options Command
+The commands:
+@verbatim
+    target create CMDNAME TYPE  [configure-options]	
+    CMDNAME configure [configure-options]
+    CMDNAME cget      [configure-options]
+@end verbatim
+@itemize
+@item
+In the 'create' case, one is creating the target and can specify any
+number of configuration parameters.
+@item
+In the 'CMDNAME configure' case, one can change the setting [Not all things can, or should be changed].
+@item
+In the 'CMDNAME cget' case, the goal is to query the target for a
+specific configuration option.
+@end itemize
+
+In the above, the "default" name target0 is 'target0'.
+
+	Example:
+
+		From the (gdb) prompt, one can type this:
+
+@verbatim
+	(gdb) mon target0 configure -endian big
+@end verbatim
+
+		And change target0 to 'big-endian'.  This is a contrived example,
+		specifically for this document - don't expect changing endian
+		'mid-operation' to work you should set the endian at creation.
+
+Known options [30/august/2008] are:
+@itemize
+@item
+[Mandatory 'create' Options]
+	@itemize
+	@item
+    type arm7tdmi|arm720|etc ...
+	@item
+    chain-position NUMBER
+	@item
+    endian ENDIAN
+	@end itemize
+@item
+Optional
+	@itemize
+	@item
+    event EVENTNAME  "tcl-action"
+	@item
+    reset RESETACTION
+	@item
+    work-area-virt ADDR
+	@item
+    work-area-phys ADDR
+	@item
+    work-area-size ADDR
+	@item
+    work-area-backup BOOLEAN
+	@end itemize
+@end itemize
+Hint: To get a list of available options, try this:
+@verbatim
+	(gdb) mon target0 cget -BLAHBLAHBLAH
+@end verbatim
+
+    the above causes an error - and a helpful list of valid options.
+	
+One can query any of the above options at run time, for example:
+@verbatim
+ (gdb) mon target0 cget -OPTION [param]
+@end verbatim
+
+Example TCL script
+
+@verbatim
+    # For all targets...
+    set c [target count]
+    for { set x 0 } { $x < $c } { incr x ] {
+      set n [target number $x]
+      set t [$n cget -type]
+      set e [$n cget -endian]
+      puts [format "%d: %s, %s, endian: %s\n" $x $n $t $n]
+   }
+@end verbatim
+
+Might produce:
+
+@verbatim
+    0: pic32chip, mips_m4k, endain: little
+    1: arm7, arm7tdmi, endian: big
+    2: blackfin, bf534, endian: little
+@end verbatim
+
+Notice the above example is not target0, target1, target2 Why? Because in this contrived multi-target example - 
+more human understandable target names might be helpful.
+
+For example these two are the same:
+
+@verbatim
+   (gdb) mon blackfin configure -event FOO {puts "Hi mom"}
+@end verbatim
+
+or:
+
+@verbatim
+   (gdb) mon [target number 2] configure -event FOO {puts "Hi mom"}
+@end verbatim
+   
+In the second case, we use [] to get the command name of target #2, in this contrived example - it is "blackfin".
+
+Two important configuration options are:
+
+    "-event" and "-reset"
+
+The "-reset" option specifies what should happen when the chip is reset, for example should it 'halt', 're-init', 
+or what.
+
+The "-event" option less you specify a TCL command to occur when a specific event occurs.
+
+@subsection Target Events
+@cindex Target Events
+
+@subsubsection Overview
+@cindex Overview
+At various points in time - certain 'target' events happen.  You can create a custom event action to occur at that time.
+For example - after reset, the PLLs and CLOCKs may need to be reconfigured, or perhaps the SDRAM needs to be re-initialized.
+Often the easiest way to do that is to create a simple script file containing the series of (mww [poke memory]) commands 
+you would type by hand, to reconfigure the target clocks. You could specify the "event action" like this:
+
+@verbatim
+   (gdb) mon target0 configure -event reset-init "script cfg.clocks"
+@end verbatim
+
+In the above example, when the event "reset-init" occurs, the "action-string" will be evaluated as if you typed it at the 
+console:
+@itemize
+@item @b{Option1} - The simple approach (above) is to create a script file with lots of "mww" (memory write word) commands 
+	to configure your targets clocks and/or external memory;
+@item @b{Option2} -	You can instead create a fancy TCL procedure and invoke that procedure instead of sourcing a file [In fact, 
+	"script" is a TCL procedure that loads a file].
+@end itemize
+
+@subsubsection Details
+@cindex Details
+There are many events one could use, to get a current list of events type the following invalid command, you'll get a helpful 
+"runtime error" message, see below [list valid as of 30/august/2008]:
+
+@verbatim
+(gdb) mon target0 cget -event FAFA
+Runtime error, file "../../../openocd23/src/helper/command.c", line 433:
+	-event: Unknown: FAFA, try one of: old-pre_reset, 
+	old-gdb_program_config, old-post_reset, halted, 
+	resumed, resume-start, resume-end, reset-start, 
+	reset-assert-pre, reset-assert-post, 
+	reset-deassert-pre, reset-deassert-post, 
+	reset-halt-pre, reset-halt-post, reset-wait-pre, 
+	reset-wait-post, reset-init, reset-end, 
+	examine-start, examine-end, debug-halted, 
+	debug-resumed, gdb-attach, gdb-detach, 
+	gdb-flash-write-start, gdb-flash-write-end, 
+	gdb-flash-erase-start, gdb-flash-erase-end, 
+	resume-start, resume-ok, or resume-end
+@end verbatim
+
+NOTE: The event-names "old-*" are deprecated and exist only to help old scripts continue to function, and the old "target_script" 
+command to work. Please do not rely on them.
+
+These are some other important names:
+@itemize
+@item gdb-flash-erase-start
+@item gdb-flash-erase-end
+@item gdb-flash-write-start
+@item gdb-flash-write-end
+@end itemize
+
+These occur when GDB/OpenOCD attempts to erase & program the FLASH chip via GDB. For example - some PCBs may have a simple GPIO 
+pin that acts like a "flash write protect" you might need to write a script that disables "write protect".
+
+To get a list of current 'event actions', type the following command:
+
+@verbatim
+   (gdb) mon target0 eventlist
+
+    Event actions for target (0) target0
+
+    Event                     | Body
+    ------------------------- | ----------------------------------------
+    old-post_reset            | script event/sam7x256_reset.script    
+@end verbatim
+
+Here is a simple example for all targets:
+
+@verbatim
+   (gdb)  mon foreach x [target names] { $x eventlist }
+@end verbatim
+
+The above uses some TCL tricks:
+@enumerate a
+@item foreach VARIABLE  LIST  BODY
+@item to generate the list, we use [target names]
+@item the BODY, contains $x - the loop variable and expands to the target specific name
+@end enumerate
+
+Recalling the earlier discussion - the "object command" there are other things you can 
+do besides "configure" the target.
+
+Note: Many of these commands exist as "global" commands, and they also exist as target 
+specific commands. For example, the "mww" (memory write word) operates on the current 
+target if you have more then 1 target, you must switch. In contrast to the normal 
+commands, these commands operate on the specific target. For example, the command "mww" 
+writes data to the *current* command line target. 
+
+Often, you have only a single target - but if you have multiple targets (ie: a PIC32 
+and an at91sam7 - your reset-init scripts might get a bit more complicated, ie: you must 
+specify which of the two chips you want to write to. Writing 'pic32' clock configuration 
+to an at91sam7 does not work).
+
+The commands are [as of 30/august/2008]:
+@verbatim
+    TNAME  mww ADDRESS VALUE
+    TNAME  mwh ADDRESS VALUE
+    TNAME  mwb ADDRESS VALUE
+    	   Write(poke): 32, 16, 8bit values to memory.
+
+    TNAME  mdw ADDRESS VALUE
+    TNAME  mdh ADDRESS VALUE
+    TNAME  mdb ADDRESS VALUE
+    	   Human 'hexdump' with ascii 32, 16, 8bit values
+
+    TNAME  mem2array  [see mem2array command]
+    TNAME  array2mem  [see array2mem command]
+
+    TNAME  curstate
+    	   Returns the current state of the target.
+
+    TNAME  examine
+    	   See 'advanced target reset'
+    TNAME  poll
+    	   See 'advanced target reset'
+    TNAME  reset assert
+    	   See 'advanced target reset'
+    TNAME  reset deassert
+    	   See 'advanced target reset'
+    TNAME  halt
+    	   See 'advanced target reset'
+    TNAME  waitstate STATENAME
+    	   See 'advanced target reset'
+@end verbatim
+
+@page
 @section Target Specific Commands
 @cindex Target Specific Commands