[docs/userguide/simulating_the_processor] add admonition and recommen…

…d MARCH=rv32im to build hello_world (#819)
stnolting · Feb 20, 2024 · af0633d · af0633d
2 parents 20cc8f0 + b74d0e3
commit af0633d
Showing 1 changed file with 37 additions and 29 deletions.
diff --git a/docs/userguide/simulating_the_processor.adoc b/docs/userguide/simulating_the_processor.adoc
@@ -30,6 +30,11 @@ A plain-VHDL (no third-party libraries) testbench (`sim/simple/neorv32_tb.simple
 testing the processor.
 This testbench features a 100MHz clock and enables all optional peripheral and CPU extensions except for the `E`.
 
+[IMPORTANT]
+In the simple testbench several optional extensions are disabled, such as C or E.
+If software is compiled using instructions corresponding to disabled extensions, the whole processor will hang in an eternal exception loop and, therefore, the simulation will timeout.
+The `MARCH` must be a subset of the extensions enabled in the testbench.
+
 .True Random Number Generator
 [NOTE]
 The NEORV32 TRNG will be set to "simulation mode" when enabled for simulation (replacing the ring-oscillators
@@ -149,49 +154,52 @@ Blinking LED demo program
 
 To do a quick test of the NEORV32 make sure to have https://github.com/ghdl/ghdl[GHDL] and a
 https://github.com/stnolting/riscv-gcc-prebuilt[RISC-V gcc toolchain] installed.
-Navigate to the project's `sw/example/hello_world` folder and run `make USER_FLAGS+=-DUART0_SIM_MODE MARCH=rv32imc clean_all sim`:
+Navigate to the project's `sw/example/hello_world` folder and run `make USER_FLAGS+=-DUART0_SIM_MODE clean_all sim`:
 
 [TIP]
 The simulator will output some _sanity check_ notes (and warnings or even errors if something is ill-configured)
 right at the beginning of the simulation to give a brief overview of the actual NEORV32 SoC and CPU configurations.
 
 [source, bash]
 ----
-stnolting@Einstein:/mnt/n/Projects/neorv32/sw/example/hello_world$ make USER_FLAGS+=-DUART0_SIM_MODE MARCH=rv32imc clean_all sim
-../../../sw/lib/source/neorv32_uart.c: In function 'neorv32_uart0_setup':
-../../../sw/lib/source/neorv32_uart.c:301:4: warning: #warning UART0_SIM_MODE (primary UART) enabled! Sending all UART0.TX data to text.io simulation output instead of real UART0 transmitter. Use this for simulations only! [-Wcpp]
-  301 |   #warning UART0_SIM_MODE (primary UART) enabled! Sending all UART0.TX data to text.io simulation output instead of real UART0 transmitter. Use this for simulations only! <1>
-      |    ^~~~~~~
+neorv32/sw/example/hello_world$ make USER_FLAGS+=-DUART0_SIM_MODE clean_all sim
+../../../sw/lib/source/neorv32_uart.c: In function 'neorv32_uart_setup':
+../../../sw/lib/source/neorv32_uart.c:116:2: warning: #warning UART0_SIM_MODE (primary UART) enabled! Sending all UART0.TX data to text.io simulation output instead of real UART0 transmitter. Use this for simulations only! [-Wcpp]
+  116 | #warning UART0_SIM_MODE (primary UART) enabled! Sending all UART0.TX data to text.io simulation output instead of real UART0 transmitter. Use this for simulations only! <1>
+      |  ^~~~~~~
 Memory utilization:
    text    data     bss     dec     hex filename
-   4612       0     120    4732    127c main.elf <2>
+   4664       0     116    4780    12ac main.elf <2>
 Compiling ../../../sw/image_gen/image_gen
 Installing application image to ../../../rtl/core/neorv32_application_image.vhd <3>
 Simulating neorv32_application_image.vhd...
 Tip: Compile application with USER_FLAGS+=-DUART[0/1]_SIM_MODE to auto-enable UART[0/1]'s simulation mode (redirect UART output to simulator console). <4>
-Using simulation runtime args: --stop-time=10ms <5>
-../rtl/core/neorv32_top.vhd:347:3:@0ms:(assertion note): NEORV32 PROCESSOR IO Configuration: GPIO MTIME UART0 UART1 SPI TWI PWM WDT CFS NEOLED XIRQ <6>
-../rtl/core/neorv32_top.vhd:370:3:@0ms:(assertion note): NEORV32 PROCESSOR CONFIG NOTE: Boot configuration: Direct boot from memory (processor-internal IMEM).
-../rtl/core/neorv32_top.vhd:394:3:@0ms:(assertion note): NEORV32 PROCESSOR CONFIG NOTE: Implementing on-chip debugger (OCD).
-../rtl/core/neorv32_cpu.vhd:169:3:@0ms:(assertion note): NEORV32 CPU ISA Configuration (MARCH): RV32IMCU_Zbb_Zicsr_Zifencei_Zfinx_Debug
-../rtl/core/neorv32_imem.vhd:107:3:@0ms:(assertion note): NEORV32 PROCESSOR CONFIG NOTE: Implementing processor-internal IMEM as ROM (16384 bytes), pre-initialized with application (4612 bytes).
-../rtl/core/neorv32_dmem.vhd:89:3:@0ms:(assertion note): NEORV32 PROCESSOR CONFIG NOTE: Implementing processor-internal DMEM (RAM, 8192 bytes).
-../rtl/core/neorv32_wishbone.vhd:136:3:@0ms:(assertion note): NEORV32 PROCESSOR CONFIG NOTE: External Bus Interface - Implementing STANDARD Wishbone protocol.
-../rtl/core/neorv32_wishbone.vhd:140:3:@0ms:(assertion note): NEORV32 PROCESSOR CONFIG NOTE: External Bus Interface - Implementing auto-timeout (255 cycles).
-../rtl/core/neorv32_wishbone.vhd:144:3:@0ms:(assertion note): NEORV32 PROCESSOR CONFIG NOTE: External Bus Interface - Implementing LITTLE-endian byte order.
-../rtl/core/neorv32_wishbone.vhd:148:3:@0ms:(assertion note): NEORV32 PROCESSOR CONFIG NOTE: External Bus Interface - Implementing registered RX path.
+Using simulation run arguments: --stop-time=10ms <5>
+../../rtl/core/neorv32_top.vhd:355:5:@0ms:(assertion note): [NEORV32] The NEORV32 RISC-V Processor (version 0x01090504), github.com/stnolting/neorv32 <6>
+../../rtl/core/neorv32_top.vhd:361:5:@0ms:(assertion note): [NEORV32] Processor Configuration: IMEM DMEM I-CACHE D-CACHE WISHBONE GPIO MTIME UART0 UART1 SPI SDI TWI PWM WDT TRNG CFS NEOLED XIRQ GPTMR XIP ONEWIRE DMA SLINK CRC SYSINFO OCD
+../../rtl/core/neorv32_clockgate.vhd:60:3:@0ms:(assertion warning): [NEORV32] Clock gating enabled (using generic clock switch).
+../../rtl/core/neorv32_cpu.vhd:142:3:@0ms:(assertion note): [NEORV32] CPU ISA: rv32imabu_zicsr_zicntr_zicond_zifencei_zfinx_zihpm_zxcfu_sdext_sdtrig_smpmp
+../../rtl/core/neorv32_cpu.vhd:163:3:@0ms:(assertion note): [NEORV32] CPU tuning options: fast_mul fast_shift
+../../rtl/core/neorv32_cpu.vhd:170:3:@0ms:(assertion warning): [NEORV32] Assuming this is a simulation.
+../../rtl/core/neorv32_cpu_cp_bitmanip.vhd:172:3:@0ms:(assertion note): [NEORV32] Implementing bit-manipulation (B) sub-extensions Zba Zbb Zbc Zbs
+../../rtl/core/neorv32_cpu_cp_fpu.vhd:292:3:@0ms:(assertion warning): [NEORV32] The floating-point unit (Zfinx) is still in experimental state.
+../../rtl/core/mem/neorv32_imem.legacy.vhd:72:3:@0ms:(assertion note): [NEORV32] Implementing LEGACY processor-internal IMEM as pre-initialized ROM.
+../../rtl/core/neorv32_wishbone.vhd:117:3:@0ms:(assertion note): [NEORV32] Ext. Bus Interface (WISHBONE) - PIPELINED Wishbone protocol, auto-timeout, LITTLE-endian byte order, registered RX, registered TX
+../../rtl/core/neorv32_trng.vhd:343:3:@0ms:(assertion note): [neoTRNG NOTE] << neoTRNG V3 - A Tiny and Platform-Independent True Random Number Generator >>
+../../rtl/core/neorv32_trng.vhd:545:5:@0ms:(assertion warning): [neoTRNG WARNING] Implementing non-physical pseudo-RNG!
+../../rtl/core/neorv32_trng.vhd:545:5:@0ms:(assertion warning): [neoTRNG WARNING] Implementing non-physical pseudo-RNG!
+../../rtl/core/neorv32_trng.vhd:545:5:@0ms:(assertion warning): [neoTRNG WARNING] Implementing non-physical pseudo-RNG!
+../../rtl/core/neorv32_debug_dm.vhd:227:3:@0ms:(assertion note): [NEORV32] OCD DM compatible to debug spec. version 1.0
 <7>
-                                                                                       ##
-                                                                                       ##         ##   ##   ##
- ##     ##   #########   ########    ########   ##      ##   ########    ########      ##       ################
-####    ##  ##          ##      ##  ##      ##  ##      ##  ##      ##  ##      ##     ##     ####            ####
-## ##   ##  ##          ##      ##  ##      ##  ##      ##          ##         ##      ##       ##   ######   ##
-##  ##  ##  #########   ##      ##  #########   ##      ##      #####        ##        ##     ####   ######   ####
-##   ## ##  ##          ##      ##  ##    ##     ##    ##           ##     ##          ##       ##   ######   ##
-##    ####  ##          ##      ##  ##     ##     ##  ##    ##      ##   ##            ##     ####            ####
-##     ##    #########   ########   ##      ##      ##       ########   ##########     ##       ################
-                                                                                       ##         ##   ##   ##
-                                                                                       ##
+                                                                                      ##        ##   ##   ##
+ ##     ##   #########   ########    ########   ##      ##   ########    ########     ##      ################
+####    ##  ##          ##      ##  ##      ##  ##      ##  ##      ##  ##      ##    ##    ####            ####
+## ##   ##  ##          ##      ##  ##      ##  ##      ##          ##         ##     ##      ##   ######   ##
+##  ##  ##  #########   ##      ##  #########   ##      ##      #####        ##       ##    ####   ######   ####
+##   ## ##  ##          ##      ##  ##    ##     ##    ##           ##     ##         ##      ##   ######   ##
+##    ####  ##          ##      ##  ##     ##     ##  ##    ##      ##   ##           ##    ####            ####
+##     ##    #########   ########   ##      ##      ##       ########   ##########    ##      ################
+                                                                                      ##        ##   ##   ##
 Hello world! :)
 ----
 <1> Notifier that "simulation mode" of UART0 is enabled (by the `USER_FLAGS+=-DUART0_SIM_MODE` makefile flag). All UART0 output is send to the simulator console.