jochen
/
urjtag
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
patches
master
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '5990c665ef'
${ noResults }
urjtag/jtag/doc/UrJTAG.xml

667 lines
25 KiB
XML
Raw Blame History

<?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>
<editor><firstname>Kolja</firstname><surname>Waschk</surname></editor>
<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>JTAG</title>
<para>
JTAG basics can be found all over the internet. This page should go into
some more details about working with JTAG. What hardwarde do you need, what is
the usage of JTAG, where do I get files. What file formats are available...
</para>
<section><title>Introduction</title>
<para>
JTAG (IEEE 1149.1) is a serial interface for testing devices with
integrated circuits. The problem that the JTAG interface was designed to solve
is checking if connections between ICs are OK. Therefore you can set and check
in- and outputs of ICs. In order to save pins and logic a very simple serial
design was invented.
</para>
<orderedlist>
<listitem><para>one pin serial input</para></listitem>
<listitem><para>one pin serial output</para></listitem>
<listitem><para>one pin clock</para></listitem>
<listitem><para>one pin control</para></listitem>
</orderedlist>
<para>
The control pin (together with clock) allows to switch device states. A state
machine inside each chip can be controlled, e.g. to reset the device. This
control machine also allows to have two internal shift registers in each device
(although we only have on in- and one output-pin). The registers are called
instruction register (IR) and data register (DR). The current UrJTAG tool
allows you to set the IR and set and get the DR. It doesn't allow you to
directly control the statemachine (yet).
</para>
</section><section><title>Interfaces</title>
<para>
The simplest interface that you can build is the Xilinx parallel cable (also
called DLC5). If your device works with a 5V or 3.3V supply voltage then this
device can even be build just with passive parts. (picture missing here)
UrJTAG also supports a number of other interface adapters.
</para>
</section><section><title>Additions</title>
<para>
In the meantime the jtag specification was used as a basis for programming flash files and debugging processors.
UrJTAG supports programming a couple of different flash devices. It also supports programming of non-flash devices via svf files.
UrJTAG does not support debugging yet. Other open source solutions allow you to debug ARM processors with gdb.
</para>
</section><section><title>BSDL files</title>
<para>
The bsdl file format describes the jtag interface for one IC.
It is a vhdl syntax with the needed information (like pin-names, register lengths and commands) that is usually done by the supplier. e.g. the Xilinx .bsd files are all included in their free web-pack.
</para><para>
Urjtag uses a different file format internally. So in order to add a new device to UrJTAG you need to convert those files and produce a directory structure. Currently there are at least three tools available to do that. Please ask on the mailing list in case of problems with that. Please also send proven working files back to this project.
</para>
</section>
<section><title>SVF files</title>
<para>
The svf file format contains a number of high level commands to drive the jtag bus. For example you can shift the IR or DR and even check for the results.
The Xilinxs impact tool allows you to write this file to program devices.
</para>
</section>
</section>
<section><title>UrJTAG</title>
<section><title>Introduction></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>
Kolja wrote: I 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>
<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 "Installation" 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 &amp; 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>JTAG commands</title>
<section><title>Overview</title>
<para>
Following is a list of commands currently supported by jtag and some example usage.
</para>
<programlisting>
quit exit and terminate this session
help display this help
frequency setup JTAG frequency
cable select JTAG cable
discovery discovery of unknown parts in the JTAG chain
detect detect parts on the JTAG chain
signal define new signal for a part
bit define new BSR bit
register define new data register for a part
initbus initialize bus driver for active part
print display JTAG chain list/status
part change active part for current JTAG chain
bus change active bus
instruction change active instruction for a part or declare new instruction
shift shift data/instruction registers through JTAG chain
dr display active data register for a part
get get external signal value
set set external signal value
endian set/print endianess
peek read a single word
poke write a single word
readmem read content of the memory and write it to file
detectflash detect parameters of flash chips attached to a part
flashmem burn flash memory with data from a file
eraseflash erase flash memory by number of blocks
script run command sequence from external file
include include command sequence from external repository
svf execute svf commands from file
</programlisting>
</section>
<section><title>Generic commands</title>
<section><title>quit</title>
<para>
Guess what. That command closes the jtag console.
</para>
</section>
<section><title>help</title>
<para>
Without additional parameter it gives an overview of the available commands.
With a parameter you can get more information about any of the commands. Example:
</para>
<programlisting>
jtag> help cable
</programlisting>
</section>
</section>
<section><title>Part definition commands</title>
<para>
The following commands are also used in the data files to define a
device (IC) on the jtag bus. I do not recommend using those commands in an
interactive session. Instead you should produce a device definition file out of
a .bsd file using one of the supplied tools.
</para>
<section><title>signal</title><para/></section>
<section><title>bit</title><para/></section>
<section><title>register</title><para/></section>
</section>
<section><title>Flash commands</title>
<para>
These commands can be used if the device supports flashing.
</para>
<section><title>detectflash</title><para/></section>
<section><title>flashmem</title><para/></section>
<section><title>eraseflash</title><para/></section>
</section>
<section><title>Chain management</title>
<section><title>cable</title>
<para>
Sets and initialized the cable driver. This is usually the first
command that you are executing in a session. Example:
</para>
<programlisting>
jtag> cable parallel 0x378 EA253
Initializing ETC EA253 JTAG Cable on parallel port at 0x378
</programlisting>
<para>
For a parallel cable using the ppdev driver you would use
</para>
<programlisting>
cable ppdev /dev/parport0 DLC5
</programlisting>
<para>
After seeing an error you will remember that the parallel port kernel driver
was compiled as a module in your Linux kernel. So you will probably also
execute (with root rights outside of UrJTAG):
</para>
<programlisting>
modprobe ppdev
modprobe parport
modprobe parport_pc
</programlisting>
</section>
<section><title>detect</title>
<para>
Detects devices on the bus. Example:
</para>
<programlisting>
jtag> detect
IR length: 5
Chain length: 1
Device Id: 01011001001001100100000000010011
Manufacturer: Intel
Part: PXA250
Stepping: C0
Filename: /usr/local/share/jtag/intel/pxa250/pxa250c0
</programlisting>
</section>
</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>Internals</title>
<section><title>Software structure</title>
<section><title>Overview</title>
<para/>
</section>
<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>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>Document history</title><para/>
</appendix>
&FDL;
&GPL;
&LGPL;
</book>
Reference in New Issue View Git Blame Copy Permalink