$Id: README,v 1.48 2004/11/16 21:51:26 telka Exp $

JTAG Tools
~~~~~~~~~~

JTAG Tools is a software package which enables working with JTAG-aware
(IEEE 1149.1) hardware devices (parts) and boards through JTAG adapter.

This package has open and modular architecture with ability to write
miscellaneous extensions (like board testers, flash memory programmers,
and so on).

JTAG Tools package is free software, covered by the GNU General Public
License, and you are welcome to change it and/or distribute copies of it
under certain conditions. There is absolutely no warranty for JTAG Tools.
Please read COPYING file for more info.

Warning: This software may damage your hardware!

Feedback and contributions are welcome.


Supported host operating systems
--------------------------------

JTAG Tools should run on all Unix like operating systems including
MS Windows with Cygwin installed.

Supported hardware
------------------

JTAG adapters/cables (see 'help cable' command for more info):
- Arcom JTAG Cable
- Altera ByteBlaster/ByteBlaster II/ByteBlasterMV Parallel Port Download Cable
- Xilinx DLC5 JTAG Parallel Cable III
- ETC EA253 JTAG Cable
- ETC EI012 JTAG Cable
- Keith & Koep JTAG Cable
- Lattice Parallel Port JTAG Cable
- Mpcbdm JTAG Cable
- Ka-Ro TRITON (PXA255/250) JTAG Cable
- Macraigor Wiggler JTAG Cable

JTAG-aware parts (chips):
- Altera EP1C20F400
- Altera EPM7128AETC100
- Atmel ATmega128 (partial support)
- Broadcom BCM1250
- Broadcom BCM3310 (partial support)
- Broadcom BCM5421S
- Broadcom BCM4712 (partial support)
- DEC SA1100
- Hitachi HD64465
- Hitachi SH7727
- Hitachi SH7729
- IBM PowerPC 440GX
- Intel IXP425
- Intel SA1110
- Intel PXA250/PXA255/PXA260/PXA261/PXA262/PXA263
- Lattice LC4032V
- Lattice M4A3-64/32
- Lattice M4A3-256/192
- Motorola MPC8245
- Samsung S3C4510B
- Sharp LH7A400
- Toshiba TX4925/TX4926
- Xilinx XC2C256-TQ144
- Xilinx XCR3032XL-VQ44
- Xilinx XCR3128XL-CS144
- Xilinx XCR3128XL-VQ100
- Xilinx XCR3256XL-FT256

Flash chips:
- Intel 28FxxxJ3A (28F320J3A, 28F640J3A, 28F128J3A)
- Intel 28FxxxK3 (28F640K3, 28F128K3, 28F256K3)
- Intel 28FxxxK18 (28F640K18, 28F128K18, 28F256K18)
- AMD Am29LV64xD (Am29LV640D, Am29LV641D, Am29LV642D)


Required software
-----------------

Required only for MS Windows:
- current Cygwin net installation from <http://cygwin.com/>
- ioperm package (a part of the standard Cygwin net installation)

Required for all systems:
- include package from <http://openwince.sourceforge.net/include/>
- readline (it is probably a standard part of your distribution)


Build & installation instructions
---------------------------------

1. Download and install required software (see previous section).
2. Download and unpack jtag sources.
3. Run ./configure script. Use optional --with-include parameter if required.
   See `./configure --help` for more info.
4. Run `make`.
5. Run `make install`.


Running JTAG Tools
------------------

Connect your JTAG adapter between your PC and target device and turn
on your device.

To run JTAG Tools type "jtag" and press <Enter>. jtag should start and
display some initial informations. Output should end with line like this:

jtag>

This is "jtag command prompt". Type "help" and press <Enter> for initial help
about available commands. To exit JTAG Tools type "quit" and press <Enter>.

===> First task: Select JTAG cable and parallel port address.

Type "help cable" for list of supported JTAG cables.
Type "cable" command with arguments. Example:

jtag> cable parallel 0x378 EA253
Initializing ETC EA253 JTAG Cable on parallel port at 0x378

===> Second task: Detect parts on the JTAG chain.

Type "detect" at the jtag command prompt:
jtag> detect

Your output should look like this:

IR length: 5
Chain length: 1
Device Id: 01011001001001100100000000010011
  Manufacturer: Intel
  Part:         PXA250
  Stepping:     C0
  Filename:     /usr/local/share/jtag/intel/pxa250/pxa250c0

