Subversion Repositories adv_debug_sys

These are the notes for building the Advanced JTAG Bridge program.

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.  An alternate, libftdi-based driver

has been added as a compile-time option.  Set

USE_ALT_FTDI_USBBLASTER_DRIVER true to try the alternate driver; note

the two different drivers are mutually exclusive. Also note that the

alternate libftdi-based driver is not a high-performance driver, and

should not be used unless necessary.

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

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

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.