diff --git a/Makefile.am b/Makefile.am index 722c37323..4e6c28507 100644 --- a/Makefile.am +++ b/Makefile.am @@ -24,7 +24,8 @@ EXTRA_DIST = \ BUGS \ HACKING \ NEWTAPS \ - README.Win32 \ + README.Windows \ + README.OSX \ Doxyfile.in \ tools/logger.pl \ contrib/loaders @@ -89,7 +90,7 @@ uninstall-hook: distclean-local: rm -rf Doxyfile doxygen rm -f $(srcdir)/jimtcl/configure.gnu - + DISTCLEANFILES = doxygen.log MAINTAINERCLEANFILES = \ diff --git a/README b/README index d1b983d76..0781dfc42 100644 --- a/README +++ b/README @@ -2,36 +2,69 @@ Welcome to OpenOCD! =================== OpenOCD provides on-chip programming and debugging support with a -layered architecture of JTAG interface and TAP support, debug target -support (e.g. ARM, MIPS), and flash chip drivers (e.g. CFI, NAND, etc.). -Several network interfaces are available for interactiving with OpenOCD: -HTTP, telnet, TCL, and GDB. The GDB server enables OpenOCD to function -as a "remote target" for source-level debugging of embedded systems -using the GNU GDB program. +layered architecture of JTAG interface and TAP support including: + +- (X)SVF playback to faciliate automated boundary scan and FPGA/CPLD + programming; +- debug target support (e.g. ARM, MIPS): single-stepping, + breakpoints/watchpoints, etc; +- flash chip drivers (e.g. CFI, NAND, internal flash); +- embedded TCL intepreter for easy scripting. + +Several network interfaces are available for interacting with OpenOCD: +telnet, TCL, and GDB. The GDB server enables OpenOCD to function as a +"remote target" for source-level debugging of embedded systems using +the GNU GDB program (and the others who talk GDB protocol, e.g. IDA +Pro). This README file contains an overview of the following topics: + +- quickstart instructions, - how to find and build more OpenOCD documentation, -- the build process +- list of the supported hardware, +- the installation and build process, - packaging tips. -- configuration options + + +============================ +Quickstart for the impatient +============================ + +If you have a popular board then just start OpenOCD with its config, +e.g.: + + openocd -f board/stm32f4discovery.cfg + +If you are connecting a particular adapter with some specific target, +you need to source both the jtag interface and the target configs, +e.g.: + + openocd -f interface/ftdi/jtagkey2.cfg -f target/ti_calypso.cfg + +NB: when using an FTDI-based adapter you should prefer configs in the +ftdi directory; the old configs for the ft2232 are deprecated. + +After OpenOCD startup, connect GDB with + + (gdb) target extended-remote localhost:3333 + ===================== OpenOCD Documentation ===================== -In addition to in-tree documentation, the latest documentation may be -viewed on-line at the following URLs: +In addition to the in-tree documentation, the latest manuals may be +viewed online at the following URLs: - OpenOCD User's Guide: + OpenOCD User's Guide: http://openocd.sourceforge.net/doc/html/index.html - OpenOCD Developer's Manual: + OpenOCD Developer's Manual: http://openocd.sourceforge.net/doc/doxygen/html/index.html These reflect the latest development versions, so the following section introduces how to build the complete documentation from the package. - For more information, refer to these documents or contact the developers by subscribing to the OpenOCD developer mailing list: @@ -40,7 +73,12 @@ by subscribing to the OpenOCD developer mailing list: Building the OpenOCD Documentation ---------------------------------- -The OpenOCD User's Guide can be produced in two different format: +By default the OpenOCD build process prepares documentation in the +"Info format" and installs it the standard way, so that "info openocd" +can access it. + +Additionally, the OpenOCD User's Guide can be produced in the +following different formats: # If PDFVIEWER is set, this creates and views the PDF User Guide. make pdf && ${PDFVIEWER} doc/openocd.pdf @@ -52,24 +90,47 @@ The OpenOCD Developer Manual contains information about the internal architecture and other details about the code: # NB! make sure doxygen is installed, type doxygen --version - make doxygen + make doxygen && ${HTMLVIEWER} doxygen/index.html - # If HTMLVIEWER is set, this views the HTML Doxygen output. - ${HTMLVIEWER} doxygen/index.html -The remaining sections describe how to configure the system such that -you can build the in-tree documentation. +================== +Supported hardware +================== + +JTAG adapters +------------- + +AICE, ARM-JTAG-EW, ARM-USB-OCD, ARM-USB-TINY, AT91RM9200, axm0432, +BCM2835, Bus Blaster, Buspirate, Chameleon, Cortino, DLC 5, +DLP-USB1232H, embedded projects, eStick, FlashLINK, FlossJTAG, +Flyswatter, Flyswatter2, Hoegl, ICDI, ICEBear, J-Link, JTAGkey, +JTAGkey2, JTAG-lock-pick, KT-Link, Lisa/L, LPC1768-Stick, MiniModule, +NGX, NXHX, OOCDLink, Opendous, OpenJTAG, Openmoko, OpenRD, OSBDM, +Presto, Redbee, RLink, SheevaPlug devkit, Stellaris evkits, ST-LINK, +STM32-PerformanceStick, STR9-comStick, sysfsgpio, TUMPA, Turtelizer, +ULINK, USB-A9260, USB-Blaster, USB-JTAG, USBprog, VPACLink, VSLLink, +Wiggler, XDS100v2, Xverve. + +Debug targets +------------- + +ARM11, ARM7, ARM9, AVR32, Cortex-A, Cortex-R, Cortex-M, +Feroceon/Dragonite, DSP563xx, DSP5680xx, FA526, MIPS EJTAG, NDS32, +XScale. + +Flash drivers +------------- + +ADUC702x, AT91SAM, AVR, CFI, DSP5680xx, EFM32, EM357, FM3, Kinetis, +LPC2000, LPC2900, LPCSPIFI, PIC32mx, Stellaris, STM32, STMSMI, STR7x, +STR9x; NAND controllers of AT91SAM9, LPC3180, LPC32xx, i.MX31, MXC, +NUC910, Orion/Kirkwood, S3C24xx, S3C6400. + ================== Installing OpenOCD ================== -On Linux, you may have permissions problems to address. The best way -to do this is to use the contrib/openocd.udev rules file. It probably -belongs somewhere in /etc/udev/rules.d, but consult your operating -system documentation to be sure. In particular, make sure that it -matches the syntax used by your operating system's version of udev. - A Note to OpenOCD Users ----------------------- @@ -77,13 +138,14 @@ If you would rather be working "with" OpenOCD rather than "on" it, your operating system or JTAG interface supplier may provide binaries for you in a convenient-enough package. -Such packages may be more stable than git mainline, where bleeding-edge -development takes place. These "Packagers" produce binary releases of -OpenOCD after the developers produces new "release" versions of the -source code. Previous versions of OpenOCD cannot be used to diagnose -problems with the current release, so users are encouraged to keep in -contact with their distribution package maintainers or interface vendors -to ensure suitable upgrades appear regularly. +Such packages may be more stable than git mainline, where +bleeding-edge development takes place. These "Packagers" produce +binary releases of OpenOCD after the developers produces new "release" +versions of the source code. Previous versions of OpenOCD cannot be +used to diagnose problems with the current release, so users are +encouraged to keep in contact with their distribution package +maintainers or interface vendors to ensure suitable upgrades appear +regularly. Users of these binary versions of OpenOCD must contact their Packager to ask for support or newer versions of the binaries; the OpenOCD @@ -94,10 +156,9 @@ A Note to OpenOCD Packagers You are a PACKAGER of OpenOCD if you: -- Sell dongles: and include pre-built binaries -- Supply tools: A complete development solution -- Supply IDEs: like Eclipse, or RHIDE, etc. -- Build packages: RPM files, or DEB files for a Linux Distro +- Sell dongles and include pre-built binaries; +- Supply tools or IDEs (a development solution integrating OpenOCD); +- Build packages (e.g. RPM or DEB files for a GNU/Linux distribution). As a PACKAGER, you will experience first reports of most issues. When you fix those problems for your users, your solution may help @@ -111,21 +172,25 @@ resolved in our future releases. That said, the OpenOCD developers would also like you to follow a few suggestions: -- Send patches, including config files, upstream. -- Always build with printer ports enabled. -- Use libftdi + libusb for FT2232 support. +- Send patches, including config files, upstream, participate in the + discussions; +- Enable all the options OpenOCD supports, even those unrelated to your + particular hardware; +- Use "ftdi" interface adapter driver for the FTDI-based devices. + +As a PACKAGER, never link against the FTD2XX library, as the resulting +binaries can't be legally distributed, due to the restrictions of the +GPL. -Remember, the FTD2XX library cannot be used in binary distributions, due -to restrictions of the GPL v2. ================ Building OpenOCD ================ The INSTALL file contains generic instructions for running 'configure' -and compiling the OpenOCD source code. That file is provided by default -for all GNU automake packages. If you are not familiar with the GNU -autotools, then you should read those instructions first. +and compiling the OpenOCD source code. That file is provided by +default for all GNU autotools packages. If you are not familiar with +the GNU autotools, then you should read those instructions first. The remainder of this document tries to provide some instructions for those looking for a quick-install. @@ -133,249 +198,108 @@ those looking for a quick-install. OpenOCD Dependencies -------------------- -Presently, GCC is required to build OpenOCD. The developers have begun -to enforce strict code warnings (-Wall, -Werror, -Wextra, and more) and -use C99-specific features: inline functions, named initializers, mixing -declarations with code, and other tricks. While it may be possible to -use other compilers, they must be somewhat modern and could require -extending support to conditionally remove GCC-specific extensions. +GCC or Clang is currently required to build OpenOCD. The developers +have begun to enforce strict code warnings (-Wall, -Werror, -Wextra, +and more) and use C99-specific features: inline functions, named +initializers, mixing declarations with code, and other tricks. While +it may be possible to use other compilers, they must be somewhat +modern and could require extending support to conditionally remove +GCC-specific extensions. -Also, you need to install the appropriate driver files, if you want to -build support for a USB or FTDI-based interface: +You'll also need: -- ft2232, jlink, rlink, vsllink, usbprog, arm-jtag-ew: - - libusb: required for portable communication with USB dongles -- ft2232 also requires: - - libftdi: http://www.intra2net.com/opensource/ftdi/ *OR* - - ftd2xx: http://www.ftdichip.com/Drivers/D2XX.htm, - or the Amontec version (from http://www.amontec.com), for - easier support of JTAGkey's vendor and product IDs. +- make +- libtool -Many Linux distributions provide these packages through their automated -installation and update mechanisms; however, some Linux versions include -older versions of libftdi. In particular, using Ubuntu 8.04 has been -problematic, but newer versions of Ubuntu do not have this problem. +Additionally, for building from git: + +- autoconf >= 2.59 +- automake >= 1.9 +- texinfo + +USB-based adapters depend on libusb-1.0 and some older drivers require +libusb-0.1 or libusb-compat-0.1. + +USB-Blaster, ASIX Presto, OpenJTAG and ft2232 interface adapter +drivers need either one of: + - libftdi: http://www.intra2net.com/en/developer/libftdi/index.php + - ftd2xx: http://www.ftdichip.com/Drivers/D2XX.htm (proprietary, + GPL-incompatible) + +Permissions delegation +---------------------- + +Running OpenOCD with root/administrative permissions is strongly +discouraged for security reasons. + +For USB devices on GNU/Linux you should use the contrib/openocd.udev +rules file. It probably belongs somewhere in /etc/udev/rules.d, but +consult your operating system documentation to be sure. Do not forget +to add yourself to the "plugdev" group. + +For parallel port adapters on GNU/Linux and FreeBSD please change your +"ppdev" (parport* or ppi*) device node permissions accordingly. + +For parport adapters on Windows you need to run install_giveio.bat +(it's also possible to use "ioperm" with Cygwin instead) to give +ordinary users permissions for accessing the "LPT" registers directly. Compiling OpenOCD ----------------- -To build OpenOCD (on both Linux and Cygwin), use the following sequence -of commands: +To build OpenOCD, use the following sequence of commands: - ./configure [with some options listed in the next section] - make - make install + ./bootstrap (when building from the git repository) + ./configure [options] + make + sudo make install -The 'configure' step generates the Makefiles required to build OpenOCD, -usually with one or more options provided to it. The first 'make' step -will build OpenOCD and place the final executable in ./src/. The -final (optional) step, ``make install'', places all of the files in the -required location. +The 'configure' step generates the Makefiles required to build +OpenOCD, usually with one or more options provided to it. The first +'make' step will build OpenOCD and place the final executable in +'./src/'. The final (optional) step, ``make install'', places all of +the files in the required location. -Cross-Compiling Options +To see the list of all the supported options, run + ./configure --help + +Cross-compiling Options ----------------------- -To cross-compile, you must specify both --build and --host options to -the 'configure' script. For example, you can configure OpenOCD to -cross-compile on a x86 Linux host to run on Windows (MinGW32), you could -use the following configuration options: +Cross-compiling is supported the standard autotools way, you just need +to specify the cross-compiling target triplet in the --host option, +e.g. for cross-building for Windows 32-bit with MinGW on Debian: - ./configure --build=i686-pc-linux-gnu --host=i586-mingw32msvc ... - -Likewise, the following options allow OpenOCD to be cross-compiled for -an ARM target on the same x86 host: - - ./configure --build=i686-pc-linux-gnu --host=arm-elf ... - -Both must be specified to work around bugs in autoconf. - -Scripts for producing ARM cross-compilers can be found on the web with a -little searching. A script to produce an x86 Linux-hosted MinGW32 -cross-compiler can be downloaded from the following URL: - - http://www.mingw.org/wiki/LinuxCrossMinGW - -Configuration Options ---------------------- - -The configure script takes numerous options, specifying which JTAG -interfaces should be included (among other things). The following list -of options was extracted from the output of './configure --help'. Other -options may be available there: - - --enable-dummy Enable building the dummy JTAG port driver - - --enable-parport Enable building the pc parallel port driver - --disable-parport-ppdev Disable use of ppdev (/dev/parportN) for parport - (for x86 only) - --enable-parport-giveio Enable use of giveio for parport (for CygWin only) - - --enable-ftdi Enable building support for the MPSSE mode of FTDI - based devices, using libusb-1.0 in asynchronous mode - - --enable-ft2232_libftdi Enable building support for FT2232 based devices - using the libftdi driver, opensource alternate of - FTD2XX - --enable-ft2232_ftd2xx Enable building support for FT2232 based devices - using the FTD2XX driver from ftdichip.com - - --enable-usb_blaster_libftdi - Enable building support for the Altera USB-Blaster - using the libftdi driver, opensource alternate of - FTD2XX - --enable-usb_blaster_ftd2xx - Enable building support for the Altera USB-Blaster - using the FTD2XX driver from ftdichip.com - - --enable-amtjtagaccel Enable building the Amontec JTAG-Accelerator driver - - --enable-zy1000-master Use ZY1000 JTAG master registers - --enable-zy1000 Enable ZY1000 interface - - --enable-ioutil Enable ioutil functions - useful for standalone - OpenOCD implementations - - --enable-ep93xx Enable building support for EP93xx based SBCs - - --enable-at91rm9200 Enable building support for AT91RM9200 based SBCs - - --enable-gw16012 Enable building support for the Gateworks GW16012 - JTAG Programmer - - --enable-presto_libftdi Enable building support for ASIX Presto Programmer - using the libftdi driver - --enable-presto_ftd2xx Enable building support for ASIX Presto Programmer - using the FTD2XX driver - - --enable-usbprog Enable building support for the usbprog JTAG - Programmer - - --enable-oocd_trace Enable building support for some prototype - OpenOCD+trace ETM capture hardware - - --enable-jlink Enable building support for the Segger J-Link JTAG - Programmer - - --enable-vsllink Enable building support for the Versaloon-Link JTAG - Programmer - - --enable-rlink Enable building support for the Raisonance RLink - JTAG Programmer - --enable-ulink Enable building support for the Keil ULINK JTAG - Programmer - --enable-arm-jtag-ew Enable building support for the Olimex ARM-JTAG-EW - Programmer - - --enable-buspirate Enable building support for the Buspirate - - --enable-stlink Enable building support for the ST-Link JTAG - Programmer - --enable-ti-icdi Enable building support for the TI/Stellaris ICDI - JTAG Programmer - - --enable-osbdm Enable building support for the OSBDM (JTAG only) - Programmer - - --enable-opendous Enable building support for the estick/opendous JTAG - Programmer - --enable-sysfsgpio Enable building support for programming driven via - sysfs gpios. - - --enable-minidriver-dummy - Enable the dummy minidriver. - - --disable-internal-jimtcl - Disable building internal jimtcl - - --enable-remote-bitbang Enable building support for the Remote Bitbang jtag - driver - - --disable-doxygen-html Disable building Doxygen manual as HTML. - --enable-doxygen-pdf Enable building Doxygen manual as PDF. - -Miscellaneous Configure Options -------------------------------- - -The following additional options may also be useful: - - --disable-assert turn off assertions - - --enable-verbose Enable verbose JTAG I/O messages (for debugging). - --enable-verbose-jtag-io - Enable verbose JTAG I/O messages (for debugging). - --enable-verbose-usb-io Enable verbose USB I/O messages (for debugging) - --enable-verbose-usb-comms - Enable verbose USB communication messages (for - debugging) - --enable-malloc-logging Include free space in logging messages (requires - malloc.h). - - --disable-gccwarnings Disable extra gcc warnings during build. - --disable-wextra Disable extra compiler warnings - --disable-werror Do not treat warnings as errors - - --disable-option-checking - Ignore unrecognized --enable and --with options. - --disable-dependency-tracking speeds up one-time build - --enable-shared[=PKGS] build shared libraries [default=no] - --enable-static[=PKGS] build static libraries [default=yes] + ./configure --host=i686-w64-mingw32 [options] Parallel Port Dongles --------------------- If you want to access the parallel port using the PPDEV interface you have to specify both --enable-parport AND --enable-parport-ppdev, since the -the later option is an option to the parport driver (see -http://forum.sparkfun.com/viewtopic.php?t=3795 for more info). +the later option is an option to the parport driver. -The same is true for the --enable-parport-giveio option, you -have to use both the --enable-parport AND the --enable-parport-giveio -option if you want to use giveio instead of ioperm parallel port access +The same is true for the --enable-parport-giveio option, you have to +use both the --enable-parport AND the --enable-parport-giveio option +if you want to use giveio instead of ioperm parallel port access method. -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. - -Using LIBFTDI -------------- - -The libftdi source code can be download from the following website: - - http://www.intra2net.com/en/developer/libftdi/download.php - -For both Linux and Windows, both libusb and libftdi must be built and -installed. To use the newer FT2232H chips, supporting RTCK and USB high -speed (480 Mbps), use libftdi version 0.17 or newer. Many Linux -distributions provide suitable packages for these libraries. - -For Windows, libftdi is supported with versions 0.14 and later. - -With these prerequisites met, configure the libftdi solution like this: - - ./configure --prefix=/path/for/your/install --enable-ft2232_libftdi - -Then type ``make'', and perhaps ``make install''. - Using FTDI's FTD2XX ------------------- -The (closed source) FTDICHIP.COM solution is faster on MS-Windows. That -is the motivation for supporting it even though its licensing restricts -it to non-redistributable OpenOCD binaries, and it is not available for -all operating systems used with OpenOCD. You may, however, build such -copies for personal use. +The (closed source) FTDICHIP.COM solution is faster than libftdi on +Windows. That is the motivation for supporting it even though its +licensing restricts it to non-redistributable OpenOCD binaries, and it +is not available for all operating systems used with OpenOCD. You may, +however, build such copies for personal use. The FTDICHIP drivers come as either a (win32) ZIP file, or a (Linux) TAR.GZ file. You must unpack them ``some where'' convenient. As of this writing FTDICHIP does not supply means to install these files "in an appropriate place." -If your distribution does not package these, there are several -'./configure' options to solve this problem: +You should use the following ./configure options to make use of +FTD2XX: --with-ftd2xx-win32-zipdir Where (CYGWIN/MINGW) the zip file from ftdichip.com @@ -383,34 +307,18 @@ If your distribution does not package these, there are several --with-ftd2xx-linux-tardir Where (Linux/Unix) the tar file from ftdichip.com was unpacked - --with-ftd2xx-lib Use static or shared ftd2xx libs on default static - -If you are using the FTDICHIP.COM driver, download and unpack the -Windows or Linux FTD2xx drivers from the following location: - - http://www.ftdichip.com/Drivers/D2XX.htm + --with-ftd2xx-lib=(static|shared) + Use static or shared ftd2xx libs (default is static) Remember, this library is binary-only, while OpenOCD is licenced -according to GNU GPLv2 without any exceptions. That means that -_distributing_ copies of OpenOCD built with the FTDI code would violate -the OpenOCD licensing terms. - -Linux Notes -*********** - -The Linux tar.gz archive contains a directory named libftd2xx0.4.16 -(or similar). Assuming that you have extracted this archive in the same -directory as the OpenOCD package, you could configure with options like -the following: - - ./configure \ - --enable-ft2232_ftd2xx \ - --with-ft2xx-linux-tardir=../libftd2xx0.4.16 \ - ... other options ... +according to GNU GPLv2 without any exceptions. That means that +_distributing_ copies of OpenOCD built with the FTDI code would +violate the OpenOCD licensing terms. Note that on Linux there is no good reason to use these FTDI binaries; they are no faster (on Linux) than libftdi, and cause licensing issues. + ========================== Obtaining OpenOCD From GIT ========================== @@ -442,15 +350,3 @@ the repository or to download arbitrary snapshots using HTTP: Snapshots are compressed tarballs of the source tree, about 1.3 MBytes each at this writing. - - -Tips For Building From a GIT Repository ---------------------------------------- - -Building OpenOCD from a repository requires a recent version of the GNU -autotools (autoconf >= 2.60 and automake >= 1.9). - -1) Run './bootstrap' to create the 'configure' script and prepare - the build process for your host system. - -2) Run './configure' with other options. diff --git a/README.OSX b/README.OSX new file mode 100644 index 000000000..5fec44f20 --- /dev/null +++ b/README.OSX @@ -0,0 +1,28 @@ +Building OpenOCD for OSX +------------------------ + +There are a few prerequisites you will need first: + +- Xcode 4 (install from the AppStore) +- Command Line Tools (install from Xcode 4 -> Preferences -> Downloads) +- MacPorts (http://www.macports.org/install.php) + or +- Homebrew (http://mxcl.github.io/homebrew/) + +libtool, automake, autoconf and libusb can be easily installed via +MacPorts: + sudo port install libtool automake autoconf libusb [libusb-compat] +or with Homebrew: + brew install libtool automake libusb [libusb-compat] + +You should also specify LDFLAGS and CPPFLAGS to allow configure to use +MacPorts' libraries, so run configure like this: + LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include ./configure [options] + +If you're using Homebrew, no custom flags are necessary. + +See README for the generic building instructions. + +If you use an FTDI-based adapter and have the FTDI kext installed, you +will need to unload it prior to using OpenOCD: + sudo kextunload FTDIUSBSerialDriver.kext diff --git a/README.Win32 b/README.Win32 deleted file mode 100644 index 6c690c9cd..000000000 --- a/README.Win32 +++ /dev/null @@ -1,98 +0,0 @@ -Building OpenOCD for Windows ----------------------------- - -For building on Windows, you have to use CygWin. Make sure that your -PATH environment variable contains no other locations with Unix utilities -(like UnxUtils). Those tools can't handle the CygWin paths, resulting -in obscure dependency errors. This was an observation gathered from the -logs of one user; please correct us if this is wrong. - -The following URL is a good reference if you want to build OpenOCD -under CygWin: - - http://forum.sparkfun.com/viewtopic.php?t=11221 - -Alternatively you can build the Windows binary under Linux using -MinGW cross compiler. The following documents some tips of -using this cross build option. - -libusb-win32 ------------- - -You can choose to use the libusb-win32 binary distribution from -its SourceForge page. As of this writing, the latest version -is 0.1.12.2. This is the recommend version to use since it fixed -an issue with USB composite device and this is important for FTDI -based JTAG debuggers. - - http://sourceforge.net/projects/libusb-win32/ - -You need to download the libusb-win32-device-bin-0.1.12.2.tar.gz -package. Extract this file into a temp directory. - -Copy the file libusb-win32-device-bin-0.1.12.2\include\usb.h -to your MinGW include directory. - -Copy the library libusb-win32-device-bin-0.1.12.2\lib\gcc\libusb.a -to your MinGW library directory. - -Take note that different Linux distributions often have different MinGW -installation directory. Some of them also put the library and include -into a separate sys-root directory. - -When the libusb-win32 repository is more current than its release code, -you could build that instead. - -These are the instruction from the libusb-win32 Makefile: - -# If you're cross-compiling and your mingw32 tools are called -# i586-mingw32msvc-gcc and so on, then you can compile libusb-win32 -# by running -# make host_prefix=i586-mingw32msvc all - -libftdi -------- - -The author does not provide Windows binary. You can build it from a -released source tarball or the git tree. - -If you are using the git tree, the following are the instructions from -README.mingw. You will need to have the cmake utility installed. - -- Edit Toolchain-mingw32.cmake to point to the correct MinGW - installation. -- Create a build directory like "mkdir build-win32", e.g in ../libftdi/ -- cd into that directory and run - "cmake -DCMAKE_TOOLCHAIN_FILE=../Toolchain-mingw32.cmake .." -- Copy src/ftdi.h to your MinGW include directory. -- Copy build-win32/src/*.a to your MinGW lib directory. - -libftd2xx ---------- - -The Cygwin/Win32 ZIP file contains a directory named ftd2xx.win32. -After being extracted, the directory does not need further preparation. -Instead, its path must be provided to the --with-ftd2xx-win32-zipdir -configure option, as shown in the next section. - -OpenOCD -------- - -Now you can build OpenOCD under Linux using MinGW. You need to use ---build and --host configure options. - -To use libftdi: - - ./configure --build=i686-pc-linux-gnu --host=i586-mingw32msvc \ - --enable-ft2232_libftdi \ - ... other options ... - -To use ftd2xx: - - ./configure --build=i686-pc-linux-gnu --host=i586-mingw32msvc \ - --enable-ft2232_ftd2xx \ - --with-ftd2xx-win32-zipdir=/path/to/libftd2xx-win32 \ - ... other options ... - -If you are using the GIT repository, see the README file for additional -instructions about configuring and building OpenOCD. diff --git a/README.Windows b/README.Windows new file mode 100644 index 000000000..1e9c49631 --- /dev/null +++ b/README.Windows @@ -0,0 +1,20 @@ +Building OpenOCD for Windows +---------------------------- + +You can build OpenOCD for Windows natively with either MinGW/MSYS or +Cygwin. Alternatively, one can cross-compile it using MinGW on a *nix +host. See README for the generic instructions. + +USB adapters +------------ + +You usually need to have WinUSB.sys (or libusbK.sys) driver installed +for a USB-based adapter. Some vendor software (e.g. for ST-LINKv2) +does it on its own. For the other cases the easiest way to assign +WinUSB to a device is to use the Zadig installer: + + http://sourceforge.net/projects/libwdi/files/zadig/ + +For the old drivers that use libusb-0.1 API you might need to link +against libusb-win32 headers and install the corresponding driver with +Zadig.