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