X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=0c0b9519feea4cec5fbe9d1bc45b816a9ea0b595;hp=233da0ef8f2429f4cc9d11f39a316dbe9c157e78;hb=064475459bf869d5c722851fdfd22719ec0a3adc;hpb=e8b094b846c2f16d2a5b682be35dcb3a45e7fee1 diff --git a/doc/openocd.texi b/doc/openocd.texi index 233da0ef8f..0c0b9519fe 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -255,7 +255,7 @@ communication between developers: @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 @@ -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,35 +417,62 @@ 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} @* 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} -@* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604 +@* Link: @url{http://shop.embedded-projects.net/} - which uses an Atmel MEGA32 and a UBN9604 @item @b{USB - Presto} @* Link: @url{http://tools.asix.net/prg_presto.htm} @item @b{Versaloon-Link} -@* Link: @url{http://www.simonqian.com/en/Versaloon} +@* Link: @url{http://www.versaloon.com} @item @b{ARM-JTAG-EW} @* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html} @item @b{Buspirate} @* Link: @url{http://dangerousprototypes.com/bus-pirate-manual/} + +@item @b{opendous} +@* Link: @url{http://code.google.com/p/opendous-jtag/} + +@item @b{estick} +@* Link: @url{http://code.google.com/p/estick-jtag/} @end itemize @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 @@ -465,8 +495,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 @@ -489,8 +518,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 @@ -1318,7 +1346,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. @@ -1528,6 +1556,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 @@ -1789,6 +1858,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 @@ -1901,6 +2011,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 @@ -2564,6 +2675,34 @@ which are not currently documented here. @end quotation @end deffn +@deffn {Interface Driver} {stlink} +ST Micro ST-LINK adapter. + +@deffn {Config Command} {stlink_device_desc} description +Currently Not Supported. +@end deffn + +@deffn {Config Command} {stlink_serial} serial +Currently Not Supported. +@end deffn + +@deffn {Config Command} {stlink_layout} (@option{sg}|@option{usb}) +Specifies the stlink layout to use. +@end deffn + +@deffn {Config Command} {stlink_vid_pid} vid pid +The vendor ID and product ID of the STLINK device. +@end deffn + +@deffn {Config Command} {stlink_api} api_level +Manually sets the stlink api used, valid options are 1 or 2. +@end deffn +@end deffn + +@deffn {Interface Driver} {opendous} +opendous-jtag is a freely programmable USB adapter. +@end deffn + @deffn {Interface Driver} {ZY1000} This is the Zylin ZY1000 JTAG debugger. @end deffn @@ -3261,7 +3400,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. @@ -3801,6 +3940,10 @@ base @var{address} to be used when an MMU is active. The value should normally correspond to a static mapping for the @code{-work-area-phys} address, set up by the current operating system. +@item @code{-rtos} @var{rtos_type} -- enable rtos support for target, +@var{rtos_type} can be one of @option{auto}|@option{eCos}|@option{ThreadX}| +@option{FreeRTOS}|@option{linux}. + @end itemize @end deffn @@ -4429,6 +4572,7 @@ flash bank $_FLASHNAME aduc702x 0 0 0 0 $_TARGETNAME @end example @end deffn +@anchor{at91sam3} @deffn {Flash Driver} at91sam3 @cindex at91sam3 All members of the AT91SAM3 microcontroller family from @@ -4493,6 +4637,13 @@ This command shows/sets the slow clock frequency used in the @end deffn @end deffn +@deffn {Flash Driver} at91sam4 +@cindex at91sam4 +All members of the AT91SAM4 microcontroller family from +Atmel include internal flash and use ARM's Cortex-M4 core. +This driver uses the same cmd names/syntax as @xref{at91sam3}. +@end deffn + @deffn {Flash Driver} at91sam7 All members of the AT91SAM7 microcontroller family from Atmel include internal flash and use ARM7TDMI cores. The driver automatically @@ -4546,13 +4697,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. @@ -4804,6 +4948,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