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

doc: convert vendor notes from md to rst

This commit is contained in:
umarcor 2021-11-28 08:41:15 +01:00
parent 53b3121c53
commit 2cb92af70f
13 changed files with 422 additions and 299 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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
```

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)

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`

28
doc/index.rst
View File

@ -2,3 +2,31 @@ openFPGALoader: universal utility for programming FPGA
###################################################### ######################################################
Welcome to the documentation of openFPGALoader (a universal utility for programming FPGA)! Welcome to the documentation of openFPGALoader (a universal utility for programming FPGA)!
.. toctree::
:caption: User Guide
:hidden:
first-steps
install
troubleshooting
advanced-usage
.. toctree::
:caption: Compatibility
:hidden:
fpga-compatibility-list
board-compatibility-list
cable-compatibility-list
.. toctree::
:caption: Vendors
:hidden:
vendors/anlogic
vendors/efinix
vendors/gowin
vendors/intel
vendors/lattice
vendors/xilinx

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
```

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.