X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;ds=sidebyside;f=doc%2Fopenocd.texi;h=13825fb89ded5611a12ce08050c4668c47d1c1ad;hb=bdb5fd8c98ad474bf2ad790eefc62a830b33f0d4;hp=95f7f3d454654ef46264459b69edb354d6be850a;hpb=7044908cf0184f5d82b3812f1c56a7098ea12850;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 95f7f3d454..13825fb89d 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -12,6 +12,7 @@ @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 @@ -52,6 +53,7 @@ This manual documents edition @value{EDITION} of the Open On-Chip Debugger * 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 @@ -192,6 +194,13 @@ absolute path containing no spaces. 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 @@ -252,6 +261,16 @@ Port on which to listen for incoming telnet connections @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. @@ -273,12 +292,6 @@ Default behaviour is <@var{enable}> 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 @@ -327,12 +340,13 @@ Segger jlink usb adapter @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} @@ -344,7 +358,7 @@ is optional, in which case the reset speed is used. 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 @@ -423,13 +437,20 @@ Currently supported cables are @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. @@ -440,7 +461,14 @@ This is also the layout used by the HollyGates design (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 @@ -515,7 +543,7 @@ Currently, there are no options available for the ep93xx interface. @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: @@ -537,35 +565,6 @@ target board 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: @@ -573,11 +572,6 @@ 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 @@ -590,7 +584,7 @@ a working_area that doesn't need to be backed up, as performing a backup slows d @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. @@ -654,13 +648,17 @@ vector table. @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 @@ -705,6 +703,13 @@ stellaris flash plugin only require the @var{target#}. @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 @@ -723,7 +728,7 @@ is set to 10kHz for reset and 8MHz for post reset. @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 @@ -828,12 +833,11 @@ OpenOCD will wait 5 seconds for the target to resume. @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 @@ -845,13 +849,6 @@ Immediately halt the target (works only with certain configurations). @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 @@ -1079,15 +1076,6 @@ The target is resumed in the currently set @option{core_mode}. 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 @@ -1339,7 +1327,7 @@ working area. 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} @@ -1366,9 +1354,9 @@ target_script 0 gdb_program_config config.script 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. @@ -1378,10 +1366,10 @@ The command and file interfaces are fairly straightforward, while the network 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} { @@ -1394,11 +1382,60 @@ 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 @@ -1408,6 +1445,10 @@ Certain OpenOCD commands have been deprecated/removed during the various revisio @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 @@ -1426,6 +1467,28 @@ use @option{arm7_9 fast_memory_access} 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 @@ -1444,11 +1507,7 @@ arm7_9_add_breakpoint(): sw breakpoint requested, but software breakpoints not e 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.