XC3SPROG(1)

💅 xc3sprog — the JTAG glow-up manual (part 1)

okay bestie, sit down, hydrate, because we're talking about xc3sprog, aka the JTAG programming utility for Xilinx FPGAs and PROMs. yes, that's the whole vibe: it's a command-line tool that programs FPGAs, microcontrollers and PROMs over JTAG. no cap. 🦋

---

✨ SYNOPSIS ✨

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

---

🌸 DESCRIPTION 🌸

So. xc3sprog is a command-line tool for programming FPGAs, microcontrollers and PROMs via JTAG. That's it, that's the job, and it does it beautifully. 💖

In a typical application — like, the main character use case — xc3sprog reads a .BIT file that an FPGA design tool generated, and programs it into the PROM chip on an FPGA board for persistent storage, or into the configuration RAM of an FPGA for temporary storage. Other use cases? Scroll down to the EXAMPLES section, bestie, they're right there.

As its name indicates, xc3sprog was originally designed for Xilinx Spartan-3 FPGAs. But the way it's been extended… it now handles several other types of devices, including Xilinx FPGAs, CPLDs, XCF flash PROMs, Atmel AVRs and SPI flash chips. And it supports several JTAG cables too — parallel port cables and USB programmers both. iconic behaviour, honestly ✨

---

🎀 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). you basically always need this one, fr fr
• -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 the 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. forever forever. like, until you ctrl-C it. 💀
• -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. only FTDI, don't come for me
• -e — Erase the entire device. poof. gone. 🫧
• -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. pp only, bestie, don't try it elsewhere
• -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. multi-adapter girlies, this one's for you
• -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. your bestie telling you everything that's happening, in detail, unprompted 🗣️
• -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. windows girlies, watch that colon 👀
• 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. capital R does NOT care about your existing files, periodt
• 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. like a little rolodex of everyone invited to the chain party 📇

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 known, 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. DIY database glow-up ✨

---

🦋 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 known, 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 known 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. do not skip the description string, bestie, it's how your cable gets picked out of the crowd 💅

---

🌈 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.

---

okay that's part 1, don't go anywhere — there's more, and it's giving 🫶

🌸 ENVIRONMENT 🌸

ok so bestie, these are the env vars that change how xc3sprog acts, no cap. Set them in your shell and they just... vibe in the background 💅

• XCDB — the name of the file to use as the device database. default is devlist.txt in the current directory. ✨
• CABLEDB — the name of the file to use as the cable database. default is cablelist.txt in the current directory. 🎀
• XCPORT — the parallel port device used for JTAG cable type pp. default is /dev/parport0. lowkey important: this setting can be overridden by the command-line option -d.
• XC_MAPDIR — the default directory to search for XC2C map files. and yes, this one can be overridden by the command-line option -m. she's flexible like that 💁
• JTAG_DEBUG — if you specify it, a log of JTAG operations gets 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, iykyk.
• XPC_DEBUG — if specified, a log of interactions with the XPC programmer is written to a file with this name. only 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 fr fr.
• 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. and if it's not found? no stress — an internal compile-time version of the device database gets used instead 💖
• cablelist.txt — the cable database, containing a list of known JTAG cable types. read from the current directory by default, or from wherever the CABLEDB environment variable points. if it's not found, an internal compile-time version of the cable database is used. iconic fallback behaviour tbh 🫶

---

⭐ SEE ALSO ⭐

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

💌 Contribute back 💌

got feedback? success stories, failure reports, enhancement requests — all of it is welcome, bestie:

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

---

and that's the whole page!! go flash something and tell the group chat 💅✨

mwah 💖 this was xc3sprog, dated 2011-09-04, living in section XC3SPROG(1) of the manual — go forth and slay, bestie 🧚🌈