The JTAG wiki page for the ERESI project

A new project has born: JEDBG.

This pages compiles various documentation and research about existing open-source JTAG software that we could use to perform such task.

Introduction

The wikipedia JTAG page (a brief introduction to JTAG): http://en.wikipedia.org/wiki/JTAG

The JTAG state machine diagram:

Existing software

OpenOCD (last update: February 2009)
http://openocd.berlios.de/web/
http://openocd.berlios.de/web/?page_id=54
http://www.amontec.com/openocd.shtml
Supported architectures: see previous links, a lot.
Supported memory: see previous link, a lot.
Supported cables: see previous link, a lot.
Remarks: the most complete, for sure. Has a great variety of supported boards/cables/architectures, including ARM7TDMI.
Has specifically ARM-JTAG parallel cable support, but a config file for LPC-E2124 board need to be updated.
Also, it seems that its community is the most active one, with daily patches committed on the public mailing list.

URJTAG (last update: Sept 2008)
http://urjtag.org/
http://urjtag.svn.sourceforge.net/viewvc/urjtag/tags/URJTAG_0_9/web/htdocs/book/_system_requirements.html
Supported architectures: see previous link (a lot, but no ARM)
Supported memory: see previous link, a lot.
Supported cables: see previous link, a lot.
Remarks: the most complete, maintained package. Support BSDL2JTAG converter!

JTAGER (last update: October 2004)
http://jtager.sourceforge.net/
Supported architecture: ARM9TDMI / ARM920T
Supported memory: mbm29lv650 / sst39vf160 FLASH
Supported cables: Macriagor Wiggler (Parallel)
Remarks: well coded, modular, but we want ARM7 and not ARM9.

JTAGPACK (last update: April 2005)
http://jtagpack.sourceforge.net/
Supported architecture: ARM7TDMI and MIPS.
Supported memory: ?
Supported cables: Parallel.
Remarks: support our architecture, but code is commented in japanese.

JTAG-ARM9 (last update: March 2006)
http://jtag-arm9.sourceforge.net/
Supported architecture: ARM9
Supported memory: ?
Supported cables: Parallel.
Remarks: small and easy to understand, include tutorial on how to create your own Parallel JTAG cable.

IANJTAG (last update: Jan 2002)
http://www.inaccessnetworks.com/projects/ianjtag
Supported architecture: INTEL StrongARM
Supported memory: INTEL strataflash
Supported cables: Parallel
Remarks: very small and well documented.

All the latest versions of those packages are in attachement of this wiki page.

Documentation

Our first target hardware is the LPC-E2124 board based on ARM7-TMDI: http://www.olimex.com/dev/lpc-e2124.html[[BR]]

An interesting JTAG FAQ: http://hri.sourceforge.net/tools/jtag_faq_org.html[[BR]]

This last link contains a lot of very precious links. Make sure you visit it.

The cable to be used is a Macgraigor Wiggler Compatible cable, the Olimex ARM-JTAG cable. http://www.olimex.com/dev/arm-jtag.html

JTAG vs GDB serial protocol

Many of the existing JTAG packages relies on a proxy with the GDB protocol, so that JTAG targets can be debugged with a GDB client. This is very slow. ERESI also supports the GDB protocol thanks to the libgdbwrap, but it sounds a better strategy to implement the JTAG debugger interface independently of the GDB protocol, because:

- We are not dependent on the GDB protocol as the GDB client is.
- We want to keep a clear separation of concerns between the 2 debug protocols.
- We want to have maximum performance.

Homebrew LibJTAG vs existing JTAG Tool

ERESI has the tradition of writing its own libraries and tools from scratch, and has been doing this really well. ;) In this particular case, regarding the JTAG protocol, keeping on this way may be not the best decision. There are some differences between each manufacterer implementation of the JTAG protocol and, so, if we are aiming portability this has to be considered.

In the other hand, we have the performance issue. Any of the above presented JTAG tools - OpenOCD, URJTAG, etc - has an official API-like library to be used by external applications. OpenOCD has client-server capability, using a telnet session or the GDB protocol. URJTAG has this libjtag on their roadmap, but no official release of this was found until this moment.

3rdparty liburjtag

During research, several discussions were started on UrJTAG's forum and mailing list. This email attached below brings this external liburjtag development version.

From: Przemyslaw Iskra <sparky@…>
To: urjtag-development@…
"Converting UrJTAG into a library is quite straightforward. I've done this already and it works quite well for me. I'm planning to contribute the code to UrJTAG project, but there's still a lot to change and I'm swamped with other work right now (http://labserver.uv.es/ioboard/).[[BR]]

You may get my code from svn:
$ svn co http://labserver.uv.es/svn_FPGA/trunk/source/urjtag urjtag-lib

AFAIR it is based on revision 1407. The main changes are:
- changed autotools sources (configure.ac, Makefile.am) to use libtool
- moved some code from jtag.c to liburjtag.c
- moved code unused in the library from from cmd/cmd.c to jtag.c
- command-line app now uses the library
- added XS code to build a perl module

What needs to be done (before adding it to official UrJTAG tree):
- sanitise namespace (hide unused functions, prefix all the used ones with jtag_)
- cleanup and install public headers
- perl: allow to call any function usable within perl

I'll be working on that, but for now I've got to finish the PCB, which may take few more weeks."

This is good! :)

JEDBG Development Status

Right now, we are on final steps for deciding the main architecture. Possible approaches:

- Implementing from scratch a libjtag for JEDBG.
Pros: Performance.
Cons: Lack of portability, since just what is needed for ARM7TDMI would be implementaded. Can became a huge task for the next (and initial) three months.

- Add needed support to URJTAG and test its external liburjtag
Pros: Portability and a very stable code base.
Cons: Not sure yet what should be done for this, since there is no ARM support here. Also, liburjtag is a development version and shall need some care.

- Enable libgdbwrap to use OpenOCD's GDB server
Pros: Portability and a very stable code base. Growing daily. Tested ARM7TDMI support.
Cons: All issues previously stated.

Once this interfacing decision has been made and developed, JEDBG development will start.
Need help defining what is the minimum JTAG instruction set we need to implement in order to have a complete debugger.

LPC-E2124 Setup

In order to setup the board, you must:

- have user-space access to the parallel port, if using a Wigglers' compatible cable. Check if you have ppdev module (/dev/parport0). Also, beware of having any lp (printer) module or built-in support, as it can take full control of the parallel port.
- download and install CrossWorks? for ARM (CrossStudio?). Just tested with 1.7 and it works well.
- download and install LPC2000 support package (http://www.rowleydownload.co.uk/arm/packages/), on Tools->Install Package submenu.
- download and unzip FreeRTOS package. It contains all available demos, for all supported boards. (http://sourceforge.net/project/showfiles.php?group_id=111543&package_id=120544)
- follow these instructions: http://www.freertos.org/portrowleylpc2124.html
- set BSL jumper for flashing and JRST for running.

Having fun... ;)