ben-blinkenlights/ubb-jtag/README

JTAG with UBB 
=============

JTAG [1] typically uses 4 to 6 signals between the host and the
target, making it perfectly suitable for UBB.

UBB can be either used with just a cable or with minimum circuitry
if level shifting is needed. If the level difference is small
enough, simple resistive dividers that can be soldered directly to
UBB will be sufficient.

If using the "gpio" cable driver of UrTAG, we don't even need new
code for this.

[1] http://en.wikipedia.org/wiki/Jtag
[2] http://urjtag.org/


Overview
--------

This is an example of using UBB to communicate via JTAG with the
Xilinx XC6SLX45 FPGA of a Milkymist One. We first describe the
hardware setup, then configuration and installation of UrJTAG,
and finally changes to the kernel configuration.

The whole setup looks like this:
http://downloads.qi-hardware.com/people/werner/ubb/jtag/ubb-jtag-m1-all.jpg


UBB-JTAG-M1 hardware: 2.5 V level adaptation
--------------------------------------------

Note that this is target-specifc. No level adaptation is necessary
if the target's JTAG interface runs at 3.3 V.

Milkymist One uses 2.5 V for its JTAG interface while the Ben's
IO runs at 3.3 V. The difference is small enough that we need no
special provisions for going from 2.5 V to 3.3 V, but we have to
adapt the level in the opposite direction.

Since we will run the interface at fairly low speeds, simple
resistive dividers will be sufficient. A 220/680 Ohm divider
reduces the Ben's nominal 3.3 V to a nominal 2.5 V. Small
through-hole resistors can be soldered directly to UBB.

ubb-jtag-m1.sch shows the configuration. Since CLK is used as
input and has no pull-up inside the Ben, no resistor is needed.
However, it may be advisable to add a 220 Ohm series resistor
as protection in case of misconfiguration.

This is what UBB with voltage dividers (without series resistor
on CLK) looks like:
http://downloads.qi-hardware.com/people/werner/ubb/jtag/ubb-jtag-m1-card.jpg


UBB-JTAG-M1 hardware: connector
-------------------------------

Milkymist One uses a shrouded 14 pin male connector with a 2 mm
pitch for JTAG. While suitable connectors for ribbon cables are
available, e.g., Molex 087568-1493, one can also improvise with
female contacts designed for the ubiquitous 2.54 mm headers.

If building a UBB-JTAG board with individual wires, the labels
in m1-labels.fig can be used to identify them. Each label has
the name of the JTAG signal and the position in the J6 connector
of the Milkymist One.


Building UrJTAG
---------------

Prequisite: the OpenWRT cross-compilation toolchain for the Ben
has to be installed. I.e., mipsel-openwrt-linux-gcc and friends
must be in PATH.

git clone git://urjtag.git.sourceforge.net/gitroot/urjtag/urjtag
cd urjtag/urjtag
./autogen.sh --host=mipsel-openwrt-linux --enable-cable=gpio \
   --enable-lowlevel= --without-libusb --without-libftdi
make


Installing UrJTAG
-----------------

Prerequisites: the Ben must be reachable via TCP/IP. We assume we
can reach it under the name "ben". ldconfig must be installed (*).

(*) E.g., with
    wget http://downloads.qi-hardware.com/software/packages/NanoNote/Ben/2012-10-24/ldconfig_0.9.33.2-1_xburst.ipk
    opkg install ldconfig_0.9.33.2-1_xburst.ipk

scp src/apps/jtag/.libs/jtag ben:/usr/bin/
scp src/.libs/liburjtag.so.0.0.0 ben:/usr/lib/
ssh ben mkdir -p /usr/local/share/urjtag
scp -r data/* ben:/usr/local/share/urjtag/
ssh ben ldconfig


Enabling the /sys/class/gpio/... interface
------------------------------------------

For simplicity, we use the "gpio" cable driver of UrTAG. This
driver requires the Ben kernel to be compiled with
CONFIG_GPIO_SYSFS (this option is not available as a module).
If /sys/class/gpio does not exist, we need to rebuild the
kernel.

Prerequisite: you have checked out and set up the openwrt-xburst
repository from Qi-Hardware.

make kernel_menuconfig

Then go to "Device Drivers" > "GPIO Support" and enable
"/sys/class/gpio/... (sysfs interface)" (GPIO_SYSFS)


Enabling ZRAM
-------------

UrTAG spends memory fairly generously and loading a bitstream for
the XC6LX45 of Milkymist One is likely to exceed the memory
available on the Ben.

Since we can't swap on ubifs and we can't use an SD card for swap
since the 8:10 card slot is already occupied, the next best choice
is to use ZRAM.

Note that this is not necessary if the driver for the respective
target isn't quite as memory-hungry as the one for Xilinx FPGAs,
or if the bitstream is smaller.

make kernel_menuconfig

Then go to "Device Drivers" and enable "Staging drivers" (STAGING).
After that, enter "Staging drivers" and enable "Compressed RAM
block device support" (ZRAM).


Building and installing the OpenWRT kernel
------------------------------------------

make -j5
scp bin/xburst/openwrt-xburst-qi_lb60-uImage.bin ben:
ssh ben flash_eraseall /dev/mtd1
ssh ben nandwrite -p /dev/mtd1 openwrt-xburst-qi_lb60-uImage.bin


Using UBB-JTAG-M1
-----------------

First connect UBB-JTAG-M1 to the Milkymist One (powered off) but
without inserting UBB into the Ben. This should look like this:

http://downloads.qi-hardware.com/people/werner/ubb/jtag/ubb-jtag-m1-j6.jpg

Then boot the Ben and disable the MMC driver with

echo jz4740-mmc.0 >/sys/bus/platform/drivers/jz4740-mmc/unbind

Now UBB-JTAG-M1 can be safely connected to the Ben. After connecting
power to the Milkymist One, we can probe it with

ben# jtag
jtag> cable gpio tdi=107 tdo=105 tck=109 tms=108
jtag> detect


For the next step, we need fjmem.bit, e.g., available here:
http://milkymist.org/updates/fjmem.bit.bz2

We also need to enable swap space on ZRAM. 32 MB should be
sufficient:

ben# echo 33554432 >/sys/block/zram0/disksize
ben# mkswap /dev/zram0
ben# swapon /dev/zram0

Now fjmem.bit can be loaded and executed:

jtag> instruction CFG_OUT  000100 BYPASS
jtag> instruction CFG_IN   000101 BYPASS
jtag> pld load "fjmem.bit"
jtag> initbus fjmem opcode=000010
jtag> detectflash 0

Since the sysfs GPIO interface is rather slow and we make things
worse by swapping to compressed RAM, the loading of fjmem.bit
takes about four or five minutes.


Going faster
------------

In many applications, UrJTAG will be able to run without compressed
swap and thus faster. Smaller amounts of data will also make even
slow transfers more bearable.

To further increase the speed, a Ben-specific GPIO driver could be
written that accesses registers directly without the very long
detour through sysfs.

Finally, even higher speeds could be reached by using the MMC
controller to send data, similar to UBB-VGA. For this purpose, CMD
and DAT0 have been left unconnected. When connecting them to each
other, they could be used to generate fake start bits, signaling
the MMC controller to begin a transfer. (See ubb-vga for details.)