tinyriscv-openocd/doc/README_TARGET_COMMAND.txt

428 lines
13 KiB
Plaintext

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'