luke
/
openFPGALoader
mirror of https://github.com/trabucayre/openFPGALoader.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #138 from umarcor/doc-sphinx 

doc: add Sphinx site and publish it through GitHub Pages
This commit is contained in:
Gwenhael Goavec-Merou 2021-11-28 12:23:49 +01:00 committed by GitHub
parent f9980a566f 85d4bdb950
commit 048ddecd38
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
36 changed files with 1064 additions and 674 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.btd.yml Normal file
View File

@ -0,0 +1,6 @@
input: doc
output: _build
requirements: requirements.txt
target: gh-pages
formats: [ html ]
theme: https://codeload.github.com/buildthedocs/sphinx.theme/tar.gz/v1

20
.github/workflows/Test.yml vendored
View File

@ -8,6 +8,26 @@ on:
jobs:
doc:
runs-on: ubuntu-latest
name: '📓 Docs'
steps:
- name: '🧰 Checkout'
uses: actions/checkout@v2
- name: '📓 BuildTheDocs (BTD)'
uses: buildthedocs/btd@v0
with:
token: ${{ github.token }}
skip-deploy: ${{ github.event_name == 'pull_request' }}
- name: '📤 Upload artifact: HTML'
uses: actions/upload-artifact@v2
with:
path: doc/_build/html
lin-build:
strategy:
fail-fast: false

3
.gitignore vendored
View File

@ -38,3 +38,6 @@ openFPGALoader
# Build directory
build/
# Documentation
/doc/_build
/doc/_theme

109
INSTALL.md
View File

@ -1,109 +0,0 @@
# Installing openFPGALoader
## 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-hidraw0 libhidapi-dev libudev-dev \
zlib1g-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
```
By default, **cmsisdap** support is enabled (used for colorlight I5).
If you don't want this option, use:
```bash
-DENABLE_CMSISDAP=OFF
```
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.
```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 $USER -G plugdev # add user to plugdev group
```
After that you need to unplug and replug your device.
## macOS
openFPGALoader is available as a [Homebrew](https://brew.sh) formula:
```
brew install openfpgaloader
```
## Windows
## Common
Bitstreams for **XC2C (coolrunner-II)** needs to be remapped using `.map` shipped with
**ISE**. **ISE** path is set at configure time using
```
-DISE_PATH=/somewhere/Xilinx/ISE_VERS/
```
default: `/opt/Xilinx/14.7`

38
README.md
View File

@ -1,46 +1,48 @@
# openFPGALoader
<p align="right">
<a title="'Test' workflow Status" href="https://github.com/trabucayre/openFPGALoader/actions?query=workflow%3ATest"><img alt="'Test' workflow Status" src="https://img.shields.io/github/workflow/status/trabucayre/openFPGALoader/Test?longCache=true&style=flat-square&label=Test&logo=github%20actions&logoColor=fff"></a>
<a title="Documentation" href="https://trabucayre.github.io/openFPGALoader"><img src="https://img.shields.io/website.svg?label=trabucayre.github.io%2FopenFPGALoader&longCache=true&style=flat-square&url=http%3A%2F%2Ftrabucayre.github.io%2FopenFPGALoader%2Findex.html&logo=GitHub"></a><!--
-->
<a title="'Test' workflow Status" href="https://github.com/trabucayre/openFPGALoader/actions?query=workflow%3ATest"><img alt="'Test' workflow Status" src="https://img.shields.io/github/workflow/status/trabucayre/openFPGALoader/Test?longCache=true&style=flat-square&label=Test&logo=github%20actions&logoColor=fff"></a><!--
-->
<a title="Releases" href="https://github.com/trabucayre/openFPGALoader/releases"><img src="https://img.shields.io/github/commits-since/trabucayre/openFPGALoader/latest.svg?longCache=true&style=flat-square&logo=git&logoColor=fff"></a>
</p>
<p align="center">
<strong><a href="doc/first-steps.md">First steps</a> • <a href="INSTALL.md">Install</a> • <a href="doc/troubleshooting.md">Troubleshooting</a></strong> • <a href="doc/advanced-usage.md">Advanced usage</a>
<strong><a href="https://trabucayre.github.io/openFPGALoader/guide/first-steps.html">First steps</a> • <a href="https://trabucayre.github.io/openFPGALoader/guide/install.html">Install</a> • <a href="https://trabucayre.github.io/openFPGALoader/guide/troubleshooting.html">Troubleshooting</a></strong> • <a href="https://trabucayre.github.io/openFPGALoader/guide/advanced.html">Advanced usage</a>
</p>
Universal utility for programming FPGAs. Compatible with many boards, cables and FPGA from major manufacturers (Xilinx, Altera/Intel, Lattice, Gowin, Efinix, Anlogic). openFPGALoader works on [Linux](INSTALL.md#linux), [Windows](INSTALL.md#windows) and [macOS](INSTALL.md#macos).
Universal utility for programming FPGAs. Compatible with many boards, cables and FPGA from major manufacturers (Xilinx, Altera/Intel, Lattice, Gowin, Efinix, Anlogic). openFPGALoader works on Linux, Windows and macOS.
Not sure if your hardware is supported? Check the hardware compatibility lists:
* [FPGA compatibility list](doc/fpga-compatibility-list.md)
* [Board compatibility list](doc/board-compatibility-list.md)
* [Cable compatibility list](doc/cable-compatibility-list.md)
* [FPGA compatibility list](https://trabucayre.github.io/openFPGALoader/compatibility/fpga.html)
* [Board compatibility list](https://trabucayre.github.io/openFPGALoader/compatibility/board.html)
* [Cable compatibility list](https://trabucayre.github.io/openFPGALoader/compatibility/cable.html)
Also checkout the vendor-specific documentation: [Anlogic](doc/anlogic.md), [Efinix](doc/efinix.md), [Gowin](doc/gowin.md), [Intel/Altera](doc/intel.md), [Lattice](doc/lattice.md), [Xilinx](doc/xilinx.md).
Also checkout the vendor-specific documentation:
[Anlogic](https://trabucayre.github.io/openFPGALoader/vendors/anlogic.html),
[Efinix](https://trabucayre.github.io/openFPGALoader/vendors/efinix.html),
[Gowin](https://trabucayre.github.io/openFPGALoader/vendors/gowin.html),
[Intel/Altera](https://trabucayre.github.io/openFPGALoader/vendors/intel.html),
[Lattice](https://trabucayre.github.io/openFPGALoader/vendors/lattice.html),
[Xilinx](https://trabucayre.github.io/openFPGALoader/vendors/xilinx.html).
## Quick Usage
`arty` in the example below is one of the many FPGA board configurations listed [here](doc/board-compatibility-list.md).
`arty` in the example below is one of the many FPGA board configurations listed [here](https://trabucayre.github.io/openFPGALoader/compatibility/board.html).
```bash
openFPGALoader -b arty arty_bitstream.bit # Loading in SRAM
openFPGALoader -b arty -f arty_bitstream.bit # Writing in flash
```
You can also specify a JTAG cable model (complete list [here](doc/cable-compatibility-list.md)) instead of the board model:
You can also specify a JTAG cable model (complete list [here](https://trabucayre.github.io/openFPGALoader/compatibility/cable.html)) instead of the board model:
```bash
openFPGALoader -c cmsisdap fpga_bitstream.bit
```
For detailed instructions, by vendor devices, see:
- [Anlogic](doc/anlogic.md)
- [Efinix](doc/efinix.md)
- [Gowin](doc/gowin.md)
- [Intel/Altera](doc/intel.md)
- [Lattice](doc/lattice.md)
- [Xilinx](doc/xilinx.md)
## Usage
```
@ -61,7 +63,7 @@ openFPGALoader -- a program to flash FPGA
--detect detect FPGA
--dfu DFU mode
--dump-flash Dump flash mode
--external-flash select ext flash for device with internal and
--external-flash select ext flash for device with internal and
external storage
--file-size arg provides size in Byte to dump, must be used with
dump-flash

