
Getting Started with F4PGA Toolchain development
################################################

.. warning::
   This documentation explains the first steps in the development of the toolchain itself.
   If you are looking for the **user documentation**, please look at :doc:`examples:index` instead.

This section provides an introduction on how to get started with the development of the F4PGA toolchain.
In order to generate a bitstream (or any intermediate file format), you can use one of the toolchain tests.
The following steps describe the whole process:

Clone repository
================

.. sourcecode:: bash

    git clone https://github.com/chipsalliance/f4pga-arch-defs.git

Prepare environment
===================

Download all the necessary packages, tools and databases into an isolated conda environment:

.. sourcecode:: bash

    cd f4pga-arch-defs
    make env

This also checks out all the submodules and generates the build system (``Make`` or ``Ninja``) from the CMake configuration.
If you want to use the ``Ninja`` build tool add this line before calling ``make env``:

.. sourcecode:: bash

    export CMAKE_FLAGS="-GNinja"

Build example
=============

While different architectures provide different build targets, there are some targets that should exist for all architectures.

Each architecture has its own toolchain backend that will be called during build.
(See `Project X-Ray <https://prjxray.readthedocs.io/en/latest/>`_
and `Project Trellis <https://prjtrellis.readthedocs.io/en/latest/>`_ for more information)

For development purposes a set of test designs are included for each supported architecture.
In order to perform a build of a test design with the ``Make`` build system enter the appropriate test build directory
specific to your target architecture and invoke desired make target.
Assuming that you would like to generate the bitstream ``.bit`` file with the counter example for the Arty board, which
uses Xilinx Artix-7 FPGA, you will execute the following:

.. sourcecode:: bash

  cd build/xc/xc7/tests/counter
  make counter_arty_bit

If you use ``Ninja`` then the target is accessible from root build directory:

.. sourcecode:: bash

  cd build
  ninja counter_arty_bit

.. note::

 Test design targets names are based on the following naming convention:  ``<design>_<platform>_<target_step>``, where ``<target_step>`` is the actual step to be done, e.g.: ``bit``, ``place``, ``route``, ``prog``.

.. warning::

  Generating architecture files is expected to take a long time to build, even on fast machines.

To build all demo bitstreams there are 3 useful targets:

.. sourcecode:: bash

  # Build all demo bitstreams, targetting all architectures
  make all_demos

  # Build all 7-series demo bitstreams
  make all_xc7

  # Build all ice40 demo bitstreams
  make all_ice40

Specific bitstreams can be built by specifying their target name, followed by a suffix specifying the desired output.
For example, the LUT-RAM test for the RAM64X1D primative is called `dram_test_64x1d`.
Example targets are:

.. sourcecode:: bash

  # Just run synthesis on the input Verilog
  make dram_test_64x1d_eblif

  # Complete synthesis and place and route the circuit
  make dram_test_64x1d_route

  # Create the output bitstream (including synthesis and place and route)
  make dram_test_64x1d_bin

  # Run bitstream back into Vivado for timing checks, etc.
  make dram_test_64x1d_vivado

Load bitstream
==============

The last step is to load the bitstream to your platform.
The final output file can be found in the appropriate test directory, i.e:
``build/xc/xc7/tests/counter/counter_arty/artix7-xc7a50t-arty-swbut-roi-virt-xc7a50t-arty-swbut-test/top.bit``

For every board the loading process may be different and different tools will be required.
``OpenOCD`` is the most widely used tool for loading bitstream in the F4PGA Toolchain.
It is provided as a conda package during the environment setup and ``CMake`` keeps track of its executable.
Other programming tools used in F4PGA that are automatically downloaded and referenced by ``CMake`` are ``tinyfpgab``
and ``tinyprog``.

For convenience the ``prog`` targets are provided for loading the bitstream, e.g.:

.. sourcecode:: bash

    make counter_arty_prog

or for ``Ninja``:

.. sourcecode:: bash

    ninja counter_arty_prog

.. note::
    Loading the bitstream into an FPGA can be done outside of the F4PGA.
    There are multiple tools for loading bitstreams into FPGA development boards.
    Typically, each tool supports a specific target family or the lines of products of a vendor.
    Some of the most known are listed in :ref:`hdl/constraints: Programming and debugging <constraints:ProgDebug>`.

OpenFPGALoader
--------------

OpenFPGALoader is an universal utility for programming the FPGA devices that is a great alternative to OpenOCD.
It supports many different boards with FPGAs based on the architectures including xc7, ECP5, iCE40 and many more.
It can utilize a variety of the programming adapters based on JTAG, DAP interface, ORBTrace, DFU and FTDI chips.

Installing OpenFPGALoader
*************************

OpenFPGALoader is available in several packaging solutions.
It can be installed with distribution specific package managers on Arch Linux and Fedora.
There are also prebuilt packages available in `conda <https://anaconda.org/litex-hub/openfpgaloader>`__
or packages in tool :gh:`repository <trabucayre/openFPGALoader/releases>`.
OpenFPGALoader can also be built from sources.
For installation guidelines using both prebuilt packages and building from source please refer to instructions in
:gh:`readme <trabucayre/openFPGALoader/blob/master/INSTALL.md>`.

Usage
*****

For programming the FPGA use one of these commands:

.. sourcecode:: bash

    openFPGALoader -b <board> <bitstream>           # (e.g. arty)
    openFPGALoader -c <cable> <bitstream>           # (e.g. digilent)
    openFPGALoader -d <device> <bitstream>          # (e.g. /dev/ttyUSB0)

You can also list the supported boards, cables and fpgas:

.. sourcecode:: bash

    openFPGALoader --list-boards
    openFPGALoader --list-cables
    openFPGALoader --list-fpga

If you encounter any issues, please refer to the :gh:`OpenFPGALoader README <trabucayre/openFPGALoader#readme>` as it
provides more useful information on the usage of the tool.