xc3sprog.1

'\" t
.\" ** The above line should force tbl to be a preprocessor **
.\"
.\" Man page for XC3Sprog
.\"
.\" Copyright (C) 2011 Joris van Rantwijk, ...
.\"
.\" This manpage 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.
.\"
.TH XC3SPROG 1 "2011-09-04"
.nh

.SH NAME
xc3sprog \- JTAG programming utility for Xilinx FPGAs and PROMs
.SH SYNOPSIS
.B xc3sprog
.B \-c
.I cable
.RI [\| options \|]
.I file1spec
.RI [\| file2spec \ ...\|]
.br
.B xc3sprog
.B \-c
.I cable
.RI [\| options \|]
.B \-j

.SH DESCRIPTION
.B xc3sprog
is a command-line tool for programming FPGAs, microcontrollers and PROMs via JTAG.

In a typical application, \fBxc3sprog\fR reads a .BIT file generated by an
FPGA design tool, and programs it into the PROM chip on an FPGA board for
persistant storage or the configuration RAM of a FPGA for temporary storage.
For other use cases, see the section \fBEXAMPLES\fR below.

As its name indicates, \fBxc3sprog\fR was originally designed for Xilinx Spartan-3 FPGAs.
However, it has been extended to handle several other types of devices
including Xilinx FPGAs, CPLDs, XCF flash PROMs, Atmel AVRs and SPI flash chips.
\fBxc3sprog\fR supports several JTAG cables, including parallel port cables and USB programmers.

.SH OPTIONS

.TP
\fB\-c\fR \fIcable\fR
Specify the type of JTAG cable.
The specified type, \fIcable\fR refers to a label in the cable database.
.br
Common cable types are \fBpp\fR (parallel port cable),
\fBxpc\fR (Xilinx USB programmer), and
\fBftdi\fR (FTDI-based USB programmer).

.TP
.B \-j
Detect the JTAG chain and print a list of attached devices.
This is the default if no other action is specified.

.TP
\fB\-p\fR \fIval\fR[,\fIval\fR,...]
Use device at JTAG chain position \fIval\fR, default is position 0,
the device connected to the TDO pin of the JTAG cable.
Use this option to select a device from a multi-device JTAG chain.

If multiple chain positions are specified, the data file will be split,
programming the first part of the file into the first specified device
and so on. This is useful for boards which a chain of multiple XCF chips to
configure a single FPGA.

.TP
\fB\-T\fR\fIn\fR
Test the JTAG chain \fIn\fR times.
When running in ISF mode, test the SPI connection.
.br
If \fIn\fR is not specified, the default is to test 10000 times.
.br
If \fIn\fR = 0, keep testing forever.

.TP
\fB\-J\fR \fIfreq\fR
Run at the specified JTAG clock frequency (\fIfreq\fR in Hz).
If not specified, or if \fIfreq\fR = 0, the default is to run at the
maximum frequency supported by the cable.
.br
Currently only supported for FTDI-based cables.

.TP
.B \-e
Erase the entire device.

.TP
\fB\-I\fR[\fIfile\fR]
Work in ISF mode to program an internal serial flash memory.
The flash memory is attached to the primary JTAG target, but not directly
accessible via the JTAG chain.
The primary JTAG target is used as a proxy to forward SPI transactions
to the flash memory.
If \fIfile\fR is specified, start by programming the specified bitfile into
the primary JTAG target (typically an FPGA).

.TP
.B \-R
Send a reconfiguration command to the target device (XCV, XCF, XCFP for
reconfiguration of the connected FPGA device or XC3S, XC6S, XC2V direct)

.TP
\fB\-m\fR \fImapdir\fR
Search for XC2C map files in the specified directory.
Map files are required to handle JEDEC files during CPLD programming.
If not specified, defaults to the value of \fB$XC_MAPDIR\fR.

.TP
\fB\-d\fR \fI/dev/parportN\fR
Specify the parallel port device to be used.
If not specified, defaults to the value of \fB$XCPORT\fR or \fI/dev/parport0\fR.
.br
Only used for cable type \fBpp\fR.

