diff options
Diffstat (limited to 'doc/README_TARGET_COMMAND.txt')
| -rw-r--r-- | doc/README_TARGET_COMMAND.txt | 427 |
1 files changed, 0 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' |