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