doc/README_TARGET_COMMAND.txt

   1 To be incorporated in openocd.texi...
   2
   3
   4 ==
   5 Current as of Aug 30, 2008 - Duane Ellis
   6 ==
   7
   8 ===================================================
   9 Overview - History
  10
  11   Pre "tcl" - many commands in openocd where implimented as C
  12   functions.  Post "tcl" (Jim-Tcl to be more exact, June 2008 ...) TCL
  13   became a bigger part of OpenOCD.
  14
  15 One of the biggest changes is the introduction of 'target specific'
  16 commands. When every you create a target, a special command name is
  17 created specifically for that target.
  18
  19         For example - in Tcl/Tk - if you create a button (or any other
  20         screen object) you can specify various "button configuration
  21         parameters". One of those parameters is the "object cmd/name"
  22         [ In TK - this is refered to as the object path ]. Later you
  23         can use that 'path' as a command to modify the button, for
  24         example to make it "grey", or change the color.
  25
  26 In effect, the "path" function is an 'object oriented command'
  27
  28 The TCL change in OpenOCD follows the same principle, you create a
  29 target, and a specific "targetname" command is created.
  30
  31 There are two methods of creating a target.
  32
  33   (1) Depricated: Using the old syntax Target names are autogenerated
  34       as: "target0", "target1" etc..
  35
  36   (2) Using the new syntax, you can specify the name of the target.
  37
  38 As most users will have a single JTAG target, and by default the
  39 command name will probably default to "target0", thus for reasons of
  40 simplicity the instructions below use the name 'target0'
  41
  42 Overview - History *END*
  43 ==================================================
  44
  45 OpenOCD has the following 'target' or 'target-like' commands.
  46
  47 (1) targets -(plural) lists all known targets and a little bit of
  48     information about each target, most importantly the target
  49     *COMMAND*NAME* (it also lists the target number)
  50
  51 (2) target -(singular) used to create, configure list, etc the targets
  52
  53 (3) target0 - the command object for the first target.
  54     Unless you specified another name.
  55
  56 ===================================================
  57
  58 The "targets" (plural, 1 above) command has 2 functions.
  59
  60 With a parameter, you can change the current command line target.
  61
  62      NOTE: "with a parameter" is really only useful with 'multiple
  63      jtag targets' not something you normally encounter (ie: If you
  64      had 2 arm chips - sharing the same JTAG chain)
  65
  66      # using a target name..
  67     (gdb) mon targets target0
  68      # or a target by number.
  69     (gdb) mon targets 3
  70
  71 Or - plain, without any parameter lists targets, for example:
  72
  73     (gdb) mon targets
  74               CmdName    Type       Endian     ChainPos State
  75           --  ---------- ---------- ---------- -------- ----------
  76            0: target0    arm7tdmi   little     0        halted
  77
  78 This shows:
  79    (a) in this example, a single target
  80    (b) target number 0 (1st column)
  81    (c) the 'object name' is target0 (the default name)
  82    (d) it is an arm7tdmi
  83    (e) little endian
  84    (f) The position in the JTAG chain
  85    (g) and is currently halted.
  86
  87 ====================================================
  88
  89 The "target" (singular, 2 above) command has the following options:
  90
  91     target create CMDNAME TYPE  ... config options ...
  92           argv[0] = 'target'
  93           argv[1] = 'create'
  94           argv[2] = the 'object command'
  95                   (normally, target0, see (3) above)
  96           argv[3] = the target type, ie: arm7tdmi
  97           argv[4..N] = configuration parameters
  98
  99     target types
 100            Lists all supported target types.
 101            ie: arm7tdmi, xscale, fericon, cortex-m3
 102
 103            The result TCL List of all known target types (and is human
 104            readable)
 105
 106     target names
 107
 108            Returns a TCL list of all known target commands (and is
 109            human readable)
 110
 111            Example:
 112                 foreach t [target names] {
 113                     puts [format "Target: %s\n" $t]
 114                 }
 115
 116
 117     target current
 118
 119            Returns the TCL command name of the current target.
 120
 121            Example:
 122                 set ct [target current]
 123                 set t  [$ct cget -type]
 124
 125                 puts "Current target name is: $ct, and is a: $t"
 126
 127
 128     target number <VALUE>
 129
 130            Returns the TCL command name of the specified target.
 131            For example
 132
 133                set thename [target number $x]
 134                puts [format "Target %d is: %s\n" $x $thename]
 135
 136            For instance, assuming the defaults
 137
 138                target number 0
 139
 140            Would return 'target0' (or whatever you called it)
 141
 142     target count
 143
 144            Returns the larget+1 target number.
 145            For example:
 146
 147                set c [target count]
 148                for { set x 0 } { $x < $c } { incr x } {
 149                    # Assuming you have this function..
 150                    print_target_details $x
 151                }
 152
 153 ====================================================
 154
 155 "target0" - (#3 above) the "Target Object" command.
 156
 157   Once a target is 'created' a command object by that targets name is
 158   created, for example
 159
 160   target create BiGRed arm7tdmi -endian little -chain-position 3
 161
 162 Would create a [case sensative] "command" BiGRed
 163
 164 If you use the old [deprecated] syntax, the name is automatically
 165 generated and is in the form:
 166
 167           target0, target1, target2, target3, .... etc.
 168
 169 ====================================================
 170
 171 ** Target CREATE, CONFIGURE and CGET options **
 172
 173 The commands:
 174
 175     target create CMDNAME TYPE  [configure-options]
 176     CMDNAME configure [configure-options]
 177     CMDNAME cget      [configure-options]
 178
 179 In the 'create' case, one is creating the target and can specify any
 180 number of configuration parameters.
 181
 182 In the 'CMDNAME cget' case, the goal is to query the target for a
 183 specific configuration option.
 184
 185 In the 'CMDNAME configure' case, one can change the setting.
 186 [Not all things can, or should be changed]
 187
 188 In the above, the "default" name target0 is 'target0'
 189
 190 Example:
 191
 192    From the (gdb) prompt, one can type this:
 193
 194        (gdb) mon target0 configure -endian big
 195
 196    And change target0 to 'big-endian'.  This is a contrived example,
 197    specifically for this document - don't expect changing endian
 198    'mid-operation' to work you should set the endian at creation.
 199
 200 Known options [30/august/2008] are:
 201
 202 [Manditory 'create' Options]
 203        -type arm7tdmi|arm720|etc ...
 204        -chain-position NUMBER
 205        -endian ENDIAN
 206
 207 Optional
 208
 209        -event EVENTNAME  "tcl-action"
 210        -reset RESETACTION
 211        -work-area-virt ADDR
 212        -work-area-phys ADDR
 213        -work-area-size ADDR
 214        -work-area-backup BOOLEAN
 215
 216 [Hint: To get a list of avaialable options, try this]
 217
 218        (gdb) mon target0 cget -BLAHBLAHBLAH
 219
 220     the abov causes an error - and a helpful list of valid options.
 221
 222 ==================================================
 223 ** Example Target Configure Query **
 224
 225 One can query any of the above options at run time, for example:
 226
 227  (gdb) mon target0 cget -OPTION [param]
 228
 229 Example TCL script
 230
 231     # For all targets...
 232     set c [target count]
 233     for { set x 0 } { $x < $c } { incr x ] {
 234       set n [target number $x]
 235       set t [$n cget -type]
 236       set e [$n cget -endian]
 237       puts [format "%d: %s, %s, endian: %s\n" $x $n $t $n]
 238    }
 239
 240 Might produce:
 241       0: pic32chip, mips_m4k, endain: little
 242       1: arm7, arm7tdmi, endian: big
 243       2: blackfin, bf534, endian: little
 244
 245 Notice the above example is not target0, target1, target2 Why? Because
 246 in this contrived multi-target example - more human understandable
 247 target names might be helpful.
 248
 249 For example these two are the same:
 250
 251    (gdb) mon blackfin configure -event FOO {puts "Hi mom"}
 252
 253 or:
 254    (gdb) mon [target number 2] configure -event FOO {puts "Hi mom"}
 255
 256 In the second case, we use [] to get the command name of target #2, in
 257 this contrived example - it is "blackfin"
 258
 259 ====================================================
 260 ** TWO Important Configure Options Are: **
 261
 262 Two important configuration options are:
 263
 264     "-event" and "-reset"
 265
 266 The "-reset" option specifies what should happen when the chip is
 267 reset, for example should it 'halt', 're-init', or what.
 268
 269 The "-event" option less you specifiy a TCL command to occur when a
 270 specific event occurs.
 271
 272 ====================================================
 273 ** Target Events * Overview **
 274
 275 At various points in time - certian 'target' events happen.  You can
 276 create a custom event action to occur at that time.
 277
 278 For example - after reset, the PLLs and CLOCKs may need to be
 279 reconfigured, or perhaps the SDRAM needs to be re-initialized
 280
 281 Often the easiest way to do that is to create a simple script file
 282 containing the series of (mww [poke memory]) commands you would type
 283 by hand, to reconfigure the target clocks. You could specify the
 284 "event action" like this:
 285
 286    (gdb) mon target0 configure -event reset-init "script cfg.clocks"
 287
 288 In the above example, when the event "reset-init" occurs, the
 289 "action-string" will be evaluated as if you typed it at the console
 290
 291 Option1 -
 292
 293         The simple approach (above) is to create a script file with
 294         lots of "mww" (memory write word) commands to configure your
 295         targets clocks and/or external memory.
 296
 297 Option2 -
 298
 299         You can instead create a fancy Tcl procedure and invoke that
 300         procedure instead of sourcing a file.
 301
 302         [Infact, "script" is a TCL procedure that loads a file]
 303
 304 ==================================================
 305
 306 ** Target Events * Details **
 307
 308 There are many events one could use, to get a current list of events
 309 type the following invalid command, you'll get a helpful "runtime
 310 error" message, see below: [list valid as of 30/august/2008]
 311
 312    (gdb) mon target0 cget -event FAFA
 313
 314 Runtime error, file "../../../openocd23/src/helper/command.c", line 433:
 315     -event: Unknown: FAFA, try one of: old-pre_reset,
 316     old-gdb_program_config, old-post_reset, halted,
 317     resumed, resume-start, resume-end, reset-start,
 318     reset-assert-pre, reset-assert-post,
 319     reset-deassert-pre, reset-deassert-post,
 320     reset-halt-pre, reset-halt-post, reset-wait-pre,
 321     reset-wait-post, reset-init, reset-end,
 322     examine-start, examine-end, debug-halted,
 323     debug-resumed, gdb-attach, gdb-detach,
 324     gdb-flash-write-start, gdb-flash-write-end,
 325     gdb-flash-erase-start, gdb-flash-erase-end,
 326     resume-start, resume-ok, or resume-end
 327
 328 NOTE:
 329
 330     The event-names "old-*" are deprecated and exist only to help old
 331     scripts continue to function, and the old "target_script" command
 332     to work. Please do not rely on them.
 333
 334 These are some other important names.
 335
 336     gdb-flash-erase-start
 337     gdb-flash-erase-end
 338     gdb-flash-write-start
 339     gdb-flash-write-end
 340
 341     These occur when GDB/OpenOCD attempts to erase & program the FLASH
 342     chip via GDB.
 343
 344     For example - some PCBs may have a simple GPIO pin that acts like
 345     a "flash write protect" you might need to write a script that
 346     disables "write protect"
 347
 348 ==================================================
 349
 350 ** How to get a list of current event actions **
 351
 352 To get a list of current 'event actions', type the following command:
 353
 354    (gdb) mon target0 eventlist
 355
 356     Event actions for target (0) target0
 357
 358     Event                     | Body
 359     ------------------------- | ----------------------------------------
 360     old-post_reset            | script event/sam7x256_reset.script
 361     ***END***
 362
 363 Here is a simple example for all targets:
 364
 365    (gdb)  mon foreach x [target names] { $x eventlist }
 366
 367 The above uses some TCL tricks:
 368
 369    (a) foreach VARIABLE  LIST  BODY
 370
 371    (b) to generate the list, we use [target names]
 372
 373    (c) the BODY, contains $x - the loop variable
 374        and expands to the target specific name
 375
 376 ====================================================
 377
 378 Recalling the earlier discussion - the "object command" there are
 379 other things you can do besides "configure" the target.
 380
 381 Note: Many of these commands exist as "global" commands, and they also
 382 exist as target specific commands.
 383
 384 For example, the "mww" (memory write word) operates on the current target
 385 if you have more then 1 target, you must switch
 386
 387 In contrast to the normal commands, these commands operate on the
 388 specific target. For example, the command "mww" writes data to the
 389 *current* command line target.
 390
 391 Often, you have only a single target - but if you have multiple
 392 targets (ie: a PIC32 and an at91sam7 - your reset-init scripts might
 393 get a bit more complicated, ie: you must specify which of the two
 394 chips you want to write to. Writing 'pic32' clock configuration to an
 395 at91sam7 does not work)
 396
 397 The commands are: [as of 30/august/2008]
 398
 399     TNAME  mww ADDRESS VALUE
 400     TNAME  mwh ADDRESS VALUE
 401     TNAME  mwb ADDRESS VALUE
 402            Write(poke): 32, 16, 8bit values to memory.
 403
 404     TNAME  mdw ADDRESS VALUE
 405     TNAME  mdh ADDRESS VALUE
 406     TNAME  mdb ADDRESS VALUE
 407            Human 'hexdump' with ascii 32, 16, 8bit values
 408
 409     TNAME  mem2array  [see mem2array command]
 410     TNAME  array2mem  [see array2mem command]
 411
 412     TNAME  curstate
 413           Returns the current state of the target.
 414
 415
 416     TNAME examine
 417           See 'advanced target reset'
 418     TNAME poll
 419           See 'advanced target reset'
 420     TNAME reset assert
 421           See 'advanced target reset'
 422     TNAME reset deassert
 423           See 'advanced target reset'
 424     TNAME halt
 425           See 'advanced target reset'
 426     TNAME waitstate STATENAME
 427           See 'advanced target reset'