.TP
\fB\-s\fR \fIserialnum\fR
Use the USB device with the specified serial number string. Needed if
several adapters of the same type are connected at the same time.

.TP
.B \-L
Use libFTD2XX instead of libftdi to access FTDI-based cables.

.TP
.B \-D
Dump the device database and cable database to files \fIdevlist.txt\fR and
\fIcablelist.txt\fR in the current directory. If a file already exists,
xc3sprog tries to generate a unique name by appending an increasing number.


.TP
.B \-v
Enable verbose output.

.TP
.B \-h
Print a help text.

.SH "ACTION SPECIFICATION"

One or more programming actions may be specified.
Each action consists of a filename, optionally followed by attributes
in the form
<\fIfilename\fR:\fIaction\fR:\fIoffset\fR:\fIstyle\fR:\fIlength\fR>.

.TP 4
.I filename
The file to be written to the device, or the file in which to store
data after reading from the device.

.TP
.I action
One letter indicating whether to write, read, or verify the device.
If not specified, the default action is 'w'.
.TS
tab (@);
l l.
w@Erase, then write data from file to device and verify.
W@Write with auto-sector erase, then verify.
v@Verify device against file.
r@Read from device and write to file (no overwriting).
R@Read from device and write to file, overwriting existing files.
.TE

.TP
.I offset
The byte offset inside the device where programming/reading should start.
Only supported for SPI, XCFnnS devices and XMEGA.

.TP
.I style
The format of the specified file.

.TS
tab (@);
l lw(56).
BIT@T{
Xilinx \.BIT file format.
Default for FPGA, XCF and SPI devices.
T}
BIN@Raw binary file.
MCS@Xilinx .MCS file format.
IHEX@T{
Intel HEX format.
Also used by Xilinx PROMGEN when writing MCS files.
Default for XMEGA devices.
T}
HEXRAW@Raw sequence of hexadecimal digits.
JEDEC@Default for CPLD devices.
.TE

.TP
.I length
The number of bytes to program/read.
Only supported for SPI, XCFnnS and XMEGA devices.

.SH "DEVICE DATABASE"

The device database contains a list of supported JTAG devices.
When \fBxc3sprog\fR starts, it scans the JTAG chain to discover
all attached devices.
A device database is used to map the 32-bit ID codes of the devices
to descriptive names and get basic knowledge how to handle the part, at
minimum how to skip it. 

A default device database is compiled into the \fBxc3sprog\fR executable.
The database is tried to be loaded from a file at run time.  If the
environment variable \fB$XCDB\fR is defined, it specifies the name of the
device database file, otherwise the file \fIdevlist.txt\fR is read from the
current directory.  If a database file is not found at all, the internal
compile-time database will be used.

If a device is not yet know, the builtin list can be dumped, the information
on the unknown part added and on the next run the new list will be read and used.

.SH "CABLE DATABASE"

The cable database contains a list of supported JTAG cables.
Each cable type is identified by a short label,
such as \fBpp\fR, \fBftdijtag\fR, or \fBxpc\fR.
The database maps the label to parameters to be used to access the hardware
of the cable.

A default cable database is compiled into the \fBxc3sprog\fR executable.
The database is tried to be loaded from a file at run time.  If the
environment variable \fB$CABLEDB\fR is defined, it specifies the name of the
cable database file, otherwise the file \fIcablelist.txt\fR is read from the
current directory.  If a database file is not found at all, the internal
compile-time database will be used.

If a cable subtype (e.g. different VID/PID) is not yet know, the builtin
list can be dumped, the information on the new cable added and on the next
run the new list will be read and used.

The database contains a line for each nown cable. The line consists of the
alias for that cable to used with the \-c option, the basic type of the
cable, the maximum allowed JTAG frequency of the cable and an optional
option string.

