urjtag/jtag/doc/UrJTAG.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
         "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY datafilespecs SYSTEM "internals.xml">
  <!ENTITY FDL SYSTEM "fdl.xml">
  <!ENTITY GPL SYSTEM "gpl.dbk">
  <!ENTITY LGPL SYSTEM "lgpl.dbk">
]>

<book>
  <bookinfo>
    <title>Universal JTAG library, server and tools</title>
    <authorgroup>
      <author><firstname>Kolja</firstname><surname>Waschk</surname></author>
    </authorgroup>

    <legalnotice>
      <para>
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free
Documentation License, Version 1.2 or any later version published by the Free
Software Foundation. A copy of the license is included in the section entitled
"GNU Free Documentation License".
      </para>
    </legalnotice>

    <copyright>
      <year>2007</year>
      <year>2008</year>
      <holder>Kolja Waschk and the respective authors</holder>
    </copyright>

  </bookinfo>

  <toc/>

<chapter><title>General</title>

  <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</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> SVF Player </title><para/></section>
  <section><title> bsdl2jtag, data files </title><para/></section>
  <section><title> target specific documentation</title><para/></section>
  <section><title> EJTAG support </title><para/></section> 
  <section><title> Blackfin support (when available) </title><para/></section> 
</chapter>

<chapter><title>For developers</title>
  <section><title>Source code directory layout</title>
    <para>
      <programlisting>
    data/
    ./include/
    ../include/
    libbrux/
      cmd/ flash/
    src/
      bus/ cmd/ lib/ tap/ svf/
      </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".

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>

    <section><title> API and library package
    </title><para/></section><section><title> Bindings for Python, Perl, ...
    </title><para/></section><section><title> TCP/IP access
    </title><para/></section><section><title> New cable drivers
    </title><para/></section><section><title> ...
    </title><para/></section>
</chapter>

&datafilespecs;

<appendix><title>UrJTAG shell quick reference sheet</title><para/> </appendix>
<appendix><title>man pages</title>
  <section><title>jtag(1)</title><para/></section>
  <section><title>bsdl2jtag(1)</title><para/></section>
</appendix>

<appendix><title> Exkurs: JTAG </title><para/></appendix>

<appendix><title>UrJTAG Revision information</title><para/>
  <section><title>UrJTAG 0.6</title><para/></section>
  <section><title>openwince JTAG Tools 0.5.1</title><para/></section>
</appendix>

&FDL;
&GPL;
&LGPL;

</book>