diff --git a/doc/anlogic.md b/doc/anlogic.md deleted file mode 100644 index f15ba8b..0000000 --- a/doc/anlogic.md +++ /dev/null @@ -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 -``` \ No newline at end of file diff --git a/doc/efinix.md b/doc/efinix.md deleted file mode 100644 index 880f031..0000000 --- a/doc/efinix.md +++ /dev/null @@ -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) \ No newline at end of file diff --git a/doc/gowin.md b/doc/gowin.md deleted file mode 100644 index 70a629e..0000000 --- a/doc/gowin.md +++ /dev/null @@ -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` diff --git a/doc/index.rst b/doc/index.rst index 331b92e..f80d77e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -2,3 +2,31 @@ openFPGALoader: 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 diff --git a/doc/intel.md b/doc/intel.md deleted file mode 100644 index 2d64b8d..0000000 --- a/doc/intel.md +++ /dev/null @@ -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 -``` - -**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: -```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 -``` \ No newline at end of file diff --git a/doc/lattice.md b/doc/lattice.md deleted file mode 100644 index 32abd6f..0000000 --- a/doc/lattice.md +++ /dev/null @@ -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 -``` diff --git a/doc/vendors/anlogic.rst b/doc/vendors/anlogic.rst new file mode 100644 index 0000000..99eb042 --- /dev/null +++ b/doc/vendors/anlogic.rst @@ -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 `__: + +.. 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 diff --git a/doc/vendors/efinix.rst b/doc/vendors/efinix.rst new file mode 100644 index 0000000..8fe30dc --- /dev/null +++ b/doc/vendors/efinix.rst @@ -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). diff --git a/doc/vendors/gowin.rst b/doc/vendors/gowin.rst new file mode 100644 index 0000000..7f88990 --- /dev/null +++ b/doc/vendors/gowin.rst @@ -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``. diff --git a/doc/vendors/intel.rst b/doc/vendors/intel.rst new file mode 100644 index 0000000..f8f0fcb --- /dev/null +++ b/doc/vendors/intel.rst @@ -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 diff --git a/doc/vendors/lattice.rst b/doc/vendors/lattice.rst new file mode 100644 index 0000000..cd9999d --- /dev/null +++ b/doc/vendors/lattice.rst @@ -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 diff --git a/doc/vendors/xilinx.rst b/doc/vendors/xilinx.rst new file mode 100644 index 0000000..ff63dbd --- /dev/null +++ b/doc/vendors/xilinx.rst @@ -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 ` 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 `, or :ghsrc:`spiOverJtag ` directory for examples. diff --git a/doc/xilinx.md b/doc/xilinx.md deleted file mode 100644 index 13d41a0..0000000 --- a/doc/xilinx.md +++ /dev/null @@ -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) - -**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). - -*.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]` - -**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:__ -```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: - -*.bit*, *.bin*, and *.mcs* are supported for FLASH. - -.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.