README* refactoring

This is an attempt to bring the README files in line with the current
status of the OpenOCD development.

- remove some obsolete information and duplicated instructions
- reword some statements
- restructure in a way more appealing to a regular user
- add a supported hardware list to allow a potential user to determine
  if his/her usecase is covered by a freetext keyword search through
  the document
- Add OSX notes (courtesy GrizzlyAdams and inca)

Since most ftdi-based adapters are now covered by the ftdi driver, I
think it's ok to remove some of the libftdi/ftd2xx instructions, the
few users who still need them should refer to upstream docs instead.

I'm not sure if README.Windows should come with the DOS line endings,
but i'd expect many windows users to use their silly notepad to view
it, and notepad ignores LF apparently. (Decided to use LF anyway.)

I understand discussing and reviewing such a massive README change is
a somewhat demanding task but I feel it's a necessity to move forward
maintaining proper documentation.

Change-Id: Idfde3014c72dd5c32ad292ee1ab205322e51a138
Signed-off-by: Paul Fertser <fercerpav@gmail.com>
Signed-off-by: Andreas Fritiofson <andreas.fritiofson@gmail.com>
Reviewed-on: http://openocd.zylin.com/1503


Tested-by: jenkins
Reviewed-by: Xiaofan <xiaofanc@gmail.com>

Makefile.am

@@ -24,7 +24,8 @@ EXTRA_DIST = \
 	BUGS \
 	HACKING \
 	NEWTAPS \
-	README.Win32 \
+	README.Windows \
+	README.OSX \
 	Doxyfile.in \
 	tools/logger.pl \
 	contrib/loaders

README.OSX

+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

README.Win32

-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.

README.Windows

+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.