OpenCores
URL https://opencores.org/ocsvn/neorv32/neorv32/trunk

Subversion Repositories neorv32

[/] [neorv32/] [trunk/] [docs/] [datasheet/] [software.adoc] - Blame information for rev 66

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 60 zero_gravi
:sectnums:
2
== Software Framework
3
 
4
To make actual use of the NEORV32 processor, the project comes with a complete software eco-system. This
5
ecosystem is based on the RISC-V port of the GCC GNU Compiler Collection and consists of the following elementary parts:
6
 
7
[cols="<6,<4"]
8
[grid="none"]
9
|=======================
10
| Application/bootloader start-up code | `sw/common/crt0.S`
11
| Application/bootloader linker script | `sw/common/neorv32.ld`
12
| Core hardware driver libraries | `sw/lib/include/` & `sw/lib/source/`
13 62 zero_gravi
| Central makefile | `sw/common/common.mk`
14 60 zero_gravi
| Auxiliary tool for generating NEORV32 executables | `sw/image_gen/`
15
| Default bootloader | `sw/bootloader/bootloader.c`
16
|=======================
17
 
18
Last but not least, the NEORV32 ecosystem provides some example programs for testing the hardware, for
19
illustrating the usage of peripherals and for general getting in touch with the project (`sw/example`).
20
 
21
// ####################################################################################################################
22
:sectnums:
23
=== Compiler Toolchain
24
 
25
The toolchain for this project is based on the free RISC-V GCC-port. You can find the compiler sources and
26
build instructions on the official RISC-V GNU toolchain GitHub page: https://github.com/riscv/riscv-gnutoolchain.
27
 
28
The NEORV32 implements a 32-bit base integer architecture (`rv32i`) and a 32-bit integer and soft-float ABI
29
(ilp32), so make sure you build an according toolchain.
30
 
31
Alternatively, you can download my prebuilt `rv32i/e` toolchains for 64-bit x86 Linux from: https://github.com/stnolting/riscv-gcc-prebuilt
32
 
33
The default toolchain prefix used by the project's makefiles is (can be changed in the makefiles): **`riscv32-unknown-elf`**
34
 
35
[TIP]
36
More information regarding the toolchain (building from scratch or downloading the prebuilt ones)
37 61 zero_gravi
can be found in the user guides' section https://stnolting.github.io/neorv32/ug/#_software_toolchain_setup[Software Toolchain Setup].
38 60 zero_gravi
 
39
 
40
 
41
<<<
42
// ####################################################################################################################
43
:sectnums:
44
=== Core Libraries
45
 
46
The NEORV32 project provides a set of C libraries that allows an easy usage of the processor/CPU features.
47
Just include the main NEORV32 library file in your application's source file(s):
48
 
49
[source,c]
50
----
51
#include 
52
----
53
 
54
Together with the makefile, this will automatically include all the processor's header files located in
55
`sw/lib/include` into your application. The actual source files of the core libraries are located in
56
`sw/lib/source` and are automatically included into the source list of your software project. The following
57
files are currently part of the NEORV32 core library:
58
 
59
[cols="<3,<4,<8"]
60
[options="header",grid="rows"]
61
|=======================
62
| C source file | C header file | Description
63
| -                  | `neorv32.h`            | main NEORV32 definitions and library file
64 64 zero_gravi
| -                  | `neorv32_legacy.h`     | legacy back-compatibility layer
65 60 zero_gravi
| `neorv32_cfs.c`    | `neorv32_cfs.h`        | HW driver (stub)footnote:[This driver file only represents a stub, since the real CFS drivers are defined by the actual CFS implementation.] functions for the custom functions subsystem
66
| `neorv32_cpu.c`    | `neorv32_cpu.h`        | HW driver functions for the NEORV32 **CPU**
67
| `neorv32_gpio.c`   | `neorv32_gpio.h`       | HW driver functions for the **GPIO**
68
| -                  | `neorv32_intrinsics.h` | macros for custom intrinsics/instructions
69
| `neorv32_mtime.c`  | `neorv32_mtime.h`      | HW driver functions for the **MTIME**
70
| `neorv32_neoled.c` | `neorv32_neoled.h`     | HW driver functions for the **NEOLED**
71
| `neorv32_pwm.c`    | `neorv32_pwm.h`        | HW driver functions for the **PWM**
72
| `neorv32_rte.c`    | `neorv32_rte.h`        | NEORV32 **runtime environment** and helpers
73
| `neorv32_spi.c`    | `neorv32_spi.h`        | HW driver functions for the **SPI**
74
| `neorv32_trng.c`   | `neorv32_trng.h`       | HW driver functions for the **TRNG**
75
| `neorv32_twi.c`    | `neorv32_twi.h`        | HW driver functions for the **TWI**
76
| `neorv32_uart.c`   | `neorv32_uart.h`       | HW driver functions for the **UART0** and **UART1**
77
| `neorv32_wdt.c`    | `neorv32_wdt.h`        | HW driver functions for the **WDT**
78
|=======================
79
 
80
.Documentation
81
[TIP]
82
All core library software sources are highly documented using _doxygen_. See section <>.
83
The documentation is automatically built and deployed to GitHub pages by the CI workflow (:https://stnolting.github.io/neorv32/sw/files.html).
84
 
85
 
86
 
87
 
88
<<<
89
// ####################################################################################################################
90
:sectnums:
91
=== Application Makefile
92
 
93 62 zero_gravi
Application compilation is based on a single, centralized **GNU makefiles** `sw/common/common.mk`. Each project in the
94
`sw/example` folder features a makefile that just includes this central makefile. When creating a new project, copy an existing project folder or
95 60 zero_gravi
at least the makefile to your new project folder. I suggest to create new projects also in `sw/example` to keep
96
the file dependencies. Of course, these dependencies can be manually configured via makefiles variables
97
when your project is located somewhere else.
98
 
99 62 zero_gravi
[NOTE]
100 60 zero_gravi
Before you can use the makefiles, you need to install the RISC-V GCC toolchain. Also, you have to add the
101 62 zero_gravi
installation folder of the compiler to your system's `PATH` variable. More information can be found in
102
https://stnolting.github.io/neorv32/ug/#_software_toolchain_setup[User Guide: Software Toolchain Setup].
103 60 zero_gravi
 
104
The makefile is invoked by simply executing make in your console:
105
 
106
[source,bash]
107
----
108
neorv32/sw/example/blink_led$ make
109
----
110
 
111
:sectnums:
112
==== Targets
113
 
114 62 zero_gravi
Just executing `make` (or executing `make help`) will show the help menu listing all available targets.
115 60 zero_gravi
 
116 62 zero_gravi
[source,makefile]
117
----
118
$ make
119
<<< NEORV32 Application Makefile >>>
120
Make sure to add the bin folder of RISC-V GCC to your PATH variable.
121
Targets:
122
 help       - show this text
123
 check      - check toolchain
124
 info       - show makefile/toolchain configuration
125
 exe        - compile and generate  executable for upload via bootloader
126
 hex        - compile and generate  executable raw file
127 65 zero_gravi
 image      - compile and generate VHDL IMEM boot image (for application) in local folder
128 62 zero_gravi
 install    - compile, generate and install VHDL IMEM boot image (for application)
129 65 zero_gravi
 sim        - in-console simulation using default/simple testbench and GHDL
130 62 zero_gravi
 all        - exe + hex + install
131
 elf_info   - show ELF layout info
132
 clean      - clean up project
133
 clean_all  - clean up project, core libraries and image generator
134 65 zero_gravi
 bl_image   - compile and generate VHDL BOOTROM boot image (for bootloader only!) in local folder
135 62 zero_gravi
 bootloader - compile, generate and install VHDL BOOTROM boot image (for bootloader only!)
136
----
137 60 zero_gravi
 
138
 
139
:sectnums:
140
==== Configuration
141
 
142 62 zero_gravi
The compilation flow is configured via variables right at the beginning of the **central**
143
makefile (`sw/common/common.mk`):
144 60 zero_gravi
 
145 62 zero_gravi
[TIP]
146
The makefile configuration variables can be (re-)defined directly when invoking the makefile. For
147 65 zero_gravi
example via `$ make MARCH=rv32ic clean_all exe`. You can also make project-specific definitions
148 62 zero_gravi
of all variables inside the project's actual makefile (e.g., `sw/example/blink_led/makefile`).
149
 
150 60 zero_gravi
[source,makefile]
151
----
152
# *****************************************************************************
153
# USER CONFIGURATION
154
# *****************************************************************************
155
# User's application sources (*.c, *.cpp, *.s, *.S); add additional files here
156
APP_SRC ?= $(wildcard ./*.c) $(wildcard ./*.s) $(wildcard ./*.cpp) $(wildcard ./*.S)
157
# User's application include folders (don't forget the '-I' before each entry)
158
APP_INC ?= -I .
159
# User's application include folders - for assembly files only (don't forget the '-I' before each
160
entry)
161
ASM_INC ?= -I .
162
# Optimization
163
EFFORT ?= -Os
164
# Compiler toolchain
165 62 zero_gravi
RISCV_PREFIX ?= riscv32-unknown-elf-
166 60 zero_gravi
# CPU architecture and ABI
167 65 zero_gravi
MARCH ?= rv32i
168
MABI  ?= ilp32
169 60 zero_gravi
# User flags for additional configuration (will be added to compiler flags)
170
USER_FLAGS ?=
171
# Relative or absolute path to the NEORV32 home folder
172
NEORV32_HOME ?= ../../..
173
# *****************************************************************************
174
----
175
 
176
[cols="<3,<10"]
177
[grid="none"]
178
|=======================
179
| _APP_SRC_         | The source files of the application (`*.c`, `*.cpp`, `*.S` and `*.s` files are allowed; file of these types in the project folder are automatically added via wildcards). Additional files can be added; separated by white spaces
180
| _APP_INC_         | Include file folders; separated by white spaces; must be defined with `-I` prefix
181
| _ASM_INC_         | Include file folders that are used only for the assembly source files (`*.S`/`*.s`).
182
| _EFFORT_          | Optimization level, optimize for size (`-Os`) is default; legal values: `-O0`, `-O1`, `-O2`, `-O3`, `-Os`
183 62 zero_gravi
| _RISCV_PREFIX_    | The toolchain prefix to be used; follows the naming convention "architecture-vendor-output-"
184 65 zero_gravi
| _MARCH_           | The targeted RISC-V architecture/ISA. Only `rv32` is supported by the NEORV32. Enable compiler support of optional CPU extension by adding the according extension letter (e.g. `rv32im` for _M_ CPU extension). See https://stnolting.github.io/neorv32/ug/#_enabling_risc_v_cpu_extensions[User Guide: Enabling RISC-V CPU Extensions] for more information.
185 60 zero_gravi
| _MABI_            | The default 32-bit integer ABI.
186
| _USER_FLAGS_      | Additional flags that will be forwarded to the compiler tools
187
| _NEORV32_HOME_    | Relative or absolute path to the NEORV32 project home folder. Adapt this if the makefile/project is not in the project's `sw/example folder`.
188
| _COM_PORT_        | Default serial port for executable upload to bootloader.
189
|=======================
190
 
191
:sectnums:
192
==== Default Compiler Flags
193
 
194
The following default compiler flags are used for compiling an application. These flags are defined via the
195
`CC_OPTS` variable. Custom flags can be appended via the `USER_FLAGS` variable to the `CC_OPTS` variable.
196
 
197
[cols="<3,<9"]
198
[grid="none"]
199
|=======================
200
| `-Wall` | Enable all compiler warnings.
201
| `-ffunction-sections` | Put functions and data segment in independent sections. This allows a code optimization as dead code and unused data can be easily removed.
202
| `-nostartfiles` | Do not use the default start code. The makefiles use the NEORV32-specific start-up code instead (`sw/common/crt0.S`).
203
| `-Wl,--gc-sections` | Make the linker perform dead code elimination.
204
| `-lm` | Include/link with `math.h`.
205
| `-lc` | Search for the standard C library when linking.
206
| `-lgcc` | Make sure we have no unresolved references to internal GCC library subroutines.
207 66 zero_gravi
| `-mno-fdiv` | Use built-in software functions for floating-point divisions and square roots (since the according instructions are not supported yet).
208 60 zero_gravi
| `-falign-functions=4` .4+| Force a 32-bit alignment of functions and labels (branch/jump/call targets). This increases performance as it simplifies instruction fetch when using the C extension. As a drawback this will also slightly increase the program code.
209
| `-falign-labels=4`
210
| `-falign-loops=4`
211
| `-falign-jumps=4`
212
|=======================
213
 
214
 
215
 
216
<<<
217
// ####################################################################################################################
218
:sectnums:
219
=== Executable Image Format
220
 
221 61 zero_gravi
In order to generate a file, which can be executed by the processor, all source files have to be compiler, linked
222
and packed into a final _executable_.
223 60 zero_gravi
 
224 61 zero_gravi
:sectnums:
225
==== Linker Script
226
 
227
When all the application sources have been compiled, they need to be _linked_ in order to generate a unified
228
program file. For this purpose the makefile uses the NEORV32-specific linker script `sw/common/neorv32.ld` for
229
linking all object files that were generated during compilation.
230
 
231
The linker script defines three memory _sections_: `rom`, `ram` and `iodev`. Each section provides specific
232
access _attributes_: read access (`r`), write access (`w`) and executable (`x`).
233
 
234
.Linker memory sections - general
235 60 zero_gravi
[cols="<2,^1,<7"]
236
[options="header",grid="rows"]
237
|=======================
238
| Memory section  | Attributes | Description
239 61 zero_gravi
| `ram`           | `rwx`      | Data memory address space (processor-internal/external DMEM)
240
| `rom`           | `rx`       | Instruction memory address space (processor-internal/external IMEM) _or_ internal bootloader ROM
241
| `iodev`         | `rw`       | Processor-internal memory-mapped IO/peripheral devices address space
242 60 zero_gravi
|=======================
243
 
244 61 zero_gravi
These sections are defined right at the beginning of the linker script:
245 60 zero_gravi
 
246 61 zero_gravi
.Linker memory sections - cut-out from linker script `neorv32.ld`
247
[source,c]
248
----
249
MEMORY
250
{
251
  ram  (rwx) : ORIGIN = 0x80000000, LENGTH = DEFINED(make_bootloader) ? 512 : 8*1024
252
  rom   (rx) : ORIGIN = DEFINED(make_bootloader) ? 0xFFFF0000 : 0x00000000, LENGTH = DEFINED(make_bootloader) ? 32K : 2048M
253
  iodev (rw) : ORIGIN = 0xFFFFFE00, LENGTH = 512
254
}
255
----
256 60 zero_gravi
 
257 61 zero_gravi
Each memory section provides a _base address_ `ORIGIN` and a _size_ `LENGTH`. The base address and size of the `iodev` section is
258
fixed and must not be altered. The base addresses and sizes of the `ram` and `rom` regions correspond to the total available instruction
259
and data memory address space (see section <<_address_space_layout>>).
260 60 zero_gravi
 
261 61 zero_gravi
[IMPORTANT]
262
`ORIGIN` of the `ram` section has to be always identical to the processor's `dspace_base_c` hardware configuration. Additionally,
263
`ORIGIN` of the `rom` section has to be always identical to the processor's `ispace_base_c` hardware configuration.
264
 
265
The sizes of `ram` section has to be equal to the size of the **physical available data instruction memory**. For example, if the processor
266
setup only uses processor-internal DMEM (<<_mem_int_dmem_en>> = _true_ and no external data memory attached) the `LENGTH` parameter of
267
this memory section has to be equal to the size configured by the <<_mem_int_dmem_size>> generic.
268
 
269
The sizes of `rom` section is a little bit more complicated. The default linker script configuration assumes a _maximum_ of 2GB _logical_
270
memory space, which is also the default configuration of the processor's hardware instruction memory address space. This size _does not_ have
271
to reflect the _actual_ physical size of the instruction memory (internal IMEM and/or processor-external memory). It just provides a maximum
272
limit. When uploading new executable via the bootloader, the bootloader itself checks if sufficient _physical_ instruction memory is available.
273
If a new executable is embedded right into the internal-IMEM the synthesis tool will check, if the configured instruction memory size
274
is sufficient (e.g., via the <<_mem_int_imem_size>> generic).
275
 
276
[IMPORTANT]
277
The `rom` region uses a conditional assignment (via the `make_bootloader` symbol) for `ORIGIN` and `LENGTH` that is used to place
278
"normal executable" (i.e. for the IMEM) or "the bootloader image" to their according memories. +
279
 +
280
The `ram` region also uses a conditional assignment (via the `make_bootloader` symbol) for `LENGTH`. When compiling the bootloader
281
(`make_bootloader` symbol is set) the generated bootloader will only use the _first_ 512 bytes of the data address space. This is
282
a fall-back to ensure the bootloader can operate independently of the actual _physical_ data memory size.
283
 
284
The linker maps all the regions from the compiled object files into four final sections: `.text`, `.rodata`, `.data` and `.bss`.
285
These four regions contain everything required for the application to run:
286
 
287
.Linker memory regions
288 60 zero_gravi
[cols="<1,<9"]
289
[options="header",grid="rows"]
290
|=======================
291 62 zero_gravi
| Region    | Description
292 60 zero_gravi
| `.text`   | Executable instructions generated from the start-up code and all application sources.
293
| `.rodata` | Constants (like strings) from the application; also the initial data for initialized variables.
294
| `.data`   | This section is required for the address generation of fixed (= global) variables only.
295
| `.bss`    | This section is required for the address generation of dynamic memory constructs only.
296
|=======================
297
 
298
The `.text` and `.rodata` sections are mapped to processor's instruction memory space and the `.data` and
299 61 zero_gravi
`.bss` sections are mapped to the processor's data memory space. Finally, the `.text`, `.rodata` and `.data`
300
sections are extracted and concatenated into a single file `main.bin`.
301 60 zero_gravi
 
302
 
303 61 zero_gravi
:sectnums:
304
==== Executable Image Generator
305 60 zero_gravi
 
306 61 zero_gravi
The `main.bin` file is packed by the NEORV32 image generator (`sw/image_gen`) to generate the final executable file.
307
 
308
[NOTE]
309
The sources of the image generator are automatically compiled when invoking the makefile.
310
 
311
The image generator can generate three types of executables, selected by a flag when calling the generator:
312
 
313 60 zero_gravi
[cols="<1,<9"]
314
[grid="none"]
315
|=======================
316
| `-app_bin` | Generates an executable binary file `neorv32_exe.bin` (for UART uploading via the bootloader).
317 62 zero_gravi
| `-app_hex` | Generates a plain ASCII hex-char file `neorv32_exe.hex` that can be used to initialize custom (instruction-) memories (in synthesis/simulation).
318 60 zero_gravi
| `-app_img` | Generates an executable VHDL memory initialization image for the processor-internal IMEM. This option generates the `rtl/core/neorv32_application_image.vhd` file.
319
| `-bld_img` | Generates an executable VHDL memory initialization image for the processor-internal BOOT ROM. This option generates the `rtl/core/neorv32_bootloader_image.vhd` file.
320
|=======================
321
 
322 61 zero_gravi
All these options are managed by the makefile. The _normal application_ compilation flow will generate the `neorv32_exe.bin`
323
executable to be upload via UART to the NEORV32 bootloader.
324 60 zero_gravi
 
325 61 zero_gravi
The image generator add a small header to the `neorv32_exe.bin` executable, which consists of three 32-bit words located right at the
326
beginning of the file. The first word of the executable is the signature word and is always `0x4788cafe`. Based on this word the bootloader
327
can identify a valid image file. The next word represents the size in bytes of the actual program
328 60 zero_gravi
image in bytes. A simple "complement" checksum of the actual program image is given by the third word. This
329
provides a simple protection against data transmission or storage errors.
330
 
331
 
332 61 zero_gravi
:sectnums:
333
==== Start-Up Code (crt0)
334 60 zero_gravi
 
335 61 zero_gravi
The CPU and also the processor require a minimal start-up and initialization code to bring the CPU (and the SoC)
336
into a stable and initialized state and to initialize the C runtime environment before the actual application can be executed.
337
This start-up code is located in `sw/common/crt0.S` and is automatically linked _every_ application program
338
and placed right before the actual application code so it gets executed right after reset.
339 60 zero_gravi
 
340 61 zero_gravi
The `crt0.S` start-up performs the following operations:
341 60 zero_gravi
 
342 61 zero_gravi
[start=1]
343
. Initialize all integer registers `x1 - x31` (or jsut `x1 - x15` when using the `E` CPU extension) to a defined value.
344
. Initialize the global pointer `gp` and the stack pointer `sp` according to the `.data` segment layout provided by the linker script.
345
. Initialize all CPU core CSRs and also install a default "dummy" trap handler for _all_ traps. This handler catches all traps during the early boot phase.
346
. Clear IO area: Write zero to all memory-mapped registers within the IO region (`iodev` section). If certain devices have not been implemented, a bus access fault exception will occur. This exception is captured by the dummy trap handler.
347
. Clear the `.bss` section defined by the linker script.
348
. Copy read-only data from the `.text` section to the `.data` section to set initialized variables.
349
. Call the application's `main` function (with _no_ arguments: `argc` = `argv` = 0).
350
. If the `main` function returns `crt0` can call an "after-main handler" (see below)
351
. If there is no after-main handler or after returning from the after-main handler the processor goes to an endless sleep mode (using a simple loop or via the `wfi` instruction if available).
352 60 zero_gravi
 
353 61 zero_gravi
:sectnums:
354
===== After-Main Handler
355
 
356
If the application's `main()` function actually returns, an _after main handler_ can be executed. This handler can be a normal function
357
since the C runtime is still available when executed. If this handler uses any kind of peripheral/IO modules make sure these are
358
already initialized within the application or you have to initialize them _inside_ the handler.
359
 
360
.After-main handler - function prototype
361
[source,c]
362
----
363
int __neorv32_crt0_after_main(int32_t return_code);
364
----
365
 
366
The function has exactly one argument (`return_code`) that provides the _return value_ of the application's main function.
367
For instance, this variable contains _-1_ if the main function returned with `return -1;`. The return value of the
368
`__neorv32_crt0_after_main` function is irrelevant as there is no further "software instance" executed afterwards that can check this.
369
However, the on-chip debugger could still evaluate the return value of the after-main handler.
370
 
371
A simple `printf` can be used to inform the user when the application main function return
372
(this example assumes that UART0 has been already properly configured in the actual application):
373
 
374
.After-main handler - example
375
[source,c]
376
----
377
int __neorv32_crt0_after_main(int32_t return_code) {
378
 
379 65 zero_gravi
  neorv32_uart0_printf("Main returned with code: %i\n", return_code);
380 61 zero_gravi
  return 0;
381
}
382
----
383
 
384
 
385 60 zero_gravi
<<<
386
// ####################################################################################################################
387
:sectnums:
388
=== Bootloader
389
 
390 61 zero_gravi
[NOTE]
391
This section illustrated the **default** bootloader from the repository. The bootloader can be customized
392
to target application-specific scenarios. See User Guide section
393
https://stnolting.github.io/neorv32/ug/#_customizing_the_internal_bootloader[Customizing the Internal Bootloader]
394
for more information.
395 60 zero_gravi
 
396 61 zero_gravi
The default NEORV32 bootloader (source code `sw/bootloader/bootloader.c`) provides a build-in firmware that
397
allows to upload new application executables via UART at every time and to optionally store/boot them to/from
398
an external SPI flash. It features a simple "automatic boot" feature that will try to fetch an executable
399
from SPI flash if there is _no_ UART user interaction. This allows to build processor setup with
400
non-volatile application storage, which can be updated at any time.
401 60 zero_gravi
 
402 61 zero_gravi
The bootloader is only implemented if the <<_int_bootloader_en>> generic is _true_. This will
403
select the <<_indirect_boot>> boot configuration.
404 60 zero_gravi
 
405 61 zero_gravi
.Hardware requirements of the _default_ NEORV32 bootloader
406 60 zero_gravi
[IMPORTANT]
407 61 zero_gravi
**REQUIRED**: The bootloader requires the CSR access CPU extension (<<_cpu_extension_riscv_zicsr>> generic is _true_)
408
and at least 512 bytes of data memory (processor-internal DMEM or external DMEM). +
409
 +
410
_RECOMMENDED_: For user interaction via UART (like uploading executables) the primary UART (UART0) has to be
411
implemented (<<_io_uart0_en>> generic is _true_). Without UART the bootloader does not make much sense. However, auto-boot
412
via SPI is still supported but the bootloader should be customized (see User Guide) for this purpose. +
413
 +
414
_OPTIONAL_: The default bootloader uses bit 0 of the GPIO output port as "heart beat" and status LED if the
415
GPIO controller is implemented (<<_io_gpio_en>> generic is _true_). +
416
 +
417
_OPTIONAL_: The MTIME machine timer (<<_io_mtime_en>> generic is _true_) and the SPI controller
418
(<<_io_spi_en>> generic is _true_) are required in order to use the bootloader's auto-boot feature
419
(automatic boot from external SPI flash if there is no user interaction via UART).
420 60 zero_gravi
 
421
To interact with the bootloader, connect the primary UART (UART0) signals (`uart0_txd_o` and
422
`uart0_rxd_o`) of the processor's top entity via a serial port (-adapter) to your computer (hardware flow control is
423
not used so the according interface signals can be ignored.), configure your
424 62 zero_gravi
terminal program using the following settings and perform a reset of the processor.
425 60 zero_gravi
 
426
Terminal console settings (`19200-8-N-1`):
427
 
428
* 19200 Baud
429
* 8 data bits
430
* no parity bit
431
* 1 stop bit
432
* newline on `\r\n` (carriage return, newline)
433
* no transfer protocol / control flow protocol - just the raw byte stuff
434
 
435
The bootloader uses the LSB of the top entity's `gpio_o` output port as high-active status LED (all other
436
output pin are set to low level by the bootloader). After reset, this LED will start blinking at ~2Hz and the
437
following intro screen should show up in your terminal:
438
 
439
[source]
440
----
441
<< NEORV32 Bootloader >>
442
 
443
BLDV: Mar 23 2021
444
HWV:  0x01050208
445
CLK:  0x05F5E100
446
MISA: 0x40901105
447 64 zero_gravi
CPU:  0x00000023
448
SOC:  0x0EFF0037
449 60 zero_gravi
IMEM: 0x00004000 bytes @ 0x00000000
450
DMEM: 0x00002000 bytes @ 0x80000000
451
 
452
Autoboot in 8s. Press key to abort.
453
----
454
 
455
This start-up screen also gives some brief information about the bootloader and several system configuration parameters:
456
 
457
[cols="<2,<15"]
458
[grid="none"]
459
|=======================
460
| `BLDV` | Bootloader version (built date).
461
| `HWV`  | Processor hardware version (from the `mimpid` CSR) in BCD format (example: `0x01040606` = v1.4.6.6).
462
| `CLK`  | Processor clock speed in Hz (via the SYSINFO module, from the _CLOCK_FREQUENCY_ generic).
463
| `MISA` | CPU extensions (from the `misa` CSR).
464 64 zero_gravi
| `CPU`  | CPU sub-extensions (via the `CPU` register in the SYSINFO module)
465
| `SOC`  | Processor configuration (via the `SOC` register in the SYSINFO module / from the IO_* and MEM_* configuration generics).
466 60 zero_gravi
| `IMEM` | IMEM memory base address and size in byte (from the _MEM_INT_IMEM_SIZE_ generic).
467
| `DMEM` | DMEM memory base address and size in byte (from the _MEM_INT_DMEM_SIZE_ generic).
468
|=======================
469
 
470
Now you have 8 seconds to press any key. Otherwise, the bootloader starts the auto boot sequence. When
471
you press any key within the 8 seconds, the actual bootloader user console starts:
472
 
473
[source]
474
----
475
<< NEORV32 Bootloader >>
476
 
477
BLDV: Mar 23 2021
478
HWV:  0x01050208
479
CLK:  0x05F5E100
480
USER: 0x10000DE0
481
MISA: 0x40901105
482 64 zero_gravi
CPU:  0x00000023
483
SOC:  0x0EFF0037
484 60 zero_gravi
IMEM: 0x00004000 bytes @ 0x00000000
485
DMEM: 0x00002000 bytes @ 0x80000000
486
 
487
Autoboot in 8s. Press key to abort.
488
Aborted.
489
 
490
Available commands:
491
h: Help
492
r: Restart
493
u: Upload
494
s: Store to flash
495
l: Load from flash
496
e: Execute
497
CMD:>
498
----
499
 
500
The auto-boot countdown is stopped and now you can enter a command from the list to perform the
501
corresponding operation:
502
 
503
* `h`: Show the help text (again)
504
* `r`: Restart the bootloader and the auto-boot sequence
505
* `u`: Upload new program executable (`neorv32_exe.bin`) via UART into the instruction memory
506
* `s`: Store executable to SPI flash at `spi_csn_o(0)`
507
* `l`: Load executable from SPI flash at `spi_csn_o(0)`
508
* `e`: Start the application, which is currently stored in the instruction memory (IMEM)
509
 
510
A new executable can be uploaded via UART by executing the `u` command. After that, the executable can be directly
511
executed via the `e` command. To store the recently uploaded executable to an attached SPI flash press `s`. To
512
directly load an executable from the SPI flash press `l`. The bootloader and the auto-boot sequence can be
513
manually restarted via the `r` command.
514
 
515
[TIP]
516
The CPU is in machine level privilege mode after reset. When the bootloader boots an application,
517
this application is also started in machine level privilege mode.
518
 
519 61 zero_gravi
[TIP]
520
For detailed information on using an SPI flash for application storage see User Guide section
521
https://stnolting.github.io/neorv32/ug/#_programming_an_external_spi_flash_via_the_bootloader[Programming an External SPI Flash via the Bootloader].
522 60 zero_gravi
 
523
 
524
:sectnums:
525
==== Auto Boot Sequence
526 61 zero_gravi
When you reset the NEORV32 processor, the bootloader waits 8 seconds for a UART console input before it
527 60 zero_gravi
starts the automatic boot sequence. This sequence tries to fetch a valid boot image from the external SPI
528 61 zero_gravi
flash, connected to SPI chip select `spi_csn_o(0)`. If a valid boot image is found that can be successfully
529
transferred into the instruction memory, it is automatically started. If no SPI flash is detected or if there
530
is no valid boot image found, and error code will be shown.
531 60 zero_gravi
 
532
 
533
:sectnums:
534
==== Bootloader Error Codes
535
 
536
If something goes wrong during bootloader operation, an error code is shown. In this case the processor
537
stalls, a bell command and one of the following error codes are send to the terminal, the bootloader status
538 61 zero_gravi
LED is permanently activated and the system must be manually reset.
539 60 zero_gravi
 
540
[cols="<2,<13"]
541
[grid="rows"]
542
|=======================
543 62 zero_gravi
| **`ERROR_0`** | If you try to transfer an invalid executable (via UART or from the external SPI flash), this error message shows up. There might be a transfer protocol configuration error in the terminal program. Also, if no SPI flash was found during an auto-boot attempt, this message will be displayed.
544
| **`ERROR_1`** | Your program is way too big for the internal processor’s instructions memory. Increase the memory size or reduce your application code.
545 60 zero_gravi
| **`ERROR_2`** | This indicates a checksum error. Something went wrong during the transfer of the program image (upload via UART or loading from the external SPI flash). If the error was caused by a UART upload, just try it again. When the error was generated during a flash access, the stored image might be corrupted.
546
| **`ERROR_3`** | This error occurs if the attached SPI flash cannot be accessed. Make sure you have the right type of flash and that it is properly connected to the NEORV32 SPI port using chip select #0.
547 66 zero_gravi
| **`ERR 0x???????? 0x???????? 0x????????`** | The bootloader encountered an exception during operation. This might be caused when it tries to access peripherals that were not implemented during synthesis. Example: executing `l` or `s` (SPI flash operations) without the SPI module beeing implemented.
548 60 zero_gravi
|=======================
549
 
550
 
551
 
552
<<<
553
// ####################################################################################################################
554
:sectnums:
555
=== NEORV32 Runtime Environment
556
 
557
The NEORV32 provides a minimal runtime environment (RTE) that takes care of a stable
558
and _safe_ execution environment by handling _all_ traps (including interrupts).
559
 
560
[NOTE]
561
Using the RTE is **optional**. The RTE provides a simple and comfortable way of delegating traps while making sure that all traps (even though they are not
562
explicitly used by the application) are handled correctly. Performance-optimized applications or embedded operating systems should not use the RTE for delegating traps.
563
 
564
When execution enters the application's `main` function, the actual runtime environment is responsible for catching all implemented exceptions
565
and interrupts. To activate the NEORV32 RTE execute the following function:
566
 
567
[source,c]
568
----
569
void neorv32_rte_setup(void);
570
----
571
 
572
This setup initializes the `mtvec` CSR, which provides the base entry point for all trap
573
handlers. The address stored to this register reflects the first-level exception handler provided by the
574
NEORV32 RTE. Whenever an exception or interrupt is triggered, this first-level handler is called.
575
 
576
The first-level handler performs a complete context save, analyzes the source of the exception/interrupt and
577
calls the according second-level exception handler, which actually takes care of the exception/interrupt
578
handling. For this, the RTE manages a private look-up table to store the addresses of the according trap
579
handlers.
580
 
581
After the initial setup of the RTE, each entry in the trap handler's look-up table is initialized with a debug
582
handler, that outputs detailed hardware information via the **primary UART (UART0)** when triggered. This
583
is intended as a fall-back for debugging or for accidentally-triggered exceptions/interrupts.
584 66 zero_gravi
For instance, an illegal instruction exception caught by the RTE debug handler might look like this in the UART0 output:
585 60 zero_gravi
 
586
[source]
587
----
588
 Illegal instruction @0x000002d6, MTVAL=0x00001537 
589
----
590
 
591
To install the **actual application's trap handlers** the NEORV32 RTE provides functions for installing and
592
un-installing trap handler for each implemented exception/interrupt source.
593
 
594
[source,c]
595
----
596
int neorv32_rte_exception_install(uint8_t id, void (*handler)(void));
597
----
598
 
599
[cols="<5,<12"]
600
[options="header",grid="rows"]
601
|=======================
602
| ID name [C] | Description / trap causing entry
603
| `RTE_TRAP_I_MISALIGNED` | instruction address misaligned
604
| `RTE_TRAP_I_ACCESS`     | instruction (bus) access fault
605
| `RTE_TRAP_I_ILLEGAL`    | illegal instruction
606
| `RTE_TRAP_BREAKPOINT`   | breakpoint (`ebreak` instruction)
607
| `RTE_TRAP_L_MISALIGNED` | load address misaligned
608
| `RTE_TRAP_L_ACCESS`     | load (bus) access fault
609
| `RTE_TRAP_S_MISALIGNED` | store address misaligned
610
| `RTE_TRAP_S_ACCESS`     | store (bus) access fault
611
| `RTE_TRAP_MENV_CALL`    | environment call from machine mode (`ecall` instruction)
612
| `RTE_TRAP_UENV_CALL`    | environment call from user mode (`ecall` instruction)
613
| `RTE_TRAP_MTI`          | machine timer interrupt
614
| `RTE_TRAP_MEI`          | machine external interrupt
615
| `RTE_TRAP_MSI`          | machine software interrupt
616
| `RTE_TRAP_FIRQ_0` : `RTE_TRAP_FIRQ_15` | fast interrupt channel 0..15
617
|=======================
618
 
619
When installing a custom handler function for any of these exception/interrupts, make sure the function uses
620
**no attributes** (especially no interrupt attribute!), has no arguments and no return value like in the following
621
example:
622
 
623
[source,c]
624
----
625
void handler_xyz(void) {
626
 
627
  // handle exception/interrupt...
628
}
629
----
630
 
631
[WARNING]
632
Do NOT use the `((interrupt))` attribute for the application exception handler functions! This
633
will place an `mret` instruction to the end of it making it impossible to return to the first-level
634
exception handler of the RTE, which will cause stack corruption.
635
 
636
Example: Installation of the MTIME interrupt handler:
637
 
638
[source,c]
639
----
640
neorv32_rte_exception_install(EXC_MTI, handler_xyz);
641
----
642
 
643
To remove a previously installed exception handler call the according un-install function from the NEORV32
644
runtime environment. This will replace the previously installed handler by the initial debug handler, so even
645
un-installed exceptions and interrupts are further captured.
646
 
647
[source,c]
648
----
649
int neorv32_rte_exception_uninstall(uint8_t id);
650
----
651
 
652
Example: Removing the MTIME interrupt handler:
653
 
654
[source,c]
655
----
656
neorv32_rte_exception_uninstall(EXC_MTI);
657
----
658
 
659
[TIP]
660
More information regarding the NEORV32 runtime environment can be found in the doxygen
661
software documentation (also available online at https://stnolting.github.io/neorv32/sw/files.html[GitHub pages]).

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.