Laurentiu Cocanu - integrated new tcl target command docs
git-svn-id: svn://svn.berlios.de/openocd/trunk@1073 b42882b7-edfa-0310-969c-e2dbd0fdcd60__archive__
oharboe
parent
ba02ce97a4
commit
e2f941b546
|
|
@ -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'
|
|
||||||
443
doc/openocd.texi
443
doc/openocd.texi
|
|
@ -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
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue