Provided by: xc3sprog_0+svn795+dfsg-4_amd64 bug

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.

SEE ALSO

       http://sourceforge.net/projects/xc3sprog/

Contribute back

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

                                            2011-09-04                                XC3SPROG(1)