X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=1866fa0e046fd17c4dab1590d8b0d2656dc0124e;hp=a26f9ed28f8520ded0f682b9a45d5318fd80557a;hb=d2a8922bd451d0d99303d038aefb9e62c63ba831;hpb=f7274784a22e975dbab6a8b24770b652a813e64d;ds=sidebyside diff --git a/doc/openocd.texi b/doc/openocd.texi index a26f9ed28f..1866fa0e04 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -133,6 +133,46 @@ OpenOCD, then check if your interface supplier provides binaries for you. Chances are that that binary is from some SVN version that is more stable than SVN trunk where bleeding edge development takes place. +@section Packagers Please Read! + +If you are a @b{PACKAGER} of OpenOCD if you + +@enumerate +@item @b{Sell dongles} and include pre-built binaries +@item @b{Supply tools} ie: A complete development solution +@item @b{Supply IDEs} like Eclipse, or RHIDE, etc. +@item @b{Build packages} ie: RPM files, or DEB files for a Linux Distro +@end enumerate + +As a @b{PACKAGER} - you are at the top of the food chain. You solve +problems for downstream users. What you fix or solve - solves hundreds +if not thousands of user questions. If something does not work for you +please let us know. That said, would also like you to follow a few +suggestions: + +@enumerate +@item @b{Always build with Printer Ports Enabled} +@item @b{Try where possible to use LIBFTDI + LIBUSB} You cover more bases +@end enumerate + +It is your decision.. + +@itemize @bullet +@item @b{Why YES to LIBFTDI + LIBUSB} +@itemize @bullet +@item @b{LESS} work - libusb perhaps already there +@item @b{LESS} work - identical code multiple platforms +@item @b{MORE} dongles are supported +@item @b{MORE} platforms are supported +@item @b{MORE} complete solution +@end itemize +@item @b{Why not LIBFTDI + LIBUSB} (ie: ftd2xx instead) +@itemize @bullet +@item @b{LESS} Some say it is slower. +@item @b{LESS} complex to distribute (external dependencies) +@end itemize +@end itemize + @section Building From Source You can download the current SVN version with SVN client of your choice from the @@ -222,6 +262,8 @@ should be included: @item @option{--enable-jlink} - From SEGGER @item +@option{--enable-vsllink} +@item @option{--enable-rlink} - Raisonance.com dongle. @end itemize @@ -395,6 +437,9 @@ Raisonance has an adapter called @b{RLink}. It exists in a stripped-down form o @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} @end itemize @section IBM PC Parallel Printer Port Based @@ -512,7 +557,6 @@ the @option{-s } switch. The current directory and the OpenOCD target library is in the search path by default. For details on the @option{-p} option. @xref{Connecting to GDB}. -Option @option{-p} is not currently supported under native win32. 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 @@ -1140,6 +1184,9 @@ libusb. @item @b{rlink} @* Raisonance RLink usb adapter + +@item @b{vsllink} +@* vsllink is part of Versaloon which is a versatile USB programmer. @comment - End parameters @end itemize @comment - End Interface @@ -1459,7 +1506,7 @@ parameters'', the required parameters are: @itemize @bullet @item @b{-irlen NUMBER} - the length in bits of the instruction register @item @b{-ircapture NUMBER} - the ID code capture command. -@item @b{-irmask NUMBER} - the corrisponding mask for the ir register. +@item @b{-irmask NUMBER} - the corresponding mask for the ir register. @comment END REQUIRED @end itemize An example of a FOOBAR Tap @@ -1470,8 +1517,6 @@ Creates the tap ``foobar.tap'' with the instruction register (IR) is 7 bits long, during Capture-IR 0x42 is loaded into the IR, and bits [6,4,2,0] are checked. -FIXME: The IDCODE - this was not used in the old code, it should be? -Right? -Duane. @item @b{Optional configparams} @comment START Optional @itemize @bullet @@ -1566,13 +1611,13 @@ have the taps created in the proper order. @* @b{Removed: 28/nov/2008} This command has been removed and replaced by the ``jtag newtap'' command. The documentation remains here so that one can easily convert the old syntax to the new syntax. About the old -syntax: The old syntax is positional, ie: The 4th parameter is the +syntax: The old syntax is positional, ie: The 3rd parameter is the ``irmask''. The new syntax requires named prefixes, and supports -additional options, for example ``-irmask 4''. Please refer to the +additional options, for example ``-expected-id 0x3f0f0f0f''. Please refer to the @b{jtag newtap} command for details. @example -OLD: jtag_device 8 0x01 0x0e3 0xfe -NEW: jtag newtap CHIPNAME TAPNAME -irlen 8 -ircapture 0xe3 -irmask 0xfe +OLD: jtag_device 8 0x01 0xe3 0xfe +NEW: jtag newtap CHIPNAME TAPNAME -irlen 8 -ircapture 0x01 -irmask 0xe3 @end example @section Enable/Disable Taps @@ -2399,14 +2444,12 @@ port is 5555. @section Daemon Commands -@subsection sleep -@b{sleep} <@var{msec}> +@subsection sleep [@var{msec}] @cindex sleep @*Wait for n milliseconds before resuming. Useful in connection with script files (@var{script} command and @var{target_script} configuration). -@subsection sleep -@b{shutdown} +@subsection shutdown @cindex shutdown @*Close the OpenOCD daemon, disconnecting all clients (GDB, Telnet, Other). @@ -2803,7 +2846,8 @@ In general these commands control JTAG taps at a very low level. For example if you need to control a JTAG Route Controller (ie: the OMAP3530 on the Beagle Board has one) you might use these commands in a script or an event procedure. - +@section Commands +@cindex Commands @itemize @bullet @item @b{scan_chain} @cindex scan_chain @@ -2837,6 +2881,44 @@ a script or an event procedure. Display/modify variable field <@var{var}> <@var{field}> [@var{value}|@var{flip}]. @end itemize +@section Tap states +@cindex Tap states +Available tap_states are: +@itemize @bullet +@item @b{RESET} +@cindex RESET +@item @b{IDLE} +@cindex IDLE +@item @b{DRSELECT} +@cindex DRSELECT +@item @b{DRCAPTURE} +@cindex DRCAPTURE +@item @b{DRSHIFT} +@cindex DRSHIFT +@item @b{DREXIT1} +@cindex DREXIT1 +@item @b{DRPAUSE} +@cindex DRPAUSE +@item @b{DREXIT2} +@cindex DREXIT2 +@item @b{DRUPDATE} +@cindex DRUPDATE +@item @b{IRSELECT} +@cindex IRSELECT +@item @b{IRCAPTURE} +@cindex IRCAPTURE +@item @b{IRSHIFT} +@cindex IRSHIFT +@item @b{IREXIT1} +@cindex IREXIT1 +@item @b{IRPAUSE} +@cindex IRPAUSE +@item @b{IREXIT2} +@cindex IREXIT2 +@item @b{IRUPDATE} +@cindex IRUPDATE +@end itemize + @node TFTP @chapter TFTP @@ -2906,10 +2988,11 @@ This would cause GDB to connect to the gdbserver on the local pc using port 3333 @item A pipe connection is typically started as follows: @example -target remote openocd --pipe +target remote | openocd --pipe @end example This would cause GDB to run OpenOCD and communicate using pipes (stdin/stdout). -Using this method has the advantage of GDB starting/stopping OpenOCD for debug session. +Using this method has the advantage of GDB starting/stopping OpenOCD for the debug +session. @end enumerate @*To see a list of available OpenOCD commands type @option{monitor help} on the @@ -3101,24 +3184,29 @@ halt @* In digital circuit design it is often refered to as ``clock -syncronization'' the JTAG interface uses one clock (TCK or TCLK) +synchronisation'' the JTAG interface uses one clock (TCK or TCLK) operating at some speed, your target is operating at another. The two -clocks are not syncronized, they are ``asynchronous'' +clocks are not synchronised, they are ``asynchronous'' -In order for the two to work together they must syncronize. Otherwise +In order for the two to work together they must be synchronised. Otherwise the two systems will get out of sync with each other and nothing will -work. There are 2 basic options. @b{1.} use a special circuit or -@b{2.} one clock must be some multile slower the the other. +work. There are 2 basic options. +@enumerate +@item +Use a special circuit. +@item +One clock must be some multiple slower the the other. +@end enumerate @b{Does this really matter?} For some chips and some situations, this -is a non-issue (ie: A 500mhz ARM926) but for others - for example some -ATMEL SAM7 and SAM9 chips start operation from reset at 32khz - +is a non-issue (ie: A 500MHz ARM926) but for others - for example some +ATMEL SAM7 and SAM9 chips start operation from reset at 32kHz - program/enable the oscillators and eventually the main clock. It is in those critical times you must slow the jtag clock to sometimes 1 to -4khz. +4kHz. -Imagine debugging that 500mhz arm926 hand held battery powered device -that ``deep sleeps'' at 32khz between every keystroke. It can be +Imagine debugging that 500MHz ARM926 hand held battery powered device +that ``deep sleeps'' at 32kHz between every keystroke. It can be painful. @b{Solution #1 - A special circuit} @@ -3130,14 +3218,14 @@ The RTCK signal often found in some ARM chips is used to help with this problem. ARM has a good description of the problem described at this link: @url{http://www.arm.com/support/faqdev/4170.html} [checked 28/nov/2008]. Link title: ``How does the jtag synchronisation logic -work? / how does adaptive clocking working?''. +work? / how does adaptive clocking work?''. The nice thing about adaptive clocking is that ``battery powered hand held device example'' - the adaptiveness works perfectly all the time. One can set a break point or halt the system in the deep power down code, slow step out until the system speeds up. -@b{Solution #2 - Always works - but is slower} +@b{Solution #2 - Always works - but may be slower} Often this is a perfectly acceptable solution. @@ -3147,7 +3235,7 @@ depending upon the chips on your board. @b{ARM Rule of thumb} Most ARM based systems require an 8:1 division. @b{Xilinx Rule of thumb} is 1/12 the clock speed. -Note: Many FTDI2232C based JTAG dongles are limited to 6mhz. +Note: Many FTDI2232C based JTAG dongles are limited to 6MHz. You can still debug the 'lower power' situations - you just need to manually adjust the clock speed at every step. While painful and @@ -3161,7 +3249,7 @@ this way. To set the JTAG frequency use the command: @example - # Example: 1.234mhz + # Example: 1.234MHz jtag_khz 1234 @end example @@ -3307,7 +3395,7 @@ You can use the ``scan_chain'' command to verify and display the tap order. Many newer devices have multiple JTAG taps. For example: ST Microsystems STM32 chips have two taps, a ``boundary scan tap'' and -``cortexM3'' tap. Example: The STM32 reference manual, Document ID: +``CortexM3'' tap. Example: The STM32 reference manual, Document ID: RM0008, Section 26.5, Figure 259, page 651/681, the ``TDI'' pin is connected to the Boundary Scan Tap, which then connects to the CortexM3 Tap, which then connects to the TDO pin.