24
TODO.md
View File

@ -1,24 +0,0 @@
## Global
- improve error message (be more precise)
- catch all exception
- documentation (code + API)
## Cable
- fix *ch552* (*Sipeed tangNano*): works with *SRAM*, fails with *Flash*
- *busblaster* support
- *anlogic* cable support
## Devices/boards
- improve frequency configuration. Use FPGA, cable or --freq args maximum frequency
- rework *cyclone10* eeprom access to avoid using FT2232 interfaceB Spi
emulation (only supported by trenz board)
- fix checksum computation with *gowin GW2A*
- add support for *tangPrimer* (*anlogic EG4S20*)
## Misc
- fix spiFlash class to be able to write everywhere (currently offset is hardcoded
to 0)

11
doc/Makefile Normal file
View File

@ -0,0 +1,11 @@
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees -T -D language=en $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
%:
$(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) $(BUILDDIR)/$@

59
doc/advanced-usage.md
View File

@ -1,59 +0,0 @@
# 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.

45
doc/anlogic.md
View File

@ -1,45 +0,0 @@
# 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
```

65
doc/board-compatibility-list.md
View File

@ -1,65 +0,0 @@
# 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 |
| **icebreaker-bitsy** | [iCEBreaker-bitsy](https://1bitsquared.com/collections/fpga/products/icebreaker-bitsy) | iCE40UltraPlus</br>UP5K | NA | OK |
| **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** | [Icezum Alhambra II ](https://alhambrabits.com/alhambra) | iCE40</br>HX4k | NA | 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 |
| **qmtechCycloneIV** | [QMTech CycloneIV Core Board](https://fr.aliexpress.com/item/32949281189.html) | Cyclone IV</br>EP4CE15F23C8N | OK | NT |
| **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/EF |
| | [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 | |
| **tangnano4k** | [Sipeed Tang Nano 4K](https://tangnano.sipeed.com/en/) | littleBee</br>GW1NSR-4C | OK | IF/EF |
| **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 |
| **trion_t120_bga576_spi** | [Efinix Trion T120 BGA576 Dev Kit](https://www.efinixinc.com/products-devkits-triont120bga576.html) | Trion</br>T120BGA576 | NA | AS |
| **xmf3** | [PLDkit XMF3](https://pldkit.com/xilinx/xmf3) | Xilinx</br>xc3s200ft256, xcf01s | OK | OK |
| **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
- *EF* External Flash
- *AS* Active Serial flash mode
- *NA* Not Available
- *NT* Not Tested

18
doc/cable-compatibility-list.md
View File

@ -1,18 +0,0 @@
# 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)
* [Tang Nano 4k USB-JTAG interface](https://github.com/sipeed/RV-Debugger-BL702): USB-JTAG/UART debugger based on BL702 microcontroler.
* [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

71
doc/compatibility/board.rst Normal file
View File

@ -0,0 +1,71 @@
.. _compatibility:boards:
Boards
######
.. NOTE::
`arty` can be any of the board names from the first column.
.. code-block:: bash
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 xc7a200tsbg484 OK OK
alchitry_au `Alchitry Au <https://alchitry.com/products/alchitry-au-fpga-development-board>`__ Artix xc7a35tftg256 OK OK
arty `Digilent Arty A7 <https://reference.digilentinc.com/reference/programmable-logic/arty-a7/start>`__ Artix xc7a35ticsg324 OK OK
arty `Digilent Arty S7 <https://reference.digilentinc.com/reference/programmable-logic/arty-s7/start>`__ Spartan7 xc7s50csga324 OK OK
arty `Digilent Analog Discovery 2 <https://reference.digilentinc.com/test-and-measurement/analog-discovery-2/start>`__ Spartan6 xc6slx25 OK NT
arty `Digilent Digital Discovery <https://reference.digilentinc.com/test-and-measurement/digital-discovery/start>`__ Spartan6 xc6slx25 OK NT
basys3 `Digilent Basys3 <https://reference.digilentinc.com/reference/programmable-logic/basys-3/start>`__ Artix xc7a35tcpg236 OK OK
colorlight `Colorlight 5A-75B (version 7) <https://fr.aliexpress.com/item/32281130824.html>`__ ECP5 LFE5U-25F-6BG256C OK OK
colorlight_i5 `Colorlight I5 <https://www.colorlight-led.com/product/colorlight-i5-led-display-receiver-card.html>`__ ECP5 LFE5U-25F-6BG381C OK OK
crosslinknx_evn `Lattice CrossLink-NX Evaluation Board <https://www.latticesemi.com/en/Products/DevelopmentBoardsAndKits/CrossLink-NXEvaluationBoard>`__ Nexus 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 10CL025YU256C8G OK OK
de0 `Terasic DE0 <https://www.terasic.com.tw/cgi-bin/page/archive.pl?No=364>`__ Cyclone III EP3C16F484C6 OK NT
de0nano `Terasic de0nano <https://www.terasic.com.tw/cgi-bin/page/archive.pl?No=593>`__ Cyclone IV E 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 5CSEMA4U23C6 OK
de10nano `Terasic de10Nano <https://www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&CategoryNo=205&No=1046>`__ Cyclone V SoC 5CSEBA6U23I7 OK
ecp5_evn `Lattice ECP5 5G Evaluation Board <https://www.latticesemi.com/en/Products/DevelopmentBoardsAndKits/ECP5EvaluationBoard>`__ ECP5G 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 LFE5UM5G-85F OK OK
fireant `Fireant Trion T8 <https://www.crowdsupply.com/jungle-elec/fireant>`__ Trion T8F81 NA AS
fomu `Fomu PVT <https://tomu.im/fomu.html>`__ iCE40UltraPlus UP5K NA OK
honeycomb `honeycomb <https://github.com/Disasm/honeycomb-pcb>`__ littleBee GW1NS-2C OK IF
ice40_generic `iCEBreaker <https://1bitsquared.com/collections/fpga/products/icebreaker>`__ iCE40UltraPlus UP5K NA AS
icebreaker-bitsy `iCEBreaker-bitsy <https://1bitsquared.com/collections/fpga/products/icebreaker-bitsy>`__ iCE40UltraPlus UP5K NA OK
ice40_generic `icestick <https://www.latticesemi.com/icestick>`__ iCE40 HX1k NA AS
ice40_generic `iCE40-HX8K <https://www.latticesemi.com/Products/DevelopmentBoardsAndKits/iCE40HX8KBreakoutBoard.aspx>`__ iCE40 HX8k NT AS
ice40_generic `Olimex iCE40HX1K-EVB <https://www.olimex.com/Products/FPGA/iCE40/iCE40HX1K-EVB/open-source-hardware>`__ iCE40 HX1k NT AS
ice40_generic `Olimex iCE40HX8K-EVB <https://www.olimex.com/Products/FPGA/iCE40/iCE40HX8K-EVB/open-source-hardware>`__ iCE40 HX8k NT AS
ice40_generic `Icezum Alhambra II <https://alhambrabits.com/alhambra>`__ iCE40 HX4k NT AS
kc705 `Xilinx KC705 <https://www.xilinx.com/products/boards-and-kits/ek-k7-kc705-g.html>`__ Kintex7 xc7k325t OK NT
licheeTang `Sipeed Lichee Tang <https://tang.sipeed.com/en/hardware-overview/lichee-tang/>`__ eagle s20 EG4S20BG256 OK OK
machXO2EVN `Lattice MachXO2 Breakout Board Evaluation Kit <https://www.latticesemi.com/products/developmentboardsandkits/machxo2breakoutboard>`__ MachXO2 LCMXO2-7000HE OK OK
machXO3EVN `Lattice MachXO3D Development Board <https://www.latticesemi.com/products/developmentboardsandkits/machxo3d_development_board>`__ MachXO3D LCMXO3D-9400HC OK NT
machXO3SK `Lattice MachXO3LF Starter Kit <https://www.latticesemi.com/en/Products/DevelopmentBoardsAndKits/MachXO3LFStarterKit>`__ MachXO3 LCMX03LF-6900C OK OK
nexysVideo `Digilent Nexys Video <https://reference.digilentinc.com/reference/programmable-logic/nexys-video/start>`__ Artix xc7a200tsbg484 OK OK
orangeCrab `Orange Crab <https://github.com/gregdavill/OrangeCrab>`__ ECP5 LFE5U-25F-8MG285C OK (JTAG) OK (DFU)
pipistrello `Saanlima Pipistrello LX45 <http://pipistrello.saanlima.com/index.php?title=Welcome_to_Pipistrello>`__ Spartan6 xc6slx45-csg324 OK OK
qmtechCycloneIV `QMTech CycloneIV Core Board <https://fr.aliexpress.com/item/32949281189.html>`__ Cyclone IV EP4CE15F23C8N OK NT
qmtechCycloneV `QMTech CycloneV Core Board <https://fr.aliexpress.com/i/1000006622149.html>`__ Cyclone V 5CEFA2F23I7 OK OK
runber `SeeedStudio Gowin RUNBER <https://www.seeedstudio.com/Gowin-RUNBER-Development-Board-p-4779.html>`__ littleBee GW1N-4 OK IF/EF
runber `Scarab Hardware MiniSpartan6+ <https://www.kickstarter.com/projects/1812459948/minispartan6-a-powerful-fpga-board-and-easy-to-use>`__ Spartan6 xc6slx25-3-ftg256 OK NT
spartanEdgeAccelBoard `SeeedStudio Spartan Edge Accelerator Board <http://wiki.seeedstudio.com/Spartan-Edge-Accelerator-Board>`__ Spartan7 xc7s15ftgb196 OK NA
tangnano `Sipeed Tang Nano <https://tangnano.sipeed.com/en/>`__ littleBee GW1N-1 OK
tangnano4k `Sipeed Tang Nano 4K <https://tangnano.sipeed.com/en/>`__ littleBee GW1NSR-4C OK IF/EF
tec0117 `Trenz Gowin LittleBee (TEC0117) <https://shop.trenz-electronic.de/en/TEC0117-01-FPGA-Module-with-GOWIN-LittleBee-and-8-MByte-internal-SDRAM>`__ littleBee GW1NR-9 OK IF
xtrx `FairWaves XTRXPro <https://www.crowdsupply.com/fairwaves/xtrx>`__ Artix xc7a50tcpg236 OK OK
xyloni_spi `Efinix Xyloni <https://www.efinixinc.com/products-devkits-xyloni.html>`__ Trion T8F81 NA AS
trion_t120_bga576_spi `Efinix Trion T120 BGA576 Dev Kit <https://www.efinixinc.com/products-devkits-triont120bga576.html>`__ Trion T120BGA576 NA AS
xmf3 `PLDkit XMF3 <https://pldkit.com/xilinx/xmf3>`__ Xilinx xc3s200ft256, xcf01s OK OK
zedboard `Avnet ZedBoard <https://www.avnet.com/wps/portal/us/products/avnet-boards/avnet-board-families/zedboard/>`__ zynq7000 xc7z020clg484 OK NA
======================= ================================================================================================================================================= ============================= ========= ========
* IF: Internal Flash
* EF: External Flash
* AS: Active Serial flash mode
* NA: Not Available
* NT: Not Tested

