trabucayre · trabucayre · Aug 16, 2021 · Aug 3, 2021 · Aug 3, 2021 · Aug 7, 2021
diff --git a/INSTALL.md b/INSTALL.md
@@ -1,27 +1,97 @@
-# Install instructions
+# Installing openFPGALoader
 
-## Get the code from git project
+## Linux
 
+### Arch Linux
+
+openFPGALoader is available in the default repositories:
+
+```
+sudo pacman -S openfpgaloader
+```
+
+### Fedora
+
+openFPGALoader is available as a Copr repository:
+
+```
+sudo dnf copr enable mobicarte/openFPGALoader
+sudo dnf install openFPGALoader
+```
+
+### From source (Debian, Ubuntu)
+
+This application uses **libftdi1**, so this library must be installed (and,
+depending of the distribution, headers too)
+```bash
+apt-get install libftdi1-2 libftdi1-dev libhidapi-libusb0 libhidapi-dev libudev-dev cmake pkg-config make g++
+```
+**libudev-dev** is optional, may be replaced by **eudev-dev** or just not installed.
+
+By default, **(e)udev** support is enabled (used to open a device by his */dev/xx*
+node). If you don't want this option, use:
+
+```bash
+-DENABLE_UDEV=OFF
 ```
-$ git clone https://github.com/trabucayre/openFPGALoader.git
+
+By default, **cmsisdap** support is enabled (used for colorlight I5).
+If you don't want this option, use:
+
+```bash
+-DENABLE_CMSISDAP=OFF
 ```
 
-## Compile from source
+Alternatively you can manually specify the location of **libusb** and **libftdi1**:
 
+```bash
+-DUSE_PKGCONFIG=OFF -DLIBUSB_LIBRARIES=<path_to_libusb> -DLIBFTDI_LIBRARIES=<path_to_libftdi> -DLIBFTDI_VERSION=<version> -DCMAKE_CXX_FLAGS="-I<libusb_include_dir> -I<libftdi1_include_dir>"
 ```
+
+You may also need to add this if you see link errors between **libusb** and **pthread**:
+
+```bash
+-DLINK_CMAKE_THREADS=ON
+```
+
+To build the app:
+```bash
 $ mkdir build
 $ cd build
 $ cmake ../ # add -DBUILD_STATIC=ON to build a static version
             # add -DENABLE_UDEV=OFF to disable udev support and -d /dev/xxx
+            # add -DENABLE_CMSISDAP=OFF to disable CMSIS DAP support
 $ cmake --build .
 or
 $ make -j$(nproc)
 ```
+To install
+```bash
+$ sudo make install
+```
+The default install path is `/usr/local`, to change it, use
+`-DCMAKE_INSTALL_PREFIX=myInstallDir` in cmake invokation.
+
+## Udev rules
+
+By default, users have no access to converters. A rule file
+(*99-openfpgaloader.rules*) for *udev* is provided at the root directory
+of this repository. These rules set access right and group (*plugdev*)
+when a converter is plugged.
 
-## Install
+```bash
+$ sudo cp 99-openfpgaloader.rules /etc/udev/rules.d/
+$ sudo udevadm control --reload-rules && sudo udevadm trigger # force udev to take new rule
+$ sudo usermod -a YourUserName -G plugdev # add user to plugdev group
+```
+After that you need to unplug and replug your device.
+
+## macOS
 