If you get empty output or an error message your JTAG adapter is not connected
properly, or your target board doesn't work, or it is turned off.

"detect" command is required before all other commands.

===> Third task: Print current JTAG chain status.

Type "print" at the jtag command prompt. Here is an output example:

jtag> print chain
 No. Manufacturer              Part                 Stepping Instruction          Register
---------------------------------------------------------------------------------------------
   0 Intel                     PXA250               C0       BYPASS               BR
jtag>

===> Fourth task: Sample device pin status.

jtag> instruction SAMPLE/PRELOAD
jtag> shift ir
jtag> shift dr
jtag> dr
10001100100000100001100101111111111111111110011011100000111011111111111111111111
11111111111111111111111111111111111111111111101111111101100000100010101000000000
00011111000000111010111111100000100001100100000000000000000111000011100000000000
00000000000000000000000000000001000000000000000000000000000000000000000000000000
11110000000000000000000000000000000000000000001000000000000000000000000000000000
0000000000
jtag> print chain
 No. Manufacturer              Part                 Stepping Instruction          Register
---------------------------------------------------------------------------------------------
   0 Intel                     PXA250               C0       SAMPLE/PRELOAD       BSR
jtag> get signal BOOT_SEL[0]
BOOT_SEL[0] = 0
jtag>

Note: BSR is "Boundary Scan Register"

===> Fifth task: Burn flash connected to the part.

jtag> flashmem 0 brux.b
0x00000000
Note: Supported configuration is 2 x 16 bit only
BOOT_SEL: Asynchronous 32-bit ROM

2 x 16 bit CFI devices detected (QRY ok)!

program:
block 0 unlocked
erasing block 0: 0
addr: 0x00002854
verify:
addr: 0x00002854
Done.
jtag>

or:

jtag> flashmem msbin xboot.bin
Note: Supported configuration is 2 x 16 bit only
BOOT_SEL: Asynchronous 32-bit ROM

2 x 16 bit CFI devices detected (QRY ok)!

block 0 unlocked
erasing block 0: 0
program:
record: start = 0x00000000, len = 0x00000004, checksum = 0x000001EB
record: start = 0x00000040, len = 0x00000008, checksum = 0x000001B0
record: start = 0x00001000, len = 0x00002B30, checksum = 0x00122CAB
record: start = 0x00004000, len = 0x00000160, checksum = 0x0000684B
record: start = 0x00005000, len = 0x00000054, checksum = 0x000008EE
record: start = 0x00005054, len = 0x00000030, checksum = 0x00000DA9
record: start = 0x00000000, len = 0x00001000, checksum = 0x00000000

verify:
record: start = 0x00000000, len = 0x00000004, checksum = 0x000001EB
record: start = 0x00000040, len = 0x00000008, checksum = 0x000001B0
record: start = 0x00001000, len = 0x00002B30, checksum = 0x00122CAB
record: start = 0x00004000, len = 0x00000160, checksum = 0x0000684B
record: start = 0x00005000, len = 0x00000054, checksum = 0x000008EE
record: start = 0x00005054, len = 0x00000030, checksum = 0x00000DA9
record: start = 0x00000000, len = 0x00001000, checksum = 0x00000000

Done.
jtag>


Frequently Asked Questions
--------------------------

Q. When I type "cable parallel 0x378 DLC5" on Windows XP I get
   "Error: Cable initialization failed!". Where is the problem?
A. Please install ioperm.sys driver using `ioperm -i` command.


Contacts
--------

Homepage: <http://openwince.sourceforge.net/jtag/>

CVS repository: <http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/openwince/jtag/>

Please report and track bugs at (please use Category 'jtag'):
<http://sourceforge.net/tracker/?group_id=52603&atid=469850>

Mailing list (discussion, questions): openwince-list@lists.sourceforge.net
Subscribe: <http://lists.sourceforge.net/mailman/listinfo/openwince-list>

Mailing list (announce): openwince-announce@lists.sourceforge.net
Subscribe: <http://lists.sourceforge.net/mailman/listinfo/openwince-announce>

Patches and improvements are welcome at (please use Category 'jtag'):
<http://sourceforge.net/tracker/?group_id=52603&atid=469852>

Feature requests are welcome at (please use Category 'jtag'):
<http://sourceforge.net/tracker/?group_id=52603&atid=469853>

Support requests are welcome at (please use Category 'jtag'):
<http://sourceforge.net/tracker/?group_id=52603&atid=469851>
