@ -35,32 +35,341 @@ Software Foundation. A copy of the license is included in the section entitled
<chapter > <title > General</title>
<section > <title > The name "UrJTAG"</title> <para /> </section>
<section > <title > Authors, contributors, ... thanks</title> <para /> </section>
<section > <title > Copyright/Licensing</title> <para /> <para /> </section>
<section > <title > UrJTAG/openwince history</title> <para /> <para /> </section>
<section > <title > Supported hardware</title> <para /> <para /> </section>
<section > <title > Installation </title> <para /> </section>
<section > <title > from binary tarball </title> <para /> </section>
<section > <title > from source tarball </title> <para /> </section>
<section > <title > from svn </title> <para /> </section>
<section > <title > Cygwin/MinGW specifics </title> <para /> </section>
<section > <title > About UrJTAG</title>
<para >
UrJTAG Tools is a software package which enables working with JTAG-aware
(IEEE 1149.1) hardware devices (parts) and boards through JTAG adapter.
</para>
<para >
This package has open and modular architecture with ability to write
miscellaneous extensions (like board testers, flash memory programmers,
and so on).
</para>
<para >
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.
</para>
<para >
<emphasis > Warning: This software may damage your hardware!</emphasis>
</para>
<para >
Feedback and contributions are welcome.
</para>
</section>
<section > <title > UrJTAG Website</title>
<para >
The most current version of this documentation and UrJTAG sourcecode
is always available from the project page at Sourceforge, http://urjtag.sourceforge.net
</para>
</section>
<section > <title > The name "UrJTAG"</title>
<para >
I (Kolja) favour short names, so I thought about adding only a few
letters to "JTAG". The prefix "Ur" in German means "ancestral", an "Ur-Vater"
is a forefather. UrJTAG shall become the forefather, the basis for many other
JTAG tools.
</para>
</section>
<section > <title > Authors, contributors, ... thanks</title>
<para >
At the moment, please see the files AUTHORS and THANKS in the source distribution.
</para>
</section>
<section > <title > UrJTAG/openwince history</title>
<para >
The JTAG Tools originally were developed by Marcel Telka as part of the openwince project. Still
a large portion of the source code is his work. However, the last release of the JTAG tools was
version 0.5.1 in 2003. After a few years the development completely stalled. Every few months or
so on the project's mailing list someone asked about continuing, but a critical mass wasn't
reached before late 2007. A fork of the JTAG tools was created under the wings of the UrJTAG
project at Sourceforge.
</para>
</section>
<section > <title > System requirements</title>
<section > <title > Supported host operating systems</title>
<para >
JTAG Tools should run on all Unix like operating systems including
MS Windows with Cygwin installed.
</para>
</section>
<section > <title > Required software for running UrJTAG</title>
<para >
More software is needed if you want to compile UrJTAG (which you probably want because
currently no pre-compiled binaries are avaible...). See "For developers..." below.
</para>
<para >
Required only for MS Windows:
<itemizedlist >
<listitem > <para > current Cygwin net installation from http://cygwin.com</para> </listitem>
<listitem > <para > ioperm package (a part of the standard Cygwin net installation)</para> </listitem>
</itemizedlist>
</para>
<para >
Required for all systems:
<itemizedlist >
<listitem > <para > readline (it is probably a standard part of your distribution)</para> </listitem>
</itemizedlist>
</para>
</section>
<section > <title > Supported JTAG adapters/cables</title>
<para > See 'help cable' command for up-to-date info.
</para>
<itemizedlist >
<listitem > <para > Arcom JTAG Cable</para> </listitem>
<listitem > <para > Altera ByteBlaster/ByteBlaster II/ByteBlasterMV Parallel Port Download Cable</para> </listitem>
<listitem > <para > Xilinx DLC5 JTAG Parallel Cable III</para> </listitem>
<listitem > <para > ETC EA253 JTAG Cable</para> </listitem>
<listitem > <para > ETC EI012 JTAG Cable</para> </listitem>
<listitem > <para > Keith & Koep JTAG Cable</para> </listitem>
<listitem > <para > Lattice Parallel Port JTAG Cable</para> </listitem>
<listitem > <para > Mpcbdm JTAG Cable</para> </listitem>
<listitem > <para > Ka-Ro TRITON (PXA255/250) JTAG Cable</para> </listitem>
<listitem > <para > Macraigor Wiggler JTAG Cable</para> </listitem>
</itemizedlist>
</section>
<section > <title > JTAG-aware parts (chips)</title>
<itemizedlist >
<listitem > <para > Altera EP1C20F400</para> </listitem>
<listitem > <para > Altera EPM7128AETC100</para> </listitem>
<listitem > <para > Analog Devices Sharc-21065L</para> </listitem>
<listitem > <para > Atmel ATmega128 (partial support)</para> </listitem>
<listitem > <para > Broadcom BCM1250</para> </listitem>
<listitem > <para > Broadcom BCM3310 (partial support)</para> </listitem>
<listitem > <para > Broadcom BCM5421S</para> </listitem>
<listitem > <para > Broadcom BCM4712 (partial support)</para> </listitem>
<listitem > <para > DEC SA1100</para> </listitem>
<listitem > <para > Hitachi HD64465</para> </listitem>
<listitem > <para > Hitachi SH7727</para> </listitem>
<listitem > <para > Hitachi SH7729</para> </listitem>
<listitem > <para > IBM PowerPC 440GX</para> </listitem>
<listitem > <para > Intel IXP425</para> </listitem>
<listitem > <para > Intel SA1110</para> </listitem>
<listitem > <para > Intel PXA250/PXA255/PXA260/PXA261/PXA262/PXA263</para> </listitem>
<listitem > <para > Lattice LC4032V</para> </listitem>
<listitem > <para > Lattice M4A3-64/32</para> </listitem>
<listitem > <para > Lattice M4A3-256/192</para> </listitem>
<listitem > <para > Motorola MPC8245</para> </listitem>
<listitem > <para > Samsung S3C4510B</para> </listitem>
<listitem > <para > Sharp LH7A400</para> </listitem>
<listitem > <para > Toshiba TX4925/TX4926</para> </listitem>
<listitem > <para > Xilinx XC2C256-TQ144</para> </listitem>
<listitem > <para > Xilinx XCR3032XL-VQ44</para> </listitem>
<listitem > <para > Xilinx XCR3128XL-CS144</para> </listitem>
<listitem > <para > Xilinx XCR3128XL-VQ100</para> </listitem>
<listitem > <para > Xilinx XCR3256XL-FT256</para> </listitem>
</itemizedlist>
</section>
<section > <title > Flash chips</title>
<itemizedlist >
<listitem > <para > - Intel 28FxxxJ3A (28F320J3A, 28F640J3A, 28F128J3A)</para> </listitem>
<listitem > <para > - Intel 28FxxxK3 (28F640K3, 28F128K3, 28F256K3)</para> </listitem>
<listitem > <para > - Intel 28FxxxK18 (28F640K18, 28F128K18, 28F256K18)</para> </listitem>
<listitem > <para > - AMD Am29LV64xD (Am29LV640D, Am29LV641D, Am29LV642D)</para> </listitem>
<listitem > <para > - AMD Am29xx040B (Am29F040B, Am29LV040B)</para> </listitem>
</itemizedlist>
</section>
</section>
<section > <title > Installation </title>
<section > <title > Required software for compiling UrJTAG</title>
<para />
</section>
<section > <title > Installing from source tar.gz</title>
<para >
<programlisting >
tar xzvf urjtag.tar.gz
cd urjtag/include
./configure
make
make install
cd ../jtag
./configure
make
make install
</programlisting>
</para>
</section>
<section > <title > Installing from Subversion repository</title>
<para >
<programlisting >
svn co http://urjtag.svn.sourceforge.net/svnroot/urjtag/trunk urjtag
cd urjtag/include ./autogen.sh
# ./configure is run by autogen.sh
make
make install
cd ../jtag
./autogen.sh
# ./configure is run by autogen.sh
make
make install
</programlisting>
</para>
</section>
<section > <title > Cygwin/MinGW specifics</title>
<para />
</section>
</section>
<section > <title > Getting updates </title> <para /> </section>
<section > <title > Further info / support</title> <para /> </section>
</chapter>
<chapter > <title > Usage</title>
<section > <title > Quick start: flash example </title> <para /> </section>
<section > <title > Configuration, cable setup </title> <para /> </section>
<section > <title > Chain setup </title> <para /> </section>
<section > <title > Part setup </title> <para /> </section>
<section > <title > Doing things with parts </title> <para /> </section>
<section > <title > Pin I/O </title> <para /> </section>
<section > <title > Quick start</title>
<section > <title > Run the software</title>
<para >
Connect your JTAG adapter between your PC and target device and turn
on your device.
</para> <para >
To run JTAG Tools type "jtag" and press Enter. jtag should start and
display some initial informations. Output should end with line like this:
</para> <programlisting >
jtag>
</programlisting> <para >
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.
</para>
</section>
<section > <title > Configure the cable</title>
<para >
Type "help cable" for list of supported JTAG cables.
Type "cable" command with arguments. Example:
</para> <programlisting >
jtag> cable parallel 0x378 EA253
Initializing ETC EA253 JTAG Cable on parallel port at 0x378
</programlisting>
</section>
<section > <title > Detect parts on the JTAG chain</title>
<para >
Type "detect" at the jtag command prompt:
</para> <programlisting >
jtag> detect
</programlisting> <para >
Your output should look like this:
</para>
<programlisting >
IR length: 5
Chain length: 1
Device Id: 01011001001001100100000000010011
Manufacturer: Intel
Part: PXA250
Stepping: C0
Filename: /usr/local/share/jtag/intel/pxa250/pxa250c0
</programlisting>
<para >
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.
</para>
<para >
"detect" command is required before all other commands.
</para>
</section>
<section > <title > Print current JTAG chain status</title>
<para >
Type "print" at the jtag command prompt. Here is an output example:
</para>
<programlisting >
jtag> print chain
No. Manufacturer Part Stepping Instruction Register
---------------------------------------------------------------------------------------------
0 Intel PXA250 C0 BYPASS BR
jtag>
</programlisting>
</section>
<section > <title > Sample device pin status</title>
<programlisting >
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>
</programlisting>
<para >
Note: BSR is "Boundary Scan Register"
</para>
</section>
<section > <title > Burn flash connected to the part</title>
<programlisting >
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>
</programlisting>
<para >
or:
</para>
<programlisting >
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>
</programlisting>
</section>
</section>
<section > <title > Memory I/O </title> <para /> </section>
<section > <title > FPGA configuration </title> <para /> </section>
<section > <title > Flash programming </title> <para /> </section>
<section > <title > ... </title> <para /> </section>
<section > <title > SVF Player </title> <para /> </section>
<section > <title > bsdl2jtag, data files </title> <para /> </section>
<section > <title > target specific documentation</title> <para /> </section>
@ -68,21 +377,10 @@ Software Foundation. A copy of the license is included in the section entitled
<section > <title > Blackfin support (when available) </title> <para /> </section>
</chapter>
<chapter > <title > Internals</title>
<section > <title > How to</title>
<para >
.. add a part
.. add a command
.. add a bus driver
.. add a cable driver
,,
.. create a patch and upload to SF
</para>
<para /> </section>
<section > <title > Directory structure</title>
<para >
<chapter > <title > For developers</title>
<section > <title > Source code directory layout</title>
<para >
<programlisting >
data/
./include/
../include/
@ -90,24 +388,72 @@ Software Foundation. A copy of the license is included in the section entitled
cmd/ flash/
src/
bus/ cmd/ lib/ tap/ svf/
</para>
<para /> </section>
<section > <title > Cable driver interface</title>
<para >
parport
cable
chain
</para>
<para /> </section>
<section > <title > Bus driver interface </title> <para /> </section>
<section > <title > target specific internals </title> <para /> </section> <section > <title >
</title> <para /> </section>
</programlisting>
</para>
</section>
<section > <title > Internal structure</title>
<section > <title > Parport drivers</title>
<para />
</section>
<section > <title > Cable drivers</title>
<para />
</section>
<section > <title > TAP drivers</title>
<para />
</section>
<section > <title > Chain drivers</title>
<para />
</section>
<section > <title > Bus drivers</title>
<para />
</section>
<section > <title > Flash drivers</title>
<para />
</section>
<section > <title > Commands</title>
<para />
</section>
</section>
<section > <title > How to contribute</title>
<section > <title > Use Subversion, stay up to date</title>
<para />
</section>
<section > <title > Create and submit a patch</title>
<para />
</section>
<section > <title > Use the SourceForge trackers</title>
<para />
</section>
</section>
</chapter>
<chapter > <title > Frequently asked questions </title>
<programlisting >
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.
</programlisting>
<programlisting >
To run autogen.sh, you need autoconf and automake. Furthermore, libtool should be available. And if you plan to use any USB adapter with Linux, libusb-dev and probably libftdi-dev are a good choice (that are Debian package names; other distributions certainly have similar packages).
Can't exec "autopoint": No such file or directory
You need gettext-devel.
svf_bison.y: No such file or directory
You need "bison".
<section > <title > Cygwin/MinGW </title> <para /> </section>
<section > <title > Compilation problems </title> <para /> </section>
flex: can't open ... src/svf/svf_flex.l
You need "flex"
"src/svf/svf_flex.l", line 27: unrecognized %option: bison-locations
You need a newer version of flex. It should be 2.5.31 or newer,
Unfortunately, Cygwin comes with only 2.5.4a. You may try to compile and install a newer version of flex from source to solve this.
</programlisting>
</chapter>
<chapter > <title > Future plans</title>
@ -141,3 +487,4 @@ Software Foundation. A copy of the license is included in the section entitled
</book>
Kolja Waschk
17 years ago