@copying
Copyright @copyright{} 2007-2008 Spen @email{spen@@spen-soft.co.uk}
+Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
* Sample Scripts:: Sample Target Scripts
* GDB and OpenOCD:: Using GDB and OpenOCD
* TCL and OpenOCD:: Using TCL and OpenOCD
+* TCL scripting API:: Tcl scripting API
* Upgrading:: Deprecated/Removed Commands
* FAQ:: Frequently Asked Questions
* License:: GNU Free Documentation License
Linux users should copy the various parts of the D2XX package to the appropriate
locations, i.e. /usr/include, /usr/lib.
+Miscellaneous configure options
+
+@itemize @bullet
+@item
+@option{--enable-gccwarnings} - enable extra gcc warnings during build
+@end itemize
+
@node Running
@chapter Running
@cindex running OpenOCD
@cindex gdb_port
First port on which to listen for incoming GDB connections. The GDB port for the
first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
+@item @b{gdb_breakpoint_override} <@var{hard/soft/disabled}>
+@cindex gdb_breakpoint_override
+hard/soft/disabled - force breakpoint type for gdb 'break' commands.
+The raison d'etre for this option is to support GDB GUI's without
+a hard/soft breakpoint concept where the default OpenOCD and
+GDB behaviour is not sufficient. Note that GDB will use hardware
+breakpoints if the memory map has been set up for flash regions.
+
+This option replaces older arm7_9 target commands that addressed
+the same issue.
@item @b{gdb_detach} <@var{resume|reset|halt|nothing}>
@cindex gdb_detach
Configures what OpenOCD will do when gdb detaches from the daeman.
Port on which to listen for incoming TCL syntax. This port is intended as
a simplified RPC connection that can be used by clients to issue commands
and get the output from the TCL engine.
-@item @b{daemon_startup} <@var{mode}>
-@cindex daemon_startup
-@option{mode} can either @option{attach} or @option{reset}
-This is equivalent to adding "init" and "reset" to the end of the config script.
-
-It is available as a command mainly for backwards compatibility.
@end itemize
@section JTAG interface configuration
@end itemize
@itemize @bullet
-@item @b{jtag_speed} <@var{reset speed}> <@var{post reset speed}>
+@item @b{jtag_speed} <@var{reset speed}>
@cindex jtag_speed
Limit the maximum speed of the JTAG interface. Usually, a value of zero means maximum
-speed. The actual effect of this option depends on the JTAG interface used. Reset
-speed is used during reset and post reset speed after reset. post reset speed
-is optional, in which case the reset speed is used.
+speed. The actual effect of this option depends on the JTAG interface used.
+
+The speed used during reset can be adjusted using setting jtag_speed during
+pre_reset and post_reset events.
@itemize @minus
@item wiggler: maximum speed / @var{number}
Note: Make sure the jtag clock is no more than @math{1/6th × CPU-Clock}. This is
especially true for synthesized cores (-S).
-@item @b{jtag_khz} <@var{reset speed kHz}> <@var{post reset speed kHz}>
+@item @b{jtag_khz} <@var{reset speed kHz}>
@cindex jtag_khz
Same as jtag_speed, except that the speed is specified in maximum kHz. If
the device can not support the rate asked for, or can not translate from
@cindex wiggler
The original Wiggler layout, also supported by several clones, such
as the Olimex ARM-JTAG
+@item @b{wiggler2}
+@cindex wiggler2
+Same as original wiggler except an led is fitted on D5.
+@item @b{wiggler_ntrst_inverted}
+@cindex wiggler_ntrst_inverted
+Same as original wiggler except TRST is inverted.
@item @b{old_amt_wiggler}
@cindex old_amt_wiggler
The Wiggler configuration that comes with Amontec's Chameleon Programmer. The new
version available from the website uses the original Wiggler layout ('@var{wiggler}')
@item @b{chameleon}
@cindex chameleon
-The Amontec Chameleon's CPLD when operated in configuration mode. This is only used to program the Chameleon itself, not a connected target.
+The Amontec Chameleon's CPLD when operated in configuration mode. This is only used to
+program the Chameleon itself, not a connected target.
@item @b{dlc5}
@cindex dlc5
The Xilinx Parallel cable III.
(see @uref{http://www.lartmaker.nl/projects/jtag/}).
@item @b{flashlink}
@cindex flashlink
-The ST Parallel cable.
+The ST Parallel cable.
+@item @b{arm-jtag}
+@cindex arm-jtag
+Same as original wiggler except SRST and TRST connections reversed and
+TRST is also inverted.
+@item @b{altium}
+@cindex altium
+Altium Universal JTAG cable.
@end itemize
@item @b{parport_write_on_exit} <@var{on|off}>
@cindex parport_write_on_exit
@section Target configuration
@itemize @bullet
-@item @b{target} <@var{type}> <@var{endianess}> <@var{reset_mode}> <@var{JTAG pos}>
+@item @b{target} <@var{type}> <@var{endianess}> <@var{JTAG pos}>
<@var{variant}>
@cindex target
Defines a target that should be debugged. Currently supported types are:
Endianess may be @option{little} or @option{big}.
-The reset_mode specifies what should happen to the target when a reset occurs:
-@itemize @minus
-@item @b{reset_halt}
-@cindex reset_halt
-Immediately request a target halt after reset. This allows targets to be debugged
-from the very first instruction. This is only possible with targets and JTAG
-interfaces that correctly implement the reset signals.
-@item @b{reset_init}
-@cindex reset_init
-Similar to @option{reset_halt}, but executes the script file defined to handle the
-'reset' event for the target. Like @option{reset_halt} this only works with
-correct reset implementations.
-@item @b{reset_run}
-@cindex reset_run
-Simply let the target run after a reset.
-@item @b{run_and_halt}
-@cindex run_and_halt
-Let the target run for some time (default: 1s), and then request halt.
-@item @b{run_and_init}
-@cindex run_and_init
-A combination of @option{reset_init} and @option{run_and_halt}. The target is allowed
-to run for some time, then halted, and the @option{reset} event script is executed.
-@end itemize
-
-On JTAG interfaces / targets where system reset and test-logic reset can't be driven
-completely independent (like the LPC2000 series), or where the JTAG interface is
-unavailable for some time during startup (like the STR7 series), you can't use
-@option{reset_halt} or @option{reset_init}.
-
@item @b{target_script} <@var{target#}> <@var{event}> <@var{script_file}>
@cindex target_script
Event is one of the following:
@option{pre_resume} or @option{gdb_program_config}.
@option{post_reset} and @option{reset} will produce the same results.
-@item @b{run_and_halt_time} <@var{target#}> <@var{time_in_ms}>
-@cindex run_and_halt_time
-The amount of time the debugger should wait after releasing reset before it asserts
-a debug request. This is used by the @option{run_and_halt} and @option{run_and_init}
-reset modes.
@item @b{working_area} <@var{target#}> <@var{address}> <@var{size}>
<@var{backup}|@var{nobackup}>
@cindex working_area
@subsection arm7tdmi options
@cindex arm7tdmi options
-target arm7tdmi <@var{endianess}> <@var{reset_mode}> <@var{jtag#}>
+target arm7tdmi <@var{endianess}> <@var{jtag#}>
The arm7tdmi target definition requires at least one additional argument, specifying
the position of the target in the JTAG daisy-chain. The first JTAG device is number 0.
The optional [@var{variant}] parameter has been removed in recent versions.
@cindex cfi options
@b{flash bank cfi} <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}>
-<@var{target#}>
+<@var{target#}> [@var{jedec_probe}|@var{x16_as_x8}]
CFI flashes require the number of the target they're connected to as an additional
argument. The CFI driver makes use of a working area (specified for the target)
to significantly speed up operation.
@var{chip_width} and @var{bus_width} are specified in bytes.
+The @var{jedec_probe} option is used to detect certain non-CFI flash roms, like AM29LV010 and similar types.
+
+@var{x16_as_x8} ???
+
@subsection at91sam7 options
@cindex at91sam7 options
@b{flash bank stm32x} <@var{base}> <@var{size}> 0 0 <@var{target#}>
stm32x flash plugin only require the @var{target#}.
+@subsection aduc702x options
+@cindex aduc702x options
+
+@b{flash bank aduc702x} <@var{base}> <@var{size}> 0 0 <@var{target#}>
+aduc702x flash plugin require the flash @var{base}, @var{size} and @var{target#}.
+currently only the aduc7206 is supported.
+
@node Target library
@chapter Target library
@cindex Target library
@smallexample
-openocd -f interface/parport.cfg -c "jtag_khz 10 8000" -f target/str710.cfg -c "init" -c "reset"
+openocd -f interface/parport.cfg -f target/str710.cfg -c "init" -c "reset"
@end smallexample
@cindex step
Single-step the target at its current code position, or at an optional address.
-@item @b{reset} [@option{run}|@option{halt}|@option{init}|@option{run_and_halt}
-|@option{run_and_init}]
+@item @b{reset} [@option{run}|@option{halt}|@option{init}]
@cindex reset
Perform a hard-reset. The optional parameter specifies what should happen after the reset.
-This optional parameter overrides the setting specified in the configuration file,
-making the new behaviour the default for the @option{reset} command.
+
+With no arguments a "reset run" is executed
@itemize @minus
@item @b{run}
@cindex reset run
@cindex reset init
Immediately halt the target, and execute the reset script (works only with certain
configurations)
-@item @b{run_and_halt}
-@cindex reset run_and_halt
-Let the target run for a certain amount of time, then request a halt.
-@item @b{run_and_init}
-@cindex reset run_and_init
-Let the target run for a certain amount of time, then request a halt. Execute the
-reset script once the target enters debug mode.
@end itemize
@end itemize
These commands are specific to ARM7 and ARM9 targets, like ARM7TDMI, ARM720t,
ARM920t or ARM926EJ-S.
@itemize @bullet
-@item @b{arm7_9 sw_bkpts} <@var{enable}|@var{disable}>
-@cindex arm7_9 sw_bkpts
-Enable/disable use of software breakpoints. On ARMv4 systems, this reserves
-one of the watchpoint registers to implement software breakpoints. Disabling
-SW Bkpts frees that register again.
-@item @b{arm7_9 force_hw_bkpts} <@var{enable}|@var{disable}>
-@cindex arm7_9 force_hw_bkpts
-When @option{force_hw_bkpts} is enabled, the @option{sw_bkpts} support is disabled, and all
-breakpoints are turned into hardware breakpoints.
@item @b{arm7_9 dbgrq} <@var{enable}|@var{disable}>
@cindex arm7_9 dbgrq
Enable use of the DBGRQ bit to force entry into debug mode. This should be
Informing gdb of the memory map of the target will enable gdb to protect any
flash area of the target and use hardware breakpoints by default. This means
-that the OpenOCD option @option{arm7_9 force_hw_bkpts} is not required when
+that the OpenOCD option @option{gdb_breakpoint_override} is not required when
using a memory map.
To view the configured memory map in gdb, use the gdb command @option{info mem}
To verify any flash programming the gdb command @option{compare-sections}
can be used.
- at node TCL and OpenOCD
- at chapter TCL and OpenOCD
- at cindex TCL and OpenOCD
+@node TCL and OpenOCD
+@chapter TCL and OpenOCD
+@cindex TCL and OpenOCD
OpenOCD embeds a TCL interpreter (see JIM) for command parsing and scripting
support.
port is geared toward intergration with external clients. A small example
of an external TCL script that can connect to openocd is shown below.
- at verbatim
+@verbatim
# Simple tcl client to connect to openocd
puts "Use empty line to exit"
-set fo [socket 127.0.0.1 5555]
+set fo [socket 127.0.0.1 6666]
puts -nonewline stdout "> "
flush stdout
while {[gets stdin line] >= 0} {
flush stdout
}
close $fo
- at end verbatim
+@end verbatim
This script can easily be modified to front various GUIs or be a sub
component of a larger framework for control and interaction.
+
+@node TCL scripting API
+@chapter TCL scripting API
+@cindex TCL scripting API
+API rules
+
+The commands are stateless. E.g. the telnet command line has a concept
+of currently active target, the Tcl API proc's take this sort of state
+information as an argument to each proc.
+
+There are three main types of return values: single value, name value
+pair list and lists.
+
+Name value pair. The proc 'foo' below returns a name/value pair
+list.
+
+@verbatim
+
+ > set foo(me) Duane
+ > set foo(you) Oyvind
+ > set foo(mouse) Micky
+ > set foo(duck) Donald
+
+If one does this:
+
+ > set foo
+
+The result is:
+
+ me Duane you Oyvind mouse Micky duck Donald
+
+Thus, to get the names of the associative array is easy:
+
+ foreach { name value } [set foo] {
+ puts "Name: $name, Value: $value"
+ }
+@end verbatim
+
+Lists returned must be relatively small. Otherwise a range
+should be passed in to the proc in question.
+
+Low level commands are prefixed with "openocd_", e.g. openocd_flash_banks
+is the low level API upon which "flash banks" is implemented.
+
+OpenOCD commands can consist of two words, e.g. "flash banks". The
+startup.tcl "unknown" proc will translate this into a tcl proc
+called "flash_banks".
+
+
@node Upgrading
@chapter Deprecated/Removed Commands
@cindex Deprecated/Removed Commands
@item @b{load_binary}
@cindex load_binary
use @option{load_image} command with same args
+@item @b{target}
+@cindex target
+@option{target} no longer take the reset_init, reset_run, run_and_halt, run_and_init. The @option{reset} command
+always does a @option{reset run} when passed no arguments.
@item @b{dump_binary}
@cindex dump_binary
use @option{dump_image} command with same args
@item @b{flash auto_erase}
@cindex flash auto_erase
use @option{flash write_image} command passing @option{erase} as the first parameter.
+@item @b{daemon_startup}
+@cindex daemon_startup
+this config option has been removed, simply adding @option{init} and @option{reset halt} to
+the end of your config script will give the same behaviour as using @option{daemon_startup reset}
+and @option{target cortex_m3 little reset_halt 0}.
+@item @b{arm7_9 sw_bkpts}
+@cindex arm7_9 sw_bkpts
+On by default. See also @option{gdb_breakpoint_override}.
+@item @b{arm7_9 force_hw_bkpts}
+@cindex arm7_9 force_hw_bkpts
+Use @option{gdb_breakpoint_override} instead. Note that GDB will use hardware breakpoints
+for flash if the gdb memory map has been set up(default when flash is declared in
+target configuration).
+@item @b{run_and_halt_time}
+@cindex run_and_halt_time
+This command has been removed for simpler reset behaviour, it can be simulated with the
+following commands:
+@smallexample
+reset run
+sleep 100
+halt
+@end smallexample
@end itemize
@node FAQ
GDB issues software breakpoints when a normal breakpoint is requested, or to implement
source-line single-stepping. On ARMv4T systems, like ARM7TDMI, ARM720t or ARM920t,
-software breakpoints consume one of the two available hardware breakpoints,
-and are therefore disabled by default. If your code is running from RAM, you
-can enable software breakpoints with the @option{arm7_9 sw_bkpts enable} command. If
-your code resides in Flash, you can't use software breakpoints, but you can force
-OpenOCD to use hardware breakpoints instead: @option{arm7_9 force_hw_bkpts enable}.
+software breakpoints consume one of the two available hardware breakpoints.
@item When erasing or writing LPC2000 on-chip flash, the operation fails sometimes
and works sometimes fine.
Code Review / openocd.git / blobdiff