22
doc/compatibility/cable.rst Normal file
View File

@ -0,0 +1,22 @@
.. _compatibility:cables:
Cables
######
* 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 `dirtyjtag2 <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)
* `Tang Nano 4k USB-JTAG interface <https://github.com/sipeed/RV-Debugger-BL702>`__: USB-JTAG/UART debugger based on BL702 microcontroler.
* `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

35
doc/compatibility/fpga.rst Normal file
View File

@ -0,0 +1,35 @@
.. _compatibility:fpgas:
FPGAs
#####
======== =================================================================================================================================== ====== =====
Vendor Model Memory Flash
======== =================================================================================================================================== ====== =====
Anlogic `EG4S20 <http://www.anlogic.com/prod_view.aspx?TypeId=10&Id=168&FId=t3:10:3>`__ OK AS
Efinix `Trion T8 <https://www.efinixinc.com/products-trion.html>`__ NA OK
Gowin `GW1N (GW1N-1, GW1N-4, GW1NR-9, GW1NS-2C, GW1NSR-4C) <https://www.gowinsemi.com/en/product/detail/2/>`__ OK IF
Intel Cyclone III `EP3C16 <https://www.intel.com/content/www/us/en/programmable/products/fpga/cyclone-series/cyclone-iii/support.html>`__ OK OK
Intel Cyclone IV CE `EP4CE22 <https://www.intel.com/content/www/us/en/products/programmable/fpga/cyclone-iv/features.html>`__ OK OK
Intel Cyclone V E `5CEA2, 5CEBA4 <https://www.intel.com/content/www/us/en/products/programmable/fpga/cyclone-v.html>`__ OK OK
Intel Cyclone 10 LP `10CL025 <https://www.intel.com/content/www/us/en/products/programmable/fpga/cyclone-10.html>`__ OK OK
Lattice `CrossLink-NX (LIFCL-40) <https://www.latticesemi.com/en/Products/FPGAandCPLD/CrossLink-NX>`__ OK OK
Lattice `ECP5 (25F, 5G 85F) <http://www.latticesemi.com/Products/FPGAandCPLD/ECP5>`__ OK OK
Lattice `iCE40 (HX1K, HX4K, HX8K, UP5K) <https://www.latticesemi.com/en/Products/FPGAandCPLD/iCE40>`__ NA AS
Lattice `MachXO2 <https://www.latticesemi.com/en/Products/FPGAandCPLD/MachXO2>`__ OK OK
Lattice `MachXO3D <http://www.latticesemi.com/en/Products/FPGAandCPLD/MachXO3D.aspx>`__ OK OK
Lattice `MachXO3LF <http://www.latticesemi.com/en/Products/FPGAandCPLD/MachXO3.aspx>`__ OK OK
Xilinx Artix 7 `xc7a35ti, xc7a50t, xc7a75t, xc7a100t, xc7a200t <https://www.xilinx.com/products/silicon-devices/fpga/artix-7.html>`__ OK OK
Xilinx Kintex 7 `xc7k325t <https://www.xilinx.com/products/silicon-devices/fpga/kintex-7.html#productTable>`__ OK NT
Xilinx Spartan 3 `xc3s200 <https://www.xilinx.com/products/silicon-devices/fpga/spartan-3.html>`__ OK NA
Xilinx Spartan 6 `xc6slx9, xc6slx16, xc6slx25, xc6slx45 <https://www.xilinx.com/products/silicon-devices/fpga/spartan-6.html>`__ OK OK
Xilinx Spartan 7 `xc7s15, xc7s25, xc7s50 <https://www.xilinx.com/products/silicon-devices/fpga/spartan-7.html>`__ OK OK
Xilinx XC9500XL `xc9536xl, xc9572xl, xc95144xl, xc95188xl <https://www.xilinx.com/support/documentation/data_sheets/ds054.pdf>`__ NA OK
Xilinx XC2C (coolrunner II) `xc2c32a <https://www.xilinx.com/support/documentation/data_sheets/ds090.pdf>`__ TBD OK
Xilinx XCF `xcf01s, xcf02s, xcf04s <https://www.xilinx.com/products/silicon-devices/configuration-memory/platform-flash.html>`__ NA OK
======== =================================================================================================================================== ====== =====
* IF: Internal Flash
* AS: Active Serial flash mode
* NA: Not Available
* NT: Not Tested

