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
@section Stand alone Systems
-@b{ZY1000} See: @url{http://www.zylin.com/zy1000.html} Technically, not a
+@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/33-zylin-zy1000-jtag-probe} Technically, not a
dongle, but a standalone box. The ZY1000 has the advantage that it does
not require any drivers installed on the developer PC. It also has
a built in web interface. It supports RTCK/RCLK or adaptive clocking
@itemize @bullet
@item @b{usbjtag}
-@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
+@* Link @url{http://elk.informatik.fh-augsburg.de/hhweb/doc/openocd/usbjtag/usbjtag.html}
@item @b{jtagkey}
@* See: @url{http://www.amontec.com/jtagkey.shtml}
@item @b{jtagkey2}
Stellaris eval boards, they can be used to debug other target boards.
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
-@item @b{flyswatter}
+@item @b{Flyswatter/Flyswatter2}
@* See: @url{http://www.tincantools.com}
@item @b{turtelizer2}
@* See:
@item @b{stm32stick}
@* Link @url{http://www.hitex.com/stm32-stick}
@item @b{axm0432_jtag}
-@* Axiom AXM-0432 Link @url{http://www.axman.com}
+@* Axiom AXM-0432 Link @url{http://www.axman.com} - NOTE: This JTAG does not appear
+to be available anymore as of April 2012.
@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}
+@item @b{digilent-hs1}
+@* Link @url{http://www.digilentinc.com/Products/Detail.cfm?Prod=JTAG-HS1}
@end itemize
@section USB-JTAG / Altera USB-Blaster compatibles
@itemize
@item @b{USB-JTAG} Kolja Waschk's USB Blaster-compatible adapter
-@* Link: @url{http://www.ixo.de/info/usb_jtag/}
+@* Link: @url{http://ixo-jtag.sourceforge.net/}
@item @b{Altera USB-Blaster}
@* Link: @url{http://www.altera.com/literature/ug/ug_usb_blstr.pdf}
@end itemize
@item @b{SEGGER JLINK}
@* Link: @url{http://www.segger.com/jlink.html}
@item @b{IAR J-Link}
-@* Link: @url{http://www.iar.com/website1/1.0.1.0/369/1/index.php}
+@* Link: @url{http://www.iar.com/en/products/hardware-debug-probes/iar-j-link/}
@end itemize
@section USB RLINK based
@itemize @bullet
@item @b{Raisonance RLink}
-@* Link: @url{http://www.raisonance.com/products/RLink.php}
+@* Link: @url{http://www.mcu-raisonance.com/~rlink-debugger-programmer__microcontrollers__tool~tool__T018:4cn9ziz4bnx6.html}
@item @b{STM32 Primer}
@* Link: @url{http://www.stm32circle.com/resources/stm32primer.php}
@item @b{STM32 Primer2}
@* 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 work 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
+
+For info the original ST-LINK enumerates using the mass storage usb class, however
+it's implementation is completely broken. The result is this causes issues under linux.
+The simplest solution is to get linux to ignore the ST-LINK using one of the following methods:
+@itemize @bullet
+@item modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i
+@item add "options usb-storage quirks=483:3744:i" to /etc/modprobe.conf
+@end itemize
+
@section USB Other
@itemize @bullet
@item @b{USBprog}
@section IBM PC Parallel Printer Port Based
The two well known ``JTAG Parallel Ports'' cables are the Xilnx DLC5
-and the MacGraigor Wiggler. There are many clones and variations of
+and the Macraigor Wiggler. There are many clones and variations of
these on the market.
Note that parallel ports are becoming much less common, so if you
@* Link: @url{http://www.gateworks.com/products/avila_accessories/gw16042.php}
@item @b{Wiggler2}
-@*@uref{http://www.ccac.rwth-aachen.de/@/~michaels/@/index.php/hardware/@/armjtag,
-Improved parallel-port wiggler-style JTAG adapter}
+@* Link: @url{http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag}
@item @b{Wiggler_ntrst_inverted}
@* Yet another variation - See the source code, src/jtag/parport.c
@item @b{flashlink}
@* From ST Microsystems;
-@uref{http://www.st.com/stonline/@/products/literature/um/7889.pdf,
-FlashLINK JTAG programing cable for PSD and uPSD}
+@* Link: @url{http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATA_BRIEF/DM00039500.pdf}
@end itemize
which can be found here: @url{http://www.tcl.tk}. Jim-Tcl has far
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
A separate chapter gives information about how to set these up.
@xref{Debug Adapter Configuration}.
-Read the OpenOCD source code (and Developer's GUide)
+Read the OpenOCD source code (and Developer's Guide)
if you have a new kind of hardware interface
and need to provide a driver for it.
Set the slow rate at the beginning of the reset sequence,
and the faster rate as soon as the clocks are at full speed.
+@anchor{The init_board procedure}
+@subsection The init_board procedure
+@cindex init_board procedure
+
+The concept of @code{init_board} procedure is very similar to @code{init_targets} (@xref{The init_targets procedure}.)
+- it's a replacement of ``linear'' configuration scripts. This procedure is meant to be executed when OpenOCD enters run
+stage (@xref{Entering the Run Stage},) after @code{init_targets}. The idea to have spearate @code{init_targets} and
+@code{init_board} procedures is to allow the first one to configure everything target specific (internal flash,
+internal RAM, etc.) and the second one to configure everything board specific (reset signals, chip frequency,
+reset-init event handler, external memory, etc.). Additionally ``linear'' board config file will most likely fail when
+target config file uses @code{init_targets} scheme (``linear'' script is executed before @code{init} and
+@code{init_targets} - after), so separating these two configuration stages is very convenient, as the easiest way to
+overcome this problem is to convert board config file to use @code{init_board} procedure. Board config scripts don't
+need to override @code{init_targets} defined in target config files when they only need to to add some specifics.
+
+Just as @code{init_targets}, the @code{init_board} procedure can be overriden by ``next level'' script (which sources
+the original), allowing greater code reuse.
+
+@example
+### board_file.cfg ###
+
+# source target file that does most of the config in init_targets
+source [find target/target.cfg]
+
+proc enable_fast_clock @{@} @{
+ # enables fast on-board clock source
+ # configures the chip to use it
+@}
+
+# initialize only board specifics - reset, clock, adapter frequency
+proc init_board @{@} @{
+ reset_config trst_and_srst trst_pulls_srst
+
+ $_TARGETNAME configure -event reset-init @{
+ adapter_khz 1
+ enable_fast_clock
+ adapter_khz 10000
+ @}
+@}
+@end example
+
@section Target Config Files
@cindex config file, target
@cindex target config file
@cindex SMP
After setting targets, you can define a list of targets working in SMP.
-@example
+@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
+-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.
+-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.
@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
+@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
@example
>cortex_a8 smp_gdb
-gdb coreid 0 -> -1
+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
+gdb coreid 0 -> 1
#0 :coreid 0 is displayed to GDB ,
-#->1 : next resume displays coreid 1 to GDB
+#->1 : next resume displays coreid 1 to GDB
> resume
-> cortex_a8 smp_gdb
+> cortex_a8 smp_gdb
gdb coreid 1 -> 1
#1 :coreid 1 is displayed to GDB ,
#->1 : next resume displays coreid 1 to GDB
look at how you are setting up JTAG clocking.
@end quotation
+@anchor{The init_targets procedure}
+@subsection The init_targets procedure
+@cindex init_targets procedure
+
+Target config files can either be ``linear'' (script executed line-by-line when parsed in configuration stage,
+@xref{Configuration Stage},) or they can contain a special procedure called @code{init_targets}, which will be executed
+when entering run stage (after parsing all config files or after @code{init} command, @xref{Entering the Run Stage}.)
+Such procedure can be overriden by ``next level'' script (which sources the original). This concept faciliates code
+reuse when basic target config files provide generic configuration procedures and @code{init_targets} procedure, which
+can then be sourced and enchanced or changed in a ``more specific'' target config file. This is not possible with
+``linear'' config scripts, because sourcing them executes every initialization commands they provide.
+
+@example
+### generic_file.cfg ###
+
+proc setup_my_chip @{chip_name flash_size ram_size@} @{
+ # basic initialization procedure ...
+@}
+
+proc init_targets @{@} @{
+ # initializes generic chip with 4kB of flash and 1kB of RAM
+ setup_my_chip MY_GENERIC_CHIP 4096 1024
+@}
+
+### specific_file.cfg ###
+
+source [find target/generic_file.cfg]
+
+proc init_targets @{@} @{
+ # initializes specific chip with 128kB of flash and 64kB of RAM
+ setup_my_chip MY_CHIP_WITH_128K_FLASH_64KB_RAM 131072 65536
+@}
+@end example
+
+The easiest way to convert ``linear'' config files to @code{init_targets} version is to enclose every line of ``code''
+(i.e. not @code{source} commands, procedures, etc.) in this procedure.
+
+For an example of this scheme see LPC2000 target config files.
+
+The @code{init_boards} procedure is a similar concept concerning board config files (@xref{The init_board procedure}.)
+
@subsection ARM Core Specific Hacks
If the chip has a DCC, enable it. If the chip is an ARM9 with some
After it leaves this stage, configuration commands may no
longer be issued.
+@anchor{Entering the Run Stage}
@section Entering the Run Stage
The first thing OpenOCD does after leaving the configuration
"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 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
option. When vendors put out multiple versions of a chip, or use the same
JTAG-level ID for several largely-compatible chips, it may be more practical
to ignore the version field than to update config files to handle all of
-the various chip IDs.
+the various chip IDs. The version field is defined as bit 28-31 of the IDCODE.
@item @code{-ircapture} @var{NUMBER}
@*The bit pattern loaded by the TAP into the JTAG shift register
on entry to the @sc{ircapture} state, such as 0x01.
@* 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
@comment - defines mass_erase ... pointless given flash_erase_address
@end deffn
-@deffn {Flash Driver} ecosflash
-@emph{No idea what this is...}
-The @var{ecosflash} driver defines one mandatory parameter,
-the name of a modules of target code which is downloaded
-and executed.
-@end deffn
-
@deffn {Flash Driver} lpc2000
Most members of the LPC1700 and LPC2000 microcontroller families from NXP
include internal flash and use Cortex-M3 (LPC1700) or ARM7TDMI (LPC2000) cores.
flash bank $_FLASHNAME stm32f1x 0 0 0 0 $_TARGETNAME
@end example
+If you have a target with dual flash banks then define the second bank
+as per the following example.
+@example
+flash bank $_FLASHNAME stm32f1x 0x08080000 0 0 0 $_TARGETNAME
+@end example
+
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
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
@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.
@anchor{load_image}
@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.
+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}, @option{elf}, or @option{s19}).
In addition the following arguments may be specifed:
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
@cindex SMP
For SMP support following GDB serial protocol packet have been defined :
@itemize @bullet
-@item j - smp status request
+@item j - smp status request
@item J - smp set request
@end itemize
@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}
+@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
+@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
+set $_core 1
#Jc01 packet is sent
-print $_core
-#jc packet is sent and result is affected in $
+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
+# 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
Code Review / openocd.git / blobdiff