Ubuntu Manpage: xc3sprog - JTAG programming utility for Xilinx FPGAs and PROMs

Provided by: xc3sprog_0+svn795+dfsg-4_amd64

NAME

       xc3sprog - JTAG programming utility for Xilinx FPGAs and PROMs

SYNOPSIS

       xc3sprog -c cable [options] file1spec [file2spec ...]
       xc3sprog -c cable [options] -j

DESCRIPTION

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

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

       As its name indicates, xc3sprog 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.  xc3sprog supports several JTAG cables, including parallel port cables and  USB
       programmers.

OPTIONS

-c cable
Specify the type of JTAG cable. The specified type, cable refers to a label in the cable
database.
Common cable types are pp (parallel port cable), xpc (Xilinx USB programmer), and ftdi (FTDI-based
USB programmer).

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

-p val[,val,...]
Use device at JTAG chain position val, 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.

-Tn Test the JTAG chain n times. When running in ISF mode, test the SPI connection.
If n is not specified, the default is to test 10000 times.
If n = 0, keep testing forever.

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

-e Erase the entire device.

-I[file]
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 file is specified, start by
programming the specified bitfile into the primary JTAG target (typically an FPGA).

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

-m mapdir
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 $XC_MAPDIR.

-d /dev/parportN
Specify the parallel port device to be used. If not specified, defaults to the value of $XCPORT
or /dev/parport0.
Only used for cable type pp.

-s serialnum
Use the USB device with the specified serial number string. Needed if several adapters of the same
type are connected at the same time.

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

-D Dump the device database and cable database to files devlist.txt and cablelist.txt in the current
directory. If a file already exists, xc3sprog tries to generate a unique name by appending an
increasing number.

-X opt[,opt...]
Set configuration mode for XCFnnP PROM devices. Configuration from XCFnnP PROM may be done in
several modes, depending on the wiring between XCFnnP and FPGA. By default, xc3sprog prepares
XCFnnP devices for slave serial mode (FPGA running in master serial mode).

To override the defaults, specify a comma-separated list of options. The following options are
accepted:
master XCFnnP is master (FPGA is slave)
slave XCFnnP is slave (FPGA is master, this is default)
parallel Parallel configuration data bus
serial Serial configuration data line (default)
extclk Use external clock in master mode
intclk Use internal clock in master mode
fastclk Use fast internal clock
slowclk Use slow internal clock

-v Enable verbose output.

-h Print a help text.

ACTION SPECIFICATION

One or more programming actions may be specified. Each action consists of a filename, optionally
followed by attributes in the form <filename:action:offset:style:length>.

filename
The file to be written to the device, or the file in which to store data after reading from the
device. On windows systems, a colon on position 2 is considered as filename part and not as an action
separator.

action
One letter indicating whether to write, read, or verify the device. If not specified, the default
action is 'w'.
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.

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

style
The format of the specified file.

BIT Xilinx .BIT file format. Default for FPGA, XCF and SPI
devices.
BIN Raw binary file.
BPI Raw binary file not bit reversed.
MCS Xilinx .MCS file format.
IHEX Intel HEX format. Also used by Xilinx PROMGEN when
writing MCS files. Default for XMEGA devices.
HEXRAW Raw sequence of hexadecimal digits.
JEDEC Default for CPLD devices.

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

DEVICE DATABASE

       The  device  database contains a list of supported JTAG devices.  When xc3sprog 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 xc3sprog executable.  The database is tried to be loaded
       from a file at run time.  If the environment variable $XCDB is defined, it  specifies  the  name  of  the
       device  database  file, otherwise the file devlist.txt 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.

CABLE DATABASE

The cable database contains a list of supported JTAG cables. Each cable type is identified by a short
label, such as pp, ftdijtag, or xpc. 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 xc3sprog executable. The database is tried to be loaded
from a file at run time. If the environment variable $CABLEDB is defined, it specifies the name of the
cable database file, otherwise the file cablelist.txt 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

EXAMPLES

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

       xc3sprog -c ftdijtag -v -p 0 design.bit
           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.

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

       xc3sprog -c xpc -p 1 dump.bit:r
           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.

       xc3sprog -c cable -Ibscan_spi/xc3s50an.bit design.bit
           Load  xc3s50an.bit  into the FPGA in position 0 in the JTAG chain.  Then, program design.bit into the
           ISF memory in the FPGA.

       xc3sprog -c cable -I image.bit:w:0x10000
           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.

ENVIRONMENT

       XCDB   Name of the file to use as device database.  The default is devlist.txt in the current directory.

       CABLEDB
              Name of the file to use as cable database.  The default is cablelist.txt in the current directory.

       XCPORT Parallel  port  device  to  be  used  for JTAG cable type pp.  The default is /dev/parport0.  This
              setting may be overridden by command-line option -d.

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

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

       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.

       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.

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

       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.

FILES

       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 XCDB environment variable.  If
              not found, an internal compile-time version of the device database is used.

       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 CABLEDB environment  variable.
              If not found, an internal compile-time version of the cable database is used.

Contribute back

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

                                                   2011-09-04                                        XC3SPROG(1)