Skip to content
Snippets Groups Projects
Commit e2f941b5 authored by oharboe's avatar oharboe
Browse files

Laurentiu Cocanu - integrated new tcl target command docs 

git-svn-id: svn://svn.berlios.de/openocd/trunk@1073 b42882b7-edfa-0310-969c-e2dbd0fdcd60
parent ba02ce97
Branches
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
doc/README_TARGET_COMMAND.txt deleted 100644 → 0
+ 0
− 427
View file @ ba02ce97
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'
doc/openocd.texi
+ 443
− 0
View file @ e2f941b5
...@@ -980,6 +980,449 @@ Dump <size> bytes, starting at <@var{offset}> bytes from the beginning of the <@ ...@@ -980,6 +980,449 @@ Dump <size> bytes, starting at <@var{offset}> bytes from the beginning of the <@
to a <@var{file}>. to a <@var{file}>.
@end itemize @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 @page
@section Target Specific Commands @section Target Specific Commands
@cindex Target Specific Commands @cindex Target Specific Commands
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment