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