-As root:
+openFPGALoader is available as a [Homebrew](https://brew.sh) formula:
 
 ```
-$ make install
+brew install openfpgaloader
 ```
+
+## Windows
diff --git a/README.md b/README.md
diff --git a/doc/advanced-usage.md b/doc/advanced-usage.md
@@ -0,0 +1,59 @@
+# Advanced usage of openFPGALoader
+
+## Resetting an FPGA
+
+```bash
+openFPGALoader [options] -r
+```
+
+## Reading the bitstream from STDIN
+
+```bash
+cat /path/to/bitstream.ext | openFPGALoader --file-type ext [options]
+```
+
+`--file-type` is required to detect file type
+
+Note: It's possible to load a bitstream through network:
+
+```bash
+# FPGA side
+nc -lp port | openFPGALoader --file-type xxx [option
+# Bitstream side
+nc -q 0 host port < /path/to/bitstream.ext
+```
+
+## Automatic file type detection bypass
+
+Default behavior is to use file extension to determine file parser. To avoid
+this mecanism `--file-type type` must be used.
+
+## FT231/FT232 bitbang mode and pins configuration
+
+*FT232R* and *ft231X* may be used as JTAG programmer. JTAG communications are
+emulated in bitbang mode.
+
+To use these devices user needs to provides both the cable and the pin mapping:
+```bash
+openFPGALoader [options] -cft23XXX --pins=TDI:TDO:TCK:TMS /path/to/bitstream.ext
+```
+where:
+* ft23XXX may be **ft232RL** or **ft231X**
+* TDI:TDO:TCK:TMS may be the pin ID (0 <= id <= 7) or string value
+
+allowed values are:
+
+| value | ID |
+|-------|----|
+|  TXD  | 0  |
+|  RXD  | 1  |
+|  RTS  | 2  |
+|  CTS  | 3  |
+|  DTR  | 4  |
+|  DSR  | 5  |
+|  DCD  | 6  |
+|  RI   | 7  |
+
+## Writing to an arbitrary address in flash memory
+
+With FPGA using an external SPI flash (*xilinx*, *lattice ECP5/nexus/ice40*, *anlogic*, *efinix*) option  **-o** allows one to write raw binary file to an arbitrary adress in FLASH.
diff --git a/doc/anlogic.md b/doc/anlogic.md
@@ -0,0 +1,45 @@
+# Anlogic notes
+
+## Sipeed Lichee Tang
+
+For this target, *openFPGALoader* support *svf* and *bit*
+
+__bit file load (memory)__
+
+```bash
+openFPGALoader -m -b licheeTang /somewhere/project/prj/*.bit
+```
+
+Since *-m* is the default, this argument is optional
+
+__bit file load (spi flash)__
+
+```bash
+openFPGALoader -f -b licheeTang /somewhere/project/prj/*.bit
+```
+
+__svf file load__
+
+It's possible to produce this file by using *TD*:
+* Tools->Device Chain
+* Add your bit file
+* Option : Create svf
+
+or by using [prjtang project](https://github.com/mmicko/prjtang)
+
+```bash
+mkdir build
+cd build
+cmake ../
+make
+```
+
+Now a file called *tangbit* is present in current directory and has to be used as
+follow:
+```bash
+tangbit --input /somewhere.bit --svf bitstream.svf
+```
+
+```bash
+openFPGALoader -b licheeTang /somewhere/*.svf
+```
diff --git a/doc/board-compatibility-list.md b/doc/board-compatibility-list.md
@@ -0,0 +1,58 @@
+# Board compatibility list
+
+**Quick usage reminder.** `arty` can be any of the board names from the first column.
+
+```
+openFPGALoader -b arty bitstream.bit # Loading in SRAM (volatile)
+openFPGALoader -b arty -f bitstream.bit # Writing in flash (non-volatile)
+```
+
+|                Board name | Description                                                                                                                                   | FPGA                              | Memory    | Flash    |
+|--------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------|:----------|:---------|
+|           **acornCle215** | [Acorn CLE 215+](http://squirrelsresearch.com/acorn-cle-215/)                                                                                 | Artix</br>xc7a200tsbg484          | OK        | OK       |
+|           **alchitry_au** | [Alchitry Au](https://alchitry.com/products/alchitry-au-fpga-development-board)                                                               | Artix</br>xc7a35tftg256           | OK        | OK       |
+|                  **arty** | [Digilent Arty A7](https://reference.digilentinc.com/reference/programmable-logic/arty-a7/start)                                              | Artix</br>xc7a35ticsg324          | OK        | OK       |
+|                           | [Digilent Arty S7](https://reference.digilentinc.com/reference/programmable-logic/arty-s7/start)                                              | Spartan7</br>xc7s50csga324        | OK        | OK       |
+|                           | [Digilent Analog Discovery 2](https://reference.digilentinc.com/test-and-measurement/analog-discovery-2/start)                                | Spartan6</br>xc6slx25             | OK        | NT       |
+|                           | [Digilent Digital Discovery](https://reference.digilentinc.com/test-and-measurement/digital-discovery/start)                                  | Spartan6</br>xc6slx25             | OK        | NT       |
+|                **basys3** | [Digilent Basys3](https://reference.digilentinc.com/reference/programmable-logic/basys-3/start)                                               | Artix</br>xc7a35tcpg236           | OK        | OK       |
+|            **colorlight** | [Colorlight 5A-75B (version 7)](https://fr.aliexpress.com/item/32281130824.html)                                                              | ECP5</br>LFE5U-25F-6BG256C        | OK        | OK       |
+|         **colorlight_i5** | [Colorlight I5](https://www.colorlight-led.com/product/colorlight-i5-led-display-receiver-card.html)                                          | ECP5</br>LFE5U-25F-6BG381C        | OK        | OK       |
+|       **crosslinknx_evn** | [Lattice CrossLink-NX Evaluation Board](https://www.latticesemi.com/en/Products/DevelopmentBoardsAndKits/CrossLink-NXEvaluationBoard)         | Nexus</br>LIFCL-40                | OK        | OK       |
+|               **cyc1000** | [Trenz cyc1000](https://shop.trenz-electronic.de/en/TEI0003-02-CYC1000-with-Cyclone-10-FPGA-8-MByte-SDRAM)                                    | Cyclone 10 LP</br>10CL025YU256C8G | OK        | OK       |
+|                   **de0** | [Terasic DE0](https://www.terasic.com.tw/cgi-bin/page/archive.pl?No=364)                                                                      | Cyclone III</br>EP3C16F484C6      | OK        | NT       |
+|               **de0nano** | [Terasic de0nano](https://www.terasic.com.tw/cgi-bin/page/archive.pl?No=593)                                                                  | Cyclone IV E</br>EP4CE22F17C6     | OK        | OK       |
+|            **de0nanoSoc** | [Terasic de0nanoSoc](https://www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&CategoryNo=205&No=941)                               | Cyclone V SoC</br>5CSEMA4U23C6    | OK        |          |
+|              **de10nano** | [Terasic de10Nano](https://www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&CategoryNo=205&No=1046)                                | Cyclone V SoC</br>5CSEBA6U23I7    | OK        |          |
+|              **ecp5_evn** | [Lattice ECP5 5G Evaluation Board](https://www.latticesemi.com/en/Products/DevelopmentBoardsAndKits/ECP5EvaluationBoard)                      | ECP5G</br>LFE5UM5G-85F            | OK        | OK       |
+|                **ecpix5** | [LambdaConcept ECPIX-5](https://shop.lambdaconcept.com/home/46-2-ecpix-5.html#/2-ecpix_5_fpga-ecpix_5_85f)                                    | ECP5</br>LFE5UM5G-85F             | OK        | OK       |
+|               **fireant** | [Fireant Trion T8](https://www.crowdsupply.com/jungle-elec/fireant)                                                                           | Trion</br>T8F81                   | NA        | AS       |
+|                  **fomu** | [Fomu PVT](https://tomu.im/fomu.html)                                                                                                         | iCE40UltraPlus</br>UP5K           | NA        | OK       |
+|             **honeycomb** | [honeycomb](https://github.com/Disasm/honeycomb-pcb)                                                                                          | littleBee</br>GW1NS-2C            | OK        | IF       |
+|         **ice40_generic** | [iCEBreaker](https://1bitsquared.com/collections/fpga/products/icebreaker)                                                                    | iCE40UltraPlus</br>UP5K           | NA        | AS       |
+|         **ice40_generic** | [icestick](https://www.latticesemi.com/icestick)                                                                                              | iCE40</br>HX1k                    | NA        | AS       |
+|         **ice40_generic** | [iCE40-HX8K](https://www.latticesemi.com/Products/DevelopmentBoardsAndKits/iCE40HX8KBreakoutBoard.aspx)                                       | iCE40</br>HX8k                    | NT        | AS       |
+|         **ice40_generic** | [Olimex iCE40HX1K-EVB](https://www.olimex.com/Products/FPGA/iCE40/iCE40HX1K-EVB/open-source-hardware)                                         | iCE40</br>HX1k                    | NT        | AS       |
+|         **ice40_generic** | [Olimex iCE40HX8K-EVB](https://www.olimex.com/Products/FPGA/iCE40/iCE40HX8K-EVB/open-source-hardware)                                         | iCE40</br>HX8k                    | NT        | AS       |
+|                 **kc705** | [Xilinx KC705](https://www.xilinx.com/products/boards-and-kits/ek-k7-kc705-g.html)                                                            | Kintex7</br>xc7k325t              | OK        | NT       |
+|            **licheeTang** | [Sipeed Lichee Tang](https://tang.sipeed.com/en/hardware-overview/lichee-tang/)                                                               | eagle s20</br>EG4S20BG256         | OK        | OK       |
+|            **machXO2EVN** | [Lattice MachXO2 Breakout Board Evaluation Kit ](https://www.latticesemi.com/products/developmentboardsandkits/machxo2breakoutboard)          | MachXO2</br>LCMXO2-7000HE         | OK        | OK       |
+|            **machXO3EVN** | [Lattice MachXO3D Development Board ](https://www.latticesemi.com/products/developmentboardsandkits/machxo3d_development_board)               | MachXO3D</br>LCMXO3D-9400HC       | OK        | NT       |
+|             **machXO3SK** | [Lattice MachXO3LF Starter Kit](https://www.latticesemi.com/en/Products/DevelopmentBoardsAndKits/MachXO3LFStarterKit)                         | MachXO3</br>LCMX03LF-6900C        | OK        | OK       |
+|            **nexysVideo** | [Digilent Nexys Video](https://reference.digilentinc.com/reference/programmable-logic/nexys-video/start)                                      | Artix</br>xc7a200tsbg484          | OK        | OK       |
+|            **orangeCrab** | [Orange Crab](https://github.com/gregdavill/OrangeCrab)                                                                                       | ECP5</br>LFE5U-25F-8MG285C        | OK (JTAG) | OK (DFU) |
+|           **pipistrello** | [Saanlima Pipistrello LX45](http://pipistrello.saanlima.com/index.php?title=Welcome_to_Pipistrello)                                           | Spartan6</br>xc6slx45-csg324      | OK        | OK       |
+|        **qmtechCycloneV** | [QMTech CycloneV Core Board](https://fr.aliexpress.com/i/1000006622149.html)                                                                  | Cyclone V</br>5CEFA2F23I7         | OK        | OK       |
+|                **runber** | [SeeedStudio Gowin RUNBER](https://www.seeedstudio.com/Gowin-RUNBER-Development-Board-p-4779.html)                                            | littleBee</br>GW1N-4              | OK        | IF       |
+|                           | [Scarab Hardware MiniSpartan6+](https://www.kickstarter.com/projects/1812459948/minispartan6-a-powerful-fpga-board-and-easy-to-use)           | Spartan6</br>xc6slx25-3-ftg256    | OK        | NT       |
+| **spartanEdgeAccelBoard** | [SeeedStudio Spartan Edge Accelerator Board](http://wiki.seeedstudio.com/Spartan-Edge-Accelerator-Board)                                      | Spartan7</br>xc7s15ftgb196        | OK        | NA       |
+|              **tangnano** | [Sipeed Tang Nano](https://tangnano.sipeed.com/en/)                                                                                           | littleBee</br>GW1N-1              | OK        |          |
+|               **tec0117** | [Trenz Gowin LittleBee (TEC0117)](https://shop.trenz-electronic.de/en/TEC0117-01-FPGA-Module-with-GOWIN-LittleBee-and-8-MByte-internal-SDRAM) | littleBee</br>GW1NR-9             | OK        | IF       |
+|                  **xtrx** | [FairWaves XTRXPro](https://www.crowdsupply.com/fairwaves/xtrx)                                                                               | Artix</br>xc7a50tcpg236           | OK        | OK       |
+|            **xyloni_spi** | [Efinix Xyloni](https://www.efinixinc.com/products-devkits-xyloni.html)                                                                       | Trion</br>T8F81                   | NA        | AS       |
+|              **zedboard** | [Avnet ZedBoard](https://www.avnet.com/wps/portal/us/products/avnet-boards/avnet-board-families/zedboard/)                                    | zynq7000</br>xc7z020clg484        | OK        | NA       |
+
+- *IF* Internal Flash
+- *AS* Active Serial flash mode
+- *NA* Not Available
+- *NT* Not Tested
diff --git a/doc/cable-compatibility-list.md b/doc/cable-compatibility-list.md
@@ -0,0 +1,17 @@
+# Cable compatibility list
+
+* anlogic JTAG adapter
+* [digilent_hs2](https://store.digilentinc.com/jtag-hs2-programming-cable/): jtag programmer cable from digilent
+* [cmsisdap](https://os.mbed.com/docs/mbed-os/v6.11/debug-test/daplink.html): ARM CMSIS DAP protocol interface (hid only)
+* [Orbtrace](https://github.com/orbcode/orbtrace): Open source FPGA-based debug and trace interface
+* [DFU (Device Firmware Upgrade)](http://www.usb.org/developers/docs/devclass_docs/DFU_1.1.pdf): USB device compatible with DFU protocol
+* [DirtyJTAG](https://github.com/jeanthom/DirtyJTAG): JTAG probe firmware for STM32F1
+  (Best to use release (1.4 or newer) or limit the --freq to 600000 with older releases. New version https://github.com/jeanthom/DirtyJTAG/tree/dirtyjtag2 is also supported)
+* Intel USB Blaster I & II : jtag programmer cable from intel/altera
+* JTAG-HS3: jtag programmer cable from digilent
+* FT2232: generic programmer cable based on Ftdi FT2232
+* FT232RL and FT231X: generic USB<->UART converters in bitbang mode
+* [Tang Nano USB-JTAG interface](https://github.com/diodep/ch55x_jtag): FT2232C clone based on CH552 microcontroler
+  (with some limitations and workaround)
+* [Tigard](https://www.crowdsupply.com/securinghw/tigard): SWD/JTAG/UART/SPI programmer based on Ftdi FT2232HQ
+* [honeycomb USB-JTAG interface](https://github.com/Disasm/f042-ftdi): FT2232C clone based on STM32F042 microcontroler
diff --git a/doc/efinix.md b/doc/efinix.md
@@ -0,0 +1,20 @@
+# Efinix notes
+
+## Firant and Xyloni boards (efinix trion T8)
+
+*.hex* file is the default format generated by *Efinity IDE*, so nothing
+special must be done to generates this file.
+
+*openFPGALoader* support only active mode (SPI) (*JTAG* is WIP).
+
+__hex file load__
+
+```bash
+openFPGALoader -b fireant /somewhere/project/outflow/*.hex
+```
+or, for xyloni board
+```bash
+openFPGALoader -b xyloni_spi /somewhere/project/outflow/*.hex
+```
+
+Since openFPGALoader access the flash directly in SPI mode the *-b fireant*, *-b xyloni_spi* is required (no autodetection possible)
diff --git a/doc/first-steps.md b/doc/first-steps.md
@@ -0,0 +1,47 @@
+# First steps with openFPGALoader
+
+## Install
+
+Packages are available for Linux distributions and macOS:
+
+**Arch Linux**: `sudo pacman -S openfpgaloader`
+
+**Fedora**: `sudo dnf copr enable mobicarte/openFPGALoader; sudo dnf install openFPGALoader`
+
+**macOS**: `brew install openfpgaloader`
+
+More instructions for other installation scenarios (including Windows) are available in [the installation manual](../INSTALL.md).
+
+## Programming a development board
+
+Just simply replace `my_fpga_board` with any FPGA board from the [board compatibility list](board-compatibility-list.md) (or `openFPGALoader --list-boards`) in any of the two commands below, depending on if you want to program the volatile part of your FPGA (faster but not persistent) or the flash part of your FPGA (slower but persistent):
+
+```bash
+openFPGALoader -b my_fpga_board my_bitstream.bit # Program to SRAM
+openFPGALoader -b my_fpga_board -f my_bitstream.bit # Program to flash
+```
+
+**Note:** When a bitstream file is compatible with both memory load and FLASH write, the default behavior is to load bitstream in memory
+
+## Programming a "standalone" FPGA
+
+If your FPGA doesn't come with a built-in programmer or if you prefer to use an external cable, you can specify a cable to use from the [cable compatibility list](cable-compatibility-list.md) (or `openFPGALoader --list-cables`):
+
+```bash
+openFPGALoader -c my_cable my_bitstream.bit # Program to SRAM
+openFPGALoader -c my_cable -f my_bitstream.bit # Program to flash
+```
+
+**Note:** For some cable (like digilent adapters) signals from the converter are not just directly to the FPGA. For this case, the -c must be added.
+
+**FTDI/FTDI-compatible cable users:** The `-d` option lets you specify a specific FTDI device:
+
+```bash
+openFPGALoader -d /dev/ttyUSBX
+```
+
+When the `-d` option is not provided, openFPGALoader will opens the first FTDI adapter it finds. Therefore it is preferable to use this flag if your computer is connected to multiple FTDI devices.
+
+## Troubleshooting
+
+Please refer to [the troubleshooting documentation](troubleshooting.md).