The OpenOCD web site provides the latest public news from the community:
-@uref{http://openocd.berlios.de/web/}
+@uref{http://openocd.sourceforge.net/}
@section Latest User's Guide:
available. A version for more recent code may be available.
Its HTML form is published irregularly at:
-@uref{http://openocd.berlios.de/doc/html/index.html}
+@uref{http://openocd.sourceforge.net/doc/html/index.html}
PDF form is likewise published at:
-@uref{http://openocd.berlios.de/doc/pdf/openocd.pdf}
+@uref{http://openocd.sourceforge.net/doc/pdf/openocd.pdf}
@section OpenOCD User's Forum
technical information about the software internals, development
processes, and similar documentation:
-@uref{http://openocd.berlios.de/doc/doxygen/index.html}
+@uref{http://openocd.sourceforge.net/doc/doxygen/html/index.html}
This document is a work-in-progress, but contributions would be welcome
to fill in the gaps. All of the source files are provided in-tree,
The OpenOCD Developer Mailing List provides the primary means of
communication between developers:
-@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
+@uref{https://lists.sourceforge.net/mailman/listinfo/openocd-devel}
Discuss and submit patches to this list.
-The @file{PATCHES.txt} file contains basic information about how
+The @file{HACKING} file contains basic information about how
to prepare patches.
@section OpenOCD Bug Database
@* Axiom AXM-0432 Link @url{http://www.axman.com}
@item @b{cortino}
@* Link @url{http://www.hitex.com/index.php?id=cortino}
+@item @b{dlp-usb1232h}
+@* Link @url{http://www.dlpdesign.com/usb/usb1232h.shtml}
@end itemize
@section USB-JTAG / Altera USB-Blaster compatibles
@* Link: @url{http://www.stm32circle.com/resources/stm32primer2.php}
@end itemize
+@section USB ST-LINK based
+ST Micro has an adapter called @b{ST-LINK}.
+They only works with ST Micro chips, notably STM32 and STM8.
+
+@itemize @bullet
+@item @b{ST-LINK}
+@* This is available standalone and as part of some kits, eg. STM32VLDISCOVERY.
+@* Link: @url{http://www.st.com/internet/evalboard/product/219866.jsp}
+@item @b{ST-LINK/V2}
+@* This is available standalone and as part of some kits, eg. STM32F4DISCOVERY.
+@* Link: @url{http://www.st.com/internet/evalboard/product/251168.jsp}
+@end itemize
+
@section USB Other
@itemize @bullet
@item @b{USBprog}
@item @b{Jim vs. Tcl}
@* Jim-Tcl is a stripped down version of the well known Tcl language,
which can be found here: @url{http://www.tcl.tk}. Jim-Tcl has far
-fewer features. Jim-Tcl is a single .C file and a single .H file and
+fewer features. Jim-Tcl is several dozens of .C files and .H files and
implements the basic Tcl command set. In contrast: Tcl 8.6 is a
-4.2 MB .zip file containing 1540 files.
+4.2 MB .zip file containing 1540 files.
@item @b{Missing Features}
@* Our practice has been: Add/clone the real Tcl feature if/when
needed. We welcome Jim-Tcl improvements, not bloat. Also there
-are a large number of optional Jim-Tcl features that are not
+are a large number of optional Jim-Tcl features that are not
enabled in OpenOCD.
@item @b{Scripts}
@quotation Note
Don't try to use configuration script names or paths which
-include the "#" character. That character begins Tcl comments.
+include the "#" character. That character begins Tcl comments.
@end quotation
@section Simple setup, no customization
@example
Open On-Chip Debugger 0.4.0 (2010-01-14-15:06)
For bug reports, read
- http://openocd.berlios.de/doc/doxygen/bugs.html
+ http://openocd.sourceforge.net/doc/doxygen/bugs.html
Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477
(mfg: 0x23b, part: 0xba00, ver: 0x3)
@end example
You can redirect all output from the daemon to a file using the
@option{-l <logfile>} switch.
-For details on the @option{-p} option. @xref{Connecting to GDB}.
-
Note! OpenOCD will launch the GDB & telnet server even if it can not
establish a connection with the target. In general, it is possible for
the JTAG controller to be unresponsive until the target is set up
at91sam3u4e.cfg lpc1768.cfg sharp_lh79532.cfg
at91sam3uXX.cfg lpc2103.cfg smdk6410.cfg
at91sam7sx.cfg lpc2124.cfg smp8634.cfg
-at91sam9260.cfg lpc2129.cfg stm32.cfg
+at91sam9260.cfg lpc2129.cfg stm32f1x.cfg
c100.cfg lpc2148.cfg str710.cfg
c100config.tcl lpc2294.cfg str730.cfg
c100helper.tcl lpc2378.cfg str750.cfg
-work-area-size 0x4000 -work-area-backup 0
@end example
+@anchor{Define CPU targets working in SMP}
+@subsection Define CPU targets working in SMP
+@cindex SMP
+After setting targets, you can define a list of targets working in SMP.
+
+@example
+set _TARGETNAME_1 $_CHIPNAME.cpu1
+set _TARGETNAME_2 $_CHIPNAME.cpu2
+target create $_TARGETNAME_1 cortex_a8 -chain-position $_CHIPNAME.dap \
+-coreid 0 -dbgbase $_DAP_DBG1
+target create $_TARGETNAME_2 cortex_a8 -chain-position $_CHIPNAME.dap \
+-coreid 1 -dbgbase $_DAP_DBG2
+#define 2 targets working in smp.
+target smp $_CHIPNAME.cpu2 $_CHIPNAME.cpu1
+@end example
+In the above example on cortex_a8, 2 cpus are working in SMP.
+In SMP only one GDB instance is created and :
+@itemize @bullet
+@item a set of hardware breakpoint sets the same breakpoint on all targets in the list.
+@item halt command triggers the halt of all targets in the list.
+@item resume command triggers the write context and the restart of all targets in the list.
+@item following a breakpoint: the target stopped by the breakpoint is displayed to the GDB session.
+@item dedicated GDB serial protocol packets are implemented for switching/retrieving the target
+displayed by the GDB session @pxref{Using openocd SMP with GDB}.
+@end itemize
+
+The SMP behaviour can be disabled/enabled dynamically. On cortex_a8 following
+command have been implemented.
+@itemize @bullet
+@item cortex_a8 smp_on : enable SMP mode, behaviour is as described above.
+@item cortex_a8 smp_off : disable SMP mode, the current target is the one
+displayed in the GDB session, only this target is now controlled by GDB
+session. This behaviour is useful during system boot up.
+@item cortex_a8 smp_gdb : display/fix the core id displayed in GDB session see
+following example.
+@end itemize
+
+@example
+>cortex_a8 smp_gdb
+gdb coreid 0 -> -1
+#0 : coreid 0 is displayed to GDB ,
+#-> -1 : next resume triggers a real resume
+> cortex_a8 smp_gdb 1
+gdb coreid 0 -> 1
+#0 :coreid 0 is displayed to GDB ,
+#->1 : next resume displays coreid 1 to GDB
+> resume
+> cortex_a8 smp_gdb
+gdb coreid 1 -> 1
+#1 :coreid 1 is displayed to GDB ,
+#->1 : next resume displays coreid 1 to GDB
+> cortex_a8 smp_gdb -1
+gdb coreid 1 -> -1
+#1 :coreid 1 is displayed to GDB,
+#->-1 : next resume triggers a real resume
+@end example
+
+
@subsection Chip Reset Setup
As a rule, you should put the @command{reset_config} command
"gdb_port" stuck because it covers probably more than 90% of
the normal use cases.
-No arguments reports GDB port. "pipe" means listen to stdin
+No arguments reports GDB port. "pipe" means listen to stdin
output to stdout, an integer is base port number, "disable"
disables the gdb server.
The -p/--pipe option is deprecated and a warning is printed
as it is equivalent to passing in -c "gdb_port pipe; log_output openocd.log".
-Any other string is interpreted as named pipe to listen to.
+Any other string is interpreted as named pipe to listen to.
Output pipe is the same name as input pipe, but with 'o' appended,
e.g. /var/gdb, /var/gdbo.
-
-The GDB port for the first target will be the base port, the
+
+The GDB port for the first target will be the base port, the
second target will listen on gdb_port + 1, and so on.
When not specified during the configuration stage,
the port @var{number} defaults to 3333.
@end example
@end deffn
+@deffn {Interface Driver} {remote_bitbang}
+Drive JTAG from a remote process. This sets up a UNIX or TCP socket connection
+with a remote process and sends ASCII encoded bitbang requests to that process
+instead of directly driving JTAG.
+
+The remote_bitbang driver is useful for debugging software running on
+processors which are being simulated.
+
+@deffn {Config Command} {remote_bitbang_port} number
+Specifies the TCP port of the remote process to connect to or 0 to use UNIX
+sockets instead of TCP.
+@end deffn
+
+@deffn {Config Command} {remote_bitbang_host} hostname
+Specifies the hostname of the remote process to connect to using TCP, or the
+name of the UNIX socket to use if remote_bitbang_port is 0.
+@end deffn
+
+For example, to connect remotely via TCP to the host foobar you might have
+something like:
+
+@example
+interface remote_bitbang
+remote_bitbang_port 3335
+remote_bitbang_host foobar
+@end example
+
+To connect to another process running locally via UNIX sockets with socket
+named mysocket:
+
+@example
+interface remote_bitbang
+remote_bitbang_port 0
+remote_bitbang_host mysocket
+@end example
+@end deffn
+
@deffn {Interface Driver} {usb_blaster}
USB JTAG/USB-Blaster compatibles over one of the userspace libraries
for FTDI chips. These interfaces have several commands, used to
@end quotation
@end deffn
+@deffn {Interface Driver} {stlink}
+ST Micro ST-LINK adapter.
+@end deffn
+
@deffn {Interface Driver} {ZY1000}
This is the Zylin ZY1000 JTAG debugger.
@end deffn
(Support for this is preliminary and incomplete.)
@item @code{cortex_a8} -- this is an ARMv7 core with an MMU
@item @code{cortex_m3} -- this is an ARMv7 core, supporting only the
-compact Thumb2 instruction set. It supports one variant:
-@itemize @minus
-@item @code{lm3s} ... Use this when debugging older Stellaris LM3S targets.
-This will cause OpenOCD to use a software reset rather than asserting
-SRST, to avoid a issue with clearing the debug registers.
-This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will
-be detected and the normal reset behaviour used.
-@end itemize
+compact Thumb2 instruction set.
@item @code{dragonite} -- resembles arm966e
@item @code{dsp563xx} -- implements Freescale's 24-bit DSP.
(Support for this is still incomplete.)
@* Currently not used (goal: when JTAG examine starts)
@end ignore
@item @b{gdb-attach}
-@* When GDB connects. This is before any communication with the target, so this
+@* When GDB connects. This is before any communication with the target, so this
can be used to set up the target so it is possible to probe flash. Probing flash
is necessary during gdb connect if gdb load is to write the image to flash. Another
use of the flash memory map is for GDB to automatically hardware/software breakpoints
As a special case, when @var{length} is zero and @var{address} is
the start of the bank, the whole flash is erased.
If @option{unlock} is specified, then the flash is unprotected
-before erase starts.
+before erase starts.
@end deffn
@deffn Command {flash fillw} address word length
@end quotation
@end deffn
-@deffn {Flash Driver} stm32x
-All members of the STM32 microcontroller family from ST Microelectronics
+@deffn {Flash Driver} stm32f1x
+All members of the STM32f1x microcontroller family from ST Microelectronics
include internal flash and use ARM Cortex M3 cores.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
@example
-flash bank $_FLASHNAME stm32x 0 0 0 0 $_TARGETNAME
+flash bank $_FLASHNAME stm32f1x 0 0 0 0 $_TARGETNAME
@end example
-Some stm32x-specific commands
-@footnote{Currently there is a @command{stm32x mass_erase} command.
+Some stm32f1x-specific commands
+@footnote{Currently there is a @command{stm32f1x mass_erase} command.
That seems pointless since the same effect can be had using the
standard @command{flash erase_address} command.}
are defined:
-@deffn Command {stm32x lock} num
+@deffn Command {stm32f1x lock} num
Locks the entire stm32 device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32x unlock} num
+@deffn Command {stm32f1x unlock} num
Unlocks the entire stm32 device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32x options_read} num
+@deffn Command {stm32f1x options_read} num
Read and display the stm32 option bytes written by
-the @command{stm32x options_write} command.
+the @command{stm32f1x options_write} command.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP})
+@deffn Command {stm32f1x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP})
Writes the stm32 option byte with the specified values.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@end deffn
+@deffn {Flash Driver} stm32f2x
+All members of the STM32f2x microcontroller family from ST Microelectronics
+include internal flash and use ARM Cortex M3 cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+@end deffn
+
@deffn {Flash Driver} str7x
All members of the STR7 microcontroller family from ST Microelectronics
include internal flash and use ARM7TDMI cores.
@end example
@end deffn
+@deffn {Flash Driver} fm3
+All members of the FM3 microcontroller family from Fujitsu
+include internal flash and use ARM Cortex M3 cores.
+The @var{fm3} driver uses the @var{target} parameter to select the
+correct bank config, it can currently be one of the following:
+@code{mb9bfxx1.cpu}, @code{mb9bfxx2.cpu}, @code{mb9bfxx3.cpu},
+@code{mb9bfxx4.cpu}, @code{mb9bfxx5.cpu} or @code{mb9bfxx6.cpu}.
+
+@example
+flash bank $_FLASHNAME fm3 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
@subsection str9xpec driver
@cindex str9xpec
@end deffn
@comment current lpc3180 code won't issue 5-byte address cycles
+@deffn {NAND Driver} mx3
+This driver handles the NAND controller in i.MX31. The mxc driver
+should work for this chip aswell.
+@end deffn
+
+@deffn {NAND Driver} mxc
+This driver handles the NAND controller found in Freescale i.MX
+chips. It has support for v1 (i.MX27 and i.MX31) and v2 (i.MX35).
+The driver takes 3 extra arguments, chip (@option{mx27},
+@option{mx31}, @option{mx35}), ecc (@option{noecc}, @option{hwecc})
+and optionally if bad block information should be swapped between
+main area and spare area (@option{biswap}), defaults to off.
+@example
+nand device mx35.nand mxc imx35.cpu mx35 hwecc biswap
+@end example
+@deffn Command {mxc biswap} bank_num [enable|disable]
+Turns on/off bad block information swaping from main area,
+without parameter query status.
+@end deffn
+@end deffn
+
@deffn {NAND Driver} orion
These controllers require an extra @command{nand device}
parameter: the address of the controller.
current target. Must be preceeded by fast_load_image.
@end deffn
-@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
+@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}|@option{s19}]
Normally you should be using @command{load_image} or GDB load. However, for
testing purposes or when I/O overhead is significant(OpenOCD running on an embedded
host), storing the image in memory and uploading the image to the target
@end deffn
@anchor{load_image}
-@deffn Command {load_image} filename address [[@option{bin}|@option{ihex}|@option{elf}] @option{min_addr} @option{max_length}]
-Load image from file @var{filename} to target memory offset by @var{address} from its load address.
+@deffn Command {load_image} filename address [[@option{bin}|@option{ihex}|@option{elf}|@option{s19}] @option{min_addr} @option{max_length}]
+Load image from file @var{filename} to target memory offset by @var{address} from its load address.
The file format may optionally be specified
-(@option{bin}, @option{ihex}, or @option{elf}).
+(@option{bin}, @option{ihex}, @option{elf}, or @option{s19}).
In addition the following arguments may be specifed:
@var{min_addr} - ignore data below @var{min_addr} (this is w.r.t. to the target's load address + @var{address})
@var{max_length} - maximum number of bytes to load.
proc load_image_bin @{fname foffset address length @} @{
# Load data from fname filename at foffset offset to
# target at address. Load at most length bytes.
- load_image $fname [expr $address - $foffset] bin $address $length
+ load_image $fname [expr $address - $foffset] bin $address $length
@}
@end example
@end deffn
@subsection Cortex-M3 specific commands
@cindex Cortex-M3
-@deffn Command {cortex_m3 maskisr} (@option{on}|@option{off})
+@deffn Command {cortex_m3 maskisr} (@option{auto}|@option{on}|@option{off})
Control masking (disabling) interrupts during target step/resume.
+
+The @option{auto} option handles interrupts during stepping a way they get
+served but don't disturb the program flow. The step command first allows
+pending interrupt handlers to execute, then disables interrupts and steps over
+the next instruction where the core was halted. After the step interrupts
+are enabled again. If the interrupt handlers don't complete within 500ms,
+the step command leaves with the core running.
+
+Note that a free breakpoint is required for the @option{auto} option. If no
+breakpoint is available at the time of the step, then the step is taken
+with interrupts enabled, i.e. the same way the @option{off} option does.
+
+Default is @option{auto}.
@end deffn
@deffn Command {cortex_m3 vector_catch} [@option{all}|@option{none}|list]
To verify any flash programming the GDB command @option{compare-sections}
can be used.
+@anchor{Using openocd SMP with GDB}
+@section Using openocd SMP with GDB
+@cindex SMP
+For SMP support following GDB serial protocol packet have been defined :
+@itemize @bullet
+@item j - smp status request
+@item J - smp set request
+@end itemize
+
+OpenOCD implements :
+@itemize @bullet
+@item @option{jc} packet for reading core id displayed by
+GDB connection. Reply is @option{XXXXXXXX} (8 hex digits giving core id) or
+ @option{E01} for target not smp.
+@item @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue
+(core id -1 is reserved for returning to normal resume mode). Reply @option{E01}
+for target not smp or @option{OK} on success.
+@end itemize
+
+Handling of this packet within GDB can be done :
+@itemize @bullet
+@item by the creation of an internal variable (i.e @option{_core}) by mean
+of function allocate_computed_value allowing following GDB command.
+@example
+set $_core 1
+#Jc01 packet is sent
+print $_core
+#jc packet is sent and result is affected in $
+@end example
+
+@item by the usage of GDB maintenance command as described in following example (2
+cpus in SMP with core id 0 and 1 @pxref{Define CPU targets working in SMP}).
+
+@example
+# toggle0 : force display of coreid 0
+define toggle0
+maint packet Jc0
+continue
+main packet Jc-1
+end
+# toggle1 : force display of coreid 1
+define toggle1
+maint packet Jc1
+continue
+main packet Jc-1
+end
+@end example
+@end itemize
+
@node Tcl Scripting API
@chapter Tcl Scripting API
Code Review / openocd.git / blobdiff