- fix tcl_port typo in docs

[openocd.git] / doc / README_TARGET_COMMAND.txt

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'