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.
6157 lines
136 KiB
HTML
6157 lines
136 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Universal JTAG library, server and tools</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
|
|
REL="STYLESHEET"
|
|
TYPE="text/css"
|
|
HREF="UrJTAG.css"></HEAD
|
|
><BODY
|
|
CLASS="book"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="BOOK"
|
|
><A
|
|
NAME="AEN1"
|
|
></A
|
|
><DIV
|
|
CLASS="TITLEPAGE"
|
|
><H1
|
|
CLASS="title"
|
|
><A
|
|
NAME="AEN2"
|
|
>Universal JTAG library, server and tools</A
|
|
></H1
|
|
><H3
|
|
CLASS="author"
|
|
><A
|
|
NAME="AEN5"
|
|
></A
|
|
>Kolja Waschk (Ed.)</H3
|
|
><HR></DIV
|
|
><DIV
|
|
CLASS="TOC"
|
|
><DL
|
|
><DT
|
|
><B
|
|
>Table of Contents</B
|
|
></DT
|
|
><DT
|
|
>1. <A
|
|
HREF="#_copyright"
|
|
>Copyright</A
|
|
></DT
|
|
><DT
|
|
>2. <A
|
|
HREF="#_general"
|
|
>General</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>2.1. <A
|
|
HREF="#_jtag"
|
|
>JTAG</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>2.1.1. <A
|
|
HREF="#_introduction"
|
|
>Introduction</A
|
|
></DT
|
|
><DT
|
|
>2.1.2. <A
|
|
HREF="#_interfaces"
|
|
>Interfaces</A
|
|
></DT
|
|
><DT
|
|
>2.1.3. <A
|
|
HREF="#_additions"
|
|
>Additions</A
|
|
></DT
|
|
><DT
|
|
>2.1.4. <A
|
|
HREF="#_bsdl_and_urjtag_data_files"
|
|
>BSDL and UrJTAG data files</A
|
|
></DT
|
|
><DT
|
|
>2.1.5. <A
|
|
HREF="#_svf_files"
|
|
>SVF files</A
|
|
></DT
|
|
><DT
|
|
>2.1.6. <A
|
|
HREF="#_jam_stapl_files"
|
|
>JAM/STAPL files</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>2.2. <A
|
|
HREF="#_urjtag"
|
|
>UrJTAG</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>2.2.1. <A
|
|
HREF="#_introduction_2"
|
|
>Introduction</A
|
|
></DT
|
|
><DT
|
|
>2.2.2. <A
|
|
HREF="#_about_this_document"
|
|
>About this document</A
|
|
></DT
|
|
><DT
|
|
>2.2.3. <A
|
|
HREF="#_urjtag_website"
|
|
>UrJTAG Website</A
|
|
></DT
|
|
><DT
|
|
>2.2.4. <A
|
|
HREF="#_the_name_urjtag"
|
|
>The name "UrJTAG"</A
|
|
></DT
|
|
><DT
|
|
>2.2.5. <A
|
|
HREF="#_authors_contributors_8230_thanks"
|
|
>Authors, contributors, … thanks</A
|
|
></DT
|
|
><DT
|
|
>2.2.6. <A
|
|
HREF="#_urjtag_and_openwince_jtag_tools"
|
|
>UrJTAG and openwince JTAG Tools</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>2.3. <A
|
|
HREF="#_system_requirements"
|
|
>System requirements</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>2.3.1. <A
|
|
HREF="#_supported_host_operating_systems"
|
|
>Supported host operating systems</A
|
|
></DT
|
|
><DT
|
|
>2.3.2. <A
|
|
HREF="#_required_software_for_running_urjtag"
|
|
>Required software for running UrJTAG</A
|
|
></DT
|
|
><DT
|
|
>2.3.3. <A
|
|
HREF="#_supported_jtag_adapters_cables"
|
|
>Supported JTAG adapters/cables</A
|
|
></DT
|
|
><DT
|
|
>2.3.4. <A
|
|
HREF="#_jtag_aware_parts_chips"
|
|
>JTAG-aware parts (chips)</A
|
|
></DT
|
|
><DT
|
|
>2.3.5. <A
|
|
HREF="#_flash_chips"
|
|
>Flash chips</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>2.4. <A
|
|
HREF="#_compilation_and_installation"
|
|
>Compilation and installation</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>2.4.1. <A
|
|
HREF="#_installation_of_precompiled_urjtag_for_windows"
|
|
>Installation of precompiled UrJTAG for Windows</A
|
|
></DT
|
|
><DT
|
|
>2.4.2. <A
|
|
HREF="#_required_software_for_compiling_urjtag"
|
|
>Required software for compiling UrJTAG</A
|
|
></DT
|
|
><DT
|
|
>2.4.3. <A
|
|
HREF="#_required_libraries_for_usb_support"
|
|
>Required libraries for USB support</A
|
|
></DT
|
|
><DT
|
|
>2.4.4. <A
|
|
HREF="#_installing_from_source_tar_gz"
|
|
>Installing from source tar.gz</A
|
|
></DT
|
|
><DT
|
|
>2.4.5. <A
|
|
HREF="#_installing_from_subversion_repository"
|
|
>Installing from Subversion repository</A
|
|
></DT
|
|
><DT
|
|
>2.4.6. <A
|
|
HREF="#_linking_to_ftd2xx_dll_in_cygwin_environment"
|
|
>Linking to FTD2XX.DLL in Cygwin environment</A
|
|
></DT
|
|
><DT
|
|
>2.4.7. <A
|
|
HREF="#_using_libusb_win32_in_cygwin_environment"
|
|
>Using LibUSB-Win32 in Cygwin environment</A
|
|
></DT
|
|
><DT
|
|
>2.4.8. <A
|
|
HREF="#_compiling_with_mingw"
|
|
>Compiling with MinGW</A
|
|
></DT
|
|
><DT
|
|
>2.4.9. <A
|
|
HREF="#_driver_tailoring"
|
|
>Driver tailoring</A
|
|
></DT
|
|
><DT
|
|
>2.4.10. <A
|
|
HREF="#_building_the_bsdl_subsystem"
|
|
>Building the BSDL subsystem</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>3. <A
|
|
HREF="#_usage"
|
|
>Usage</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>3.1. <A
|
|
HREF="#_quick_start"
|
|
>Quick start</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>3.1.1. <A
|
|
HREF="#_run_the_software"
|
|
>Run the software</A
|
|
></DT
|
|
><DT
|
|
>3.1.2. <A
|
|
HREF="#_configure_the_cable"
|
|
>Configure the cable</A
|
|
></DT
|
|
><DT
|
|
>3.1.3. <A
|
|
HREF="#_detect_parts_on_the_jtag_chain"
|
|
>Detect parts on the JTAG chain</A
|
|
></DT
|
|
><DT
|
|
>3.1.4. <A
|
|
HREF="#_print_current_jtag_chain_status"
|
|
>Print current JTAG chain status</A
|
|
></DT
|
|
><DT
|
|
>3.1.5. <A
|
|
HREF="#_sample_device_pin_status"
|
|
>Sample device pin status</A
|
|
></DT
|
|
><DT
|
|
>3.1.6. <A
|
|
HREF="#_burn_flash_connected_to_the_part"
|
|
>Burn flash connected to the part</A
|
|
></DT
|
|
><DT
|
|
>3.1.7. <A
|
|
HREF="#_non_standard_flash_commands"
|
|
>Non-standard flash commands</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>3.2. <A
|
|
HREF="#_jtag_commands"
|
|
>JTAG commands</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>3.2.1. <A
|
|
HREF="#_overview"
|
|
>Overview</A
|
|
></DT
|
|
><DT
|
|
>3.2.2. <A
|
|
HREF="#_basic_commands"
|
|
>Basic commands</A
|
|
></DT
|
|
><DT
|
|
>3.2.3. <A
|
|
HREF="#_chain_management"
|
|
>Chain management</A
|
|
></DT
|
|
><DT
|
|
>3.2.4. <A
|
|
HREF="#_part_definition_commands"
|
|
>Part definition commands</A
|
|
></DT
|
|
><DT
|
|
>3.2.5. <A
|
|
HREF="#_tap_control"
|
|
>TAP control</A
|
|
></DT
|
|
><DT
|
|
>3.2.6. <A
|
|
HREF="#_ram_flash_access"
|
|
>RAM/Flash access</A
|
|
></DT
|
|
><DT
|
|
>3.2.7. <A
|
|
HREF="#_highlevel_commands"
|
|
>Highlevel commands</A
|
|
></DT
|
|
><DT
|
|
>3.2.8. <A
|
|
HREF="#_unsupported_commands"
|
|
>Unsupported commands</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>4. <A
|
|
HREF="#_internals"
|
|
>Internals</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>4.1. <A
|
|
HREF="#_files"
|
|
>Files</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>4.1.1. <A
|
|
HREF="#_source_code_overview"
|
|
>Source code Overview</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>4.2. <A
|
|
HREF="#_drivers"
|
|
>Drivers</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>4.2.1. <A
|
|
HREF="#_cable_specific_drivers_src_tap_cable"
|
|
>Cable-specific drivers (src/tap/cable)</A
|
|
></DT
|
|
><DT
|
|
>4.2.2. <A
|
|
HREF="#_link_drivers"
|
|
>Link drivers</A
|
|
></DT
|
|
><DT
|
|
>4.2.3. <A
|
|
HREF="#_bus_drivers"
|
|
>Bus drivers</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>4.3. <A
|
|
HREF="#_data_file_format"
|
|
>Data file format</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>4.3.1. <A
|
|
HREF="#_general_rules"
|
|
>General rules</A
|
|
></DT
|
|
><DT
|
|
>4.3.2. <A
|
|
HREF="#_signal_definition"
|
|
>Signal Definition</A
|
|
></DT
|
|
><DT
|
|
>4.3.3. <A
|
|
HREF="#_manufacturers_list"
|
|
>Manufacturers List</A
|
|
></DT
|
|
><DT
|
|
>4.3.4. <A
|
|
HREF="#_parts_list"
|
|
>Parts List</A
|
|
></DT
|
|
><DT
|
|
>4.3.5. <A
|
|
HREF="#_stepping_list"
|
|
>Stepping List</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>4.4. <A
|
|
HREF="#_development"
|
|
>Development</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>4.4.1. <A
|
|
HREF="#_future_plans"
|
|
>Future Plans</A
|
|
></DT
|
|
><DT
|
|
>4.4.2. <A
|
|
HREF="#_how_to_contribute"
|
|
>How to contribute</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>5. <A
|
|
HREF="#_f_a_q"
|
|
>F.A.Q.</A
|
|
></DT
|
|
><DT
|
|
>6. <A
|
|
HREF="#_licensing"
|
|
>Licensing</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>6.1. <A
|
|
HREF="#_overview_2"
|
|
>Overview</A
|
|
></DT
|
|
><DT
|
|
>6.2. <A
|
|
HREF="#_gnu_free_documentation_license_fdl"
|
|
>GNU Free Documentation License (FDL)</A
|
|
></DT
|
|
><DT
|
|
>6.3. <A
|
|
HREF="#_gnu_general_public_license_gpl"
|
|
>GNU General Public License (GPL)</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
></DL
|
|
></DIV
|
|
><DIV
|
|
CLASS="chapter"
|
|
><HR><H1
|
|
><A
|
|
NAME="_copyright"
|
|
></A
|
|
>Chapter 1. Copyright</H1
|
|
><P
|
|
>Copyright 2007, 2008 Kolja Waschk and the respective authors.</P
|
|
><P
|
|
>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".</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="chapter"
|
|
><HR><H1
|
|
><A
|
|
NAME="_general"
|
|
></A
|
|
>Chapter 2. General</H1
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_jtag"
|
|
>2.1. JTAG</A
|
|
></H2
|
|
><P
|
|
>JTAG basics can be found all over the Internet. This section should go into
|
|
some more details about working with JTAG. What hardware do you need, what is
|
|
the usage of JTAG, where do I get files. What file formats are available…</P
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_introduction"
|
|
>2.1.1. Introduction</A
|
|
></H3
|
|
><P
|
|
>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.</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> One pin serial input
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> One pin serial output
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> One pin clock
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> One pin control
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>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 state machine (yet).</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_interfaces"
|
|
>2.1.2. Interfaces</A
|
|
></H3
|
|
><P
|
|
>The simplest interface that you can build is like 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 built just with passive parts. (picture missing here)
|
|
UrJTAG also supports a number of other interface adapters.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_additions"
|
|
>2.1.3. Additions</A
|
|
></H3
|
|
><P
|
|
>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
|
|
such as OpenOCD allow you to debug ARM processors with gdb.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_bsdl_and_urjtag_data_files"
|
|
>2.1.4. BSDL and UrJTAG data files</A
|
|
></H3
|
|
><P
|
|
>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 created by the supplier. e.g. Xilinx BSDL files are
|
|
all included in their free web-pack (using file extension ".bsd").</P
|
|
><P
|
|
>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; included with
|
|
UrJTAG is "bsdl2jtag". Please ask on the mailing list in case of problems with
|
|
that. Please also send proven working files back to this project.</P
|
|
><P
|
|
>Starting with post-0.7 releases, UrJTAG contains a BSDL subsystem that
|
|
retrieves the descriptions for chips in the chain from BSDL files on the
|
|
fly. "bsdl2jtag" is in fact a wrapper that uses the BSDL subsystem to
|
|
convert the BSDL file.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_svf_files"
|
|
>2.1.5. SVF files</A
|
|
></H3
|
|
><P
|
|
>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 Xilinx Impact and Altera QuartusII tools allow you to write this file to
|
|
program devices.</P
|
|
><P
|
|
>The player has been developed according to the "Serial Vector Format
|
|
Specification", Revision E, 8 March 1999 issued by ASSET InterTech, Inc. The
|
|
full specification can be found at
|
|
<A
|
|
HREF="http://www.asset-intertech.com/support/svf.pdf"
|
|
TARGET="_top"
|
|
>http://www.asset-intertech.com/support/svf.pdf</A
|
|
>.</P
|
|
><P
|
|
>UrJTAG features an "SVF player" that can read SVF files and perform the
|
|
described actions on the bus.</P
|
|
><P
|
|
>SVF parser and lexer are also copyright 2002, CDS at <A
|
|
HREF="http://www-csd.ijs.si/"
|
|
TARGET="_top"
|
|
>http://www-csd.ijs.si/</A
|
|
>.
|
|
They have been reused from the "Experimental Boundary Scan" project at
|
|
<A
|
|
HREF="http://ebsp.sourceforge.net/"
|
|
TARGET="_top"
|
|
>http://ebsp.sourceforge.net/</A
|
|
>.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_jam_stapl_files"
|
|
>2.1.6. JAM/STAPL files</A
|
|
></H3
|
|
><P
|
|
>Another format for describing actions over JTAG interfaces is STAPL, actually
|
|
standardized as JEDEC "JESD-71A". Compared to SVF, it looks more like an
|
|
actual programming language and features looping, conditional execution, and
|
|
more. STAPL is not yet supported by UrJTAG.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_urjtag"
|
|
>2.2. UrJTAG</A
|
|
></H2
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_introduction_2"
|
|
>2.2.1. Introduction</A
|
|
></H3
|
|
><P
|
|
>UrJTAG is a software package which enables working with JTAG-aware (IEEE
|
|
1149.1) hardware devices (parts) and boards through a JTAG adapter.</P
|
|
><P
|
|
>This package has an open and modular architecture with the ability to write
|
|
miscellaneous extensions (like board testers, flash memory programmers, and so
|
|
on).</P
|
|
><P
|
|
>UrJTAG 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 UrJTAG. Please read
|
|
the COPYING file for more info.</P
|
|
><DIV
|
|
CLASS="warning"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="warning"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/warning.gif"
|
|
HSPACE="5"
|
|
ALT="Warning"></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
>This software may damage your hardware!</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><P
|
|
>Feedback and contributions are welcome.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_about_this_document"
|
|
>2.2.2. About this document</A
|
|
></H3
|
|
><P
|
|
>This documentation is far from being complete. You're encouraged to amend and
|
|
supplement it and submit your changes in the Bugs or Enhancements tracker
|
|
at the UrJTAG website.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_urjtag_website"
|
|
>2.2.3. UrJTAG Website</A
|
|
></H3
|
|
><P
|
|
>The most current version of this documentation and UrJTAG source code
|
|
is always available from the project homepage at <A
|
|
HREF="http://www.urjtag.org"
|
|
TARGET="_top"
|
|
>http://www.urjtag.org</A
|
|
>.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_the_name_urjtag"
|
|
>2.2.4. The name "UrJTAG"</A
|
|
></H3
|
|
><P
|
|
>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 prototype for many
|
|
other JTAG tools. By mere chance the "Ur" is also another name for an aurochs,
|
|
an animal similar to the GNU…</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_authors_contributors_8230_thanks"
|
|
>2.2.5. Authors, contributors, … thanks</A
|
|
></H3
|
|
><P
|
|
>A list of contributors is maintained in the file THANKS in the source
|
|
distribution. Special thanks go to Marcel Telka, who actually "invented" the
|
|
JTAG tools and wrote most of this basis of UrJTAG, and Arnim Laeuger for his
|
|
continuous support and development of SVF and BSDL subsystem and FT2232
|
|
drivers.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_urjtag_and_openwince_jtag_tools"
|
|
>2.2.6. UrJTAG and openwince JTAG Tools</A
|
|
></H3
|
|
><P
|
|
>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.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_system_requirements"
|
|
>2.3. System requirements</A
|
|
></H2
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_supported_host_operating_systems"
|
|
>2.3.1. Supported host operating systems</A
|
|
></H3
|
|
><P
|
|
>JTAG Tools should run on all Unix like operating systems including MS Windows
|
|
with Cygwin installed. A precompiled version that runs on MS Windows without
|
|
Cygwin is available as a Windows installer executable.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_required_software_for_running_urjtag"
|
|
>2.3.2. Required software for running UrJTAG</A
|
|
></H3
|
|
><P
|
|
>Required only for MS Windows, unless you use the precompiled version:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> current Cygwin net installation from <A
|
|
HREF="http://cygwin.com"
|
|
TARGET="_top"
|
|
>http://cygwin.com</A
|
|
>
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> ioperm package (a part of the standard Cygwin net installation)
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>It may be necessary to run the command "ioperm -i" to install the IOPERM.SYS
|
|
driver in the system.</P
|
|
><P
|
|
>If UrJTAG was compiled to use the readline library, it has to be present on
|
|
the system as well. It's probably a standard part of your distribution.</P
|
|
><P
|
|
>More software is needed if you want to compile UrJTAG (which you probably want
|
|
because currently no pre-compiled binaries are available…).
|
|
See "Installation" below.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_supported_jtag_adapters_cables"
|
|
>2.3.3. Supported JTAG adapters/cables</A
|
|
></H3
|
|
><P
|
|
>See <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>help cable</I
|
|
></SPAN
|
|
> command for up-to-date info.</P
|
|
><P
|
|
>Parallel-port cables:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> Arcom JTAG Cable
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Altera ByteBlaster/ByteBlaster II/ByteBlasterMV Parallel Port Download Cable
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Xilinx DLC5 JTAG Parallel Cable III
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> ETC EA253 JTAG Cable
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> ETC EI012 JTAG Cable
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Ka-Ro TRITON (PXA255/250) JTAG Cable
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Keith &amp; Koep JTAG Cable
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Lattice Parallel Port JTAG Cable
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Mpcbdm JTAG Cable
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Macraigor Wiggler JTAG Cable
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>FT2232-based USB cables:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> Amontec JTAGkey
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Amontec JTAGkey-Tiny (supported as cable "JTAGkey")
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> KrisTech UsbScarab2 ARM JTAG <A
|
|
HREF="http://www.kristech.eu/"
|
|
TARGET="_top"
|
|
>http://www.kristech.eu/</A
|
|
>
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Olimex ARM-USB-JTAG
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Olimex ARM-USB-TINY
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> OOCDLink-s (experimental) <A
|
|
HREF="http://www.joernonline.de/dw/doku.php?id=projects:oocdlink:2_oocdlinks"
|
|
TARGET="_top"
|
|
>http://www.joernonline.de/dw/doku.php?id=projects:oocdlink:2_oocdlinks</A
|
|
>
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Other FT2232-based USB JTAG cables (experimental)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> TinCanTools Flyswatter
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Turtelizer 2 (experimental) <A
|
|
HREF="http://www.ethernut.de/en/hardware/turtelizer/"
|
|
TARGET="_top"
|
|
>http://www.ethernut.de/en/hardware/turtelizer/</A
|
|
>
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> USB to JTAG Interface (experimental)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> <A
|
|
HREF="http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html"
|
|
TARGET="_top"
|
|
>http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html</A
|
|
>
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Blackfin gnICE <A
|
|
HREF="http://docs.blackfin.uclinux.org/doku.php?id=hw:jtag:gnice"
|
|
TARGET="_top"
|
|
>http://docs.blackfin.uclinux.org/doku.php?id=hw:jtag:gnice</A
|
|
>
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Blackfin gnICE+ <A
|
|
HREF="http://docs.blackfin.uclinux.org/doku.php?id=hw:jtag:gnice-plus"
|
|
TARGET="_top"
|
|
>http://docs.blackfin.uclinux.org/doku.php?id=hw:jtag:gnice-plus</A
|
|
>
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Xverve Signalyzer Tool (experimental)
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>Other USB cables:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> Altera USB-Blaster and compatible <A
|
|
HREF="http://www.ixo.de/info/usb_jtag"
|
|
TARGET="_top"
|
|
>http://www.ixo.de/info/usb_jtag</A
|
|
>
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Segger/IAR J-Link / Atmel SAM-ICE (experimental, work in progress)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Xilinx Platform USB Cable / DLC9 (slow, experimental, work in progress - don't use)
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>Other cables:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> Technologic Systems TS-7800 SoC GPIO builtin JTAG interface
|
|
</P
|
|
></LI
|
|
></UL
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_jtag_aware_parts_chips"
|
|
>2.3.4. JTAG-aware parts (chips)</A
|
|
></H3
|
|
><P
|
|
>The data/ directory of the UrJTAG installation has some more, but at
|
|
least the following are supported:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> Altera EP1C20F400
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Altera MAX7000 (w/ BSDL)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Altera EPM7128AETC100
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Altera Cyclone I & II (w/ BSDL)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Analog Devices Blackfin (w/ BSDL)
|
|
</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> BF504/BF506
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> BF512/BF514/BF516/BF518
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> BF522/BF523/BF524/BF525/BF526/BF527
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> BF531/BF532/BF533
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> BF538/BF539
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> BF534/BF536/BF537
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> BF542/BF544/BF547/BF548/BF549
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> BF561
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> BF592
|
|
</P
|
|
></LI
|
|
></UL
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Analog Devices Sharc-21065L
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Atmel ATmega128 (partial support)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Atmel AT32AP7000 (partial support)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Broadcom BCM1250
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Broadcom BCM3310 (partial support)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Broadcom BCM5421S
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Broadcom BCM4712 (partial support)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> DEC SA1100
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Hitachi HD64465
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Hitachi SH7727
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Hitachi SH7729
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> IBM PowerPC 440GX
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Intel IXP425
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Intel SA1110
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Intel PXA250/PXA255/PXA260/PXA261/PXA262/PXA263
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Lattice LC4032V
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Lattice M4A3-64/32
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Lattice M4A3-256/192
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Motorola MPC8245
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Samsung S3C4510B
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Sharp LH7A400
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Toshiba TX4925/TX4926
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Xilinx XC2C256-TQ144
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Xilinx XCR3032XL-VQ44
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Xilinx XCR3128XL-CS144
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Xilinx XCR3128XL-VQ100
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Xilinx XCR3256XL-FT256
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Xilinx Spartan-IIE
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Xilinx Spartan-3/E
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Xilinx Spartan-3AN
|
|
</P
|
|
></LI
|
|
></UL
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_flash_chips"
|
|
>2.3.5. Flash chips</A
|
|
></H3
|
|
><DIV
|
|
CLASS="note"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="note"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/note.gif"
|
|
HSPACE="5"
|
|
ALT="Note"></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
>Not all chips are supported in every possible configuration, there may
|
|
be untested combinations of chip type, bus width, …</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> Intel 28FxxxJ3A (28F320J3A, 28F640J3A, 28F128J3A)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Intel 28FxxxK3 (28F640K3, 28F128K3, 28F256K3)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Intel 28FxxxK18 (28F640K18, 28F128K18, 28F256K18)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> AMD Am29LV64xD (Am29LV640D, Am29LV641D, Am29LV642D)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> AMD Am29xx040B (Am29F040B, Am29LV040B)
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>UrJTAG uses the multi-byte write mode if supported by the particular flash
|
|
device. The flash code will automatically switch to this algorithm if the
|
|
Device Geometry Definition reports that more than one memory location can be
|
|
written in a single step (refer to CFI details shown by <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>detectflash</I
|
|
></SPAN
|
|
>). Since
|
|
multiple locations are written in a burst-like manner with only one polling
|
|
sequence afterwards, the overall flashing performance increases by factor of
|
|
5-17.</P
|
|
><P
|
|
>In case you encounter any issues with the multi-byte write mode, run configure
|
|
with the <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>—disable-flash-multi-byte</I
|
|
></SPAN
|
|
> option and re-compile to disable this
|
|
algorithm.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_compilation_and_installation"
|
|
>2.4. Compilation and installation</A
|
|
></H2
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_installation_of_precompiled_urjtag_for_windows"
|
|
>2.4.1. Installation of precompiled UrJTAG for Windows</A
|
|
></H3
|
|
><P
|
|
>By simply running UrJTAG-xxx.exe, the executable and data files will
|
|
be installed in your Windows program folder, usually some place like
|
|
C:\Program Files\UrJTAG. It comes ready with support for JTAG cables that are
|
|
directly attached to a parallel port. However, if you work with Windows Vista
|
|
and want access to the parallel port, a driver for it has to be installed
|
|
separately. It is available from</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>http://www.highrez.co.uk/Downloads/InpOut32/</PRE
|
|
><P
|
|
>If you want to use UrJTAG with a JTAG cable attached to the USB port,
|
|
actual cable drivers have to be installed beside UrJTAG itself. Usually,
|
|
the cable vendor will provide the drivers. For example, drivers for
|
|
Altera USB-Blaster come with their Quartus software. For FTDI-based
|
|
cables, you need an INF file describing the cable and FTDIBUS.SYS and
|
|
FTD2XX.DLL from FTDI (CDM drivers). If your cable shows up in the device
|
|
manager without any warning sign, UrJTAG probably is able to talk to it.</P
|
|
><P
|
|
>Finally, UrJTAG additionally needs libusb-win32 to talk to some USB cables that
|
|
are not based on FTDI chips (Xilinx Platform Cable USB, Segger J-Link). The
|
|
so-called libusb-win32 filter driver is available from the project's download
|
|
page at Sourceforge:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>http://libusb-win32.sourceforge.net/#downloads</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_required_software_for_compiling_urjtag"
|
|
>2.4.2. Required software for compiling UrJTAG</A
|
|
></H3
|
|
><P
|
|
>To run autogen.sh, you need autoconf and automake, bison, and a recent flex.</P
|
|
><P
|
|
>The distributed source tarball contains source pregenerated with a current
|
|
flex version; flex therefore is only needed if you want to compile code
|
|
checked out from our Subversion repository. Flex 2.5.4a as it comes with
|
|
most but the very latest Cygwin release cannot build the scanners for BSDL and
|
|
SVF. Building these files requires Flex 2.5.33 or newer. The configure script
|
|
will compare the available Flex version against these preconditions and enables
|
|
or disables the related features.</P
|
|
><P
|
|
>Furthermore, libtool should be available, and "devel" versions of the following
|
|
packages:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> gettext
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> readline (not needed, but really eases interactive use)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> ioperm (needed only for Cygwin)
|
|
</P
|
|
></LI
|
|
></UL
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_required_libraries_for_usb_support"
|
|
>2.4.3. Required libraries for USB support</A
|
|
></H3
|
|
><P
|
|
>For USB adapter support (including support for parallel port adapters attached
|
|
to USB-to-parallel converters), one or more additional libraries are required.</P
|
|
><P
|
|
>Many USB JTAG adapters and USB-to-parallel converters are based on chips
|
|
made by FTDI. To support these, either intra.net's "libftdi" or FTDI's
|
|
"FTD2XX" library can be used.</P
|
|
><P
|
|
>On many modern Linux distributions, libftdi is available as a precompiled
|
|
package and can be installed using the distribution's package management system
|
|
(e.g. "apt-get libftdi-dev" for Debian and Ubuntu). If it isn't available or
|
|
you don't run Linux, you can get it from</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> <A
|
|
HREF="http://www.intra2net.com/en/developer/libftdi/"
|
|
TARGET="_top"
|
|
>http://www.intra2net.com/en/developer/libftdi/</A
|
|
>
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>Alternatively, you can use the FTD2XX library from the chip manufacturer FTDI.
|
|
It is available for Linux and Windows. There's more information about linking
|
|
to that library in a Cygwin environment below.</P
|
|
><P
|
|
>All other USB JTAG adapters can be supported only if libusb is installed.
|
|
There is a libusb-win32 variant that can be used in a Cygwin environment:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> <A
|
|
HREF="http://libusb.sourceforge.net"
|
|
TARGET="_top"
|
|
>http://libusb.sourceforge.net</A
|
|
> (libusb)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> <A
|
|
HREF="http://libusb-win32.sourceforge.net"
|
|
TARGET="_top"
|
|
>http://libusb-win32.sourceforge.net</A
|
|
> (libusb for Windows)
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>For specific notes regarding the use of these libraries in a Cygwin
|
|
environment, see below.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_installing_from_source_tar_gz"
|
|
>2.4.4. Installing from source tar.gz</A
|
|
></H3
|
|
><P
|
|
>The installation follows the standard configure, make, make install scheme:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>tar xzvf urjtag-x.y.tar.gz
|
|
cd urjtag-x.y
|
|
./configure
|
|
make
|
|
make install</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_installing_from_subversion_repository"
|
|
>2.4.5. Installing from Subversion repository</A
|
|
></H3
|
|
><P
|
|
>If you want to try the very newest version of UrJTAG…</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>svn co http://urjtag.svn.sourceforge.net/svnroot/urjtag/trunk urjtag</PRE
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>cd urjtag/jtag
|
|
./autogen.sh
|
|
# ./configure done by autogen.sh; run it here with special options if needed
|
|
make
|
|
make install</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_linking_to_ftd2xx_dll_in_cygwin_environment"
|
|
>2.4.6. Linking to FTD2XX.DLL in Cygwin environment</A
|
|
></H3
|
|
><P
|
|
>Before running configure, get the D2XX drivers from FTDI.</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> <A
|
|
HREF="http://www.ftdichip.com/Drivers/D2XX.htm"
|
|
TARGET="_top"
|
|
>http://www.ftdichip.com/Drivers/D2XX.htm</A
|
|
> (FTDI FTD2XX library)
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>Unzip the archive into a directory of your choice (probably a choice
|
|
without spaces in the name is better) and afterwards run configure with the
|
|
"—with-ftd2xx" pointing to that directory, e.g.</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>./configure --with-ftd2xx="/cygdrive/c/temp/ftdi-cdm-drivers"</PRE
|
|
><P
|
|
>Configure should now report</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag is now configured for
|
|
...
|
|
Detected libftd2xx : yes</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_using_libusb_win32_in_cygwin_environment"
|
|
>2.4.7. Using LibUSB-Win32 in Cygwin environment</A
|
|
></H3
|
|
><P
|
|
>Before running configure, install the LibUSB-Win32 "filter" driver from SF.</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> <A
|
|
HREF="http://libusb-win32.sourceforge.net"
|
|
TARGET="_top"
|
|
>http://libusb-win32.sourceforge.net</A
|
|
>
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>Then point configure to the directory where LibUSB-Win32 was installed (it
|
|
might give problems if the path contains spaces, as "Program Files" does!):</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>./configure --with-libusb="/cygdrive/c/Programme/LibUSB-Win32/"</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_compiling_with_mingw"
|
|
>2.4.8. Compiling with MinGW</A
|
|
></H3
|
|
><P
|
|
>UrJTAG may be compiled into a Windows executable using the MinGW compiler
|
|
(<A
|
|
HREF="http://www.mingw.org"
|
|
TARGET="_top"
|
|
>http://www.mingw.org</A
|
|
>), or Cygwin GCC with the "-mno-cygwin" compiler flag.</P
|
|
><P
|
|
>This has the advantage over running in a Cygwin environment that you don't need
|
|
to install anything else but the jtag.exe (plus libraries like FTD2XX.dll or
|
|
InpOut32.DLL that are required for device access under Windows in any case).</P
|
|
><P
|
|
>However, because support for MinGW is quite new in UrJTAG, it may lack some
|
|
features (e.g. readline support) or run a little slower.</P
|
|
><P
|
|
>Because it seems to be easier to set up a Cygwin environment, we recommend
|
|
using the Cygwin GCC with "-mno-cygwin" flag instead of using a MinGW setup:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>CFLAGS="-mno-cygwin -O2" ./configure --with-ftd2xx=/tmp/cdm-drivers --with-inpout32</PRE
|
|
><P
|
|
>It is even possible to cross-compile and build the executable on a Linux
|
|
host:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>./configure --host=i586-mingw32msvc --with-ftd2xx=/tmp/cdm-drivers --with-inpout32
|
|
make</PRE
|
|
><P
|
|
>The "—with-inpout32" switch tells UrJTAG to use the InpOut32.DLL for access to
|
|
parallel ports, because the Cygwin ioperm isn't available for MinGW. The InpOut32
|
|
library is available from logix4u.net:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>http://logix4u.net/Legacy_Ports/Parallel_Port/Inpout32.dll_for_Windows_98/2000/NT/XP.html</PRE
|
|
><P
|
|
>An version updated to work in Windows Vista and 64 bit Windows is available from highrez:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>http://www.highrez.co.uk/Downloads/InpOut32/</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_driver_tailoring"
|
|
>2.4.9. Driver tailoring</A
|
|
></H3
|
|
><P
|
|
>The configure script enables all default bus, cable and lowlevel drivers. You
|
|
can include and exclude specific drivers if required. For a list of parameters
|
|
run</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>./configure --help</PRE
|
|
><P
|
|
>to figure out the appropriate —enable-bus, —enable-cable, and —enable-lowlevel
|
|
options.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_building_the_bsdl_subsystem"
|
|
>2.4.10. Building the BSDL subsystem</A
|
|
></H3
|
|
><P
|
|
>As mentioned above, building the BSDL lexer requires Flex 2.5.33 or newer. If
|
|
the detected Flex version is not recent enough, configure will disable the
|
|
BSDL subsystem. The detection result is summarized at the end of configure:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag is now configured for
|
|
...
|
|
Build BSDL subsystem : yes</PRE
|
|
><P
|
|
>Flex is only required when you're working on a check-out of the Subversion
|
|
repository. In this case Flex has to be called to transform bsdl_flex.l to
|
|
bsdl_flex.c. When you're compiling from released sources, the local Flex
|
|
version is not relevant since the output file of Flex is part of the
|
|
tarball. I.e. even if the local Flex fails the check, the BSDL subsystem is
|
|
enabled and will be compiled from the released C files.</P
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="chapter"
|
|
><HR><H1
|
|
><A
|
|
NAME="_usage"
|
|
></A
|
|
>Chapter 3. Usage</H1
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_quick_start"
|
|
>3.1. Quick start</A
|
|
></H2
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_run_the_software"
|
|
>3.1.1. Run the software</A
|
|
></H3
|
|
><P
|
|
>Connect your JTAG adapter between your PC and target device and turn
|
|
on your device.</P
|
|
><P
|
|
>To run UrJTAG type "jtag" and press Enter; jtag should start and
|
|
display some initial information. Output should end with a line like this:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>WARNING: UrJTAG may damage your hardware!
|
|
Type "quit" to exit, "help" for help.</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_configure_the_cable"
|
|
>3.1.2. Configure the cable</A
|
|
></H3
|
|
><P
|
|
>Type "help cable" for a list of supported JTAG cables.</P
|
|
><P
|
|
>Type the "cable" command followed by the cable name and possibly further
|
|
arguments for cable configuration. Example:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> cable EA253 parallel 0x378
|
|
Initializing ETC EA253 JTAG Cable on parallel port at 0x378</PRE
|
|
><P
|
|
>See the section about the "cable" command for details and USB support.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_detect_parts_on_the_jtag_chain"
|
|
>3.1.3. Detect parts on the JTAG chain</A
|
|
></H3
|
|
><P
|
|
>Type "detect" at the jtag command prompt:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> detect</PRE
|
|
><P
|
|
>Your output should look like this:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>IR length: 5
|
|
Chain length: 1
|
|
Device Id: 01011001001001100100000000010011
|
|
Manufacturer: Intel
|
|
Part: PXA250
|
|
Stepping: C0
|
|
Filename: /usr/local/share/urjtag/intel/pxa250/pxa250c0</PRE
|
|
><P
|
|
>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.</P
|
|
><P
|
|
>The "detect" command is required before all other commands.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_print_current_jtag_chain_status"
|
|
>3.1.4. Print current JTAG chain status</A
|
|
></H3
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> print chain
|
|
No. Manufacturer Part Stepping Instruction Register
|
|
---------------------------------------------------------
|
|
0 Intel PXA250 C0 BYPASS BR</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_sample_device_pin_status"
|
|
>3.1.5. Sample device pin status</A
|
|
></H3
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> instruction SAMPLE/PRELOAD
|
|
jtag> shift ir
|
|
jtag> shift dr
|
|
jtag> dr
|
|
1000110010000010000110010111111111111111111001101110...
|
|
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></PRE
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>Note: BSR is "Boundary Scan Register"</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_burn_flash_connected_to_the_part"
|
|
>3.1.6. Burn flash connected to the part</A
|
|
></H3
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> flashmem 0 brux.b
|
|
0x00000000
|
|
Note: Supported configuration is 2 x 16 bit only
|
|
BOOT_SEL: Asynchronous 32-bit ROM</PRE
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>2 x 16 bit CFI devices detected (QRY ok)!</PRE
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>program:
|
|
block 0 unlocked
|
|
erasing block 0: 0
|
|
addr: 0x00002854
|
|
verify:
|
|
addr: 0x00002854
|
|
Done.
|
|
jtag></PRE
|
|
><P
|
|
>or:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> flashmem msbin xboot.bin
|
|
Note: Supported configuration is 2 x 16 bit only
|
|
BOOT_SEL: Asynchronous 32-bit ROM</PRE
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>2 x 16 bit CFI devices detected (QRY ok)!</PRE
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>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</PRE
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>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</PRE
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>Done.
|
|
jtag></PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_non_standard_flash_commands"
|
|
>3.1.7. Non-standard flash commands</A
|
|
></H3
|
|
><P
|
|
>Erasing and programming flash devices is covered by standard procedures
|
|
in UrJTAG. Apart from these, many flash chips implement a lot more
|
|
functionality via dedicated commands that vary from between manufacturers
|
|
and device families. UrJTAG can't cover them all natively.</P
|
|
><P
|
|
>It's however possible to send any command stream to the flash by using
|
|
the poke and peek commands. You just need to clarify two things:</P
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
> base address of the flash (BA)
|
|
it's the same that's used for detectflash
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> data width, x8 or x16
|
|
defined by the width of the bus where the flash is attached
|
|
</P
|
|
></LI
|
|
></OL
|
|
><P
|
|
>Next look up the address/data pairs for the command in question. The data
|
|
sheet for your particular flash should document all commands in a table e.g.
|
|
If your flash is attached in x16 mode, the address must be shifted by one
|
|
position. Addresses in x8 mode are not affected.</P
|
|
><P
|
|
>The "Read Manufacturer ID" command in x16 mode would look like</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>poke BA+(0x555*2) 0xaa
|
|
poke BA+(0x2aa*2) 0x55
|
|
poke BA+(0x555*2) 0x90
|
|
peek BA+(0x000*2)</PRE
|
|
><P
|
|
>Note that the calculations must be done beforehand. UrJTAG can't evaluate
|
|
expressions on the command line.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_jtag_commands"
|
|
>3.2. JTAG commands</A
|
|
></H2
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_overview"
|
|
>3.2.1. Overview</A
|
|
></H3
|
|
><P
|
|
>Following is a list of commands currently supported by jtag and some
|
|
example usage.</P
|
|
><DIV
|
|
CLASS="informaltable"
|
|
><P
|
|
></P
|
|
><A
|
|
NAME="AEN442"
|
|
></A
|
|
><TABLE
|
|
BORDER="0"
|
|
FRAME="void"
|
|
RULES="none"
|
|
CLASS="CALSTABLE"
|
|
><COL
|
|
WIDTH="3*"><COL
|
|
WIDTH="7*"><TBODY
|
|
VALIGN="top"
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>bit</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> define new BSR bit
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>bus</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> change active bus
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>bsdl</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> manage BSDL files
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>cable</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> select JTAG cable
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>detect</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> detect parts on the JTAG chain
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>detectflash</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> detect parameters of flash chips attached to a part
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>discovery</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> discovery of unknown parts in the JTAG chain
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>dr</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> display or set active data register for a part
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>endian</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> set/print endianess for reading/writing binary files
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>eraseflash</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> erase flash memory by number of blocks
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>flashmem</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> burn flash memory with data from a file
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>frequency</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> setup JTAG frequency
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>get</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> get external signal value
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>help</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> display this help
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>include</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> include command sequence from external file
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>initbus</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> initialize bus driver for active part
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>instruction</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> change active instruction for a part or declare new instruction
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>part</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> change active part for current JTAG chain
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>peek</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> read a single word
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>poke</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> write a single word
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>print</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> display JTAG chain list/status
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>quit</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> exit and terminate this session
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>readmem</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> read content of the memory and write it to file
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>register</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> define new data register for a part
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>scan</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> detect changes on input pins of current part
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>set</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> set external signal value
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>shift</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> shift data/instruction registers through JTAG chain
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>signal</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> define new signal for a part
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>svf</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> execute SVF commands from file
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>writemem</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> write content from file to memory
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
></TBODY
|
|
></TABLE
|
|
><P
|
|
></P
|
|
></DIV
|
|
><P
|
|
>Some tools derived from the same openwince JTAG Tools code base as UrJTAG
|
|
know additional commands, which are not supported in UrJTAG. See the section
|
|
about "Unsupported commands", below, about workarounds.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_basic_commands"
|
|
>3.2.2. Basic commands</A
|
|
></H3
|
|
><DIV
|
|
CLASS="section"
|
|
><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_quit"
|
|
>3.2.2.1. quit</A
|
|
></H4
|
|
><P
|
|
>This command closes the jtag console.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_help"
|
|
>3.2.2.2. help</A
|
|
></H4
|
|
><P
|
|
>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:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> help cable</PRE
|
|
><P
|
|
>Most cable drivers require some more details about the cable to start properly.
|
|
To learn about the details, use the "cable" command with the name of the cable
|
|
followed by the word "help". Example:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> cable wiggler help</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_include"
|
|
>3.2.2.3. include</A
|
|
></H4
|
|
><P
|
|
>Run commands from a named script file installed with UrJTAG or applies a BSDL
|
|
file to the active part. The directory prefix is added automatically
|
|
(e.g. /usr/share/urjtag/, depending on your installation), unless the file
|
|
name starts with a dot or slash.</P
|
|
><P
|
|
>For example, the following startup sequence configures the cable, chain, and
|
|
loads definitions and bus driver for a Samsung S3C4510B CPU to peek its memory
|
|
at 0x0:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> cable wiggler ppdev /dev/parport0
|
|
jtag> detect
|
|
jtag> include samsung/s3c4510b/s3c4510b
|
|
jtag> peek 0x0000</PRE
|
|
><P
|
|
>If the file contains valid BSDL syntax, it will be converted to native
|
|
commands on the fly.</P
|
|
><P
|
|
>Optionally, a number X may be specified following the file name, to cause
|
|
an X times repetition of the command sequence from the file.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_chain_management"
|
|
>3.2.3. Chain management</A
|
|
></H3
|
|
><DIV
|
|
CLASS="section"
|
|
><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_cable"
|
|
>3.2.3.1. cable</A
|
|
></H4
|
|
><P
|
|
>Sets and initializes the cable driver. This is usually the first command that
|
|
you are executing in a session. Example:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> cable EA253 parallel 0x378
|
|
Initializing ETC EA253 JTAG Cable on parallel port at 0x378</PRE
|
|
><P
|
|
>For a parallel cable using the ppdev driver you would use this:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> cable DLC5 ppdev /dev/parport0</PRE
|
|
><P
|
|
>If you get an error, it may be that the parallel port kernel driver
|
|
was compiled as a module in your Linux kernel and wasn't loaded automatically.
|
|
Then you should try to load the ppdev driver manually (with root rights outside
|
|
the jtag shell):</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>modprobe ppdev
|
|
modprobe parport
|
|
modprobe parport_pc</PRE
|
|
><P
|
|
>UrJTAG now also supports some USB cables. Unfortunately, there is no standard
|
|
for "JTAG over USB", so this support is limited to a few selected cables only.
|
|
For cables based on the FT2232 chip from FTDI, the cable command has to be
|
|
given cable name and optionally the driver name, USB Vendor, and Product ID of
|
|
the cable:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> cable ARM-USB-OCD vid=15ba pid=0003 driver=ftdi-mpsse</PRE
|
|
><P
|
|
>For all known cables, UrJTAG knows the VID and PID so you can just say</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> cable ARM-USB-OCD</PRE
|
|
><P
|
|
>If your cable isn't detected automatically though it's listed as a known and
|
|
supported cable, feel free to report its VID and PID. It might be a different
|
|
revision and should be added to the known & tested list of cables.</P
|
|
><P
|
|
>As stated above, the driver name is not mandatory for the cable
|
|
command. UrJTAG will select the driver automatically based on UrJTAG's
|
|
configuration. In case your system provides just one of libftdi or FTD2XX
|
|
the respective driver is selected. If both libraries are available, then
|
|
FTD2XX is selected. That's simply because FTD2XX showed some performance
|
|
advantages over libftdi in the past. You can still force libftdi with the
|
|
respective parameter.</P
|
|
><DIV
|
|
CLASS="warning"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="warning"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/warning.gif"
|
|
HSPACE="5"
|
|
ALT="Warning"></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
>There's one quirk to consider when using FTDI's FTD2XX driver. It
|
|
connects to any known FTDI chip, randomly. I.e. if there's more than one FTDI
|
|
device connected to the host, chances are that the driver connects to the
|
|
wrong USB device. This might be an OEM USB-serial converter and you'll be
|
|
banging your head why there's no proper reading from the JTAG chain. Therefore
|
|
it's strongly recommended to specify the desc=xxx parameter for the cable
|
|
command if the ftd2xx driver is to be used. Set xxx to the product or serial
|
|
number descriptor string that are exhibited by the USB device.</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_detect"
|
|
>3.2.3.2. detect</A
|
|
></H4
|
|
><P
|
|
>Detects devices on the chain. Example:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>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</PRE
|
|
><P
|
|
>During "detect", UrJTAG searches through the files in its database (usually in
|
|
/usr/share/urjtag) and optionally in the search path for BSDL files (see bsdl
|
|
command) to find a match for the manufacturer, revision and part number for the
|
|
IDCODE read from the part. However, not all parts identify themselves in a way
|
|
that is useful for "detect". For example, many chips with an ARM processor core
|
|
inside present an IDCODE that may be specific to the the particular core inside
|
|
the chip (e.g. ARM7TDMI), but doesn't tell about the actual manufacturer of
|
|
the chip. In such case, the data for the part has to be included manually. See
|
|
also the documentation for the "include" command.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_print"
|
|
>3.2.3.3. print</A
|
|
></H4
|
|
><P
|
|
>Print a list of parts in the chain and the currently active instruction per part.
|
|
Further details of bus, signals and instructions can be obtained with dedicated
|
|
command options, see "help print".</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_initbus"
|
|
>3.2.3.4. initbus</A
|
|
></H4
|
|
><P
|
|
>Selects and initializes a bus of the currently selected part, e.g. the external
|
|
memory bus of a CPU. This is required in order to access chips that aren't
|
|
connected in the JTAG chain, but indirectly accessible through other chips
|
|
(e.g. CPU or programmable logic).</P
|
|
><P
|
|
>Type "help initbus" to get a list of supported bus types.
|
|
If you do not find a bus driver for your specific hardware, you might be lucky
|
|
enough to have EJTAG in your target (most MIPS-based CPUs do) and should try
|
|
the "ejtag" bus driver. In contrast to the method "via BSR", it uploads some
|
|
instructions to the CPU and triggers their execution to access the bus, and
|
|
should work with almost any EJTAG-capable chip (Note: JTAG isn't EJTAG):</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> initbus ejtag</PRE
|
|
><P
|
|
>There's another option to support new chips "via BSR", the "prototype" bus
|
|
driver, which can be adapted to support your part with command parameters.
|
|
The only prerequisite for using this driver is knowledge of the names of the
|
|
signals that represent address bus, data bus, and enable signals, and that
|
|
address and data lines are numbered in order.</P
|
|
><P
|
|
>For example, assume the signals are named in the BSDL description as follows:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> Data bus: D0, D1, … D31
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Address bus: ADDR0, ADDR1, … ADDR22
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Output Enable: nOE
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Write Enable: nWE
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Chip Select: nRCS0
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>The enable signals seem to be active low (indicated by the leading "n" in their
|
|
names). Further we assume the interesting connected part, some flash chip, is
|
|
only 16 bits wide even though the data bus width is 32 bits. With this
|
|
information, you could use the following command (all on a single line!) to
|
|
access the bus:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>initbus prototype amsb=ADDR22 alsb=ADDR0 dmsb=D15 dlsb=D0
|
|
ncs=nRCS0 nwe=nWE noe=nOE amode=x16</PRE
|
|
><P
|
|
>The "prototype" bus driver cannot deal with systems where address and data
|
|
bus are multiplexed on the same pins. If signals aren't numbered in the right
|
|
order or with gaps, you may get along by defining proper names as aliases for
|
|
the actual signals, with commands like "salias ADDR12 BSCGX44".</P
|
|
><P
|
|
>Most drivers work "via BSR", i.e. they directly access the pins of the device.
|
|
Because it isn't possible to efficiently address only particular pins but only
|
|
all at once, and data for all pins has to be transferred through JTAG for every
|
|
single change, this method isn't the fastest, but usually easiest to implement
|
|
and, well, sometimes it counts whether it works at all.</P
|
|
><P
|
|
>The "fjmem" (FPGA JTAG memory) bus driver attempts to address this issue by
|
|
moving control and observation away from BSR to a device-internal
|
|
register. For sure this is only possible on FPGAs where the designer can hook
|
|
additional logic to the JTAG chain. A core design plus examples for different
|
|
FPGA families is available in the extra/fjmem directory. Refer to the README
|
|
located there.</P
|
|
><P
|
|
>Some chips don't allow direct access to their pins via BSR at all. For these,
|
|
writing a new bus driver that utilizes a debug module to upload specific code
|
|
to access the bus is inevitable.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_bus"
|
|
>3.2.3.5. bus</A
|
|
></H4
|
|
><P
|
|
>It's possible to initialize more than one bus for part(s) within a chain. The
|
|
"bus" command allows to select the active bus for readmem, flashmem,
|
|
etc. operation.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_part_definition_commands"
|
|
>3.2.4. Part definition commands</A
|
|
></H3
|
|
><P
|
|
>The following commands are also used in the data files to define a device (IC)
|
|
on the JTAG chain. It is not recommended to use these commands in an interactive
|
|
session. Instead you should produce a device definition file out of a .bsd file
|
|
using one of the supplied tools (or use the new BSDL subsystem, see below).</P
|
|
><DIV
|
|
CLASS="informaltable"
|
|
><P
|
|
></P
|
|
><A
|
|
NAME="AEN702"
|
|
></A
|
|
><TABLE
|
|
BORDER="0"
|
|
FRAME="void"
|
|
RULES="none"
|
|
CLASS="CALSTABLE"
|
|
><COL
|
|
WIDTH="3*"><COL
|
|
WIDTH="7*"><TBODY
|
|
VALIGN="top"
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>bit</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> define new BSR bit
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>instruction</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> change active instruction for a part or declare new instruction
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>register</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> define new data register for a part
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>signal</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> define new signal for a part
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
></TBODY
|
|
></TABLE
|
|
><P
|
|
></P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_tap_control"
|
|
>3.2.5. TAP control</A
|
|
></H3
|
|
><P
|
|
>The following commands can be used to directly manipulate and display the state
|
|
of the TAP controller(s) and registers in the chain:</P
|
|
><DIV
|
|
CLASS="informaltable"
|
|
><P
|
|
></P
|
|
><A
|
|
NAME="AEN734"
|
|
></A
|
|
><TABLE
|
|
BORDER="0"
|
|
FRAME="void"
|
|
RULES="none"
|
|
CLASS="CALSTABLE"
|
|
><COL
|
|
WIDTH="3*"><COL
|
|
WIDTH="7*"><TBODY
|
|
VALIGN="top"
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>dr</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> display or set active data register for a part
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>instruction</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> change active instruction for a part or declare new instruction
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>get</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> get external signal value
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>pod</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> low level direct access to POD signals like TRST; use with care
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>scan</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> detect changes on input pins of current part
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>set</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> set external signal value
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>shift</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> shift data/instruction registers through JTAG chain
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
></TBODY
|
|
></TABLE
|
|
><P
|
|
></P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_ram_flash_access"
|
|
>3.2.6. RAM/Flash access</A
|
|
></H3
|
|
><P
|
|
>These commands can be used if a part in the chain has memory connected to it
|
|
(or integrated). Before they can be used, a bus driver has to be selected and
|
|
initialized (see initbus command).</P
|
|
><DIV
|
|
CLASS="informaltable"
|
|
><P
|
|
></P
|
|
><A
|
|
NAME="AEN784"
|
|
></A
|
|
><TABLE
|
|
BORDER="0"
|
|
FRAME="void"
|
|
RULES="none"
|
|
CLASS="CALSTABLE"
|
|
><COL
|
|
WIDTH="3*"><COL
|
|
WIDTH="7*"><TBODY
|
|
VALIGN="top"
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>detectflash</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> detect parameters of flash chips attached to a part
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>endian</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> set/print endianess for reading/writing binary files
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>eraseflash</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> erase flash memory by number of blocks
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>flashmem</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> burn flash memory with data from a file
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>peek</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> read a single word
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>poke</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> write a single word
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>readmem</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> read content of the memory and write it to file
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>writemem</B
|
|
></SPAN
|
|
>
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> write content from file to memory
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
></TBODY
|
|
></TABLE
|
|
><P
|
|
></P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_highlevel_commands"
|
|
>3.2.7. Highlevel commands</A
|
|
></H3
|
|
><DIV
|
|
CLASS="section"
|
|
><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_svf"
|
|
>3.2.7.1. svf</A
|
|
></H4
|
|
><P
|
|
>The SVF player operates on a single part in the scan chain. Therefore, you
|
|
have to bring up the JTAG software, specify a cable and detect the scan
|
|
chain beforehand.</P
|
|
><P
|
|
>The player will establish a new instruction called "SIR" and a new register
|
|
called "SDR". They are used internally by the respective SVF commands and are
|
|
reassigned with new values as the player advances through the file. It is not
|
|
recommended to use them outside of the SVF player as their content is dynamic.</P
|
|
><P
|
|
>An example session:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> cable ppdev /dev/parport0 DLC5
|
|
Initializing Xilinx DLC5 JTAG Parallel Cable III on ppdev port /dev/parport0
|
|
jtag> detect
|
|
IR length: 5
|
|
Chain length: 1
|
|
Device Id: 10010000101000100000000010010011
|
|
Manufacturer: Xilinx
|
|
Part: XC2S300E-PQ208
|
|
Stepping: 9
|
|
Filename: /usr/local/share/jtag/xilinx/xc2s300e-pq208/xc2s300e-pq208
|
|
jtag> part <desired part of the scan chain>
|
|
jtag> svf <SVF file for selected part>
|
|
jtag> instruction BYPASS
|
|
jtag> shift ir
|
|
jtag> part <next part>
|
|
jtag> svf <SVF file for selected part>
|
|
jtag> instruction BYPASS
|
|
jtag> shift ir</PRE
|
|
><P
|
|
>It is recommended to set the part's instruction register to BYPASS although
|
|
most SVF files do this at the end. By setting the instruction explicitely to
|
|
BYPASS the output of the print command will always show meaningful
|
|
information.</P
|
|
><P
|
|
>The SVF player will issue messages when situations arise that cannot be
|
|
handled. These messages are classified as warnings or errors depending on
|
|
whether the player can continue operation (warning) or not (error).
|
|
In case the TDO parameter of an SDR command leads to a mismatch the player
|
|
issues a warning and continues. If the player should abort in this case then
|
|
specify <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>stop</I
|
|
></SPAN
|
|
> at the svf command.</P
|
|
><P
|
|
>The absence of error or warning messages indicate that the SVF file was
|
|
executed without problems. To get a progress reporting while the player advances
|
|
through the SVF file, specify <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>progress</I
|
|
></SPAN
|
|
> at the svf command.</P
|
|
><TABLE
|
|
CLASS="sidebar"
|
|
BORDER="1"
|
|
CELLPADDING="5"
|
|
><TR
|
|
><TD
|
|
><DIV
|
|
CLASS="sidebar"
|
|
><A
|
|
NAME="AEN850"
|
|
></A
|
|
><P
|
|
><B
|
|
>Limitations and Deficiencies</B
|
|
></P
|
|
><P
|
|
>Several limitations exist for the SVF player.</P
|
|
><P
|
|
>The implementation of some SVF commands has deficiencies.</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> HIR, HDR commands not supported.
|
|
Their functionality should be covered by the part concept of UrJTAG.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> PIO command not supported.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> PIOMAP command not supported.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> RUNTEST SCK not supported.
|
|
The maximum time constraint is not guaranteed.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> TRST
|
|
Parameters Z and ABSENT are not supported.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> TIR, TDR commands not supported.
|
|
Their functionality should be covered by the part concept of UrJTAG.
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>SVF files for programming flash-based devices might or might not work for a given
|
|
setup. This has been observed for Actel IGLOO devices where success and failure
|
|
depends on the actual clocking rate of the chosen cable.</P
|
|
><P
|
|
>The ref_freq=<…> option to the svf command allows to tweak the calculation
|
|
of <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>RUNTEST xxx SEC</I
|
|
></SPAN
|
|
> commands. For these commands, the SVF player needs to
|
|
calculate the equivalent number of clocks and per default it will use the
|
|
current cable clock frequency. This can be overridden with the ref_freq option
|
|
that specifies a fixed reference frequency for such calculations.</P
|
|
></DIV
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_bsdl"
|
|
>3.2.7.2. bsdl</A
|
|
></H4
|
|
><P
|
|
>The <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>bsdl</I
|
|
></SPAN
|
|
> command is used to set up and test the underlying BSDL subsystem of
|
|
UrJTAG.</P
|
|
><P
|
|
>Whenever <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>detect</I
|
|
></SPAN
|
|
> encounters a new part, a configuration process is
|
|
started. This involves matching the retrieved IDCODE against the part
|
|
descriptions in /usr/share/urjtag as described above. However, before this
|
|
database is searched for a suitable description, the BSDL subsystem is started
|
|
and searches for a BSDL file that matches this device. If it finds a matching
|
|
file, traversal of the /usr/share/urjtag database is skipped. If not, then
|
|
this standard process follows.</P
|
|
><P
|
|
>To tell the BSDL subsytem where to look for BSDL files, the <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>bsdl path
|
|
pathlist</I
|
|
></SPAN
|
|
> command has to be issued prior to <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>detect</I
|
|
></SPAN
|
|
>. The contents of
|
|
<SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>pathlist</I
|
|
></SPAN
|
|
> must be a semicolon-separated list of directories where BSDL files
|
|
are located. This list is stored by <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>bsdl path</I
|
|
></SPAN
|
|
> and is used later on when
|
|
<SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>detect</I
|
|
></SPAN
|
|
> calls the BSDL subsystem.</P
|
|
><DIV
|
|
CLASS="important"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="important"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/important.gif"
|
|
HSPACE="5"
|
|
ALT="Important"></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
>The BSDL subsystem applies the first BSDL file that parses without
|
|
errors and that contains the correct IDCODE. Scanning the specified
|
|
directories happens in exactly the given order. Inside a directory however,
|
|
the order depends largely on your filesystem's behavior.</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><P
|
|
>Further details of the <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>bsdl</I
|
|
></SPAN
|
|
> command:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> bsdl path <path1>[;<path2>[;<pathN>]]
|
|
set paths for locating BSDL files
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> bsdl debug on|off
|
|
switches debug messages on or off
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> bsdl test [file]
|
|
reads file (if specified) or all files found via <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>bsdl path</I
|
|
></SPAN
|
|
> and
|
|
prints a short status, an active part is not required
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> bsdl dump [file]
|
|
reads file (if specified) or all files found via <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>bsdl path</I
|
|
></SPAN
|
|
> and
|
|
prints all configuration commands, an active part is not required
|
|
</P
|
|
></LI
|
|
></UL
|
|
><DIV
|
|
CLASS="tip"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="tip"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/tip.gif"
|
|
HSPACE="5"
|
|
ALT="Tip"></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
>The <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>bsdl dump file</I
|
|
></SPAN
|
|
> command implements the same functionality as
|
|
bsdl2jtag.</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_unsupported_commands"
|
|
>3.2.8. Unsupported commands</A
|
|
></H3
|
|
><DIV
|
|
CLASS="section"
|
|
><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_script"
|
|
>3.2.8.1. script</A
|
|
></H4
|
|
><P
|
|
>Although it's still there, its functionality has been merged into the include
|
|
command. Please use "include" instead.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_setdevice"
|
|
>3.2.8.2. setdevice</A
|
|
></H4
|
|
><P
|
|
>This command was only there to support the SHARC 21065L processor,
|
|
which has no IDCODE and therefore can't be initialized correctly by
|
|
just running "detect". However, the proper initialization can be done
|
|
after "detect" by loading the proper declarations and bus driver manually:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>jtag> include analog/sharc21065l/sharc21065l</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_spiflashmem"
|
|
>3.2.8.3. spiflashmem</A
|
|
></H4
|
|
><P
|
|
>The commands "spidetectflash", "spiflashmem", "spireadflash" and
|
|
"spieraseflash" only exist in a version of the JTAG tools copyrighted by
|
|
Intratrade Ltd., we just know about them from a posting on the net.</P
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="chapter"
|
|
><HR><H1
|
|
><A
|
|
NAME="_internals"
|
|
></A
|
|
>Chapter 4. Internals</H1
|
|
><P
|
|
>This section is only a placeholder for the information that will
|
|
be added soon…</P
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_files"
|
|
>4.1. Files</A
|
|
></H2
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_source_code_overview"
|
|
>4.1.1. Source code Overview</A
|
|
></H3
|
|
><DIV
|
|
CLASS="informaltable"
|
|
><P
|
|
></P
|
|
><A
|
|
NAME="AEN919"
|
|
></A
|
|
><TABLE
|
|
BORDER="0"
|
|
FRAME="void"
|
|
RULES="none"
|
|
CLASS="CALSTABLE"
|
|
><COL
|
|
WIDTH="3*"><COL
|
|
WIDTH="7*"><TBODY
|
|
VALIGN="top"
|
|
><TR
|
|
><TD
|
|
><P
|
|
> doc/
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> Documentation
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> data/
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> Part descriptions (data files)
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> include/
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> C header files
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> src/
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> C source code
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> src/bsdl
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> BSDL subsystem
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> src/bus
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> Bus driver for various CPUs and other parts
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> src/cmd
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> Implementation of the commands for the "jtag" shell
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> src/flash
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> Flash detection and programming algorithms
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> src/jim
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> JIM, the JTAG target simulator
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> src/lib
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> Utility functions
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> src/part
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> Functions for accessing specific parts in a chain
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> src/svf
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> SVF player
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
><P
|
|
> src/tap
|
|
</P
|
|
></TD
|
|
><TD
|
|
> <P
|
|
> Functions for accessing the chain in general
|
|
</P
|
|
>
|
|
</TD
|
|
></TR
|
|
></TBODY
|
|
></TABLE
|
|
><P
|
|
></P
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_drivers"
|
|
>4.2. Drivers</A
|
|
></H2
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> Cable drivers
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Link drivers
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> TAP drivers
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Chain drivers
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Bus drivers
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Flash drivers
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Commands
|
|
</P
|
|
></LI
|
|
></UL
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_cable_specific_drivers_src_tap_cable"
|
|
>4.2.1. Cable-specific drivers (src/tap/cable)</A
|
|
></H3
|
|
><P
|
|
>Cable-specific drivers are those which are visible to the user through
|
|
the "jtag" command shell. They're listed in response to the "help cable"
|
|
command. Each driver has to provide the following functions:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> connect(), init() - Initialization
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> done(), cable_free(), disconnect() - Cleaning up
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> set_frequency() - set bitrate for shifting data through the chain
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> clock(), get_tdo(), transfer() - immediate JTAG activities
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> flush() - internally used to actually perform JTAG activities
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> help() - a help text to be displayed by the jtag command shell
|
|
</P
|
|
></LI
|
|
></UL
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_initialization"
|
|
>4.2.1.1. Initialization</A
|
|
></H4
|
|
><P
|
|
>After allocating a "cable_t" structure, a pointer to it and further
|
|
parameters (as strings) have to be passed first to the selected cable's
|
|
connect() function.</P
|
|
><P
|
|
>Following that, the init() function is called via cable_init(). If cable_init()
|
|
returns a zero value, all is fine and the cable is ready for use.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_cleaning_up"
|
|
>4.2.1.2. Cleaning up</A
|
|
></H4
|
|
><P
|
|
>There are two functions for actual cleanup:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> done() is responsible for driving the hardware to a safe and consistent state.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> cable_free() then can be used to clean up eventually extra allocated memory etc.
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>Both are usually called from chain_disconnect().</P
|
|
><P
|
|
>An additional mechanism allows to clean up if a disconnection was detected by
|
|
the low level driver (e.g. USB or parallel port driver). A cable has to provide
|
|
a disconnect() function for this purpose:</P
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
> Low level (e.g. parport) driver calls cable driver->disconnect()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> cable driver->disconnect() calls chain_disconnect()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> chain_disconnect() calls cable driver->done()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> chain_disconnect() then calls cable driver->cable_free()
|
|
</P
|
|
></LI
|
|
></OL
|
|
><P
|
|
>After return from chain_disconnect() to cable driver->disconnect(), the cable_t
|
|
structure has been freed and must not be accessed anymore.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_jtag_activities"
|
|
>4.2.1.3. JTAG Activities</A
|
|
></H4
|
|
><P
|
|
>Currently the API provides five different functions for performing operations
|
|
at the JTAG interface on the low level signal level (using the four signals
|
|
TMS, TCK, TDI, and TDO).</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> clock(tms,tdi,n) takes values for TMS and TDI output as its parameters, ensures that actual cable signals are set accordingly, and does a 0-1 transition on TCK (n times)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> get_tdo() returns the current value at the TDO input.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> set_trst(x) sets the TRST signal and returns the current value.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> get_trst() returns the current value of the TRST signal.
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>For many JTAG adapters, there's almost no delay when doing alternating clock()
|
|
and get_tdo(). Writing and reading happens immediately and the result is
|
|
available immediately as well. This is the case with most parallel port
|
|
adapters (but not when attached to USB-to-parallel adapters or USB docking
|
|
stations) and memory mapped IO (e.g. general purpose I/O pins of
|
|
microcontrollers).</P
|
|
><P
|
|
>But there are adapters, especially USB and Ethernet based adapters, which
|
|
exhibit a rather long delay between the initiation of reading a bit and the
|
|
delivery of the value of the bit. It is at least 1 millisecond with USB,
|
|
which would limit the transfer rate to 1 kHz. One way to workaround this
|
|
is to transmit bits compacted into bytes and chunks of bytes, which is
|
|
possible with the transfer() function.</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> transfer(in, out)
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>The transfer() function does a series of TCK pulses, with data for TDI read as
|
|
bytes from memory. The bytes are automatically serialized. TMS is set to zero
|
|
during transfer()s. Optionally, prior to each bit shifted out to the interface,
|
|
TDO input can be read into memory (deserialized into a byte array of the same
|
|
size as the input array).</P
|
|
><P
|
|
>It still doesn't yield much improvement if the operation consists of many read
|
|
and write transitions (e.g. repeatedly writing an instruction and some data
|
|
register values, then reading from the data register, as it is necessary for
|
|
memory access). For that reason, the above functions are also available in
|
|
variants that don't cause immediate activity, but rather schedule it for later.
|
|
In the API, they're visible as</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> cable_defer_clock()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> cable_defer_get_tdo()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> cable_defer_set_trst()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> cable_defer_get_trst()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> cable_defer_transfer()
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>These functions aren't implemented in the cable driver (but currently in
|
|
src/tap/cable.c). The cable driver just has to provide a flush() function to
|
|
actually execute the queued activity in some cable-specific optimal way, and
|
|
to store the results of get_tdo() and transfer() activity. The caller later
|
|
can pick up the results using these functions (implemented in cable.c):</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> cable_get_tdo_late()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> cable_get_trst_late()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> cable_transfer_late()
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>As an example, consider the following sequence of activities:</P
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
> clock()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> get_tdo()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> clock()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> get_tdo()
|
|
</P
|
|
></LI
|
|
></OL
|
|
><P
|
|
>If the result of the first get_tdo() isn't absolutely required before the
|
|
second clock(), the sequence can be optimized into the following sequence (if</P
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
> defer_clock()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> defer_clock()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> flush()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> get_tdo_late()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> get_tdo_late()
|
|
</P
|
|
></LI
|
|
></OL
|
|
><P
|
|
>The next sections explain the queueing mechanism and its limits in detail.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_when_flushing_occurs"
|
|
>4.2.1.4. When flushing occurs</A
|
|
></H4
|
|
><P
|
|
>The cable_flush() function is used to flush the queue towards the cable. It
|
|
takes one additional argument, "how_much", which may be one of</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> OPTIONALLY: The cable driver may flush if it's reasonable (e.g. if the
|
|
queue has been filled so that some buffer limit for the cable interface
|
|
is reached). It would be wise to flush early to keep the queue small, if
|
|
there is no point in queueing up more items because the transfer to the
|
|
cable would have to be split into smaller chunks anyway. This is used by
|
|
UrJTAG immediately after adding items to the queue.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> TO_OUTPUT: The cable driver should at least flush as much so that one
|
|
output becomes available in the output queue. If there's already something
|
|
in the output queue, this should be interpreted similar to OPTIONALLY. This
|
|
is used by UrJTAG immediately before it wants to use that output.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> COMPLETELY: The cable driver has to flush the queue completely. This is
|
|
used by UrJTAG immediately before actions that circumvent the queueing
|
|
such as calls to the legacy clock/get_tdo functions. It could also be
|
|
used by application code to ensure that some action is actually done in
|
|
time.
|
|
</P
|
|
></LI
|
|
></UL
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_jtag_activity_queueing"
|
|
>4.2.1.5. JTAG activity queueing</A
|
|
></H4
|
|
><P
|
|
>The source in src/tap/cable.c provides to important functions to access the
|
|
two queues "todo" (with activity to be done) and "done" (with results):</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> cable_add_queue_item
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> cable_get_queue_item
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>In src/tap/cable/generic.c you'll find two implementations of dequeueing
|
|
algorithms, i.e. implementations of the flush() function. These could be used
|
|
by any new cable driver unless it provides a more sophisticated algorithm
|
|
itself:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> generic_flush_one_by_one() simply calls the "classic" functions one after
|
|
another. The performance of the cable driver using this implementation will
|
|
be the same whether the immediate or defer variants of the functions are used.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> generic_flush_using_transfer() tries to optimize as many clock() and
|
|
get_tdo() by transforming them into calls to transfer() instead. This can
|
|
give a slight advantage.
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>The generic implementations also serve as a template for new cable-specific
|
|
implementations.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_generic_implementations"
|
|
>4.2.1.6. Generic implementations</A
|
|
></H4
|
|
><P
|
|
>As a reference and in many cases completely sufficient for new cables, take a
|
|
look at the code in src/tap/cable/generic.c, which contains generic routines,
|
|
suitable for parallel port based cables (and some for other types of cables as
|
|
well).</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_link_drivers"
|
|
>4.2.2. Link drivers</A
|
|
></H3
|
|
><P
|
|
>Link drivers like the "parport" driver collection provide the basis for
|
|
communication between cable driver and actual JTAG adapter. The openwince JTAG
|
|
tools supported only parallel port links with the "parport" drivers. UrJTAG
|
|
introduced support for USB links, but in the early releases the drivers for
|
|
these just mimic the parallel port links.</P
|
|
><P
|
|
>The basic functions provided by all link drivers are</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> connect(), to called from cable driver connect()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> open(), to actually connect to the device during cable driver init()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> close(), to disconnect from the device during cable driver done()
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> free(), to free all resources, called from cable driver free()
|
|
</P
|
|
></LI
|
|
></UL
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_parport"
|
|
>4.2.2.1. parport</A
|
|
></H4
|
|
><P
|
|
>Currently there are parport drivers for direct access to the parallel port on a
|
|
PC using I/O addresses (direct.c), and for using ppdev on Linux or ppi on FreeBSD.</P
|
|
><P
|
|
>In addition, there are "ftdi" and "ftd2xx" parport drivers that actually are for
|
|
communication with USB cables based on FTDI chips. They cannot be used for
|
|
connecting old parallel port cables through parallel to USB adapters with FTDI
|
|
chips, and probably soon will be rewritten as "usbconn" drivers instead.</P
|
|
><P
|
|
>All parport drivers present a common API for setting and reading signals.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_usbconn"
|
|
>4.2.2.2. usbconn</A
|
|
></H4
|
|
><P
|
|
>The usbconn drivers provide a common API to search for and connect with USB
|
|
devices. At the moment, there are drivers for libusd, libftdi and FTD2XX
|
|
(e.g. to communicate with FTDI chip based cables through libftdi and/or
|
|
FTD2XX, to communicate with Cypress FX2 using EZUSB.SYS or CyUSB.sys, and
|
|
more).</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_bus_drivers"
|
|
>4.2.3. Bus drivers</A
|
|
></H3
|
|
><P
|
|
>Bus drivers translate read and write operations on a bus into JTAG commands
|
|
and methods. A bus in this context is neither restricted to a processor bus,
|
|
nor to memory. Any system component that can be read from and written to could
|
|
be seen as attached to a bus. I.e. external or internal memory (RAM, ROM,
|
|
Flash) and peripherals connected to a processor or simply an FPGA with 1:1
|
|
connections.</P
|
|
><P
|
|
>The available bus drivers are listed in response to "help initbus". Each
|
|
driver has to provide the following functions:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> bus_new() - Initialization
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> bus_free() - Cleaning up
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> bus_printinfo() - Short description
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> bus_prepare() - Preparation
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> bus_area() - Description of the bus geometry
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> bus_read_start() - Initiate reading
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> bus_read_next() - Read access
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> bus_read_end() - Finish reading
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> bus_read() - Atomic reading
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> bus_write() - Write access
|
|
</P
|
|
></LI
|
|
></UL
|
|
><DIV
|
|
CLASS="important"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="important"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/important.gif"
|
|
HSPACE="5"
|
|
ALT="Important"></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
>Address parameters to the functions listed above specify always
|
|
byte locations, independent of the actual data width. The bus driver has to
|
|
adjust the address on its own if required.</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_creation"
|
|
>4.2.3.1. Creation</A
|
|
></H4
|
|
><P
|
|
>Upon calling of its bus_new() function, the driver allocates a "bus_t"
|
|
structure and performs all required internal initializations.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_initialization_2"
|
|
>4.2.3.2. Initialization</A
|
|
></H4
|
|
><P
|
|
>After creation of the new "bus_t" structure, the bus_init() function will
|
|
be called to give the driver the possibility to initialize it's internal
|
|
states or BSR bits as required. Such functionality has been split from
|
|
bus_new() since some drivers require to re-initialize during runtime.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_cleaning_up_2"
|
|
>4.2.3.3. Cleaning up</A
|
|
></H4
|
|
><P
|
|
>The driver is supposed to free all allocated memory (including its "bus_t"
|
|
structure). Additionally, it should set the device into a state that doesn't
|
|
prevent it from normal operation.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_short_description"
|
|
>4.2.3.4. Short description</A
|
|
></H4
|
|
><P
|
|
>Prints a message describing the driver. This function is called by the "print"
|
|
command before it lists the areas covered by this bus driver.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_preparation"
|
|
>4.2.3.5. Preparation</A
|
|
></H4
|
|
><P
|
|
>This function is called whenever a bus operation is initiated. The
|
|
driver should perform the required preparation steps so that
|
|
subsequent calls to the bus_read_* and bus_write functions can perform
|
|
their tasks properly.</P
|
|
><P
|
|
>E.g. a BSR bus driver would put the device into EXTEST mode to activate the
|
|
boundary scan register on the device pins.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_description_of_the_bus_geometry"
|
|
>4.2.3.6. Description of the bus geometry</A
|
|
></H4
|
|
><P
|
|
>At certain stages, the bus driver's bus_area() function is called by other
|
|
commands to query the bus geometry for a given address. The bus driver must
|
|
fill in the fields of a "bus_area_t" structure describing the geometry of the
|
|
area in which the specified address is located:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> a short textual description of the area
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> start address of area
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> length of area in bytes
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> data width in bits
|
|
</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>Queries with an address out of range must result in an area length of</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>UINT64_C(0x100000000)</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_initiate_reading"
|
|
>4.2.3.7. Initiate reading</A
|
|
></H4
|
|
><P
|
|
>Since the JTAG state machine defines a capture-shift-update sequence, it is
|
|
required to shift the address for a read prior to capturing the read
|
|
data. Therefore, the bus_read_start() function is called with the very first
|
|
address to read from. This enables the driver to shift the address into the
|
|
device before it can actually retrieve the read data for this address.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_read_access"
|
|
>4.2.3.8. Read access</A
|
|
></H4
|
|
><P
|
|
>The bus_read_next() function fetches the read data from the device that has
|
|
been addressed by a previous call to bus_read_start() or
|
|
bus_read_next(). Again, this is due to the capture-shift-update sequence of
|
|
JTAG:</P
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
> capture read data from device pins
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> shift new address
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> update new address to device pins
|
|
</P
|
|
></LI
|
|
></OL
|
|
><DIV
|
|
CLASS="important"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="important"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/important.gif"
|
|
HSPACE="5"
|
|
ALT="Important"></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
>The address parameter specifies the location of the <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>following</I
|
|
></SPAN
|
|
>
|
|
read access. It is not the address of the data returned by this function call.</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_finish_reading"
|
|
>4.2.3.9. Finish reading</A
|
|
></H4
|
|
><P
|
|
>Function "bus_read_end()" is called at the end of a read sequence. I.e. when
|
|
the higher level command determines that the last data portion is to be read
|
|
from the device. There is no new address and the function driver is supposed
|
|
to return the read data that was addressed previously.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_atomic_reading"
|
|
>4.2.3.10. Atomic reading</A
|
|
></H4
|
|
><P
|
|
>For ease of use, a bus driver has to supply a "bus_read()" function that
|
|
encapsulates reading data from a single address in an atomic operation. Bus
|
|
drivers typically build this function from "bus_read_start()" and a subsequent
|
|
"bus_read_end()".</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_write_access"
|
|
>4.2.3.11. Write access</A
|
|
></H4
|
|
><P
|
|
>This function writes one data element at the specified address. Since this
|
|
translates to a single JTAG operation (capture ignored, shift and update
|
|
address & data), there is no splitting as with the read functions.</P
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_data_file_format"
|
|
>4.3. Data file format</A
|
|
></H2
|
|
><P
|
|
>JTAG declarations files are located in directory "data". The files contains
|
|
common part specific JTAG information in parseable form, e.g. list of the JTAG
|
|
commands, boundary scan register, list of JTAG registers, etc.</P
|
|
><P
|
|
>Syntax of the JTAG declaration file is defined in the following subsections.</P
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_general_rules"
|
|
>4.3.1. General rules</A
|
|
></H3
|
|
><P
|
|
>JTAG declaration file is text file which consists of lines. Empty lines are
|
|
ignored. Text after first "#" on the line to the end of line is ignored. This
|
|
is useful for comments. All other lines are significant.</P
|
|
><P
|
|
>Each significant line consists of tokens separated by whitespace. Whitespace
|
|
could be spaces and/or tabs.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_signal_definition"
|
|
>4.3.2. Signal Definition</A
|
|
></H3
|
|
><P
|
|
>Signal definition line consists of word "signal" followed by whitespace and
|
|
signal name (without spaces in the name). Rest of the line should contain
|
|
whitespace separated list of pins of the part. This list is currently not used
|
|
for any purpose in JTAG Tools. It is intended for future use.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_manufacturers_list"
|
|
>4.3.3. Manufacturers List</A
|
|
></H3
|
|
><P
|
|
>The <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>data/MANUFACTURERS</I
|
|
></SPAN
|
|
> file is used to locate the manufacturer of a specific
|
|
device found in the JTAG chain. If you get the error <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>Unknown manufacturer</B
|
|
></SPAN
|
|
>
|
|
when attempting the <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>detect</I
|
|
></SPAN
|
|
> command, this is the file you need to update.</P
|
|
><P
|
|
>See the JEDEC document for more information:
|
|
JEDEC Solid State Technology Association, "Standard Manufacturer's
|
|
Identification Code", September 2001, Order Number: JEP106-K</P
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_format"
|
|
>4.3.3.1. Format</A
|
|
></H4
|
|
><P
|
|
>The first token is a bit string that matches bits 11-1 of the device's IDCODE.
|
|
We omit bit 0 because it should always be 1 (per the JEDEC standard).</P
|
|
><P
|
|
>The second token is the name of the directory under <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>data/</I
|
|
></SPAN
|
|
> to search for
|
|
specific part information.</P
|
|
><P
|
|
>The rest of the line is the human readable form of the manufacturer's name.</P
|
|
><P
|
|
>For example, we find this in <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>data/MANUFACTURERS</I
|
|
></SPAN
|
|
>:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>00001100101 analog Analog Devices, Inc.</PRE
|
|
><P
|
|
>The manufacturer's IDCODE is <TT
|
|
CLASS="literal"
|
|
>000011001011</TT
|
|
> (notice the last bit is stripped),
|
|
more part information can be found under <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>data/analog/</I
|
|
></SPAN
|
|
>, and the human friendly
|
|
name is <TT
|
|
CLASS="literal"
|
|
>Analog Devices, Inc.</TT
|
|
>.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_parts_list"
|
|
>4.3.4. Parts List</A
|
|
></H3
|
|
><P
|
|
>Every manufacturer subdirectory needs a <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>PARTS</I
|
|
></SPAN
|
|
> file. This is used to look
|
|
up further information about a part such as the stepping and signal list. If
|
|
you get the error <SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>Unknown part</B
|
|
></SPAN
|
|
> when attempting the <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>detect</I
|
|
></SPAN
|
|
> command, this is
|
|
the file you need to update.</P
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_format_2"
|
|
>4.3.4.1. Format</A
|
|
></H4
|
|
><P
|
|
>The first token is a bit string that matches bits 27-12 of the device's IDCODE.</P
|
|
><P
|
|
>The second token is the name of the directory under the manufacturer's <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>data/</I
|
|
></SPAN
|
|
>
|
|
directory to search for specific part information.</P
|
|
><P
|
|
>The rest of the line is the human readable form of the part's name.</P
|
|
><P
|
|
>For example, we find this in <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>data/analog/PARTS</I
|
|
></SPAN
|
|
>:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>0010011111001000 bf537 BF537</PRE
|
|
><P
|
|
>The part's IDCODE is <TT
|
|
CLASS="literal"
|
|
>0010011111001000</TT
|
|
>, more part information can be found
|
|
under <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>data/analog/bf537/</I
|
|
></SPAN
|
|
>, and the human friendly name is <TT
|
|
CLASS="literal"
|
|
>BF537</TT
|
|
>.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_stepping_list"
|
|
>4.3.5. Stepping List</A
|
|
></H3
|
|
><P
|
|
>Every part subdirectory needs a <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>STEPPINGS</I
|
|
></SPAN
|
|
> file. This is used to find the
|
|
file that contains information like the signals list. If you get the error
|
|
<SPAN
|
|
CLASS="strong"
|
|
><B
|
|
CLASS="emphasis"
|
|
>Unknown stepping</B
|
|
></SPAN
|
|
> when attempting the <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>detect</I
|
|
></SPAN
|
|
> command, this is the file you
|
|
need to update.</P
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="_format_3"
|
|
>4.3.5.1. Format</A
|
|
></H4
|
|
><P
|
|
>The first token is a bit string that matches bits 31-28 of the device's IDCODE.</P
|
|
><P
|
|
>The second token is the name of the file to load that contains information like
|
|
the signal list, extra instructions/registers, etc… This file should be
|
|
placed alongside the <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>STEPPINGS</I
|
|
></SPAN
|
|
> file in the part-specific subdirectory.</P
|
|
><P
|
|
>The rest of the line is the human readable form of the part stepping's name.</P
|
|
><P
|
|
>For example, we find this in <SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>data/analog/bf537/STEPPINGS</I
|
|
></SPAN
|
|
>:</P
|
|
><PRE
|
|
CLASS="literallayout"
|
|
>0010 bf537 2</PRE
|
|
><P
|
|
>The part's stepping is <TT
|
|
CLASS="literal"
|
|
>0010</TT
|
|
>, signal information can be found in the file
|
|
<SPAN
|
|
CLASS="emphasis"
|
|
><I
|
|
CLASS="emphasis"
|
|
>data/analog/bf537/bf537</I
|
|
></SPAN
|
|
>, and the human friendly stepping name is <TT
|
|
CLASS="literal"
|
|
>2</TT
|
|
>.</P
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_development"
|
|
>4.4. Development</A
|
|
></H2
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_future_plans"
|
|
>4.4.1. Future Plans</A
|
|
></H3
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> C API and library package
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Bindings for Python, Perl, …
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> TCP/IP access
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> New cable drivers
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> …
|
|
</P
|
|
></LI
|
|
></UL
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="_how_to_contribute"
|
|
>4.4.2. How to contribute</A
|
|
></H3
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> Using Subversion
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Create and submit a patch
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Use SourceForge trackers
|
|
</P
|
|
></LI
|
|
></UL
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="chapter"
|
|
><HR><H1
|
|
><A
|
|
NAME="_f_a_q"
|
|
></A
|
|
>Chapter 5. F.A.Q.</H1
|
|
><P
|
|
>For a list of known problems in current versions, please also check the "Bugs"
|
|
tracker at the UrJTAG website!</P
|
|
><P
|
|
></P
|
|
><DIV
|
|
CLASS="variablelist"
|
|
><DL
|
|
><DT
|
|
>Q. The documentation is incomplete. Where can I get more information?</DT
|
|
><DD
|
|
><P
|
|
> A. Please ask in the "Using UrJTAG" Forum on <A
|
|
HREF="http://urjtag.org"
|
|
TARGET="_top"
|
|
>http://urjtag.org</A
|
|
>
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. My flash isn't detected or can't be programmed. What can I do?</DT
|
|
><DD
|
|
><P
|
|
> A. Please record the output of the "detect" and "detectflash" commands and ask in the Forum. If possible, re-compile UrJTAG before with "—enable-jedec-exp" to get extra information.
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. My CPU/FPGA/etc. chip isn't detected. What can I do?</DT
|
|
><DD
|
|
><P
|
|
> A. First try to get hold of a "BSDL" description of the chip from the vendor, and specify where to find this file to UrJTAG using "bsdl path" before you "detect". Second, a bus driver has to be selected. Maybe "ejtag" or "prototype" work.
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. When I type "cable parallel 0x378 DLC5" (in a Cygwin environment) I get "Unknown port driver: parallel"?</DT
|
|
><DD
|
|
><P
|
|
> A. Please install the Cygwin ioperm package, and re-configure/compile.
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. When I type "cable parallel 0x378 DLC5" (in a Cygwin environment) I get "Error: Cable initialization failed!".</DT
|
|
><DD
|
|
><P
|
|
> A. Please install ioperm.sys driver using <TT
|
|
CLASS="literal"
|
|
>ioperm -i</TT
|
|
> command.
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. When running autogen.sh, I get "Can't exec "autopoint": No such file or directory"</DT
|
|
><DD
|
|
><P
|
|
> A. You need the headers for gettext (e.g. Debian package "gettext-devel").
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. When running autogen.sh, it complains about missing CVS</DT
|
|
><DD
|
|
><P
|
|
> A. The easiest solution is to actually install CVS for this step, just to get around this error message.
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. During compilation, I get "svf_bison.y: No such file or directory"</DT
|
|
><DD
|
|
><P
|
|
> A. You need "bison".
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. During compilation, I get "flex: can't open … src/svf/svf_flex.l"</DT
|
|
><DD
|
|
><P
|
|
> A. You need "flex"
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. During compilation, I get "src/svf/svf_flex.l", line 27: unrecognized %option: bison-locations"</DT
|
|
><DD
|
|
><P
|
|
> A. 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. The distributed
|
|
source tarball contains source pregenerated with a current flex version,
|
|
you need flex yourself only to compile from fresh SVN checkouts.
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. When running "make install", I get "Permission denied" errors</DT
|
|
><DD
|
|
><P
|
|
> A. If you want to install into a system directory (the default /usr/local is one), you'll have to run "make install" as the superuser, e.g. do "sudo make install".
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. My BSDL file defines the bus DAT as bit_vector(15 downto 0), how should I access single elements?</DT
|
|
><DD
|
|
><P
|
|
> A. BSDL syntax is an extension of the VHDL language. Array elements are indexed with
|
|
parentheses: DAT(4) selects index number 4 of the DAT vector. Also refer to the "print
|
|
signals" command.
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. My board requires certain signals to be set to dedicated values before external memories can be accessed.</DT
|
|
><DD
|
|
><P
|
|
> A. Most (if not all) BSR-based bus drivers allow for static configurations of
|
|
pins that are controlled by BSR bits. Apply the required "set" commands before
|
|
issueing the "initbus …" command. These settings are preserved by all bus
|
|
related commands if they don't collide with the signals required for bus operation.
|
|
</P
|
|
></DD
|
|
><DT
|
|
>Q. My USB pod seems slow.</DT
|
|
><DD
|
|
><P
|
|
> A. USB-based JTAG pods suffer from a couple of intrinsic issues. Consider the
|
|
following to get maximum performance:
|
|
</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> Run UrJTAG on native linux. Cygwin and VMWare are reportedly slower.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Connect the pod via a high speed USB hub to a high speed USB host port.
|
|
Even though the pod is a full speed device, it benefits from the shorter
|
|
turn-around times between host and hub.
|
|
</P
|
|
></LI
|
|
></UL
|
|
></DD
|
|
></DL
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="chapter"
|
|
><HR><H1
|
|
><A
|
|
NAME="_licensing"
|
|
></A
|
|
>Chapter 6. Licensing</H1
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_overview_2"
|
|
>6.1. Overview</A
|
|
></H2
|
|
><P
|
|
>Various licenses are used for the UrJTAG project. The GPL is used for most
|
|
of the code except for some include files, JIM, and cable driver source, where
|
|
a BSD or MIT license is used; this is noted in the file headers.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_gnu_free_documentation_license_fdl"
|
|
>6.2. GNU Free Documentation License (FDL)</A
|
|
></H2
|
|
><PRE
|
|
CLASS="literallayout"
|
|
> GNU Free Documentation License
|
|
Version 1.2, November 2002
|
|
|
|
|
|
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
|
|
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
of this license document, but changing it is not allowed.
|
|
|
|
|
|
0. PREAMBLE
|
|
|
|
The purpose of this License is to make a manual, textbook, or other
|
|
functional and useful document "free" in the sense of freedom: to
|
|
assure everyone the effective freedom to copy and redistribute it,
|
|
with or without modifying it, either commercially or noncommercially.
|
|
Secondarily, this License preserves for the author and publisher a way
|
|
to get credit for their work, while not being considered responsible
|
|
for modifications made by others.
|
|
|
|
This License is a kind of "copyleft", which means that derivative
|
|
works of the document must themselves be free in the same sense. It
|
|
complements the GNU General Public License, which is a copyleft
|
|
license designed for free software.
|
|
|
|
We have designed this License in order to use it for manuals for free
|
|
software, because free software needs free documentation: a free
|
|
program should come with manuals providing the same freedoms that the
|
|
software does. But this License is not limited to software manuals;
|
|
it can be used for any textual work, regardless of subject matter or
|
|
whether it is published as a printed book. We recommend this License
|
|
principally for works whose purpose is instruction or reference.
|
|
|
|
|
|
1. APPLICABILITY AND DEFINITIONS
|
|
|
|
This License applies to any manual or other work, in any medium, that
|
|
contains a notice placed by the copyright holder saying it can be
|
|
distributed under the terms of this License. Such a notice grants a
|
|
world-wide, royalty-free license, unlimited in duration, to use that
|
|
work under the conditions stated herein. The "Document", below,
|
|
refers to any such manual or work. Any member of the public is a
|
|
licensee, and is addressed as "you". You accept the license if you
|
|
copy, modify or distribute the work in a way requiring permission
|
|
under copyright law.
|
|
|
|
A "Modified Version" of the Document means any work containing the
|
|
Document or a portion of it, either copied verbatim, or with
|
|
modifications and/or translated into another language.
|
|
|
|
A "Secondary Section" is a named appendix or a front-matter section of
|
|
the Document that deals exclusively with the relationship of the
|
|
publishers or authors of the Document to the Document's overall subject
|
|
(or to related matters) and contains nothing that could fall directly
|
|
within that overall subject. (Thus, if the Document is in part a
|
|
textbook of mathematics, a Secondary Section may not explain any
|
|
mathematics.) The relationship could be a matter of historical
|
|
connection with the subject or with related matters, or of legal,
|
|
commercial, philosophical, ethical or political position regarding
|
|
them.
|
|
|
|
The "Invariant Sections" are certain Secondary Sections whose titles
|
|
are designated, as being those of Invariant Sections, in the notice
|
|
that says that the Document is released under this License. If a
|
|
section does not fit the above definition of Secondary then it is not
|
|
allowed to be designated as Invariant. The Document may contain zero
|
|
Invariant Sections. If the Document does not identify any Invariant
|
|
Sections then there are none.
|
|
|
|
The "Cover Texts" are certain short passages of text that are listed,
|
|
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
|
|
the Document is released under this License. A Front-Cover Text may
|
|
be at most 5 words, and a Back-Cover Text may be at most 25 words.
|
|
|
|
A "Transparent" copy of the Document means a machine-readable copy,
|
|
represented in a format whose specification is available to the
|
|
general public, that is suitable for revising the document
|
|
straightforwardly with generic text editors or (for images composed of
|
|
pixels) generic paint programs or (for drawings) some widely available
|
|
drawing editor, and that is suitable for input to text formatters or
|
|
for automatic translation to a variety of formats suitable for input
|
|
to text formatters. A copy made in an otherwise Transparent file
|
|
format whose markup, or absence of markup, has been arranged to thwart
|
|
or discourage subsequent modification by readers is not Transparent.
|
|
An image format is not Transparent if used for any substantial amount
|
|
of text. A copy that is not "Transparent" is called "Opaque".
|
|
|
|
Examples of suitable formats for Transparent copies include plain
|
|
ASCII without markup, Texinfo input format, LaTeX input format, SGML
|
|
or XML using a publicly available DTD, and standard-conforming simple
|
|
HTML, PostScript or PDF designed for human modification. Examples of
|
|
transparent image formats include PNG, XCF and JPG. Opaque formats
|
|
include proprietary formats that can be read and edited only by
|
|
proprietary word processors, SGML or XML for which the DTD and/or
|
|
processing tools are not generally available, and the
|
|
machine-generated HTML, PostScript or PDF produced by some word
|
|
processors for output purposes only.
|
|
|
|
The "Title Page" means, for a printed book, the title page itself,
|
|
plus such following pages as are needed to hold, legibly, the material
|
|
this License requires to appear in the title page. For works in
|
|
formats which do not have any title page as such, "Title Page" means
|
|
the text near the most prominent appearance of the work's title,
|
|
preceding the beginning of the body of the text.
|
|
|
|
A section "Entitled XYZ" means a named subunit of the Document whose
|
|
title either is precisely XYZ or contains XYZ in parentheses following
|
|
text that translates XYZ in another language. (Here XYZ stands for a
|
|
specific section name mentioned below, such as "Acknowledgements",
|
|
"Dedications", "Endorsements", or "History".) To "Preserve the Title"
|
|
of such a section when you modify the Document means that it remains a
|
|
section "Entitled XYZ" according to this definition.
|
|
|
|
The Document may include Warranty Disclaimers next to the notice which
|
|
states that this License applies to the Document. These Warranty
|
|
Disclaimers are considered to be included by reference in this
|
|
License, but only as regards disclaiming warranties: any other
|
|
implication that these Warranty Disclaimers may have is void and has
|
|
no effect on the meaning of this License.
|
|
|
|
|
|
2. VERBATIM COPYING
|
|
|
|
You may copy and distribute the Document in any medium, either
|
|
commercially or noncommercially, provided that this License, the
|
|
copyright notices, and the license notice saying this License applies
|
|
to the Document are reproduced in all copies, and that you add no other
|
|
conditions whatsoever to those of this License. You may not use
|
|
technical measures to obstruct or control the reading or further
|
|
copying of the copies you make or distribute. However, you may accept
|
|
compensation in exchange for copies. If you distribute a large enough
|
|
number of copies you must also follow the conditions in section 3.
|
|
|
|
You may also lend copies, under the same conditions stated above, and
|
|
you may publicly display copies.
|
|
|
|
|
|
3. COPYING IN QUANTITY
|
|
|
|
If you publish printed copies (or copies in media that commonly have
|
|
printed covers) of the Document, numbering more than 100, and the
|
|
Document's license notice requires Cover Texts, you must enclose the
|
|
copies in covers that carry, clearly and legibly, all these Cover
|
|
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
|
|
the back cover. Both covers must also clearly and legibly identify
|
|
you as the publisher of these copies. The front cover must present
|
|
the full title with all words of the title equally prominent and
|
|
visible. You may add other material on the covers in addition.
|
|
Copying with changes limited to the covers, as long as they preserve
|
|
the title of the Document and satisfy these conditions, can be treated
|
|
as verbatim copying in other respects.
|
|
|
|
If the required texts for either cover are too voluminous to fit
|
|
legibly, you should put the first ones listed (as many as fit
|
|
reasonably) on the actual cover, and continue the rest onto adjacent
|
|
pages.
|
|
|
|
If you publish or distribute Opaque copies of the Document numbering
|
|
more than 100, you must either include a machine-readable Transparent
|
|
copy along with each Opaque copy, or state in or with each Opaque copy
|
|
a computer-network location from which the general network-using
|
|
public has access to download using public-standard network protocols
|
|
a complete Transparent copy of the Document, free of added material.
|
|
If you use the latter option, you must take reasonably prudent steps,
|
|
when you begin distribution of Opaque copies in quantity, to ensure
|
|
that this Transparent copy will remain thus accessible at the stated
|
|
location until at least one year after the last time you distribute an
|
|
Opaque copy (directly or through your agents or retailers) of that
|
|
edition to the public.
|
|
|
|
It is requested, but not required, that you contact the authors of the
|
|
Document well before redistributing any large number of copies, to give
|
|
them a chance to provide you with an updated version of the Document.
|
|
|
|
|
|
4. MODIFICATIONS
|
|
|
|
You may copy and distribute a Modified Version of the Document under
|
|
the conditions of sections 2 and 3 above, provided that you release
|
|
the Modified Version under precisely this License, with the Modified
|
|
Version filling the role of the Document, thus licensing distribution
|
|
and modification of the Modified Version to whoever possesses a copy
|
|
of it. In addition, you must do these things in the Modified Version:
|
|
|
|
A. Use in the Title Page (and on the covers, if any) a title distinct
|
|
from that of the Document, and from those of previous versions
|
|
(which should, if there were any, be listed in the History section
|
|
of the Document). You may use the same title as a previous version
|
|
if the original publisher of that version gives permission.
|
|
B. List on the Title Page, as authors, one or more persons or entities
|
|
responsible for authorship of the modifications in the Modified
|
|
Version, together with at least five of the principal authors of the
|
|
Document (all of its principal authors, if it has fewer than five),
|
|
unless they release you from this requirement.
|
|
C. State on the Title page the name of the publisher of the
|
|
Modified Version, as the publisher.
|
|
D. Preserve all the copyright notices of the Document.
|
|
E. Add an appropriate copyright notice for your modifications
|
|
adjacent to the other copyright notices.
|
|
F. Include, immediately after the copyright notices, a license notice
|
|
giving the public permission to use the Modified Version under the
|
|
terms of this License, in the form shown in the Addendum below.
|
|
G. Preserve in that license notice the full lists of Invariant Sections
|
|
and required Cover Texts given in the Document's license notice.
|
|
H. Include an unaltered copy of this License.
|
|
I. Preserve the section Entitled "History", Preserve its Title, and add
|
|
to it an item stating at least the title, year, new authors, and
|
|
publisher of the Modified Version as given on the Title Page. If
|
|
there is no section Entitled "History" in the Document, create one
|
|
stating the title, year, authors, and publisher of the Document as
|
|
given on its Title Page, then add an item describing the Modified
|
|
Version as stated in the previous sentence.
|
|
J. Preserve the network location, if any, given in the Document for
|
|
public access to a Transparent copy of the Document, and likewise
|
|
the network locations given in the Document for previous versions
|
|
it was based on. These may be placed in the "History" section.
|
|
You may omit a network location for a work that was published at
|
|
least four years before the Document itself, or if the original
|
|
publisher of the version it refers to gives permission.
|
|
K. For any section Entitled "Acknowledgements" or "Dedications",
|
|
Preserve the Title of the section, and preserve in the section all
|
|
the substance and tone of each of the contributor acknowledgements
|
|
and/or dedications given therein.
|
|
L. Preserve all the Invariant Sections of the Document,
|
|
unaltered in their text and in their titles. Section numbers
|
|
or the equivalent are not considered part of the section titles.
|
|
M. Delete any section Entitled "Endorsements". Such a section
|
|
may not be included in the Modified Version.
|
|
N. Do not retitle any existing section to be Entitled "Endorsements"
|
|
or to conflict in title with any Invariant Section.
|
|
O. Preserve any Warranty Disclaimers.
|
|
|
|
If the Modified Version includes new front-matter sections or
|
|
appendices that qualify as Secondary Sections and contain no material
|
|
copied from the Document, you may at your option designate some or all
|
|
of these sections as invariant. To do this, add their titles to the
|
|
list of Invariant Sections in the Modified Version's license notice.
|
|
These titles must be distinct from any other section titles.
|
|
|
|
You may add a section Entitled "Endorsements", provided it contains
|
|
nothing but endorsements of your Modified Version by various
|
|
parties--for example, statements of peer review or that the text has
|
|
been approved by an organization as the authoritative definition of a
|
|
standard.
|
|
|
|
You may add a passage of up to five words as a Front-Cover Text, and a
|
|
passage of up to 25 words as a Back-Cover Text, to the end of the list
|
|
of Cover Texts in the Modified Version. Only one passage of
|
|
Front-Cover Text and one of Back-Cover Text may be added by (or
|
|
through arrangements made by) any one entity. If the Document already
|
|
includes a cover text for the same cover, previously added by you or
|
|
by arrangement made by the same entity you are acting on behalf of,
|
|
you may not add another; but you may replace the old one, on explicit
|
|
permission from the previous publisher that added the old one.
|
|
|
|
The author(s) and publisher(s) of the Document do not by this License
|
|
give permission to use their names for publicity for or to assert or
|
|
imply endorsement of any Modified Version.
|
|
|
|
|
|
5. COMBINING DOCUMENTS
|
|
|
|
You may combine the Document with other documents released under this
|
|
License, under the terms defined in section 4 above for modified
|
|
versions, provided that you include in the combination all of the
|
|
Invariant Sections of all of the original documents, unmodified, and
|
|
list them all as Invariant Sections of your combined work in its
|
|
license notice, and that you preserve all their Warranty Disclaimers.
|
|
|
|
The combined work need only contain one copy of this License, and
|
|
multiple identical Invariant Sections may be replaced with a single
|
|
copy. If there are multiple Invariant Sections with the same name but
|
|
different contents, make the title of each such section unique by
|
|
adding at the end of it, in parentheses, the name of the original
|
|
author or publisher of that section if known, or else a unique number.
|
|
Make the same adjustment to the section titles in the list of
|
|
Invariant Sections in the license notice of the combined work.
|
|
|
|
In the combination, you must combine any sections Entitled "History"
|
|
in the various original documents, forming one section Entitled
|
|
"History"; likewise combine any sections Entitled "Acknowledgements",
|
|
and any sections Entitled "Dedications". You must delete all sections
|
|
Entitled "Endorsements".
|
|
|
|
|
|
6. COLLECTIONS OF DOCUMENTS
|
|
|
|
You may make a collection consisting of the Document and other documents
|
|
released under this License, and replace the individual copies of this
|
|
License in the various documents with a single copy that is included in
|
|
the collection, provided that you follow the rules of this License for
|
|
verbatim copying of each of the documents in all other respects.
|
|
|
|
You may extract a single document from such a collection, and distribute
|
|
it individually under this License, provided you insert a copy of this
|
|
License into the extracted document, and follow this License in all
|
|
other respects regarding verbatim copying of that document.
|
|
|
|
|
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
|
|
|
A compilation of the Document or its derivatives with other separate
|
|
and independent documents or works, in or on a volume of a storage or
|
|
distribution medium, is called an "aggregate" if the copyright
|
|
resulting from the compilation is not used to limit the legal rights
|
|
of the compilation's users beyond what the individual works permit.
|
|
When the Document is included in an aggregate, this License does not
|
|
apply to the other works in the aggregate which are not themselves
|
|
derivative works of the Document.
|
|
|
|
If the Cover Text requirement of section 3 is applicable to these
|
|
copies of the Document, then if the Document is less than one half of
|
|
the entire aggregate, the Document's Cover Texts may be placed on
|
|
covers that bracket the Document within the aggregate, or the
|
|
electronic equivalent of covers if the Document is in electronic form.
|
|
Otherwise they must appear on printed covers that bracket the whole
|
|
aggregate.
|
|
|
|
|
|
8. TRANSLATION
|
|
|
|
Translation is considered a kind of modification, so you may
|
|
distribute translations of the Document under the terms of section 4.
|
|
Replacing Invariant Sections with translations requires special
|
|
permission from their copyright holders, but you may include
|
|
translations of some or all Invariant Sections in addition to the
|
|
original versions of these Invariant Sections. You may include a
|
|
translation of this License, and all the license notices in the
|
|
Document, and any Warranty Disclaimers, provided that you also include
|
|
the original English version of this License and the original versions
|
|
of those notices and disclaimers. In case of a disagreement between
|
|
the translation and the original version of this License or a notice
|
|
or disclaimer, the original version will prevail.
|
|
|
|
If a section in the Document is Entitled "Acknowledgements",
|
|
"Dedications", or "History", the requirement (section 4) to Preserve
|
|
its Title (section 1) will typically require changing the actual
|
|
title.
|
|
|
|
|
|
9. TERMINATION
|
|
|
|
You may not copy, modify, sublicense, or distribute the Document except
|
|
as expressly provided for under this License. Any other attempt to
|
|
copy, modify, sublicense or distribute the Document is void, and will
|
|
automatically terminate your rights under this License. However,
|
|
parties who have received copies, or rights, from you under this
|
|
License will not have their licenses terminated so long as such
|
|
parties remain in full compliance.
|
|
|
|
|
|
10. FUTURE REVISIONS OF THIS LICENSE
|
|
|
|
The Free Software Foundation may publish new, revised versions
|
|
of the GNU Free Documentation License from time to time. Such new
|
|
versions will be similar in spirit to the present version, but may
|
|
differ in detail to address new problems or concerns. See
|
|
http://www.gnu.org/copyleft/.
|
|
|
|
Each version of the License is given a distinguishing version number.
|
|
If the Document specifies that a particular numbered version of this
|
|
License "or any later version" applies to it, you have the option of
|
|
following the terms and conditions either of that specified version or
|
|
of any later version that has been published (not as a draft) by the
|
|
Free Software Foundation. If the Document does not specify a version
|
|
number of this License, you may choose any version ever published (not
|
|
as a draft) by the Free Software Foundation.
|
|
|
|
|
|
ADDENDUM: How to use this License for your documents
|
|
|
|
To use this License in a document you have written, include a copy of
|
|
the License in the document and put the following copyright and
|
|
license notices just after the title page:
|
|
|
|
Copyright (c) YEAR YOUR NAME.
|
|
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;
|
|
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
|
|
A copy of the license is included in the section entitled "GNU
|
|
Free Documentation License".
|
|
|
|
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
|
|
replace the "with...Texts." line with this:
|
|
|
|
with the Invariant Sections being LIST THEIR TITLES, with the
|
|
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
|
|
|
|
If you have Invariant Sections without Cover Texts, or some other
|
|
combination of the three, merge those two alternatives to suit the
|
|
situation.
|
|
|
|
If your document contains nontrivial examples of program code, we
|
|
recommend releasing these examples in parallel under your choice of
|
|
free software license, such as the GNU General Public License,
|
|
to permit their use in free software.</PRE
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><HR><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="_gnu_general_public_license_gpl"
|
|
>6.3. GNU General Public License (GPL)</A
|
|
></H2
|
|
><PRE
|
|
CLASS="literallayout"
|
|
> GNU GENERAL PUBLIC LICENSE
|
|
Version 2, June 1991
|
|
|
|
Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
|
|
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
of this license document, but changing it is not allowed.
|
|
|
|
Preamble
|
|
|
|
The licenses for most software are designed to take away your
|
|
freedom to share and change it. By contrast, the GNU General Public
|
|
License is intended to guarantee your freedom to share and change free
|
|
software--to make sure the software is free for all its users. This
|
|
General Public License applies to most of the Free Software
|
|
Foundation's software and to any other program whose authors commit to
|
|
using it. (Some other Free Software Foundation software is covered by
|
|
the GNU Lesser General Public License instead.) You can apply it to
|
|
your programs, too.
|
|
|
|
When we speak of free software, we are referring to freedom, not
|
|
price. Our General Public Licenses are designed to make sure that you
|
|
have the freedom to distribute copies of free software (and charge for
|
|
this service if you wish), that you receive source code or can get it
|
|
if you want it, that you can change the software or use pieces of it
|
|
in new free programs; and that you know you can do these things.
|
|
|
|
To protect your rights, we need to make restrictions that forbid
|
|
anyone to deny you these rights or to ask you to surrender the rights.
|
|
These restrictions translate to certain responsibilities for you if you
|
|
distribute copies of the software, or if you modify it.
|
|
|
|
For example, if you distribute copies of such a program, whether
|
|
gratis or for a fee, you must give the recipients all the rights that
|
|
you have. You must make sure that they, too, receive or can get the
|
|
source code. And you must show them these terms so they know their
|
|
rights.
|
|
|
|
We protect your rights with two steps: (1) copyright the software, and
|
|
(2) offer you this license which gives you legal permission to copy,
|
|
distribute and/or modify the software.
|
|
|
|
Also, for each author's protection and ours, we want to make certain
|
|
that everyone understands that there is no warranty for this free
|
|
software. If the software is modified by someone else and passed on, we
|
|
want its recipients to know that what they have is not the original, so
|
|
that any problems introduced by others will not reflect on the original
|
|
authors' reputations.
|
|
|
|
Finally, any free program is threatened constantly by software
|
|
patents. We wish to avoid the danger that redistributors of a free
|
|
program will individually obtain patent licenses, in effect making the
|
|
program proprietary. To prevent this, we have made it clear that any
|
|
patent must be licensed for everyone's free use or not licensed at all.
|
|
|
|
The precise terms and conditions for copying, distribution and
|
|
modification follow.
|
|
|
|
GNU GENERAL PUBLIC LICENSE
|
|
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
|
|
|
|
0. This License applies to any program or other work which contains
|
|
a notice placed by the copyright holder saying it may be distributed
|
|
under the terms of this General Public License. The "Program", below,
|
|
refers to any such program or work, and a "work based on the Program"
|
|
means either the Program or any derivative work under copyright law:
|
|
that is to say, a work containing the Program or a portion of it,
|
|
either verbatim or with modifications and/or translated into another
|
|
language. (Hereinafter, translation is included without limitation in
|
|
the term "modification".) Each licensee is addressed as "you".
|
|
|
|
Activities other than copying, distribution and modification are not
|
|
covered by this License; they are outside its scope. The act of
|
|
running the Program is not restricted, and the output from the Program
|
|
is covered only if its contents constitute a work based on the
|
|
Program (independent of having been made by running the Program).
|
|
Whether that is true depends on what the Program does.
|
|
|
|
1. You may copy and distribute verbatim copies of the Program's
|
|
source code as you receive it, in any medium, provided that you
|
|
conspicuously and appropriately publish on each copy an appropriate
|
|
copyright notice and disclaimer of warranty; keep intact all the
|
|
notices that refer to this License and to the absence of any warranty;
|
|
and give any other recipients of the Program a copy of this License
|
|
along with the Program.
|
|
|
|
You may charge a fee for the physical act of transferring a copy, and
|
|
you may at your option offer warranty protection in exchange for a fee.
|
|
|
|
2. You may modify your copy or copies of the Program or any portion
|
|
of it, thus forming a work based on the Program, and copy and
|
|
distribute such modifications or work under the terms of Section 1
|
|
above, provided that you also meet all of these conditions:
|
|
|
|
a) You must cause the modified files to carry prominent notices
|
|
stating that you changed the files and the date of any change.
|
|
|
|
b) You must cause any work that you distribute or publish, that in
|
|
whole or in part contains or is derived from the Program or any
|
|
part thereof, to be licensed as a whole at no charge to all third
|
|
parties under the terms of this License.
|
|
|
|
c) If the modified program normally reads commands interactively
|
|
when run, you must cause it, when started running for such
|
|
interactive use in the most ordinary way, to print or display an
|
|
announcement including an appropriate copyright notice and a
|
|
notice that there is no warranty (or else, saying that you provide
|
|
a warranty) and that users may redistribute the program under
|
|
these conditions, and telling the user how to view a copy of this
|
|
License. (Exception: if the Program itself is interactive but
|
|
does not normally print such an announcement, your work based on
|
|
the Program is not required to print an announcement.)
|
|
|
|
These requirements apply to the modified work as a whole. If
|
|
identifiable sections of that work are not derived from the Program,
|
|
and can be reasonably considered independent and separate works in
|
|
themselves, then this License, and its terms, do not apply to those
|
|
sections when you distribute them as separate works. But when you
|
|
distribute the same sections as part of a whole which is a work based
|
|
on the Program, the distribution of the whole must be on the terms of
|
|
this License, whose permissions for other licensees extend to the
|
|
entire whole, and thus to each and every part regardless of who wrote it.
|
|
|
|
Thus, it is not the intent of this section to claim rights or contest
|
|
your rights to work written entirely by you; rather, the intent is to
|
|
exercise the right to control the distribution of derivative or
|
|
collective works based on the Program.
|
|
|
|
In addition, mere aggregation of another work not based on the Program
|
|
with the Program (or with a work based on the Program) on a volume of
|
|
a storage or distribution medium does not bring the other work under
|
|
the scope of this License.
|
|
|
|
3. You may copy and distribute the Program (or a work based on it,
|
|
under Section 2) in object code or executable form under the terms of
|
|
Sections 1 and 2 above provided that you also do one of the following:
|
|
|
|
a) Accompany it with the complete corresponding machine-readable
|
|
source code, which must be distributed under the terms of Sections
|
|
1 and 2 above on a medium customarily used for software interchange; or,
|
|
|
|
b) Accompany it with a written offer, valid for at least three
|
|
years, to give any third party, for a charge no more than your
|
|
cost of physically performing source distribution, a complete
|
|
machine-readable copy of the corresponding source code, to be
|
|
distributed under the terms of Sections 1 and 2 above on a medium
|
|
customarily used for software interchange; or,
|
|
|
|
c) Accompany it with the information you received as to the offer
|
|
to distribute corresponding source code. (This alternative is
|
|
allowed only for noncommercial distribution and only if you
|
|
received the program in object code or executable form with such
|
|
an offer, in accord with Subsection b above.)
|
|
|
|
The source code for a work means the preferred form of the work for
|
|
making modifications to it. For an executable work, complete source
|
|
code means all the source code for all modules it contains, plus any
|
|
associated interface definition files, plus the scripts used to
|
|
control compilation and installation of the executable. However, as a
|
|
special exception, the source code distributed need not include
|
|
anything that is normally distributed (in either source or binary
|
|
form) with the major components (compiler, kernel, and so on) of the
|
|
operating system on which the executable runs, unless that component
|
|
itself accompanies the executable.
|
|
|
|
If distribution of executable or object code is made by offering
|
|
access to copy from a designated place, then offering equivalent
|
|
access to copy the source code from the same place counts as
|
|
distribution of the source code, even though third parties are not
|
|
compelled to copy the source along with the object code.
|
|
|
|
4. You may not copy, modify, sublicense, or distribute the Program
|
|
except as expressly provided under this License. Any attempt
|
|
otherwise to copy, modify, sublicense or distribute the Program is
|
|
void, and will automatically terminate your rights under this License.
|
|
However, parties who have received copies, or rights, from you under
|
|
this License will not have their licenses terminated so long as such
|
|
parties remain in full compliance.
|
|
|
|
5. You are not required to accept this License, since you have not
|
|
signed it. However, nothing else grants you permission to modify or
|
|
distribute the Program or its derivative works. These actions are
|
|
prohibited by law if you do not accept this License. Therefore, by
|
|
modifying or distributing the Program (or any work based on the
|
|
Program), you indicate your acceptance of this License to do so, and
|
|
all its terms and conditions for copying, distributing or modifying
|
|
the Program or works based on it.
|
|
|
|
6. Each time you redistribute the Program (or any work based on the
|
|
Program), the recipient automatically receives a license from the
|
|
original licensor to copy, distribute or modify the Program subject to
|
|
these terms and conditions. You may not impose any further
|
|
restrictions on the recipients' exercise of the rights granted herein.
|
|
You are not responsible for enforcing compliance by third parties to
|
|
this License.
|
|
|
|
7. If, as a consequence of a court judgment or allegation of patent
|
|
infringement or for any other reason (not limited to patent issues),
|
|
conditions are imposed on you (whether by court order, agreement or
|
|
otherwise) that contradict the conditions of this License, they do not
|
|
excuse you from the conditions of this License. If you cannot
|
|
distribute so as to satisfy simultaneously your obligations under this
|
|
License and any other pertinent obligations, then as a consequence you
|
|
may not distribute the Program at all. For example, if a patent
|
|
license would not permit royalty-free redistribution of the Program by
|
|
all those who receive copies directly or indirectly through you, then
|
|
the only way you could satisfy both it and this License would be to
|
|
refrain entirely from distribution of the Program.
|
|
|
|
If any portion of this section is held invalid or unenforceable under
|
|
any particular circumstance, the balance of the section is intended to
|
|
apply and the section as a whole is intended to apply in other
|
|
circumstances.
|
|
|
|
It is not the purpose of this section to induce you to infringe any
|
|
patents or other property right claims or to contest validity of any
|
|
such claims; this section has the sole purpose of protecting the
|
|
integrity of the free software distribution system, which is
|
|
implemented by public license practices. Many people have made
|
|
generous contributions to the wide range of software distributed
|
|
through that system in reliance on consistent application of that
|
|
system; it is up to the author/donor to decide if he or she is willing
|
|
to distribute software through any other system and a licensee cannot
|
|
impose that choice.
|
|
|
|
This section is intended to make thoroughly clear what is believed to
|
|
be a consequence of the rest of this License.
|
|
|
|
8. If the distribution and/or use of the Program is restricted in
|
|
certain countries either by patents or by copyrighted interfaces, the
|
|
original copyright holder who places the Program under this License
|
|
may add an explicit geographical distribution limitation excluding
|
|
those countries, so that distribution is permitted only in or among
|
|
countries not thus excluded. In such case, this License incorporates
|
|
the limitation as if written in the body of this License.
|
|
|
|
9. The Free Software Foundation may publish revised and/or new versions
|
|
of the General Public License from time to time. Such new versions will
|
|
be similar in spirit to the present version, but may differ in detail to
|
|
address new problems or concerns.
|
|
|
|
Each version is given a distinguishing version number. If the Program
|
|
specifies a version number of this License which applies to it and "any
|
|
later version", you have the option of following the terms and conditions
|
|
either of that version or of any later version published by the Free
|
|
Software Foundation. If the Program does not specify a version number of
|
|
this License, you may choose any version ever published by the Free Software
|
|
Foundation.
|
|
|
|
10. If you wish to incorporate parts of the Program into other free
|
|
programs whose distribution conditions are different, write to the author
|
|
to ask for permission. For software which is copyrighted by the Free
|
|
Software Foundation, write to the Free Software Foundation; we sometimes
|
|
make exceptions for this. Our decision will be guided by the two goals
|
|
of preserving the free status of all derivatives of our free software and
|
|
of promoting the sharing and reuse of software generally.
|
|
|
|
NO WARRANTY
|
|
|
|
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
|
|
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
|
|
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
|
|
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
|
|
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
|
|
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
|
|
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
|
|
REPAIR OR CORRECTION.
|
|
|
|
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
|
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
|
|
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
|
|
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
|
|
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
|
|
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
|
|
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
|
|
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
|
|
POSSIBILITY OF SUCH DAMAGES.
|
|
|
|
END OF TERMS AND CONDITIONS
|
|
|
|
How to Apply These Terms to Your New Programs
|
|
|
|
If you develop a new program, and you want it to be of the greatest
|
|
possible use to the public, the best way to achieve this is to make it
|
|
free software which everyone can redistribute and change under these terms.
|
|
|
|
To do so, attach the following notices to the program. It is safest
|
|
to attach them to the start of each source file to most effectively
|
|
convey the exclusion of warranty; and each file should have at least
|
|
the "copyright" line and a pointer to where the full notice is found.
|
|
|
|
<one line to give the program's name and a brief idea of what it does.>
|
|
Copyright (C) <year> <name of author>
|
|
|
|
This program is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 2 of the License, or
|
|
(at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License along
|
|
with this program; if not, write to the Free Software Foundation, Inc.,
|
|
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
|
|
Also add information on how to contact you by electronic and paper mail.
|
|
|
|
If the program is interactive, make it output a short notice like this
|
|
when it starts in an interactive mode:
|
|
|
|
Gnomovision version 69, Copyright (C) year name of author
|
|
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
|
|
This is free software, and you are welcome to redistribute it
|
|
under certain conditions; type `show c' for details.
|
|
|
|
The hypothetical commands `show w' and `show c' should show the appropriate
|
|
parts of the General Public License. Of course, the commands you use may
|
|
be called something other than `show w' and `show c'; they could even be
|
|
mouse-clicks or menu items--whatever suits your program.
|
|
|
|
You should also get your employer (if you work as a programmer) or your
|
|
school, if any, to sign a "copyright disclaimer" for the program, if
|
|
necessary. Here is a sample; alter the names:
|
|
|
|
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
|
|
`Gnomovision' (which makes passes at compilers) written by James Hacker.
|
|
|
|
<signature of Ty Coon>, 1 April 1989
|
|
Ty Coon, President of Vice
|
|
|
|
This General Public License does not permit incorporating your program into
|
|
proprietary programs. If your program is a subroutine library, you may
|
|
consider it more useful to permit linking proprietary applications with the
|
|
library. If this is what you want to do, use the GNU Lesser General
|
|
Public License instead of this License.</PRE
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |