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

.. WARNING::
  For boards based on a Zynq (7000 or MPSoC), boot mode must be configured for JTAG (for Zedboard JP7->JP11 must be
  to GND).

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:

.. WARNING::
  For boards based on Zynq device (7000 and MPSoC) SPI flash is not accessible through PL.

.. 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/package format is something like xc7a35tcsg324 (arty model).
  See :ghsrc:`src/board.hpp <src/board.hpp>`, or :ghsrc:`spiOverJtag <spiOverJtag>` directory for examples.

Some boards with UltraScale FPGAs, like the VCU118 and KCU16, support the SPIx8 (Dual Quad SPI) configuration.
In this case, the ``spix8`` option ``write_cfgmem`` on the above example can be used to generate two ``.mcs`` files,
to fit bigger designs or for faster programming. Only ``.mcs`` files can be used to program the FPGA in this case.

In this case, to load the two ``.mcs`` files:

.. code-block:: bash

    openFPGALoader --board vcu118 -f --target-flash both --bitstream *.runs/impl_1/*_primary.mcs --secondary-bitstream *.runs/impl_1/*_secondary.mcs

On these boards, each SPI flash can be programmed independently with the ``--target-flash`` option.
The default target is the ``primary`` flash.

For example, to program only the secondary flash with arbitrary data not related to FPGA configuration:

.. code-block:: bash

    openFPGALoader --board vcu118 -f --target-flash secondary --bitstream arbitrary_data