@chapter Building
@cindex building OpenOCD
+@section Pre-Built Tools
If you are interested in getting actual work done rather than building
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
following repositories:
homepage (@uref{www.amontec.com}), as the JTAGkey uses a non-standard VID/PID.
@end itemize
-libftdi is supported under windows. Versions earlier than 0.13 will require patching.
-see contrib/libftdi for more details.
+libftdi is supported under windows. Do not use versions earlier then 0.14.
In general, the D2XX driver provides superior performance (several times as fast),
but has the draw-back of being binary-only - though that isn't that bad, as it isn't
@end example
Bootstrap generates the configure script, and prepares building on your system.
@example
- ./configure
+ ./configure [options, see below]
@end example
Configure generates the Makefiles used to build OpenOCD.
@example
make
+ make install
@end example
-Make builds OpenOCD, and places the final executable in ./src/.
+Make builds OpenOCD, and places the final executable in ./src/, the last step, ``make install'' is optional.
The configure script takes several options, specifying which JTAG interfaces
should be included:
@itemize @bullet
@item
-@option{--enable-parport}
+@option{--enable-parport} - Bit bang pc printer ports.
+@item
+@option{--enable-parport_ppdev} - Parallel Port [see below]
@item
-@option{--enable-parport_ppdev}
+@option{--enable-parport_giveio} - Parallel Port [see below]
@item
-@option{--enable-parport_giveio}
+@option{--enable-amtjtagaccel} - Parallel Port [Amontec, see below]
@item
-@option{--enable-amtjtagaccel}
+@option{--enable-ft2232_ftd2xx} - Numerous USB Type ARM JTAG dongles use the FT2232C chip from this FTDICHIP.COM chip (closed source).
@item
-@option{--enable-ft2232_ftd2xx}
-@footnote{Using the latest D2XX drivers from FTDI and following their installation
-instructions, I had to use @option{--enable-ft2232_libftd2xx} for OpenOCD to
-build properly.}
+@option{--enable-ft2232_libftdi} - An open source (free) alternate to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin)
@item
-@option{--enable-ft2232_libftdi}
+@option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c, point at the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
@item
-@option{--with-ftd2xx=/path/to/d2xx/}
+@option{--with-ftd2xx-linux-tardir=PATH} - Linux only equal of @option{--with-ftd2xx-win32-zipdir}, where you unpacked the TAR.GZ file.
+@item
+@option{--with-ftd2xx-lib=shared|static} - Linux only. Default: static, specifies how the FTDICHIP.COM libftd2xx driver should be linked. Note 'static' only works in conjunction with @option{--with-ftd2xx-linux-tardir}. Shared is supported (12/26/2008), however you must manually install the required header files and shared libraries in an appropriate place. This uses ``libusb'' internally.
@item
@option{--enable-gw16012}
@item
@item
@option{--enable-presto_ftd2xx}
@item
-@option{--enable-jlink}
+@option{--enable-jlink} - From SEGGER
+@item
+@option{--enable-vsllink}
@item
-@option{--enable-rlink}
+@option{--enable-rlink} - Raisonance.com dongle.
@end itemize
+@section Parallel Port Dongles
+
If you want to access the parallel port using the PPDEV interface you have to specify
both the @option{--enable-parport} AND the @option{--enable-parport_ppdev} option since
the @option{--enable-parport_ppdev} option actually is an option to the parport driver
(see @uref{http://forum.sparkfun.com/viewtopic.php?t=3795} for more info).
-Cygwin users have to specify the location of the FTDI D2XX package. This should be an
-absolute path containing no spaces.
+@section FT2232C Based USB Dongles
+
+There are 2 methods of using the FTD2232, either (1) using the
+FTDICHIP.COM closed source driver, or (2) the open (and free) driver
+libftdi. Some claim the (closed) FTDICHIP.COM solution is faster.
+
+The FTDICHIP drivers come as either a (win32) ZIP file, or a (linux)
+TAR.GZ file. You must unpack them ``some where'' convient. As of this
+writing (12/26/2008) FTDICHIP does not supply means to install these
+files ``in an appropriate place'' As a result, there are two
+``./configure'' options that help.
+
+Below is an example build process:
+
+1) Check out the latest version of ``openocd'' from SVN.
-Linux users should copy the various parts of the D2XX package to the appropriate
-locations, i.e. /usr/include, /usr/lib.
+2) Download & Unpack either the Windows or Linux FTD2xx Drivers
+ (@uref{http://www.ftdichip.com/Drivers/D2XX.htm})
-Miscellaneous configure options
+@example
+ /home/duane/ftd2xx.win32 => the Cygwin/Win32 ZIP file contents.
+ /home/duane/libftd2xx0.4.16 => the Linux TAR file contents.
+@end example
+
+3) Configure with these options:
+
+@example
+Cygwin FTCICHIP solution
+ ./configure --prefix=/home/duane/mytools \
+ --enable-ft2232_ftd2xx \
+ --with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32
+
+Linux FTDICHIP solution
+ ./configure --prefix=/home/duane/mytools \
+ --enable-ft2232_ftd2xx \
+ --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
+
+Cygwin/Linux LIBFTDI solution
+ Assumes:
+ 1a) For Windows: The windows port of LIBUSB is in place.
+ 1b) For Linux: libusb has been built and is inplace.
+
+ 2) And libftdi has been built and installed
+ Note: libftdi - relies upon libusb.
+
+ ./configure --prefix=/home/duane/mytools \
+ --enable-ft2232_libftdi
+
+@end example
+
+4) Then just type ``make'', and perhaps ``make install''.
+
+
+@section Miscellaneous configure options
@itemize @bullet
@item
@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
@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
@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
@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).
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
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
Code Review / openocd.git / blobdiff