diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README_TARGET_COMMAND.txt | 427 | ||||
| -rw-r--r-- | doc/openocd.texi | 443 |
2 files changed, 443 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' diff --git a/doc/openocd.texi b/doc/openocd.texi index 472bd895..8c8be259 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -981,6 +981,449 @@ 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 <VALUE> + + 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 |