X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=a5478b41bd5e50a9866fe4eba183e8b3cbf62e70;hp=7bfad9bf2dfe00279141e800be1c43e55815b85e;hb=0a581ccdb12ca8105a5e99ce35254bea9284f20f;hpb=dbbe2a5388c7060e2522279725dbebf78b085a67 diff --git a/doc/openocd.texi b/doc/openocd.texi index 7bfad9bf2d..a5478b41bd 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -309,7 +309,7 @@ RTCK support? Also known as ``adaptive clocking'' @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 @@ -336,7 +336,7 @@ a built-in low cost debug adapter and usb-to-serial solution. @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} @@ -358,7 +358,7 @@ Evaluation Kits. Like the non-detachable FT2232 support on the other 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: @@ -369,11 +369,14 @@ Stellaris eval boards, they can be used to debug other target boards. @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 @@ -390,7 +393,7 @@ product. The driver can be configured to search for any VID/PID pair @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 @@ -406,7 +409,7 @@ AT91SAM764 internally. @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 @@ -414,7 +417,7 @@ Raisonance has an adapter called @b{RLink}. It exists in a stripped-down form o @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} @@ -423,7 +426,7 @@ Raisonance has an adapter called @b{RLink}. It exists in a stripped-down form o @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. +They only work with ST Micro chips, notably STM32 and STM8. @itemize @bullet @item @b{ST-LINK} @@ -436,7 +439,7 @@ They only works with ST Micro chips, notably STM32 and STM8. 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 method's: +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 @@ -463,7 +466,7 @@ The simplest solution is to get linux to ignore the ST-LINK using one of the fol @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 @@ -486,8 +489,7 @@ produced, PDF schematics are easily found and it is easy to make. @* 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 @@ -510,8 +512,7 @@ Improved parallel-port wiggler-style JTAG adapter} @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 @@ -1339,7 +1340,7 @@ have only been used by the developer who created it. 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. @@ -1549,6 +1550,47 @@ also supports it. Otherwise use @command{adapter_khz}. 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 @@ -1810,6 +1852,47 @@ OpenOCD verifies the scan chain after reset, 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 @@ -1922,6 +2005,7 @@ may access or activate TAPs. 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 @@ -3286,7 +3370,7 @@ hardware to find these values. 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. @@ -4571,13 +4655,6 @@ The AVR 8-bit microcontrollers from Atmel integrate flash memory. @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. @@ -4829,6 +4906,12 @@ the chip identification register, and autoconfigures itself. 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