Removed target->reset_mode, no longer used

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

1 files changed, 427 insertions, 0 deletions

diff --git a/doc/README_TARGET_COMMAND.txt b/doc/README_TARGET_COMMAND.txt
new file mode 100644
index 00000000..b02e4881
--- /dev/null
+++ b/doc/README_TARGET_COMMAND.txt
@@ -0,0 +1,427 @@
+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'