1 |
4 |
nyawn |
These are the notes for building the Advanced JTAG Bridge program.
|
2 |
|
|
Nathan Yawn, nathan.yawn@opencores.org
|
3 |
|
|
|
4 |
|
|
BUILDING
|
5 |
|
|
|
6 |
|
|
This program doesn't use automake. It has been developed using the cygwin
|
7 |
|
|
environment under winXP, and should also compile under various GNU/Linux
|
8 |
35 |
nyawn |
distributions. It has been tested and is known to work with Ubuntu 9.04.
|
9 |
14 |
nyawn |
There are two sets of build flags defined in the Makefile,
|
10 |
4 |
nyawn |
one for cygwin and one for Linux - one set is used, one is commented out.
|
11 |
35 |
nyawn |
Edit the Makefile for your system: set BUILD_ENVIRONMENT to either "cygwin"
|
12 |
|
|
or "linux" (no quotes).
|
13 |
4 |
nyawn |
|
14 |
14 |
nyawn |
The program may be built with support for the Advanced Debug Interface
|
15 |
|
|
(the default), or the legacy "debug_if" interface. To compile for the
|
16 |
|
|
legacy interface, __LEGACY__ should be added to CFLAGS in the Makefile
|
17 |
35 |
nyawn |
(the line is present but commented out by default). This is done via
|
18 |
|
|
the SUPPORT_LEGACY flag; set true to build for the legacy debug system,
|
19 |
|
|
false (to build for the adv_dbg_if) is the default. Note that support
|
20 |
14 |
nyawn |
for the two different debug hardware units is mutually exclusive; both
|
21 |
|
|
cannot be supported in the same build.
|
22 |
|
|
|
23 |
35 |
nyawn |
If you are only going to use a parallel JTAG cable, and you don't want
|
24 |
|
|
to bother with libusb, you can set SUPPORT_USB_CABLES to false. Default
|
25 |
|
|
is true. Similarly, you can set SUPPORT_FTDI_CABLES false if you don't
|
26 |
|
|
intend to use FT2232-based JTAG cables, and don't want to bother with
|
27 |
|
|
libftdi.
|
28 |
|
|
|
29 |
|
|
Some users have reported problems getting their USB-Blaster cables to
|
30 |
|
|
work using the standard driver. An alternate, libftdi-based driver
|
31 |
|
|
has been added as a compile-time option. Set
|
32 |
|
|
USE_ALT_FTDI_USBBLASTER_DRIVER true to try the alternate driver; note
|
33 |
42 |
nyawn |
the two different drivers are mutually exclusive. Also note that the
|
34 |
|
|
alternate libftdi-based driver is not a high-performance driver, and
|
35 |
|
|
should not be used unless necessary.
|
36 |
35 |
nyawn |
|
37 |
|
|
In release 2.0 and later, the adv_dbg_if core includes a "hi-speed"
|
38 |
|
|
mode, which is used by default. This requires a protocol change,
|
39 |
|
|
and so the adv_jtag_bridge must be built to match the build options
|
40 |
|
|
used when synthesizing the adv_dbg_if. For hi-speed mode, set
|
41 |
|
|
USE_HISPEED true (this is the default). For the older mode, set
|
42 |
|
|
USE_HISPEED to false.
|
43 |
|
|
|
44 |
42 |
nyawn |
Release 2.5 added the JTAG serial port (JSP). There are three compile-
|
45 |
|
|
time options related to this feature. The first is
|
46 |
|
|
INCLUDE_JSP_SERVER, set true by default. If you synthesize the
|
47 |
|
|
adv_dbg_if without JSP support, or you don't intend to use it,
|
48 |
|
|
this may be set false. This will prevent the JSP server thread
|
49 |
|
|
from starting, and from polling constantly any time the target
|
50 |
|
|
system is running, which can take significant system resources
|
51 |
|
|
on the host system running adv_jtag_bridge.
|
52 |
|
|
|
53 |
|
|
The second JSP-related option is JSP_MULTI_DEVICE_CHAIN, set true
|
54 |
|
|
by default. The adv_dbg_if core JSP hardware is synthesized with
|
55 |
|
|
support for multi-device JTAG chains by default, as this is safe
|
56 |
|
|
to use on any system. However, this can slow JSP performance
|
57 |
|
|
somewhat, particularly with USB-based cables. The hardware core may
|
58 |
|
|
therefore be synthesized with multi-device chain support disabled.
|
59 |
|
|
If your adv_dbg_if core has been synthesized with this disabled,
|
60 |
|
|
then you should set this option to false. Note this causes a
|
61 |
|
|
change in the JSP communication protocol used, so the options you
|
62 |
|
|
compile adv_jtag_bridge with must match the options used to
|
63 |
|
|
synthesize the adv_dbg_if core. This option will be ignored if
|
64 |
|
|
the INCLUDE_JSP_SERVER option is set false.
|
65 |
|
|
|
66 |
|
|
The third JSP-related option is JSP_OPTIMIZE_FOR_USB, set true by
|
67 |
|
|
default. The JSP hardware will ignore extra bytes during read/
|
68 |
|
|
write transactions. This makes it safe to transfer the maximum of
|
69 |
|
|
8 data bytes (plus the counts byte) on every transaction, regardless
|
70 |
|
|
of the number of valid data bytes. When this option is set true,
|
71 |
|
|
all 9 bytes are sent as a single USB transaction each time a JSP
|
72 |
|
|
transaction is performed, giving maximum performance using USB
|
73 |
|
|
cables. When this option is set false, then the counts word is
|
74 |
|
|
transferred first, then used to determine the minimum number of
|
75 |
|
|
bytes to transfer. The minimum is then transferred, which gives
|
76 |
|
|
better performance when using parallel JTAG cables (or bit-banging
|
77 |
|
|
USB cables). Note that this option does NOT change the communication
|
78 |
|
|
protocol used. Therefore, either setting is safe for any system -
|
79 |
|
|
this option affects only performance.
|
80 |
|
|
|
81 |
4 |
nyawn |
DEPENDENCIES
|
82 |
|
|
|
83 |
35 |
nyawn |
Adv_jtag_bridge has three (or four) dependencies:
|
84 |
4 |
nyawn |
|
85 |
|
|
- The pthreads library (probably already installed)
|
86 |
|
|
- Cygwin only: libioperm (for parallel port device access permissions)
|
87 |
|
|
- libusb
|
88 |
35 |
nyawn |
- libftdi
|
89 |
4 |
nyawn |
|
90 |
|
|
Since adv_jtag_bridge was written, a newer version of libusb has been
|
91 |
|
|
released (1.0), which used a different interface. We still use the old
|
92 |
|
|
interface (0.1), so be sure you install the "compatibility layer" if you
|
93 |
|
|
install the latest libusb. As of December 2008, libUSB-Win32 still used
|
94 |
|
|
v0.1, so cygwin users may not need to install any additional compatibility
|
95 |
|
|
layer.
|
96 |
|
|
|
97 |
35 |
nyawn |
The libftdi library is optional, and only required if you are building
|
98 |
|
|
support for FT2232-based cables (SUPPORT_FTDI_CABLES is true).
|
99 |
|
|
|
100 |
4 |
nyawn |
BUGS
|
101 |
|
|
|
102 |
|
|
GDB 6.8 has a bug which prevents it from working when no stack frame is
|
103 |
|
|
present (such as at start-up on a bare-metal debugger, such as this one).
|
104 |
|
|
A simple patch applied to GDB 6.8 will work around the problem (a general
|
105 |
|
|
solution is not yet available). This patch can be found in the source
|
106 |
|
|
directory of adv_jtag_bridge as "gdb-6.8-bz436037-reg-no-longer-active.patch".
|
107 |
|
|
|
108 |
|
|
LICENSE
|
109 |
|
|
|
110 |
|
|
This code is based on "jp2", which was distributed under the GNU Public
|
111 |
|
|
License, version 2. Adv_jtag_bridge is therefore also distributed under
|
112 |
|
|
this license.
|
113 |
|
|
|
114 |
|
|
WARRANTY
|
115 |
|
|
|
116 |
|
|
This program is distributed in the hope that it will be useful, but WITHOUT
|
117 |
|
|
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
118 |
|
|
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
|
119 |
|
|
more details.
|