From e2f941b5465105d81cd75f9173b2afbee4d4b7be Mon Sep 17 00:00:00 2001 From: oharboe Date: Thu, 16 Oct 2008 13:16:49 +0000 Subject: Laurentiu Cocanu - integrated new tcl target command docs git-svn-id: svn://svn.berlios.de/openocd/trunk@1073 b42882b7-edfa-0310-969c-e2dbd0fdcd60 --- doc/openocd.texi | 443 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 443 insertions(+) (limited to 'doc/openocd.texi') diff --git a/doc/openocd.texi b/doc/openocd.texi index 472bd895..8c8be259 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -980,6 +980,449 @@ Dump bytes, starting at <@var{offset}> bytes from the beginning of the <@ to a <@var{file}>. @end itemize +@page +@section Target Commands +@cindex Target Commands + +@subsection Overview +@cindex Overview +Pre "TCL" - many commands in OpenOCD where implemented 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 time 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 referred 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: + +@enumerate +@item +Using the old syntax (deprecated). Target names are autogenerated as: + "target0", "target1", etc.; +@cindex old syntax +@item +Using the new syntax, you can specify the name of the target. +@cindex new syntax +@end enumerate + +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". + +@subsection Commands +@cindex Commands +OpenOCD has the following 'target' or 'target-like' commands: + +@enumerate +@item +@b{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); +@cindex targets +@item +@b{target (singular)} - used to create, configure list, etc the targets; +@cindex target +@item +@b{target0} - the command object for the first target. Unless you specified another name. +@cindex target0 +@end enumerate + +@subsubsection Targets Command +@cindex Targets Command +The "targets" command has 2 functions: + +@itemize +@item +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). +@verbatim +# using a target name. +(gdb) mon targets target0 +# or a target by number. +(gdb) mon targets 3 +@end verbatim +@cindex with a parameter +@item +Plain, without any parameter lists targets, for example: + +@verbatim +(gdb) mon targets + CmdName Type Endian ChainPos State +-- ---------- ---------- ---------- -------- ---------- + 0: target0 arm7tdmi little 0 halted +@end verbatim + +This shows: +@enumerate a +@item +in this example, a single target; +@item +target number 0 (1st column); +@item +the 'object name' is target0 (the default name); +@item +it is an arm7tdmi; +@item +little endian; +@item +the position in the JTAG chain; +@item +and is currently halted. +@end enumerate +@cindex without any parameter +@end itemize + +@subsubsection Target Command +@cindex Target Command + +The "target" command has the following options: +@itemize +@item +target create + +@verbatim + 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 +@end verbatim +@item +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). +@item +target names + + Returns a TCL list of all known target commands (and is human readable). + + Example: +@verbatim + foreach t [target names] { + puts [format "Target: %s\n" $t] + } +@end verbatim +@item +target current + + Returns the TCL command name of the current target. + + Example: +@verbatim + set ct [target current] + set t [$ct cget -type] + + puts "Current target name is: $ct, and is a: $t" +@end verbatim +@item +target number + + Returns the TCL command name of the specified target. + + Example +@verbatim + set thename [target number $x] + puts [format "Target %d is: %s\n" $x $thename] +@end verbatim + For instance, assuming the defaults +@verbatim + target number 0 +@end verbatim + Would return 'target0' (or whatever you called it) +@item +target count + + Returns the larget+1 target number. + + Example: +@verbatim + set c [target count] + for { set x 0 } { $x < $c } { incr x } { + # Assuming you have this function.. + print_target_details $x + } +@end verbatim +@end itemize + +@subsubsection Target0 Command +@cindex Target0 Command +The "target0" command (the "Target Object" command): + +Once a target is 'created' a command object by that targets name is created, for example +@verbatim + target create BiGRed arm7tdmi -endian little -chain-position 3 +@end verbatim + +Would create a [case sensitive] "command" BiGRed + +If you use the old [deprecated] syntax, the name is automatically +generated and is in the form: +@verbatim + target0, target1, target2, target3, ... etc. +@end verbatim + +@subsubsection Target CREATE, CONFIGURE and CGET Options Command +@cindex Target CREATE, CONFIGURE and CGET Options Command +The commands: +@verbatim + target create CMDNAME TYPE [configure-options] + CMDNAME configure [configure-options] + CMDNAME cget [configure-options] +@end verbatim +@itemize +@item +In the 'create' case, one is creating the target and can specify any +number of configuration parameters. +@item +In the 'CMDNAME configure' case, one can change the setting [Not all things can, or should be changed]. +@item +In the 'CMDNAME cget' case, the goal is to query the target for a +specific configuration option. +@end itemize + +In the above, the "default" name target0 is 'target0'. + + Example: + + From the (gdb) prompt, one can type this: + +@verbatim + (gdb) mon target0 configure -endian big +@end verbatim + + 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: +@itemize +@item +[Mandatory 'create' Options] + @itemize + @item + type arm7tdmi|arm720|etc ... + @item + chain-position NUMBER + @item + endian ENDIAN + @end itemize +@item +Optional + @itemize + @item + event EVENTNAME "tcl-action" + @item + reset RESETACTION + @item + work-area-virt ADDR + @item + work-area-phys ADDR + @item + work-area-size ADDR + @item + work-area-backup BOOLEAN + @end itemize +@end itemize +Hint: To get a list of available options, try this: +@verbatim + (gdb) mon target0 cget -BLAHBLAHBLAH +@end verbatim + + the above causes an error - and a helpful list of valid options. + +One can query any of the above options at run time, for example: +@verbatim + (gdb) mon target0 cget -OPTION [param] +@end verbatim + +Example TCL script + +@verbatim + # 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] + } +@end verbatim + +Might produce: + +@verbatim + 0: pic32chip, mips_m4k, endain: little + 1: arm7, arm7tdmi, endian: big + 2: blackfin, bf534, endian: little +@end verbatim + +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: + +@verbatim + (gdb) mon blackfin configure -event FOO {puts "Hi mom"} +@end verbatim + +or: + +@verbatim + (gdb) mon [target number 2] configure -event FOO {puts "Hi mom"} +@end verbatim + +In the second case, we use [] to get the command name of target #2, in this contrived example - it is "blackfin". + +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 specify a TCL command to occur when a specific event occurs. + +@subsection Target Events +@cindex Target Events + +@subsubsection Overview +@cindex Overview +At various points in time - certain '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: + +@verbatim + (gdb) mon target0 configure -event reset-init "script cfg.clocks" +@end verbatim + +In the above example, when the event "reset-init" occurs, the "action-string" will be evaluated as if you typed it at the +console: +@itemize +@item @b{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; +@item @b{Option2} - You can instead create a fancy TCL procedure and invoke that procedure instead of sourcing a file [In fact, + "script" is a TCL procedure that loads a file]. +@end itemize + +@subsubsection Details +@cindex 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]: + +@verbatim +(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 +@end verbatim + +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: +@itemize +@item gdb-flash-erase-start +@item gdb-flash-erase-end +@item gdb-flash-write-start +@item gdb-flash-write-end +@end itemize + +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". + +To get a list of current 'event actions', type the following command: + +@verbatim + (gdb) mon target0 eventlist + + Event actions for target (0) target0 + + Event | Body + ------------------------- | ---------------------------------------- + old-post_reset | script event/sam7x256_reset.script +@end verbatim + +Here is a simple example for all targets: + +@verbatim + (gdb) mon foreach x [target names] { $x eventlist } +@end verbatim + +The above uses some TCL tricks: +@enumerate a +@item foreach VARIABLE LIST BODY +@item to generate the list, we use [target names] +@item the BODY, contains $x - the loop variable and expands to the target specific name +@end enumerate + +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]: +@verbatim + 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' +@end verbatim + @page @section Target Specific Commands @cindex Target Specific Commands -- cgit v1.2.3-18-g5258