Subversion Repositories adv_debug_sys

These are the notes for building the Advanced JTAG Bridge program
using the original Makefile.classic (non-autotools) method. This
method is deprecated, but this file remains as a reference.

Nathan Yawn, nathan.yawn@opencores.org

BUILDING

This program doesn't use automake.  It has been developed using the cygwin 
environment under winXP, and should also compile under various GNU/Linux 
distributions.  It has been tested and is known to work with Ubuntu 9.04.
There are two sets of build flags defined in the Makefile, 
one for cygwin and one for Linux - one set is used, one is commented out.  
Edit the Makefile for your system: set BUILD_ENVIRONMENT to either "cygwin"
or "linux" (no quotes).

The program may be built with support for the Advanced Debug Interface
(the default), or the legacy "debug_if" interface.  To compile for the
legacy interface, __LEGACY__ should be added to CFLAGS in the Makefile
(the line is present but commented out by default).  This is done via 
the SUPPORT_LEGACY flag; set true to build for the legacy debug system,
false (to build for the adv_dbg_if) is the default. Note that support
for the two different debug hardware units is mutually exclusive; both
cannot be supported in the same build.

If you are only going to use a parallel JTAG cable, and you don't want
to bother with libusb, you can set SUPPORT_USB_CABLES to false.  Default
is true.  Similarly, you can set SUPPORT_FTDI_CABLES false if you don't
intend to use FT2232-based JTAG cables, and don't want to bother with
libftdi.

Some users have reported problems getting their USB-Blaster cables to
work using the standard driver. In this case, try the "ft245" driver,
as this appears to work for these users. The "ft245" driver supports
all of the same high-speed transfers that the "usbblaster" driver
supports. 

In release 2.0 and later, the adv_dbg_if core includes a "hi-speed"
mode, which is used by default.  This requires a protocol change,
and so the adv_jtag_bridge must be built to match the build options
used when synthesizing the adv_dbg_if. For hi-speed mode, set
USE_HISPEED true (this is the default).  For the older mode, set
USE_HISPEED to false. 

Release 2.5 added the JTAG serial port (JSP).  There are three compile-
time options related to this feature.  The first is
INCLUDE_JSP_SERVER, set true by default.  If you synthesize the
adv_dbg_if without JSP support, or you don't intend to use it,
this may be set false.  This will prevent the JSP server thread
from starting, and from polling constantly any time the target
system is running, which can take significant system resources
on the host system running adv_jtag_bridge.

The second JSP-related option is JSP_MULTI_DEVICE_CHAIN, set true
by default.  The adv_dbg_if core JSP hardware is synthesized with 
support for multi-device JTAG chains by default, as this is safe
to use on any system.  However, this can slow JSP performance 
somewhat, particularly with USB-based cables.  The hardware core may
therefore be synthesized with multi-device chain support disabled.
If your adv_dbg_if core has been synthesized with this disabled,
then you should set this option to false.  Note this causes a
change in the JSP communication protocol used, so the options you
compile adv_jtag_bridge with must match the options used to
synthesize the adv_dbg_if core.  This option will be ignored if
the INCLUDE_JSP_SERVER option is set false.

The third JSP-related option is JSP_OPTIMIZE_FOR_USB, set true by
default.  The JSP hardware will ignore extra bytes during read/
write transactions.  This makes it safe to transfer the maximum of
8 data bytes (plus the counts byte) on every transaction, regardless
of the number of valid data bytes.  When this option is set true,
all 9 bytes are sent as a single USB transaction each time a JSP
transaction is performed, giving maximum performance using USB
cables.  When this option is set false, then the counts word is
transferred first, then used to determine the minimum number of
bytes to transfer.  The minimum is then transferred, which gives
better performance when using parallel JTAG cables (or bit-banging
USB cables).  Note that this option does NOT change the communication
protocol used.  Therefore, either setting is safe for any system -
this option affects only performance.

DEPENDENCIES

Adv_jtag_bridge has three (or four) dependencies:

- The pthreads library (probably already installed)
- Cygwin only:  libioperm (for parallel port device access permissions)
- libusb
- libftdi

Since adv_jtag_bridge was written, a newer version of libusb has been 
released (1.0), which used a different interface.  We still use the old 
interface (0.1), so be sure you install the "compatibility layer" if you 
install the latest libusb.  As of December 2008, libUSB-Win32 still used 
v0.1, so cygwin users may not need to install any additional compatibility 
layer.

The libftdi library is optional, and only required if you are building
support for FT2232-based cables (SUPPORT_FTDI_CABLES is true). Note that
if you are installing libftdi using the software downloader / installer
that came with your OS, you may need to get two packages, "libftdi" and
"libftdi-dev." This is true for Ubuntu 10.04, and possibly other 
distributions as well.

BUGS

GDB 6.8 has a bug which prevents it from working when no stack frame is 
present (such as at start-up on a bare-metal debugger, such as this one).  
A simple patch applied to GDB 6.8 will work around the problem (a general 
solution is not yet available).  This patch can be found in the source
directory of adv_jtag_bridge as "gdb-6.8-bz436037-reg-no-longer-active.patch",
and also in Patches/ directory at the top level of the Advanced Debug
System.

LICENSE

This code is based on "jp2", which was distributed under the GNU Public 
License, version 2.  Adv_jtag_bridge is therefore also distributed under 
this license.

WARRANTY

This program is distributed in the hope that it will be useful, but WITHOUT 
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for 
more details.