X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=daa946098720b417d026d4ca3689ed857d3143ce;hp=4d68ae523d956d01b60cd2b42c983742870dc217;hb=20a3b14828c5015647fa438e0cbee84685bcdf5f;hpb=f2dc1eeef159f00bc5c1f5bbd99b1761f3df0ae1 diff --git a/doc/openocd.texi b/doc/openocd.texi index 4d68ae523d..daa9460987 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -66,6 +66,7 @@ Free Documentation License''. * Running:: Running OpenOCD * OpenOCD Project Setup:: OpenOCD Project Setup * Config File Guidelines:: Config File Guidelines +* Translating Configuration Files:: Translating Configuration Files * Daemon Configuration:: Daemon Configuration * Interface - Dongle Configuration:: Interface - Dongle Configuration * Reset Configuration:: Reset Configuration @@ -82,7 +83,6 @@ Free Documentation License''. * GDB and OpenOCD:: Using GDB and OpenOCD * Tcl Scripting API:: Tcl Scripting API * Upgrading:: Deprecated/Removed Commands -* Target Library:: Target Library * FAQ:: Frequently Asked Questions * Tcl Crash Course:: Tcl Crash Course * License:: GNU Free Documentation License @@ -171,38 +171,38 @@ documentation, as well as more conventional bug fixes and enhancements. The resources in this chapter are available for developers wishing to explore or expand the OpenOCD source code. -@section OpenOCD Subversion Repository +@section OpenOCD GIT Repository -You can download the current SVN version with an SVN client of your -choice from the following repositories: +During the 0.3.x release cycle, OpenOCD switched from Subversion to +a GIT repository hosted at SourceForge. The repository URL is: - @uref{svn://svn.berlios.de/openocd/trunk} +@uref{git://openocd.git.sourceforge.net/gitroot/openocd/openocd} -or +You may prefer to use a mirror and the HTTP protocol: - @uref{http://svn.berlios.de/svnroot/repos/openocd/trunk} +@uref{http://repo.or.cz/r/openocd.git} -Using the SVN command line client, you can use the following command to -fetch the latest version (make sure there is no (non-svn) directory -called "openocd" in the current directory): +With standard GIT tools, use @command{git clone} to initialize +a local repository, and @command{git pull} to update it. +There are also gitweb pages letting you browse the repository +with a web browser, or download arbitrary snapshots without +needing a GIT client: - svn checkout svn://svn.berlios.de/openocd/trunk openocd +@uref{http://openocd.git.sourceforge.net/git/gitweb.cgi?p=openocd/openocd} -If you prefer GIT based tools, the @command{git-svn} package works too: +@uref{http://repo.or.cz/w/openocd.git} - git svn clone -s svn://svn.berlios.de/openocd - -The ``README'' file contains the instructions for building the project -from the repository. +The @file{README} file contains the instructions for building the project +from the repository or a snapshot. Developers that want to contribute patches to the OpenOCD system are -@b{strongly} encouraged to base their work off of the most recent trunk -revision. Patches created against older versions may require additional +@b{strongly} encouraged to work against mainline. +Patches created against older versions may require additional work from their submitter in order to be updated for newer releases. @section Doxygen Developer Manual -During the development of the 0.2.0 release, the OpenOCD project began +During the 0.2.x release cycle, the OpenOCD project began providing a Doxygen reference manual. This document contains more technical information about the software internals, development processes, and similar documentation: @@ -211,7 +211,7 @@ processes, and similar documentation: 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, -listed in the Doxyfile configuration in the top of the repository trunk. +listed in the Doxyfile configuration in the top of the source tree. @section OpenOCD Developer Mailing List @@ -220,10 +220,9 @@ communication between developers: @uref{https://lists.berlios.de/mailman/listinfo/openocd-development} -All drivers developers are enouraged to also subscribe to the list of -SVN commits to keep pace with the ongoing changes: - -@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn} +Discuss and submit patches to this list. +The @file{PATCHES} file contains basic information about how +to prepare patches. @node JTAG Hardware Dongles @@ -910,19 +909,68 @@ including developers and integrators of OpenOCD and any user who needs to get a new board working smoothly. It provides guidelines for creating those files. -You should find the following directories under @t{$(INSTALLDIR)/scripts}: - +You should find the following directories under @t{$(INSTALLDIR)/scripts}, +with files including the ones listed here. +Use them as-is where you can; or as models for new files. @itemize @bullet @item @file{interface} ... think JTAG Dongle. Files that configure JTAG adapters go here. +@example +$ ls interface +arm-jtag-ew.cfg hitex_str9-comstick.cfg oocdlink.cfg +arm-usb-ocd.cfg icebear.cfg openocd-usb.cfg +at91rm9200.cfg jlink.cfg parport.cfg +axm0432.cfg jtagkey2.cfg parport_dlc5.cfg +calao-usb-a9260-c01.cfg jtagkey.cfg rlink.cfg +calao-usb-a9260-c02.cfg jtagkey-tiny.cfg sheevaplug.cfg +calao-usb-a9260.cfg luminary.cfg signalyzer.cfg +chameleon.cfg luminary-icdi.cfg stm32-stick.cfg +cortino.cfg luminary-lm3s811.cfg turtelizer2.cfg +dummy.cfg olimex-arm-usb-ocd.cfg usbprog.cfg +flyswatter.cfg olimex-jtag-tiny.cfg vsllink.cfg +$ +@end example @item @file{board} ... think Circuit Board, PWA, PCB, they go by many names. Board files -contain initialization items that are specific to a board. For +contain initialization items that are specific to a board. +They reuse target configuration files, since the same +microprocessor chips are used on many boards, +but support for external parts varies widely. For example, the SDRAM initialization sequence for the board, or the type of external flash and what address it uses. Any initialization sequence to enable that external flash or SDRAM should be found in the board file. Boards may also contain multiple targets: two CPUs; or -a CPU and an FPGA or CPLD. +a CPU and an FPGA. +@example +$ ls board +arm_evaluator7t.cfg keil_mcb1700.cfg +at91rm9200-dk.cfg keil_mcb2140.cfg +at91sam9g20-ek.cfg linksys_nslu2.cfg +atmel_at91sam7s-ek.cfg logicpd_imx27.cfg +atmel_at91sam9260-ek.cfg mini2440.cfg +atmel_sam3u_ek.cfg olimex_LPC2378STK.cfg +crossbow_tech_imote2.cfg olimex_lpc_h2148.cfg +csb337.cfg olimex_sam7_ex256.cfg +csb732.cfg olimex_sam9_l9260.cfg +digi_connectcore_wi-9c.cfg olimex_stm32_h103.cfg +dm355evm.cfg omap2420_h4.cfg +dm365evm.cfg osk5912.cfg +dm6446evm.cfg pic-p32mx.cfg +eir.cfg propox_mmnet1001.cfg +ek-lm3s1968.cfg pxa255_sst.cfg +ek-lm3s3748.cfg sheevaplug.cfg +ek-lm3s811.cfg stm3210e_eval.cfg +ek-lm3s9b9x.cfg stm32f10x_128k_eval.cfg +hammer.cfg str910-eval.cfg +hitex_lpc2929.cfg telo.cfg +hitex_stm32-performancestick.cfg ti_beagleboard.cfg +hitex_str9-comstick.cfg topas910.cfg +iar_str912_sk.cfg topasa900.cfg +imx27ads.cfg unknown_at91sam9260.cfg +imx27lnst.cfg x300t.cfg +imx31pdk.cfg zy1000.cfg +$ +@end example @item @file{target} ... think chip. The ``target'' directory represents the JTAG TAPs on a chip @@ -930,6 +978,37 @@ which OpenOCD should control, not a board. Two common types of targets are ARM chips and FPGA or CPLD chips. When a chip has multiple TAPs (maybe it has both ARM and DSP cores), the target config file defines all of them. +@example +$ ls target +aduc702x.cfg imx27.cfg pxa255.cfg +ar71xx.cfg imx31.cfg pxa270.cfg +at91eb40a.cfg imx35.cfg readme.txt +at91r40008.cfg is5114.cfg sam7se512.cfg +at91rm9200.cfg ixp42x.cfg sam7x256.cfg +at91sam3u1c.cfg lm3s1968.cfg samsung_s3c2410.cfg +at91sam3u1e.cfg lm3s3748.cfg samsung_s3c2440.cfg +at91sam3u2c.cfg lm3s6965.cfg samsung_s3c2450.cfg +at91sam3u2e.cfg lm3s811.cfg samsung_s3c4510.cfg +at91sam3u4c.cfg lm3s9b9x.cfg samsung_s3c6410.cfg +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 +c100.cfg lpc2148.cfg str710.cfg +c100config.tcl lpc2294.cfg str730.cfg +c100helper.tcl lpc2378.cfg str750.cfg +c100regs.tcl lpc2478.cfg str912.cfg +cs351x.cfg lpc2900.cfg telo.cfg +davinci.cfg mega128.cfg ti_dm355.cfg +dragonite.cfg netx500.cfg ti_dm365.cfg +epc9301.cfg omap2420.cfg ti_dm6446.cfg +feroceon.cfg omap3530.cfg tmpa900.cfg +icepick.cfg omap5912.cfg tmpa910.cfg +imx21.cfg pic32mx.cfg xba_revA3.cfg +$ +@end example +@item @emph{more} ... browse for other library files which may be useful. +For example, there are various generic and CPU-specific utilities. @end itemize The @file{openocd.cfg} user config @@ -1385,6 +1464,46 @@ Examples: @item pxa270 - again - CS0 flash - it goes in the board file. @end itemize +@node Translating Configuration Files +@chapter Translating Configuration Files +@cindex translation +If you have a configuration file for another hardware debugger(Abatron, +BDI2000, BDI3000, Lauterbach, Segger, MacRaigor, etc.), translating +it into OpenOCD syntax is often quite straightforward. The most tricky +part of creating a configuration script is oftentimes the reset init +sequence where e.g. PLLs, DRAM and the like is set up. + +One trick that you can use when translating is to write small +Tcl proc's to translate the syntax into OpenOCD syntax. This +can avoid manual translation errors and make it easier to +convert other scripts later on. + +Example of transforming quirky arguments to a simple search and +replace job: + +@example +# rewrite commands of the form below to arm11 mcr... +# +# Lauterbach syntax(?) +# +# Data.Set c15:0x042f %long 0x40000015 +# +# OpenOCD syntax when using procedure below. +# +# setc15 0x01 0x00050078 +# +# +proc setc15 @{regs value@} @{ + global TARGETNAME + + echo [format "set p15 0x%04x, 0x%08x" $regs $value] + + arm11 mcr $TARGETNAME 15 [expr ($regs>>12)&0x7] [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] [expr ($regs>>8)&0x7] $value +@} +@end example + + + @node Daemon Configuration @chapter Daemon Configuration @cindex initialization @@ -6909,38 +7028,6 @@ foreach who @{A B C D E@} @} @end example -@node Target Library -@chapter Target Library -@cindex Target Library - -OpenOCD comes with a target configuration script library. These scripts can be -used as-is or serve as a starting point. - -The target library is published together with the OpenOCD executable and -the path to the target library is in the OpenOCD script search path. -Similarly there are example scripts for configuring the JTAG interface. - -The command line below uses the example parport configuration script -that ship with OpenOCD, then configures the str710.cfg target and -finally issues the init and reset commands. The communication speed -is set to 10kHz for reset and 8MHz for post reset. - -@example -openocd -f interface/parport.cfg -f target/str710.cfg \ - -c "init" -c "reset" -@end example - -To list the target scripts available: - -@example -$ ls /usr/local/lib/openocd/target - -arm7_fast.cfg lm3s6965.cfg pxa255.cfg stm32.cfg xba_revA3.cfg -at91eb40a.cfg lpc2148.cfg pxa255_sst.cfg str710.cfg zy1000.cfg -at91r40008.cfg lpc2294.cfg sam7s256.cfg str912.cfg -at91sam9260.cfg nslu2.cfg sam7x256.cfg wi-9c.cfg -@end example - @include fdl.texi @node OpenOCD Concept Index