@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
@chapter Building
@cindex building OpenOCD
+If you are interested in getting actual work done rather than building
+OpenOCD, then check if your interface supplier provides binaries for
+you. Chances are that that binary is from some SVN version that is more
+stable than SVN trunk where bleeding edge development takes place.
+
+
You can download the current SVN version with SVN client of your choice from the
following repositories:
@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.
starting new JTAG operations.
@item @b{jtag_ntrst_delay} <@var{ms}>
@cindex jtag_ntrst_delay
-How long (in milliseconds) OpenOCD should wait after deasserting nTRST before
-starting new JTAG operations.
+Same @b{jtag_nsrst_delay}, but for nTRST
The jtag_n[st]rst_delay options are useful if reset circuitry (like a reset supervisor,
or on-chip features) keep a reset line asserted for some time after the external reset
@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
@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#}.
+
@node Target library
@chapter Target library
@cindex Target library
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
@section Connecting to gdb
@cindex Connecting to gdb
+Use GDB 6.7 or newer with OpenOCD if you run into trouble. For instance 6.3 has a
+known bug where it produces bogus memory access errors, which has since
+been fixed: look up 1836 in http://sourceware.org/cgi-bin/gnatsweb.pl?database=gdb
+
+
A connection is typically started as follows:
@smallexample
target remote localhost:3333
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}
@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
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
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.