1.. _litex-vexriscv:
2
3LiteX VexRiscv
4##############
5
6LiteX VexRiscv is an example of a system on a chip (SoC) that consists of
7a `VexRiscv processor <https://github.com/SpinalHDL/VexRiscv>`_
8and additional peripherals. This setup can be generated using
9`Zephyr on LiteX VexRiscv (reference platform)
10<https://github.com/litex-hub/zephyr-on-litex-vexriscv>`_
11or `LiteX SoC Builder <https://github.com/enjoy-digital/litex>`_
12and can be used on various FPGA chips.
13The bitstream (FPGA configuration file) can be obtained using both
14vendor-specific and open-source tools, including the
15`F4PGA toolchain <https://f4pga.org/>`_.
16
17The ``litex_vexriscv`` board configuration in Zephyr is meant for the
18LiteX VexRiscv SoC implementation generated for the
19`Digilent Arty A7-35T or A7-100T Development Boards
20<https://store.digilentinc.com/arty-a7-artix-7-fpga-development-board-for-makers-and-hobbyists>`_
21or `SDI-MIPI Video Converter <https://github.com/antmicro/sdi-mipi-video-converter>`_.
22
23.. image:: img/litex_vexriscv.jpg
24   :align: center
25   :alt: LiteX VexRiscv on Digilent Arty 35T Board
26
27LiteX is based on
28`Migen <https://m-labs.hk/gateware/migen/>`_/`MiSoC SoC builder <https://github.com/m-labs/misoc>`_
29and provides ready-made system components such as buses, streams, interconnects,
30common cores, and CPU wrappers to create SoCs easily. The tool contains
31mechanisms for integrating, simulating, and building various designs
32that target multiple chips of different vendors.
33More information about the LiteX project can be found on
34`LiteX's website <https://github.com/enjoy-digital/litex>`_.
35
36VexRiscv is a 32-bit implementation of the RISC-V CPU architecture
37written in the `SpinalHDL <https://spinalhdl.github.io/SpinalDoc-RTD/>`_.
38The processor supports M, C, and A RISC-V instruction
39set extensions, with numerous optimizations that include multistage
40pipelines and data caching. The project provides many optional extensions
41that can be used to customize the design (JTAG, MMU, MUL/DIV extensions).
42The implementation is optimized for FPGA chips.
43More information about the project can be found on
44`VexRiscv's website <https://github.com/SpinalHDL/VexRiscv>`_.
45
46To run the ZephyrOS on the VexRiscv CPU, it is necessary to prepare the
47bitstream for the FPGA on a Digilent Arty A7-35 Board or SDI-MIPI Video Converter. This can be achieved
48using the
49`Zephyr on LiteX VexRiscv <https://github.com/litex-hub/zephyr-on-litex-vexriscv>`_
50reference platform. You can also use the official LiteX SoC Builder.
51
52Bitstream generation
53********************
54
55Zephyr on LiteX VexRiscv
56========================
57Using this platform ensures that all registers addresses are in the proper place.
58All drivers were tested using this platform.
59In order to generate the bitstream,
60proceed with the following instruction:
61
621. Clone the repository and update all submodules:
63
64   .. code-block:: bash
65
66      git clone https://github.com/litex-hub/zephyr-on-litex-vexriscv.git
67      cd zephyr-on-litex-vexriscv
68      git submodule update --init --recursive
69
70   Generating the bitstream for the Digilent Arty A7-35 Board requires F4PGA toolchain installation. It can be done by following instructions in
71   `this tutorial <https://f4pga-examples.readthedocs.io/en/latest/getting.html>`_.
72
73   In order to generate the bitstream for the SDI-MIPI Video Converter, install
74   oxide (yosys+nextpnr) toolchain by following
75   `these instructions <https://github.com/gatecat/prjoxide#getting-started---complete-flow>`_.
76
77#. Next, get all required packages and run the install script:
78
79   .. code-block:: bash
80
81      apt-get install build-essential bzip2 python3 python3-dev python3-pip
82      ./install.sh
83
84#. Add LiteX to path:
85
86   .. code-block:: bash
87
88      source ./init
89
90#. Set up the F4PGA environment (for the Digilent Arty A7-35 Board):
91
92   .. code-block:: bash
93
94      export F4PGA_INSTALL_DIR=~/opt/f4pga
95      export FPGA_FAM="xc7"
96      export PATH="$F4PGA_INSTALL_DIR/$FPGA_FAM/install/bin:$PATH";
97      source "$F4PGA_INSTALL_DIR/$FPGA_FAM/conda/etc/profile.d/conda.sh"
98      conda activate $FPGA_FAM
99
100#. Generate the bitstream for the Arty 35T:
101
102   .. code-block:: bash
103
104      ./make.py --board=arty --variant=a7-35 --build --toolchain=symbiflow
105
106#. Generate the bitstream for the Arty 100T:
107
108   .. code-block:: bash
109
110      ./make.py --board=arty --variant=a7-100 --build --toolchain=symbiflow
111
112#. Generate the bitstream for the SDI-MIPI Video Converter:
113
114   .. code-block:: bash
115
116      ./make.py --board=sdi_mipi_bridge --build --toolchain=oxide
117
118Official LiteX SoC builder
119==========================
120You can also generate the bitstream using the `official LiteX repository <https://github.com/enjoy-digital/litex>`_.
121In that case you must also generate a dts overlay.
122
1231. Install Migen/LiteX and the LiteX's cores:
124
125   .. code-block:: bash
126
127      wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
128      chmod +x litex_setup.py
129      ./litex_setup.py --init --install --user (--user to install to user directory) --config=(minimal, standard, full)
130
131#. Install the RISC-V toolchain:
132
133   .. code-block:: bash
134
135      pip3 install meson ninja
136      ./litex_setup.py --gcc=riscv
137
138#. Build the target:
139
140   .. code-block:: bash
141
142      ./litex-boards/litex_boards/targets/digilent_arty.py --build --timer-uptime --csr-json csr.json
143
144#. Generate the dts and config overlay:
145
146   .. code-block:: bash
147
148      ./litex/litex/tools/litex_json2dts_zephyr.py --dts overlay.dts --config overlay.config csr.json
149
150Programming and booting
151*************************
152
153Building
154========
155
156Applications for the ``litex_vexriscv`` board configuration can be built as usual
157(see :ref:`build_an_application`).
158In order to build the application for ``litex_vexriscv``, set the ``BOARD`` variable
159to ``litex_vexriscv``.
160
161If you were generating bitstream with the official LiteX SoC builder you need to pass an additional argument:
162
163.. code-block:: bash
164
165   west build -b litex_vexriscv path/to/app -DDTC_OVERLAY_FILE=path/to/overlay.dts
166
167Booting
168=======
169
170To upload the bitstream to Digilent Arty A7-35 you can use `xc3sprog <https://github.com/matrix-io/xc3sprog>`_ or
171`openFPGALoader <https://github.com/trabucayre/openFPGALoader>`_:
172
173.. code-block:: bash
174
175   xc3sprog -c nexys4 digilent_arty.bit
176
177.. code-block:: bash
178
179   openFPGALoader -b arty_a7_100t digilent_arty.bit
180
181Use `ecpprog <https://github.com/gregdavill/ecpprog>`_ to upload the bitstream to SDI-MIPI Video Converter:
182
183.. code-block:: bash
184
185   ecpprog -S antmicro_sdi_mipi_video_converter.bit
186
187You can boot from a serial port using litex_term (replace `ttyUSBX` with your device) , e.g.:
188
189.. code-block:: bash
190
191   litex_term /dev/ttyUSBX --speed 115200 --kernel zephyr.bin
192