# Introduction

JTAG is a technology that allows you to debug digital hardware by reaching inside the chip on a board while they are running to read and change their contents.
You can use it to erase and reprogram the whole of the AVR32UC3A's flash memory, including the USB DFU boot loader that lives in the first 8KB.
While the AVR32 is running, you can use it to stop the program, examine the contents of CPU registers and memory, and set the program running again, as well as setting hardware breakpoint and more.

# Hardware view

Every Mizar32 main board has a 10-pin JTAG connector. To use it you will need an external JTAG emulator such as Atmel's AVR32 JTAG ICE MKII.

# Software view

To talk to the Mizar32 via a JTAG converter, you will also need to install some programs.
Atmel now only support JTAG if you use their graphical development environment AVR32 Studio 6.
The command-line tools, avr32program and/or avr32gdbproxy, are now hard to find.

## Installing command-line tools
### Finding them

The ancient Atmel AVR32 GNU Toolchain version 2.4.2 contains some extra tools that were left out of the later releases. They no longer publicise it but you may still be able to download it from:
* Debian packages for Ubuntu 9.10 (64-bit) / 9.10 / 9.04 / 8.04
* RPMs for Suse Core 11.1 / 11.0
* RPMs for RedHat Enterprice 5
* RPMs for Fedora Core 12 (64-bit) / 12 / 11 / 10

#### Installing avr32program on Debian/Ubuntu

To be able to use a JTAG programming device, you need to install the avr32program command. It used to be included in Atmel GNU Toolchain up to version 2.4.2 but for some reason it is omitted from later versions. Here, we show how to install it on a modern 32-bit version of Debian or Ubuntu from the Atmel's Ubuntu 9.04 bundle:
This creates fifteen *.deb package files, most of which are not useful. Install the necessary packages:
and if that complains about
fetch and install the ancient libraries it requires:
and complete the installation:
Atmel's packages for Ubuntu 9.10 contain the same software as the ones for 9.04 but depend on obsolete library versions that are even more difficult to find.
If you have a 64-bit installation of Ubuntu, your life is even more difficult because:
* Atmel only distributed 64-bit versions of their software for Ubuntu 9.10
* avr32program and avr32gdbproxy require you to install libboost-thread1.38
* Debian never shipped libboost-1.38 and Ubuntu's boost1.38 archive is mysteriously empty
This leaves you two options
* find the boost-1.38 packages that the programs require
* install the 32-bit packages from 9.04 and the 32-bit versions of all the libraries that they require
Good luck! Let me know how it turns out...

#### Installing avr32gdbproxy on Debian/Ubuntu

Another program, avr32gdbproxy can be used with an AVR32 JTAGICE Mk.II JTAG programming device to debug C code running on the board. It needs similar magic as avr32program:
and, if it complains about libboost-date-time and libmpfr1ldbl being missing, go
and finally
which should fetch and install libgmp3c2 if it wasn't already installed.

## Using JTAG
### Programming the firmware using avr32program

These days we usually use the USB DFU bootloader to reprogram the Mizar32. The last SimpleMachines firmware release to include JTAG programming commands and binaries was Mizar32 firmware release 20110320 for the 128K model but you can reuse that release's scripts and files with the eLua binaries from more recent ones.
The sequence of commands to erase and reprogram the whole device is fairly complicated, so download the above release and check program-mizar32-jtag.sh
You will need to connect an AVR32 JTAG ICE MKII programmer to your PC with its USB interface and to the Mizar32 via the 10-pin JTAG interface. Apply power to both.
Install the avr32program program (see above) then fetch and program the firmware:
This will reprogram the entire contents of the flash memory: the USB DFU boot loader, the ISP configuration word, the general-purpose fuse bits and the eLua interpreter. It will then start the board running.

### Debugging eLua with avr32gdbproxy

You will need:
* avr32-gdb, as included in Atmel's GNU Toolchain releases
* avr32gdbproxy - see above
* An .elf on the your PC, the same one that you programmed to the Mizar32
* A JTAG programmer device (USB-to-JTAG converter)
and with everything connected up, turned on and running, say on the PC:
Good luck!

# Further Reading

* Boundary Scan Tutorial 2007 from ASSET InterTech
* The chapter on Flashing Firmware for other ways to reprogram the flash memory