103
doc/conf.py Normal file
View File

@ -0,0 +1,103 @@
# -*- coding: utf-8 -*-
from sys import path as sys_path
from os.path import abspath
from pathlib import Path
from json import loads
ROOT = Path(__file__).resolve().parent
sys_path.insert(0, abspath("."))
# -- General configuration ------------------------------------------------
extensions = [
# Standard Sphinx extensions
"sphinx.ext.extlinks",
"sphinx.ext.intersphinx",
]
templates_path = ["_templates"]
source_suffix = {
".rst": "restructuredtext",
}
master_doc = "index"
project = u"openFPGALoader: universal utility for programming FPGA"
copyright = u"2019-2021, Gwenhael Goavec-Merou and contributors"
author = u"Gwenhael Goavec-Merou and contributors"
version = "latest"
release = version # The full version, including alpha/beta/rc tags.
language = None
exclude_patterns = []
numfig = True
# -- Options for HTML output ----------------------------------------------
html_context = {}
ctx = ROOT / "context.json"
if ctx.is_file():
html_context.update(loads(ctx.open("r").read()))
if (ROOT / "_theme").is_dir():
html_theme_path = ["."]
html_theme = "_theme"
html_theme_options = {
"home_breadcrumbs": False,
"vcs_pageview_mode": "blob",
}
else:
html_theme = "alabaster"
htmlhelp_basename = "OFLDoc"
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
"papersize": "a4paper",
}
latex_documents = [
(master_doc, "OFLDoc.tex", u"openFPGALoader: universal utility for programming FPGA (Documentation)", author, "manual"),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [(master_doc, "openFPGALoader", u"Universal utility for programming FPGA (Documentation)", [author], 1)]
# -- Options for Texinfo output -------------------------------------------
texinfo_documents = [
(
master_doc,
"openFPGALoader",
u"Universal utility for programming FPGA (Documentation)",
author,
"openFPGALoader",
"HDL verification.",
"Miscellaneous",
),
]
# -- Sphinx.Ext.InterSphinx -----------------------------------------------
intersphinx_mapping = {
"python": ("https://docs.python.org/3/", None),
}
# -- Sphinx.Ext.ExtLinks --------------------------------------------------
extlinks = {
"wikipedia": ("https://en.wikipedia.org/wiki/%s", None),
"ghsharp": ("https://github.com/trabucayre/openFPGALoader/issues/%s", "#"),
"ghissue": ("https://github.com/trabucayre/openFPGALoader/issues/%s", "issue #"),
"ghpull": ("https://github.com/trabucayre/openFPGALoader/pull/%s", "pull request #"),
"ghsrc": ("https://github.com/trabucayre/openFPGALoader/blob/master/%s", None),
}

20
doc/efinix.md
View File

@ -1,20 +0,0 @@
# 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)

47
doc/first-steps.md
View File

@ -1,47 +0,0 @@
# 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).

30
doc/fpga-compatibility-list.md
View File

@ -1,30 +0,0 @@
# FPGA compatibility list
| Vendor | Model | Memory | Flash |
|--------:|:---------------------------------------------------------------------------------------------------------------------------------|:-------|:------|
| Anlogic | [EG4S20](http://www.anlogic.com/prod_view.aspx?TypeId=10&Id=168&FId=t3:10:3) | OK | AS |
| Efinix | [Trion T8](https://www.efinixinc.com/products-trion.html) | NA | OK |
| Gowin | [GW1N (GW1N-1, GW1N-4, GW1NR-9, GW1NS-2C, GW1NSR-4C)](https://www.gowinsemi.com/en/product/detail/2/) | OK | IF |
| Intel | Cyclone III [EP3C16](https://www.intel.com/content/www/us/en/programmable/products/fpga/cyclone-series/cyclone-iii/support.html) | OK | OK |
| | Cyclone IV CE [EP4CE22](https://www.intel.com/content/www/us/en/products/programmable/fpga/cyclone-iv/features.html) | OK | OK |
| | Cyclone V E [5CEA2, 5CEBA4](https://www.intel.com/content/www/us/en/products/programmable/fpga/cyclone-v.html) | OK | OK |
| | Cyclone 10 LP [10CL025](https://www.intel.com/content/www/us/en/products/programmable/fpga/cyclone-10.html) | OK | OK |
| Lattice | [CrossLink-NX (LIFCL-40)](https://www.latticesemi.com/en/Products/FPGAandCPLD/CrossLink-NX) | OK | OK |
| | [ECP5 (25F, 5G 85F](http://www.latticesemi.com/Products/FPGAandCPLD/ECP5) | OK | OK |
| | [iCE40 (HX1K, HX4K, HX8K, UP5K)](https://www.latticesemi.com/en/Products/FPGAandCPLD/iCE40) | NA | AS |
| | [MachXO2](https://www.latticesemi.com/en/Products/FPGAandCPLD/MachXO2) | OK | OK |
| | [MachXO3D](http://www.latticesemi.com/en/Products/FPGAandCPLD/MachXO3D.aspx) | OK | OK |
| | [MachXO3LF](http://www.latticesemi.com/en/Products/FPGAandCPLD/MachXO3.aspx) | OK | OK |
| Xilinx | Artix 7 [xc7a35ti, xc7a50t, xc7a75t, xc7a100t, xc7a200t](https://www.xilinx.com/products/silicon-devices/fpga/artix-7.html) | OK | OK |
| | Kintex 7 [xc7k325t](https://www.xilinx.com/products/silicon-devices/fpga/kintex-7.html#productTable) | OK | NT |
| | Spartan 3 [xc3s200](https://www.xilinx.com/products/silicon-devices/fpga/spartan-3.html) | OK | NA |
| | Spartan 6 [xc6slx9, xc6slx16, xc6slx25, xc6slx45](https://www.xilinx.com/products/silicon-devices/fpga/spartan-6.html) | OK | OK |
| | Spartan 7 [xc7s15, xc7s25, xc7s50](https://www.xilinx.com/products/silicon-devices/fpga/spartan-7.html) | OK | OK |
| | XC9500XL [xc9536xl, xc9572xl, xc95144xl, xc95188xl](https://www.xilinx.com/support/documentation/data_sheets/ds054.pdf) | NA | OK |
| | XC2C (coolrunner II) [xc2c32a](https://www.xilinx.com/support/documentation/data_sheets/ds090.pdf) | TBD | OK |
| | XCF [xcf01s, xcf02s, xcf04s](https://www.xilinx.com/products/silicon-devices/configuration-memory/platform-flash.html) | NA | OK |
- *IF* Internal Flash
- *AS* Active Serial flash mode
- *NA* Not Available
- *NT* Not Tested

37
doc/gowin.md
View File

@ -1,37 +0,0 @@
# Gowin notes
## GOWIN GW1N (Trenz TEC0117, Sipeed Tang Nano, Sipeed Tang Nano 4K, Honeycomb and RUNBER)
*.fs* file is the default format generated by *Gowin IDE*, so nothing
special must be done to generates this file.
Since the same file is used for SRAM and Flash a CLI argument is used to
specify the destination.
### Flash SRAM
with **-m**
```bash
openFPGALoader -m -b BOARD_NAME impl/pnr/*.fs
```
where *BOARD_NAME* is:
- *tec0117*
- *tangnano*
- *tangnano4k"
- *runber*
### Flash (only with Trenz TEC0117 and runber):
with **-f**
__file load__:
```bash
openFPGALoader -f -b BOARD_NAME impl/pnr/*.fs
```
where *BOARD_NAME* is:
- **tec0117**
- **runber**
It's possible to flash external SPI Flash (connected to MSPI) in bscan mode
by using `--external-flash` instead of `-f`

75
doc/guide/advanced.rst Normal file
View File

@ -0,0 +1,75 @@
.. _advanced-usage:
Advanced usage of openFPGALoader
################################
Resetting an FPGA
=================
.. code-block:: bash
openFPGALoader [options] -r
Reading the bitstream from STDIN
================================
.. code-block:: 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:
.. code-block:: 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:
.. code-block:: 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.

65
doc/guide/first-steps.rst Normal file
View File

@ -0,0 +1,65 @@
.. _first-steps:
First steps with openFPGALoader
###############################
Install
=======
Packages are available for Linux distributionsm, Windows (MSYS2) and macOS:
* *Arch Linux*: ``sudo pacman -S openfpgaloader``
* *Fedora*: ``sudo dnf copr enable mobicarte/openFPGALoader; sudo dnf install openFPGALoader``
* *MSYS2*: ``pacman -S mingw-w64-ucrt-x86_64-openFPGALoader``
* *macOS*: ``brew install openfpgaloader``
More instructions for other installation scenarios are available in :ref:`install`.
Programming a development board
===============================
Just simply replace ``my_fpga_board`` with any FPGA board from :ref:`compatibility:boards`
(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):
.. code-block:: 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 an "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 :ref:`compatibility:cables` (or ``openFPGALoader --list-cables``):
.. code-block:: 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.
.. HINT::
FTDI/FTDI-compatible cable users: the ``-d`` option lets you specify a specific FTDI device:
.. code-block:: 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 :ref:`troubleshooting`.

140
doc/guide/install.rst Normal file
View File

@ -0,0 +1,140 @@
.. _install:
Installing openFPGALoader
#########################
Linux
=====
Arch Linux
----------
openFPGALoader is available in the default repositories:
.. code-block:: bash
sudo pacman -S openfpgaloader
Fedora
------
openFPGALoader is available as a Copr repository:
.. code-block:: bash
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 on the distribution, headers too):
.. code-block:: bash
apt-get install
libftdi1-2 \
libftdi1-dev \
libhidapi-hidraw0 \
libhidapi-dev \
libudev-dev \
zlib1g-dev \
cmake \
pkg-config \
make \
g++
.. HINT::
``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:
.. code-block:: bash
-DENABLE_UDEV=OFF
By default, ``cmsisdap`` support is enabled (used for colorlight I5).
If you don't want this option, use:
.. code-block:: bash
-DENABLE_CMSISDAP=OFF
Alternatively you can manually specify the location of ``libusb`` and ``libftdi1``:
.. code-block:: 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``:
.. code-block:: bash
-DLINK_CMAKE_THREADS=ON
To build the app:
.. code-block:: 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
.. code-block:: 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 (:ghsrc:`99-openfpgaloader.rules <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.
.. code-block:: 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 $USER -G plugdev # add user to plugdev group
After that you need to unplug and replug your device.
macOS
=====
openFPGALoader is available as a `Homebrew <https://brew.sh>`__ formula:
.. code-block:: bash
brew install openfpgaloader
Windows
=======
Common
======
Bitstreams for *XC2C (coolrunner-II)* needs to be remapped using ``.map`` shipped with *ISE*.
*ISE* path is set at configure time using:
.. code-block:: bash
-DISE_PATH=/somewhere/Xilinx/ISE_VERS/
default: ``/opt/Xilinx/14.7``.

10
doc/guide/troubleshooting.rst Normal file
View File

@ -0,0 +1,10 @@
.. _troubleshooting:
Troubleshooting
###############
I installed openFPGALoader but it says `command not found` when I try to launch it
==================================================================================
The correct spelling of the program is *openFPGALoader* with FPGA and the "L" of "Loader" in uppercase.
Ensure the spelling of the program is correct.

57
doc/index.rst Normal file
View File

@ -0,0 +1,57 @@
openFPGALoader: universal utility for programming FPGA
######################################################
Welcome to the documentation of openFPGALoader!
openFPGALoader is a universal utility for programming FPGAs.
Compatible with many boards, cables and FPGA from major manufacturers (Xilinx, Altera/Intel, Lattice, Gowin, Efinix, Anlogic).
openFPGALoader works on Linux, Windows and macOS.
Not sure if your hardware is supported? Check the hardware compatibility lists:
* :ref:`compatibility:fpgas`
* :ref:`compatibility:boards`
* :ref:`compatibility:cables`
Also checkout the vendor-specific documentation:
* `Anlogic <https://trabucayre.github.io/openFPGALoader/vendors/anlogic.html>`__
* `Efinix <https://trabucayre.github.io/openFPGALoader/vendors/efinix.html>`__
* `Gowin <https://trabucayre.github.io/openFPGALoader/vendors/gowin.html>`__
* `Intel/Altera <https://trabucayre.github.io/openFPGALoader/vendors/intel.html>`__
* `Lattice <https://trabucayre.github.io/openFPGALoader/vendors/lattice.html>`__
* `Xilinx <https://trabucayre.github.io/openFPGALoader/vendors/xilinx.html>`__
.. toctree::
:caption: User Guide
:hidden:
guide/first-steps
guide/install
guide/troubleshooting
guide/advanced
.. toctree::
:caption: Compatibility
:hidden:
compatibility/fpga
compatibility/board
compatibility/cable
.. toctree::
:caption: Vendors
:hidden:
vendors/anlogic
vendors/efinix
vendors/gowin
vendors/intel
vendors/lattice
vendors/xilinx
.. toctree::
:caption: Development
:hidden:
todo

42
doc/intel.md
View File

@ -1,42 +0,0 @@
# Intel notes
## Intel/Altera: CYC1000, DE0, de0nano
### Loading a bitstream
`SVF` and `RBF` files are supported:
sof to svf generation:
```bash
quartus_cpf -c -q -g 3.3 -n 12.0MHz p project_name.sof project_name.svf
```
sof to rbf generation:
```bash
quartus_cpf --option=bitstream_compression=off -c project_name.sof project_name.rbf
```
<span style="color:red">**Warning: as mentionned in `cyclone` handbooks, real-time decompression is not
supported by FPGA in JTAG mode. Keep in mind to disable this option.**</span>
file load:
```bash
openFPGALoader -b boardname project_name.svf
# or
openFPGALoader -b boardname project_name.rbf
```
with `boardname` = `de0`, `cyc1000`, `de0nano`, `de0nanoSoc` or `qmtechCycloneV`
### SPI flash:
`RPD` and `RBF` are supported
sof to rpd:
```bash
quartus_cpf -o auto_create_rpd=on -c -d EPCQ16A -s 10CL025YU256C8G project_name.svf project_name.jic
```
file load:
```bash
openFPGALoader -b cyc1000 -r project_name_auto.rpd
# or
openFPGALoader -b cyc1000 -r project_name.rbf
```

79
doc/lattice.md
View File

@ -1,79 +0,0 @@
# Lattice notes
## MachXO2/MachXO3
### Flash memory:
*.jed* file is the default format generated by *Lattice Diamond*, so nothing
special must be done to generates this file.
__file load__:
```bash
openFPGALoader [-b yourboard] impl1/*.jed
```
where *yourboard* may be:
* *machX02EVN*
* *machXO3SK*
### SRAM:
To generates *.bit* file **Bitstream file** must be checked under **Exports Files** in *Lattice Diamond* left panel.
__file load__:
```bash
openFPGALoader [-b yourboard] impl1/*.bit
```
where *yourboard* may be:
* *machX02EVN*
* *machXO3SK*
## iCE40
*.bin* is the default format generated by *nextpnr*, so nothing special
must be done.
Since most ice40 boards uses the same pinout between *FTDI* and *SPI flash* a generic *ice40_generic* board is provided.
For the specific case of the *iCE40HXXK-EVB* where no onboard programmer is present, please use this:
| FTDI | iCE40HXXK-EVB |
|--------------|----------------------|
| SCK (ADBUS0) | Pin 9 |
| SI (ADBUS1) | Pin 8 |
| SO (ADBUS2) | Pin 7 |
| CS (ABDUS4) | Pin 10 |
| RST (ADBUS6 | Pin 6 |
| DONE (ADBUS7)| Pin 5 |
__bin file load__
```bash
openFPGALoader -b ice40_generic /somewhere/*.bin
```
Since it's a direct access to the flash (SPI) the *-b* option is required.
## ECP5/Crosslink-NX
### SRAM:
```bash
openFPGALoader [-b yourBoard] [-c yourCable] -m project_name/*.bit
```
**By default, openFPGALoader load bitstream in memory, so the '-m' argument is optional**
### SPI Flash:
#### bit
```bash
openFPGALoader [-b yourBoard] [-c yourCable] -f project_name/*.bit # or *.bin
```
#### mcs
To generates *.mcs* file **PROM File** must be checked under **Exports Files** in *Lattice Diamond* left panel.
```bash
openFPGALoader [-b yourBoard] [-c yourCable] project_name/*.mcs
```

1
doc/requirements.txt Normal file
View File

@ -0,0 +1 @@
sphinx

31
doc/todo.rst Normal file
View File

@ -0,0 +1,31 @@
.. _todo:
To Do
#####
Global
======
* improve error message (be more precise)
* catch all exception
* documentation (code + API)
Cable
=====
* fix *ch552* (*Sipeed tangNano*): works with *SRAM*, fails with *Flash*
* *busblaster* support
* *anlogic* cable support
Devices/boards
==============
* improve frequency configuration. Use FPGA, cable or --freq args maximum frequency
* rework *cyclone10* eeprom access to avoid using FT2232 interfaceB Spi emulation (only supported by trenz board)
* fix checksum computation with *gowin GW2A*
* add support for *tangPrimer* (*anlogic EG4S20*)
Misc
====
* fix spiFlash class to be able to write everywhere (currently offset is hardcoded to 0)

5
doc/troubleshooting.md
View File

@ -1,5 +0,0 @@
# Troubleshooting
## I installed openFPGALoader but it says `command not found` when I try to launch it
The correct spelling of the program is *openFPGALoader* with FPGA and the "L" of "Loader" in uppercase. Ensure the spelling of the program is correct.

53
doc/vendors/anlogic.rst vendored Normal file
View File

@ -0,0 +1,53 @@
.. _anlogic:
Anlogic notes
#############
Sipeed Lichee Tang
==================
For this target, *openFPGALoader* supports *svf* and *bit*.
bit file load (memory)
----------------------
.. code-block:: bash
openFPGALoader -m -b licheeTang /somewhere/project/prj/*.bit
Since ``-m`` is the default, this argument is optional.
bit file load (spi flash)
-------------------------
.. code-block:: 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>`__:
.. code-block:: bash
mkdir build
cd build
cmake ../
make
Now a file called *tangbit* is present in current directory and has to be used as follows:
.. code-block:: bash
tangbit --input /somewhere.bit --svf bitstream.svf
.. code-block:: bash
openFPGALoader -b licheeTang /somewhere/*.svf

27
doc/vendors/efinix.rst vendored Normal file
View File

@ -0,0 +1,27 @@
.. _efinix:
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* supports only active mode (SPI) (*JTAG* is WIP).
hex file load
-------------
.. code-block:: bash
openFPGALoader -b fireant /somewhere/project/outflow/*.hex
or, for xyloni board
.. code-block:: 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).

55
doc/vendors/gowin.rst vendored Normal file
View File

@ -0,0 +1,55 @@
.. _gowin:
Gowin notes
###########
GOWIN GW1N
==========
.. NOTE::
* Trenz TEC0117
* Sipeed Tang Nano
* Sipeed Tang Nano 4K
* Honeycomb
* RUNBER
``.fs`` file is the default format generated by *Gowin IDE*, so nothing special must be done to generates this file.
Since the same file is used for SRAM and Flash a CLI argument is used to specify the destination.
Flash SRAM
----------
with ``-m``:
.. code-block:: bash
openFPGALoader -m -b BOARD_NAME impl/pnr/*.fs
where ``BOARD_NAME`` is:
* ``tec0117``
* ``tangnano``
* ``tangnano4k``
* ``runber``
Flash
-----
.. ATTENTION::
Only with Trenz TEC0117 and runber.
with ``-f``, file load:
.. code-block:: bash
openFPGALoader -f -b BOARD_NAME impl/pnr/*.fs
where ``BOARD_NAME`` is:
* ``tec0117``
* ``runber``
It's possible to flash external SPI Flash (connected to MSPI) in bscan mode by using ``--external-flash`` instead of
``-f``.

63
doc/vendors/intel.rst vendored Normal file
View File

@ -0,0 +1,63 @@
.. _intel:
Intel notes
###########
Intel/Altera
============
.. NOTE::
* CYC1000
* DE0
* de0nano
Loading a bitstream
-------------------
SVF and RBF files are supported.
``sof`` to ``svf`` generation:
.. code-block:: bash
quartus_cpf -c -q -g 3.3 -n 12.0MHz p project_name.sof project_name.svf
``sof`` to ``rbf`` generation:
.. code-block:: bash
quartus_cpf --option=bitstream_compression=off -c project_name.sof project_name.rbf
.. WARNING::
As mentionned in ``cyclone`` handbooks, real-time decompression is not supported by FPGA in JTAG mode.
Keep in mind to disable this option.
file load:
.. code-block:: bash
openFPGALoader -b boardname project_name.svf
# or
openFPGALoader -b boardname project_name.rbf
with ``boardname`` = ``de0``, ``cyc1000``, ``de0nano``, ``de0nanoSoc`` or ``qmtechCycloneV``.
SPI flash
---------
RPD and RBF are supported.
``sof`` to ``rpd``:
.. code-block:: bash
quartus_cpf -o auto_create_rpd=on -c -d EPCQ16A -s 10CL025YU256C8G project_name.svf project_name.jic
file load:
.. code-block:: bash
openFPGALoader -b cyc1000 -r project_name_auto.rpd
# or
openFPGALoader -b cyc1000 -r project_name.rbf

98
doc/vendors/lattice.rst vendored Normal file
View File

@ -0,0 +1,98 @@
.. _lattice:
Lattice notes
#############
MachXO2/MachXO3
===============
Flash memory
------------
``.jed`` file is the default format generated by *Lattice Diamond*, so nothing special must be done to generates this
file.
File load:
.. code-block:: bash
openFPGALoader [-b yourboard] impl1/*.jed
where ``yourboard`` may be:
* ``machX02EVN``
* ``machXO3SK``
SRAM
----
To generates ``.bit`` file *Bitstream file* must be checked under *Exports Files* in *Lattice Diamond* left panel.
File load:
.. code-block:: bash
openFPGALoader [-b yourboard] impl1/*.bit
where ``yourboard`` may be:
* ``machX02EVN``
* ``machXO3SK``
iCE40
=====
``.bin`` is the default format generated by *nextpnr*, so nothing special must be done.
Since most ice40 boards uses the same pinout between *FTDI* and *SPI flash* a generic *ice40_generic* board is provided.
For the specific case of the *iCE40HXXK-EVB* where no onboard programmer is present, please use this:
============= ===============
FTDI iCE40HXXK-EVB
============= ===============
SI (ADBUS1) Pin 8
SCK (ADBUS0) Pin 9
SO (ADBUS2) Pin 7
CS (ABDUS4) Pin 10
RST (ADBUS6 Pin 6
DONE (ADBUS7) Pin 5
============= ===============
Bin file load:
.. code-block:: bash
openFPGALoader -b ice40_generic /somewhere/*.bin
Since it's a direct access to the flash (SPI) the ``-b`` option is required.
ECP5/Crosslink-NX
=================
SRAM
----
.. code-block:: bash
openFPGALoader [-b yourBoard] [-c yourCable] -m project_name/*.bit
.. HINT::
By default, openFPGALoader loads bitstream in memory, so the ``-m`` argument is optional.
SPI Flash
---------
BIT:
.. code-block:: bash
openFPGALoader [-b yourBoard] [-c yourCable] -f project_name/*.bit # or *.bin
MCS:
To generate ``.mcs`` file *PROM File* must be checked under *Exports Files* in *Lattice Diamond* left panel.
.. code-block:: bash
openFPGALoader [-b yourBoard] [-c yourCable] project_name/*.mcs

98
doc/vendors/xilinx.rst vendored Normal file
View File

@ -0,0 +1,98 @@
.. _xilinx:
Xilinx notes
############
To simplify further explanations, we consider the project is generated in the current directory.
.. NOTE::
1. Spartan Edge Accelerator Board has only pinheader, so the cable must be provided
2. A *JTAG* <-> *SPI* bridge (used to write bitstream in FLASH) is available for some device, see
:ghsrc:`spiOverJtag <spiOverJtag>` to check if your model is supported.
3. Board provides the device/package model, but if the targeted board is not officially supported but the FPGA yes,
you can use ``--fpga-part`` to provide the model.
4. With spartan3, the flash is an independent JTAG device.
User has to use ``--index-chain`` to access FPGA (RAM only) or flash (write/read only).
.. WARNING::
``*.bin`` may be loaded in memory or in flash, but this extension is a classic extension for CPU firmware and, by
default, *openFPGALoader* loads file in memory.
Double check ``-m`` / ``-f`` when you want to use a firmware for a softcore (or anything, other than a bitstream) to
write somewhere in the FLASH device).
``.bit`` file is the default format generated by *vivado*, so nothing special task must be done to generate this
bitstream.
``.bin`` is not, by default, produced.
To have access to this file you need to configure the tool:
- GUI: *Tools* -> *Settings* -> *Bitstreams* -> check ``-bin_file``.
- TCL: append your *TCL* file with ``set_property STEPS.WRITE_BITSTREAM.ARGS.BIN_FILE true [get_runs impl_1]``.
.. WARNING::
For alchitry board the bitstream must be configured with a buswidth of 1 or 2.
Quad mode can't be used with alchitry's FLASH.
Loading a bitstream
===================
``.bit`` and ``.bin`` are allowed to be loaded in memory.
File load:
.. code-block:: bash
openFPGALoader [-m] -b arty *.runs/impl_1/*.bit (or *.bin)
or
.. code-block:: bash
openFPGALoader [-m] -b spartanEdgeAccelBoard -c digilent_hs2 *.runs/impl_1/*.bit (or *.bin)
SPI flash
---------
.. NOTE::
``.bit``, ``.bin``, and ``.mcs`` are supported for FLASH.
``.mcs`` must be generated through vivado with a tcl script like:
.. code-block:: tcl
set project [lindex $argv 0]
set bitfile "${project}.runs/impl_1/${project}.bit"
set mcsfile "${project}.runs/impl_1/${project}.mcs"
write_cfgmem -format mcs -interface spix4 -size 16 \
-loadbit "up 0x0 $bitfile" -loaddata "" \
-file $mcsfile -force
.. NOTE::
``-interface spix4`` and ``-size 16`` depends on SPI flash capability and size.
The tcl script is used with:
.. code-block:: bash
vivado -nolog -nojournal -mode batch -source script.tcl -tclargs myproject
File load:
.. code-block:: bash
openFPGALoader [--fpga-part xxxx] -f -b arty *.runs/impl_1/*.mcs (or .bit / .bin)
.. NOTE::
``-f`` is required to write bitstream (without them ``.bit`` and ``.bin`` are loaded in memory).
.. NOTE::
``--fpga-part`` is only required if this information is not provided at ``board.hpp`` level or if the board is not
officially supported.
device/packagee format is something like xc7a35tcsg324 (arty model).
See :ghsrc:`src/board.hpp <src/board.hpp>`, or :ghsrc:`spiOverJtag <spiOverJtag>` directory for examples.

76
doc/xilinx.md
View File

@ -1,76 +0,0 @@
# Xilinx notes
To simplify further explanations, we consider the project is generated in the
current directory.
**Note:**
1. Spartan Edge Accelerator Board has only pinheader, so the cable must be provided
2. a *JTAG* <-> *SPI* bridge (used to write bitstream in FLASH) is available for some device, see
[spiOverJtag](https://github.com/trabucayre/openFPGALoader/tree/master/spiOverJtag) to check if your model is supported
3. board provides the device/package model, but if the targeted board is not
officially supported but the FPGA yes, you can use --fpga-part to provides
model
4. with spartan3 the flash is an independent JTAG device. User has to use
`--index-chain` to access FPGA (RAM only) or flash (write/read only)
<span style="color:red">**Warning** *.bin* may be loaded in memory or in flash, but this extension is a classic extension
for CPU firmware and, by default, *openFPGALoader* load file in memory, double check
*-m* / *-f* when you want to use a firmware for a softcore
(or anything, other than a bitstream) to write somewhere in the FLASH device).</span>
*.bit* file is the default format generated by *vivado*, so nothing special
task must be done to generates this bitstream.
*.bin* is not, by default, produces. To have access to this file you need to configure the tool:
- **GUI**: *Tools* -> *Settings* -> *Bitstreams* -> check *-bin_file*
- **TCL**: append your *TCL* file with `set_property STEPS.WRITE_BITSTREAM.ARGS.BIN_FILE true [get_runs impl_1]`
<span style="color:red">**Warning: for alchitry board the bitstream must be configured with a buswidth of 1 or 2. Quad mode can't be used with alchitry's FLASH**</span>
## Loading a bitstream
<span style="text-decoration:underline">*.bit* and *.bin* are allowed to be loaded in memory.</span>
__file load:__
```bash
openFPGALoader [-m] -b arty *.runs/impl_1/*.bit (or *.bin)
```
or
```bash
openFPGALoader [-m] -b spartanEdgeAccelBoard -c digilent_hs2 *.runs/impl_1/*.bit (or *.bin)
```
### SPI flash:
<span style="text-decoration:underline">*.bit*, *.bin*, and *.mcs* are supported for FLASH.</span>
.mcs must be generates through vivado with a tcl script like
```tcl
set project [lindex $argv 0]
set bitfile "${project}.runs/impl_1/${project}.bit"
set mcsfile "${project}.runs/impl_1/${project}.mcs"
write_cfgmem -format mcs -interface spix4 -size 16 \
-loadbit "up 0x0 $bitfile" -loaddata "" \
-file $mcsfile -force
```
**Note:
*-interface spix4* and *-size 16* depends on SPI flash capability and size.**
The tcl script is used with:
```bash
vivado -nolog -nojournal -mode batch -source script.tcl -tclargs myproject
```
__file load:__
```bash
openFPGALoader [--fpga-part xxxx] -f -b arty *.runs/impl_1/*.mcs (or .bit / .bin)
```
**Note: *-f* is required to write bitstream (without them *.bit* and *.bin* are loaded in memory)**
Note: "--fpga-part" is only required if this information is not provided at
board.hpp level or if the board is not officially supported. device/packagee
format is something like xc7a35tcsg324 (arty model). See src/board.hpp, or
spiOverJtag directory for examples.