boards/riscv/litex_vexriscv/doc/index.rst

.. _litex-vexriscv:

LiteX VexRiscv
##############

LiteX VexRiscv is an example of a system on a chip (SoC) that consists of
a `VexRiscv processor <https://github.com/SpinalHDL/VexRiscv>`_
and additional peripherals. This setup can be generated using
`Zephyr on LiteX VexRiscv (reference platform)
<https://github.com/litex-hub/zephyr-on-litex-vexriscv>`_
or `LiteX SoC Builder <https://github.com/enjoy-digital/litex>`_
and can be used on various FPGA chips.
The bitstream (FPGA configuration file) can be obtained using both
vendor-specific and open-source tools, including the
`F4PGA toolchain <https://f4pga.org/>`_.

The ``litex_vexriscv`` board configuration in Zephyr is meant for the
LiteX VexRiscv SoC implementation generated for the
`Digilent Arty A7-35T or A7-100T Development Boards
<https://store.digilentinc.com/arty-a7-artix-7-fpga-development-board-for-makers-and-hobbyists>`_.

.. image:: img/litex_vexriscv.jpg
   :align: center
   :alt: LiteX VexRiscv on Digilent Arty 35T Board

LiteX is based on
`Migen <https://m-labs.hk/gateware/migen/>`_/`MiSoC SoC builder <https://github.com/m-labs/misoc>`_
and provides ready-made system components such as buses, streams, interconnects,
common cores, and CPU wrappers to create SoCs easily. The tool contains
mechanisms for integrating, simulating, and building various designs
that target multiple chips of different vendors.
More information about the LiteX project can be found on
`LiteX's website <https://github.com/enjoy-digital/litex>`_.

VexRiscv is a 32-bit implementation of the RISC-V CPU architecture
written in the `SpinalHDL <https://spinalhdl.github.io/SpinalDoc-RTD/>`_.
The processor supports M, C, and A RISC-V instruction
set extensions, with numerous optimizations that include multistage
pipelines and data caching. The project provides many optional extensions
that can be used to customize the design (JTAG, MMU, MUL/DIV extensions).
The implementation is optimized for FPGA chips.
More information about the project can be found on
`VexRiscv's website <https://github.com/SpinalHDL/VexRiscv>`_.

To run the ZephyrOS on the VexRiscv CPU, it is necessary to prepare the
bitstream for the FPGA on a Digilent Arty A7-35 Board. This can be achieved
using the
`Zephyr on LiteX VexRiscv <https://github.com/litex-hub/zephyr-on-litex-vexriscv>`_
reference platform. You can also use the official LiteX SoC Builder.

Bitstream generation
********************

Zephyr on LiteX VexRiscv
========================
Using this platform ensures that all registers addresses are in the proper place.
All drivers were tested using this platform.
In order to generate the bitstream for the Digilent Arty A7-35 Board,
proceed with the following instruction:

1. Clone the repository and update all submodules:

   .. code-block:: bash

      git clone https://github.com/litex-hub/zephyr-on-litex-vexriscv.git
      cd zephyr-on-litex-vexriscv
      git submodule update --init --recursive

   First, you have to install the F4PGA toolchain. It can be done by following instructions in
   `this tutorial <https://f4pga-examples.readthedocs.io/en/latest/getting.html>`_.

#. Next, get all required packages and run the install script:

   .. code-block:: bash

      apt-get install build-essential bzip2 python3 python3-dev python3-pip
      ./install.sh

#. Set up the Arty F4PGA environment:

   .. code-block:: bash

      source ./init
      export F4PGA_INSTALL_DIR=~/opt/f4pga
      export FPGA_FAM="xc7"
      export PATH="$F4PGA_INSTALL_DIR/$FPGA_FAM/install/bin:$PATH";
      source "$F4PGA_INSTALL_DIR/$FPGA_FAM/conda/etc/profile.d/conda.sh"
      conda activate $FPGA_FAM

#. Generate the bitstream for the Arty 35T:

   .. code-block:: bash

      ./make.py --board=arty --variant=a7-35 --build --toolchain=symbiflow

#. Generate the bitstream for the Arty 100T:

   .. code-block:: bash

      ./make.py --board=arty --variant=a7-100 --build --toolchain=symbiflow

Official LiteX SoC builder
==========================
You can also generate the bitstream using the `official LiteX repository <https://github.com/enjoy-digital/litex>`_.
In that case you must also generate a dts overlay.

1. Install Migen/LiteX and the LiteX's cores:

   .. code-block:: bash

      wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
      chmod +x litex_setup.py
      ./litex_setup.py --init --install --user (--user to install to user directory) --config=(minimal, standard, full)

#. Install the RISC-V toolchain:

   .. code-block:: bash

      pip3 install meson ninja
      ./litex_setup.py --gcc=riscv

#. Build the target:

   .. code-block:: bash

      ./litex-boards/litex_boards/targets/digilent_arty.py --build --timer-uptime --csr-json csr.json

#. Generate the dts and config overlay:

   .. code-block:: bash

      ./litex/litex/tools/litex_json2dts_zephyr.py --dts overlay.dts --config overlay.config csr.json

Programming and booting
*************************

Building
========

Applications for the ``litex_vexriscv`` board configuration can be built as usual
(see :ref:`build_an_application`).
In order to build the application for ``litex_vexriscv``, set the ``BOARD`` variable
to ``litex_vexriscv``.

If you were generating bitstream with the official LiteX SoC builder you need to pass an additional argument:

.. code-block:: bash

   west build -b litex_vexriscv path/to/app -DDTC_OVERLAY_FILE=path/to/overlay.dts

Booting
=======

To upload the bitstream you can use `xc3sprog <https://github.com/matrix-io/xc3sprog>`_ or
`openFPGALoader <https://github.com/trabucayre/openFPGALoader>`_:

.. code-block:: bash

   xc3sprog -c nexys4 digilent_arty.bit

.. code-block:: bash

   openFPGALoader -b arty_a7_100t digilent_arty.bit

You can boot from a serial port using litex_term (replace `ttyUSBX` with your device) , e.g.:

.. code-block:: bash

   litex_term /dev/ttyUSBX --speed 115200 --kernel zephyr.bin