diff --git a/web/htdocs/book/UrJTAG.dbk b/web/htdocs/book/UrJTAG.dbk
index 6a630c0e..8e173f2f 100644
--- a/web/htdocs/book/UrJTAG.dbk
+++ b/web/htdocs/book/UrJTAG.dbk
@@ -4,7 +4,7 @@
Universal JTAG library, server and tools
- 2008-02-19
+ 2008-02-28
Kolja
Waschk
@@ -12,7 +12,7 @@
KW(
-10612008-02-19KW(
+11052008-02-28KW(
@@ -239,6 +239,8 @@ below.
Supported JTAG adapters/cables
See help cable command for up-to-date info.
+Parallel-port cables:
+
@@ -252,11 +254,6 @@ Altera ByteBlaster/ByteBlaster II/ByteBlasterMV Parallel Port Download Cable
-Altera USB-Blaster and compatible http://www.ixo.de/info/usb_jtag
-
-
-
-
Xilinx DLC5 JTAG Parallel Cable III
@@ -295,24 +292,28 @@ Mpcbdm JTAG Cable
Macraigor Wiggler JTAG Cable
+
+FT2232-based USB cables:
+
+
-Amontec JTAGkey (FT2232-based)
+Amontec JTAGkey
-Olimex ARM-USB-JTAG (FT2232-based)
+Olimex ARM-USB-JTAG
-Olimex ARM-USB-TINY (FT2232-based)
+Olimex ARM-USB-TINY
-OOCDLink-s (FT2232-based) (experimental) http://www.joernonline.de/dw/doku.php?id=projects:oocdlink:2_oocdlinks
+OOCDLink-s (experimental) http://www.joernonline.de/dw/doku.php?id=projects:oocdlink:2_oocdlinks
@@ -322,22 +323,36 @@ Other FT2232-based USB JTAG cables (experimental)
-Xverve Signalyzer Tool (FT2232-based) (experimental)
+Turtelizer 2 (experimental) http://www.ethernut.de/en/hardware/turtelizer/
+
+
+
+
+USB to JTAG Interface (experimental) http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html
-Turtelizer 2 (FT2232-based) (experimental) http://www.ethernut.de/en/hardware/turtelizer/
+Xverve Signalyzer Tool (experimental)
+
+Other USB cables:
+
+
-USB to JTAG Interface (FT2232-based) (experimental) http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html
+Altera USB-Blaster and compatible http://www.ixo.de/info/usb_jtag
-Xilinx Platform USB Cable (experimental)
+Segger/IAR J-Link / Atmel SAM-ICE (experimental, work in progress)
+
+
+
+
+Xilinx Platform USB Cable / DLC9 (slow, experimental, work in progress - don't use)
@@ -580,20 +595,9 @@ http://www.intra2net.com/de/produkte/opensource/ftdi/
Alternatively, you can use the FTD2XX library from the chip manufacturer FTDI.
-It is available for Linux and Windows. To use the library for Windows in a
-Cygwin environment, first get it from:
-
-
-
-
-http://www.ftdichip.com/Drivers/D2XX.htm
-
-
-
-Unzip the CDM*.zip to some directory and tell UrJTAG about this directory
-during the configure step before actual compilation:
+It is available for Linux and Windows. There's more information about linking
+to that library in a Cygwin environment below.
-./configure --with-libftd2xx=/cygdrive/c/windows/temp/CDM_Drivers
All other USB JTAG adapters can be supported only if libusb is installed.
There is a libusb-win32 variant that can be used in a Cygwin environment:
@@ -1295,6 +1299,13 @@ all at once, and data for all pins has to be transferred through JTAG for every
single change, this method isn't the fastest, but usually easiest to implement
and, well, sometimes it counts whether it works at all..
+The "fjmem" (FPGA JTAG memory) bus driver attempts to address this issue by
+moving control and observation away from BSR to a device-internal
+register. For sure this is only possible on FPGAs where the designer can hook
+additional logic to the JTAG chain. A core design plus examples for different
+FPGA families is available in the extra/fjmem directory. Refer to the README
+located there.
+
Some chips don't allow direct access to their pins via BSR at all. For these,
writing a new bus driver that utilizes a debug module to upload specific code
to access the bus is inevitable.
@@ -1894,12 +1905,12 @@ Functions for accessing the chain in general
-Cable-specific drivers
+Cable drivers
-Parport drivers
+Link drivers
@@ -2194,7 +2205,7 @@ get_tdo_late()
-When flushing occurs ======
+When flushing occurs
The cable_flush() function is used to flush the queue towards the cable. It
takes one additional argument, "how_much", which may be one of
@@ -2277,6 +2288,255 @@ look at the code in src/tap/cable/generic.c, which contains generic routines,
suitable for parallel port based cables (and some for other types of cables as
well).
+
+
+
+Link drivers
+Link drivers like the "parport" driver collection provide the basis for
+communication between cable driver and actual JTAG adapter. The openwince JTAG
+tools supported only parallel port links with the "parport" drivers. UrJTAG
+introduced support for USB links, but in the early releases the drivers for
+these just mimic the parallel port links.
+
+The basic functions provided by all link drivers are
+
+
+
+
+connect(), to called from cable driver connect()
+
+
+
+
+open(), to actually connect to the device during cable driver init()
+
+
+
+
+close(), to disconnect from the device during cable driver done()
+
+
+
+
+free(), to free all resources, called from cable driver free()
+
+
+
+
+parport
+Currently there are parport drivers for direct access to the parallel port on a
+PC using I/O addresses (direct.c), and for using ppdev on Linux or ppi on FreeBSD.
+
+In addition, there are "ftdi" and "ftd2xx" parport drivers that actually are for
+communication with USB cables based on FTDI chips. They cannot be used for
+connecting old parallel port cables through parallel to USB adapters with FTDI
+chips, and probably soon will be rewritten as "usbconn" drivers instead.
+
+All parport drivers present a common API for setting and reading signals.
+
+
+
+usbconn
+The usbconn drivers provide a common API to search for and connect with USB
+devices. At the moment, there's only a libusb driver, but others will follow
+(e.g. to communicate with FTDI chip based cables through libftdi and/or FTD2XX,
+to communicate with Cypress FX2 using EZUSB.SYS or CyUSB.sys, and more).
+
+In contrast to the parport API, the usbconn drivers provide only the functions
+for connecting, disconnecting, and for releasing ressources. The actual
+communication must be implemented using the underlying library's functions,
+e.g. usb_write from libusb, or ftdi_write from libftdi. Therefore, each driver
+using usbconn usually only works together with one particular usbconn driver.
+
+
+
+
+Bus drivers
+Bus drivers translate read and write operations on a bus into JTAG commands
+and methods. A bus in this context is neither restricted to a processor bus,
+nor to memory. Any system component that can be read from and written to could
+be seen as attached to a bus. I.e. external or internal memory (RAM, ROM,
+Flash) and peripherals connected to a processor or simply an FPGA with 1:1
+connections.
+
+The available bus drivers are listed in response to "help initbus". Each
+driver has to provide the following functions:
+
+
+
+
+bus_new() - Initialization
+
+
+
+
+bus_free() - Cleaning up
+
+
+
+
+bus_printinfo() - Short description
+
+
+
+
+bus_prepare() - Preparation
+
+
+
+
+bus_area() - Description of the bus geometry
+
+
+
+
+bus_read_start() - Initiate reading
+
+
+
+
+bus_read_next() - Read access
+
+
+
+
+bus_read_end() - Finish reading
+
+
+
+
+bus_read() - Atomic reading
+
+
+
+
+bus_write() - Write access
+
+
+
+Address parameters to the functions listed above apecify always
+byte locations, independent of the actual data width. The bus driver has to
+adjust the address on its own if required.
+
+Initialization
+Upon calling of its bus_new() function, the driver allocates a "bus_t"
+structure and performs all required internal initializations.
+
+
+
+Cleaning up
+The driver is supposed to free all allocated memory (including its "bus_t"
+structure). Additionally, it should set the device into a state that doesn't
+prevent it from normal operation.
+
+
+
+Short description
+Prints a message describing the driver. This function is called by the "print"
+command before it lists the areas covered by this bus driver.
+
+
+
+Preparation
+This function is called whenever at the start of a bus operation. The driver
+should perform the required preparation steps so that subsequent calls to the
+bus_read_* and bus_write functions can perform their tasks properly.
+
+E.g. a BSR bus driver would put the device into EXTEST mode to activate the
+boundary scan register on the device pins.
+
+
+
+Description of the bus geometry
+At certain stages, the bus driver's bus_area() function is called by other
+commands to query the bus geometry for a given address. The bus driver must
+fill in the fields of a "bus_area_t" structure describing the geometry of the
+area in which the specified address is located:
+
+
+
+
+a short textual description of the area
+
+
+
+
+start address of area
+
+
+
+
+length of area in bytes
+
+
+
+
+data width in bits
+
+
+
+Queries with an address out of range must result in an area length of
+
+UINT64_C(0x100000000)
+
+
+Initiate reading
+Since the JTAG state machine defines a capture-shift-update sequence, it is
+required to shift the address for a read prior to capturing the read
+data. Therefore, the bus_read_start() function is called with the very first
+address to read from. This enables the driver to shift the address into the
+device before it can actually retrieve the read data for this address.
+
+
+
+Read access
+The bus_read_next() function fetches the read data from the device that has
+been addressed by a previous call to bus_read_start() or
+bus_read_next(). Again, this is due to the capture-shift-update sequence of
+JTAG:
+
+
+
+
+capture read data from device pins
+
+
+
+
+shift new address
+
+
+
+
+update new address to device pins
+
+
+
+The address parameter specifies the location of the following
+read access. It is not the address of the data returned by this function call.
+
+
+Finish reading
+Function "bus_read_end()" is called at the end of a read sequence. I.e. when
+the higher level command determines that the last data portion is to be read
+from the device. There is no new address and the function driver is supposed
+to return the read data that was addressed previously.
+
+
+
+Atomic reading
+For ease of use, a bus driver has to supply a "bus_read()" function that
+encapsulates reading data from a single address in an atomic operation. Bus
+drivers typically build this function from "bus_read_start()" and a subsequent
+"bus_read_end()".
+
+
+
+Write access
+This function writes one data element at the specified address. Since this
+translates to a single JTAG operation (capture ignored, shift and update
+address & data), there is no splitting as with the read functions.
+
diff --git a/web/htdocs/book/UrJTAG.html b/web/htdocs/book/UrJTAG.html
index f2439c29..bd0ed10a 100644
--- a/web/htdocs/book/UrJTAG.html
+++ b/web/htdocs/book/UrJTAG.html
@@ -343,6 +343,16 @@ HREF="#_drivers"
HREF="#_cable_specific_drivers_src_tap_cable"
>Cable-specific drivers (src/tap/cable)4.2.2. Link drivers4.2.3. Bus drivers command for up-to-date info.
Parallel-port cables:
FT2232-based USB cables:
Amontec JTAGkey (FT2232-based)
+>
Amontec JTAGkey
Olimex ARM-USB-JTAG (FT2232-based)
+>
Olimex ARM-USB-JTAG
Olimex ARM-USB-TINY (FT2232-based)
+>
Olimex ARM-USB-TINY
OOCDLink-s (FT2232-based) (experimental) http://www.joernonline.de/dw/doku.php?id=projects:oocdlink:2_oocdlinks
+>
OOCDLink-s (experimental) http://www.joernonline.de/dw/doku.php?id=projects:oocdlink:2_oocdlinks
Xverve Signalyzer Tool (FT2232-based) (experimental)
+>
Turtelizer 2 (experimental) http://www.ethernut.de/en/hardware/turtelizer/
+
USB to JTAG Interface (experimental) http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html
+
Xverve Signalyzer Tool (experimental)
Other USB cables:
Turtelizer 2 (FT2232-based) (experimental) http://www.ethernut.de/en/hardware/turtelizer/
+>
Altera USB-Blaster and compatible http://www.ixo.de/info/usb_jtag
USB to JTAG Interface (FT2232-based) (experimental) http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html
+>
Segger/IAR J-Link / Atmel SAM-ICE (experimental, work in progress)
Xilinx Platform USB Cable (experimental)
+>
Xilinx Platform USB Cable / DLC9 (slow, experimental, work in progress - don't use)
Alternatively, you can use the FTD2XX library from the chip manufacturer FTDI.
-It is available for Linux and Windows. To use the library for Windows in a
-Cygwin environment, first get it from:
Unzip the CDM*.zip to some directory and tell UrJTAG about this directory
-during the configure step before actual compilation:
./configure --with-libftd2xx=/cygdrive/c/windows/temp/CDM_Drivers
All other USB JTAG adapters can be supported only if libusb is installed.
There is a libusb-win32 variant that can be used in a Cygwin environment:
The "fjmem" (FPGA JTAG memory) bus driver attempts to address this issue by
+moving control and observation away from BSR to a device-internal
+register. For sure this is only possible on FPGAs where the designer can hook
+additional logic to the JTAG chain. A core design plus examples for different
+FPGA families is available in the extra/fjmem directory. Refer to the README
+located there.
Some chips don't allow direct access to their pins via BSR at all. For these,
writing a new bus driver that utilizes a debug module to upload specific code
to access the bus is inevitable.