For FTDI devices the option string contains the USB vendor ID (VID), USB
product ID (PID), the USB device description string, the FTDI channel of the
JTAG interface and eventual commands for setting other pins beside the JTAG
pins. e.g. to switch on some buffers. If the JTAG device uses a FTDI default
VID/PID, the USB device description string is important to destinguish your
JTAG device from other eventual connected FTDI devices with the same VID/PID

.SH EXAMPLES

.TP 4
.B xc3sprog \-c pp \-j
Show a list of JTAG devices attached to the parallel port JTAG cable.

.TP
\fBxc3sprog\fR \fB\-c\fR \fBftdijtag\fR \fB\-v\fR \fB\-p\fR 0 \fIdesign.bit\fR
Program the specified bitfile into the first device (position 0) in the JTAG chain.
Use an FTDI-based USB JTAG cable.
Show detailed progress information.

.TP
.B xc3sprog \-c ftidjtag \-T
Test the integrity of the JTAG chain.

.TP
\fBxc3sprog\fR \fB\-c\fR \fBxpc\fR \fB\-p\fR 1 \fIdump.bit\fR\fB:r\fR
Read the contents from the JTAG device in position 1 in the chain,
and write the data as a Xilinx .BIT file.
Use a Xilinx USB programmer.

.TP
\fBxc3sprog\fR \fB\-c\fR \fIcable\fR \fB\-I\fR\fIbscan_spi/xc3s50an.bit\fR \fIdesign.bit\fR
Load \fIxc3s50an.bit\fR into the FPGA in position 0 in the JTAG chain.
Then, program \fIdesign.bit\fR into the ISF memory in the FPGA.

.TP
\fBxc3sprog\fR \fB\-c\fR \fIcable\fR \fB\-I\fR \fIimage.bit\fR\fB:w:\fR0x10000
Program the image file into the SPI memory attached to the FPGA, starting
at byte offset 0x10000.
An appropriate bscan_spi file must already be loaded in the FPGA,
so that it will act as a bridge between the JTAG cable and SPI bus.

.SH ENVIRONMENT

.TP
.B XCDB
Name of the file to use as device database.
The default is \fIdevlist.txt\fR in the current directory.

.TP
.B CABLEDB
Name of the file to use as cable database.
The default is \fIcablelist.txt\fR in the current directory.

.TP
.B XCPORT
Parallel port device to be used for JTAG cable type \fBpp\fR.
The default is \fI/dev/parport0\fR.
This setting may be overridden by command-line option \fB\-d\fR.

.TP
.B XC_MAPDIR
Default directory to search for XC2C map files.
This setting may be overridden by command-line option \fB\-m\fR.

.TP
.B JTAG_DEBUG
If specified, a log of JTAG operations is written to a file with this name.

.TP
.B FTDI_DEBUG
If specified, a log of interactions with the FTDI device is written to
a file with this name.
Only used for FTDI-based cable types.

.TP
.B XPC_DEBUG
If specified, a log of interactions with the XPC programmer is written to
a file with this name.
Only used for XPC-based cable types.

.TP
.B SPI_DEBUG
If specified, a log of SPI operations is written to a file with this name.
Only used in ISF mode.

.TP
.B PDI_DEBUG
If specified, a log of PDI operations is written to a file with this name.
Only used when programming an Atmel XMega device.

.SH FILES

.TP
.I devlist.txt
The device database, containing a list of known JTAG target devices.
This file is read from the current directory by default, or from the location
indicated by the \fIXCDB\fR environment variable.
If not found, an internal compile-time version of the device database is used.

.TP
.I cablelist.txt
The cable database, containing a list of known JTAG cable types.
This file is read from the current directory by default, or from the
location indicated by the \fICABLEDB\fR environment variable.
If not found, an internal compile-time version of the cable database is used.

.SH "SEE ALSO"
http://sourceforge.net/projects/xc3sprog/

.SH "Contribute back"
 Feedback on success/failure/enhancement requests:
     http://sourceforge.net/mail/?group_id=170565