1.. zephyr:board:: neorv32
2
3Overview
4********
5
6The NEORV32 is an open-source RISC-V compatible processor system intended as a
7ready-to-go auxiliary processor within larger SoC designs or as a stand-alone
8customizable microcontroller.
9
10For more information about the NEORV32, see the following websites:
11
12- `The NEORV32 RISC-V Processor GitHub`_
13- `The NEORV32 RISC-V Processor Datasheet`_
14- `The NEORV32 RISC-V Processor User Guide`_
15
16The currently supported version is 1.8.6.
17
18Supported Features
19==================
20
21The ``neorv32`` board configuration can be used a generic definition for NEORV32
22based boards. Customisation to fit custom NEORV32 implementations can be done
23using :ref:`devicetree overlays <use-dt-overlays>`.
24
25Zephyr currently supports the following hardware features of the NEORV32
26Processor (SoC):
27
28+-----------+------------+-------------------------------------+
29| Interface | Controller | Driver/Component                    |
30+===========+============+=====================================+
31| INTC      | on-chip    | interrupt controller                |
32+-----------+------------+-------------------------------------+
33| MTIME     | on-chip    | system timer                        |
34+-----------+------------+-------------------------------------+
35| GPIO      | on-chip    | gpio, non-interrupt                 |
36+-----------+------------+-------------------------------------+
37| UART      | on-chip    | serial port-polling;                |
38|           |            | serial port-interrupt               |
39+-----------+------------+-------------------------------------+
40| TRNG      | on-chip    | entropy                             |
41+-----------+------------+-------------------------------------+
42
43The default board configuration for the NEORV32 Processor (SoC) can be found in
44the defconfig file: :file:`boards/riscv/neorv32/neorv32_defconfig`.
45
46System Clock
47============
48
49The default board configuration assumes a system clock of 100 MHz. The clock
50frequency can be overridden by changing the ``clock-frequency`` property of the
51``cpu0`` devicetree node.
52
53CPU
54===
55
56The default board configuration assumes the NEORV32 CPU implementation has the
57following RISC-V ISA extensions enabled:
58
59- C (Compresses Instructions)
60- M (Integer Multiplication and Division)
61- Zicsr (Control and Status Register (CSR) Instructions)
62
63Internal Instruction Memory
64===========================
65
66The default board configuration assumes the NEORV32 SoC implementation has a 64k
67byte internal instruction memory (IMEM) for code execution. The size of the
68instruction memory can be overridden by changing the ``reg`` property of the
69``imem`` devicetree node.
70
71Internal Data Memory
72====================
73
74The default board configuration assumes the NEORV32 SoC implementation has a 32k
75byte internal data memory (DMEM). The size of the data memory can be overridden
76by changing the ``reg`` property of the ``dmem`` devicetree node.
77
78Serial Port
79===========
80
81The default configuration assumes the NEORV32 SoC implements UART0 for use as
82system console.
83
84.. note::
85
86   The default configuration uses a baud rate of 19200 to match that of the
87   standard NEORV32 bootloader. The baudrate can be changed by modifying the
88   ``current-speed`` property of the ``uart0`` devicetree node.
89
90True Random-Number Generator
91============================
92
93The True Random-Number Generator (TRNG) of the NEORV32 is supported, but
94disabled by default. For NEORV32 SoC implementations supporting the TRNG,
95support can be enabled by setting the ``status`` property of the ``trng``
96devicetree node to ``okay``.
97
98Programming and Debugging
99*************************
100
101First, configure the FPGA with the NEORV32 bitstream as described in the NEORV32
102user guide.
103
104Next, build and flash applications as usual (see :ref:`build_an_application` and
105:ref:`application_run` for more details).
106
107Configuring a Console
108=====================
109
110Use the following settings with your serial terminal of choice (minicom, putty,
111etc.):
112
113- Speed: 19200
114- Data: 8 bits
115- Parity: None
116- Stop bits: 1
117
118Flashing via JTAG
119=================
120
121Here is an example for building and flashing the :zephyr:code-sample:`hello_world` application
122for the NEORV32 via JTAG. Flashing via JTAG requires a NEORV32 SoC
123implementation with the On-Chip Debugger (OCD) and bootloader enabled.
124
125.. note::
126
127   If the bootloader is not enabled, the internal instruction memory (IMEM) is
128   configured as ROM which cannot be modified via JTAG.
129
130.. zephyr-app-commands::
131   :zephyr-app: samples/hello_world
132   :board: neorv32
133   :goals: flash
134
135The default board configuration uses an :ref:`openocd-debug-host-tools`
136configuration similar to the example provided by the NEORV32 project. Other
137JTAGs can be used by providing further arguments when building. Here is an
138example for using the Flyswatter JTAG:
139
140.. zephyr-app-commands::
141   :zephyr-app: samples/hello_world
142   :board: neorv32
143   :goals: flash
144   :gen-args: -DBOARD_RUNNER_ARGS_openocd="--config;interface/ftdi/flyswatter.cfg;--config;neorv32.cfg;--cmd-pre-init;'adapter speed 2000'"
145
146After flashing, you should see message similar to the following in the terminal:
147
148.. code-block:: console
149
150   *** Booting Zephyr OS build zephyr-vn.n.nn  ***
151   Hello World! neorv32
152
153Note, however, that the application was not persisted in flash memory by the
154above steps. It was merely written to internal block RAM in the FPGA. It will
155revert to the application stored in the block RAM within the FPGA bitstream
156the next time the FPGA is configured.
157
158The steps to persist the application within the FPGA bitstream are covered by
159the NEORV32 user guide. If the :kconfig:option:`CONFIG_BUILD_OUTPUT_BIN` is enabled and
160the NEORV32 ``image_gen`` binary is available, the build system will
161automatically generate a :file:`zephyr.vhd` file suitable for initialising the
162internal instruction memory of the NEORV32.
163
164In order for the build system to automatically detect the ``image_gen`` binary
165it needs to be in the :envvar:`PATH` environment variable. If not, the path
166can be passed at build time:
167
168.. zephyr-app-commands::
169   :zephyr-app: samples/hello_world
170   :board: neorv32
171   :goals: build
172   :gen-args: -DCMAKE_PROGRAM_PATH=<path/to/neorv32/sw/image_gen/>
173
174Uploading via UART
175==================
176
177If the :kconfig:option:`CONFIG_BUILD_OUTPUT_BIN` is enabled and the NEORV32
178``image_gen`` binary is available, the build system will automatically generate
179a :file:`zephyr_exe.bin` file suitable for uploading to the NEORV32 via the
180built-in bootloader as described in the NEORV32 user guide.
181
182Debugging via JTAG
183==================
184
185Here is an example for the :zephyr:code-sample:`hello_world` application.
186
187.. zephyr-app-commands::
188   :zephyr-app: samples/hello_world
189   :board: neorv32
190   :goals: debug
191
192Step through the application in your debugger, and you should see a message
193similar to the following in the terminal:
194
195.. code-block:: console
196
197   *** Booting Zephyr OS build zephyr-vn.n.nn  ***
198   Hello World! neorv32
199
200.. _The NEORV32 RISC-V Processor GitHub:
201   https://github.com/stnolting/neorv32
202
203.. _The NEORV32 RISC-V Processor Datasheet:
204   https://stnolting.github.io/neorv32/
205
206.. _The NEORV32 RISC-V Processor User Guide:
207   https://stnolting.github.io/neorv32/ug/
208