From 5ac8036b7fdaa32d44fb756f46f60d8de33e3a50 Mon Sep 17 00:00:00 2001 From: oharboe Date: Mon, 1 Sep 2008 07:24:14 +0000 Subject: Removed target->reset_mode, no longer used git-svn-id: svn://svn.berlios.de/openocd/trunk@976 b42882b7-edfa-0310-969c-e2dbd0fdcd60 --- doc/README_TARGET_COMMAND.txt | 427 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 427 insertions(+) create mode 100644 doc/README_TARGET_COMMAND.txt (limited to 'doc/README_TARGET_COMMAND.txt') 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 + + 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' -- cgit v1.2.3