Merge branch 'main' into comment_mistake

CHANGELOG.md

@@ -32,6 +32,12 @@ mimpid = 0x01040312 -> Version 01.04.03.12 -> v1.4.3.12
 
 | Date (*dd.mm.yyyy*) | Version | Comment |
 |:-------------------:|:-------:|:--------|
+| 14.11.2023 | [**:rocket:1.9.1**](https://github.com/stnolting/neorv32/releases/tag/v1.9.1) | **New release** |
+| 11.11.2023 | 1.9.0.9 | :test_tube: add full hardware reset for **all** flip flops in CPU/processor; [#724](https://github.com/stnolting/neorv32/pull/724) |
+| 09.11.2023 | 1.9.0.8 | minor rtl code cleanups; [#723](https://github.com/stnolting/neorv32/pull/723) |
+| 04.11.2023 | 1.9.0.7 | upgrade true random number generator to [neoTRNG version 3](https://github.com/stnolting/neoTRNG); [#721](https://github.com/stnolting/neorv32/pull/721) |
+| 31.10.2023 | 1.9.0.6 | update crt0's early-boot trap handler; [#719](https://github.com/stnolting/neorv32/pull/719) |
+| 30.10.2023 | 1.9.0.5 | minor rtl cleanups and code beautification; [#718](https://github.com/stnolting/neorv32/pull/718) |
 | 28.10.2023 | 1.9.0.4 | :warning: :sparkles: move FreeRTOS port and demo to a new repository: https://github.com/stnolting/neorv32-freertos; [#716](https://github.com/stnolting/neorv32/pull/716) |
 | 18.10.2023 | 1.9.0.3 | :warning: remove top's `CPU_EXTENSION_RISCV_Zifencei` generic - `Zifencei` ISA extension is now always enabled; [#709](https://github.com/stnolting/neorv32/pull/709) |
 | 16.10.2023 | 1.9.0.2 | minor CPU control cleanups and optimizations (branch system); [#707](https://github.com/stnolting/neorv32/pull/707) |

docs/attrs.adoc

@@ -1,7 +1,7 @@
 :author: by stnolting
 :keywords: neorv32, risc-v, riscv, rv32, fpga, soft-core, vhdl, microcontroller, cpu, soc, processor, gcc, openocd, gdb
 :description: A size-optimized, customizable and highly extensible MCU-class 32-bit RISC-V soft-core CPU and microcontroller-like SoC written in platform-independent VHDL.
-:revnumber: v1.9.0
+:revnumber: v1.9.1
 :doctype: book
 :sectnums:
 :stem:

docs/datasheet/soc.adoc

@@ -29,7 +29,7 @@ image::neorv32_processor.png[align=center]
 * _optional_ 8-bit serial data device interface (<<_serial_data_interface_controller_spi,**SDI**>>)
 * _optional_ two wire serial interface controller (<<_two_wire_serial_interface_controller_twi,**TWI**>>), compatible to the I²C standard
 * _optional_ general purpose parallel IO port (<<_general_purpose_input_and_output_port_gpio,**GPIO**>>), 64xOut, 64xIn
-* _optional_ 32-bit external bus interface, Wishbone b4 / AXI4-Lite compatible (<<_processor_external_memory_interface_wishbone_axi4_lite,**WISHBONE**>>)
+* _optional_ 32-bit external bus interface, Wishbone b4 / AXI4-Lite compatible (<<_processor_external_memory_interface_wishbone,**WISHBONE**>>)
 * _optional_ watchdog timer (<<_watchdog_timer_wdt,**WDT**>>)
 * _optional_ PWM controller with up to 12 channels & 8-bit duty cycle resolution (<<_pulse_width_modulation_controller_pwm,**PWM**>>)
 * _optional_ ring-oscillator-based true random number generator (<<_true_random_number_generator_trng,**TRNG**>>)
@@ -370,13 +370,9 @@ a valid reset of the entire processor. The internal global reset is asserted _ay
 `rstn_i` signal. For internal reset sources, the global reset is asserted _synchronously_. If the reset cause gets inactive
 the internal reset is de-asserted _synchronously_ at a falling clock edge.
 
-Internally, all processor registers that actually do provide a hardware reset use an **asynchronous reset**. An asynchronous
-reset ensures that the entire processor logic is reset to a defined state even if the main clock is not yet operational.
-
-In order to reduce routing constraints (and by this the actual hardware requirements), some _uncritical registers_
-of the NEORV32 CPU as well as many registers of the entire NEORV32 Processor do not use a dedicated hardware reset.
-For example there are several pipeline registers and "buffer" registers that do not require a defined
-initial state to ensure correct operation.
+Internally, **all registers** that are not meant for mapping to blockRAM (like the register file) do provide a dedicated and
+low-active **asynchronous hardware reset**. This asynchronous reset ensures that the entire processor logic is reset to a
+defined state even if the main clock is not operational yet.
 
 [NOTE]
 The system reset will only reset the control registers of each implemented IO/peripheral module. This control register

docs/datasheet/soc_dmem.adoc

@@ -7,6 +7,7 @@
 |=======================
 | Hardware source file(s): | neorv32_dmem.entity.vhd      | entity-only definition
 |                          | mem/neorv32_dmem.default.vhd | default _platform-agnostic_ memory architecture
+|                          | mem/neorv32_dmem.legacy.vhd  | alternative legacy-style memory architecture
 | Software driver file(s): | none                         | _implicitly used_
 | Top entity port:         | none                         | 
 | Configuration generics:  | `MEM_INT_DMEM_EN`            | implement processor-internal DMEM when `true`
@@ -27,11 +28,12 @@ physical memory size of 64kB).
 
 .VHDL Source File
 [NOTE]
-The actual DMEM is split into two design files: a plain entity definition (`neorv32_dmem.entity.vhd`) and the actual
-architecture definition (`mem/neorv32_dmem.default.vhd`). This **default architecture** provides a _generic_ and
-_platform independent_ memory design that (should) infers embedded memory block. You can replace/modify the architecture
-source file in order to use platform-specific features (like advanced memory resources) or to improve technology mapping
-and/or timing.
+The actual DMEM is split into two design files: a plain entity definition `neorv32_dmem.entity.vhd` and the actual
+architecture definition `mem/neorv32_dmem.default.vhd`. This **default architecture** provides a _generic_ and
+_platform independent_ memory design that infers embedded memory blocks (blockRAM). The default architecture can
+be replaced by platform-specific modules in order to use platform-specific features or to improve technology mapping
+and/or timing. A "legacy-style" memory architecture is provided in `rtl/mem` that can be used if the synthesis does
+not correctly infer blockRAMs.
 
 .Execute from RAM
 [TIP]

docs/datasheet/soc_imem.adoc

@@ -7,6 +7,7 @@
 |=======================
 | Hardware source file(s): | neorv32_imem.entity.vhd      | entity-only definition
 |                          | mem/neorv32_imem.default.vhd | default _platform-agnostic_ memory architecture
+|                          | mem/neorv32_imem.legacy.vhd  | alternative legacy-style memory architecture
 | Software driver file(s): | none                         | _implicitly used_
 | Top entity port:         | none                         | 
 | Configuration generics:  | `MEM_INT_IMEM_EN`            | implement processor-internal IMEM when `true`
@@ -39,10 +40,11 @@ physical memory size of 64kB).
 .VHDL Source File
 [NOTE]
 The actual IMEM is split into two design files: a plain entity definition (`neorv32_imem.entity.vhd`) and the actual
-architecture definition (`mem/neorv32_imem.default.vhd`). This **default architecture** provides a _generic_ and
-_platform independent_ memory design that (should) infers embedded memory block. You can replace/modify the architecture
-source file in order to use platform-specific features (like advanced memory resources) or to improve technology mapping
-and/or timing.
+architecture definition `mem/neorv32_imem.default.vhd`. This **default architecture** provides a _generic_ and
+_platform independent_ memory design that infers embedded memory blocks (blockRAM). The default architecture can
+be replaced by platform-specific modules in order to use platform-specific features or to improve technology mapping
+and/or timing. A "legacy-style" memory architecture is provided in `rtl/mem` that can be used if the synthesis does
+not correctly infer blockRAMs.
 
 .Read-Only Access
 [NOTE]

docs/datasheet/soc_trng.adoc

@@ -17,26 +17,27 @@
 
 **Overview**
 
-The NEORV32 true random number generator provides _physically_ true random numbers.
-Instead of using a pseudo RNG like a LFSR, the TRNG uses a simple, straight-forward ring
-oscillator concept as physical entropy source. Hence, voltage, thermal and also semiconductor manufacturing
-fluctuations are used to provide a true physical entropy source.
+The NEORV32 true random number generator provides _physically_ true random numbers. It is based on free-running
+ring-oscillators that generate **phase noise** when being sampled by a constant clock. This phase noise is
+used as physical entropy source. The TRNG features a platform independent architecture without FPGA-specific
+primitives, macros or attributes so it can be synthesized for _any_ FPGA. 
 
-The TRNG features a platform independent architecture without FPGA-specific primitives, macros or
-attributes so it can be synthesized for _any_ FPGA. It is based on the **neoTRNG V2**, which is a "spin-off project" of the
-NEORV32 processor. More detailed information about the neoTRNG, its architecture and a
-detailed evaluation of the random number quality can be found it the neoTRNG repository: https://github.com/stnolting/neoTRNG
+.In-Depth Documentation
+[TIP]
+For more information about the neoTRNG architecture and an analysis of its random quality check out the
+neoTRNG repository: https://github.com/stnolting/neoTRNG
 
 .Inferring Latches
 [NOTE]
-The synthesis tool might emit a warning like "inferring latches for ... neorv32_trng ...". This is no problem
-as this is what we actually want: the TRNG is based on latches, which implement the inverters of the ring oscillators.
+The synthesis tool might emit warnings regarding **inferred latches** or **combinatorial loops**. However, this
+is not design flaw as this is exactly what we want. ;)
 
 .Simulation
 [IMPORTANT]
-When simulating the processor the NEORV32 TRNG is automatically set to "simulation mode". In this mode, the physical entropy
-sources (= the ring oscillators) are replaced by a simple **pseudo RNG (LFSR)** providing weak pseudo-random data only.
-The `TRNG_CTRL_SIM_MODE` flag of the control register is set if simulation mode is active.
+When simulating the processor the TRNG is automatically set to "simulation mode". In this mode the physical entropy
+sources (the ring oscillators) are replaced by a simple **pseudo RNG** based on a LFSR providing only
+**deterministic pseudo-random** data. The `TRNG_CTRL_SIM_MODE` flag of the control register is set if simulation
+mode is active.
 
 
 **Theory of Operation**

docs/datasheet/software.adoc

@@ -499,26 +499,42 @@ The `crt0.S` start-up performs the following operations:
 [start=1]
 . Clear <<_mstatus>>.
 . Clear <<_mie>> disabling all interrupt sources.
-. Install an early-boot dummy trap handler to <<_mtvec>>.
+. Install an <<_early_trap_handler>> to <<_mtvec>>.
 . Initialize the global pointer `gp` and the stack pointer `sp` according to the <<_ram_layout>> provided by the linker script.
-. Initialize all integer register `x1 - x31` (only `x1 - x15` if the `E` CPU extension is enabled).
+. Initialize all integer register `x1` - `x31` (only `x1` - `x15` if the `E` CPU extension is enabled).
 . Setup `.data` section to configure initialized variables.
 . Clear the `.bss` section.
 . Call all _constructors_ (if there are any).
 . Call the application's `main` function (with no arguments: `argc` = `argv` = 0).
 . If `main` returns:
-** Interrupts are disabled by clearing <<_mie>>.
+** All interrupt sources are disabled by clearing <<_mie>>.
 ** The return value of `main` is copied to the <<_mscratch>> CSR to allow inspection by the debugger.
 ** Call all _destructors_ (if there are any).
 ** An optional <<_after_main_handler>> is called (if defined at all).
-** The CPU enters sleep mode (executing the `wfi` instruction) in an endless loop.
+** The CPU enters sleep mode executing the `wfi` instruction in an endless loop.
 
 .Bootloader Start-Up Code
 [NOTE]
 The bootloader uses the same start-up code as any "usual" application. However, certain parts are omitted when compiling
 `crt0` for the bootloader (like calling constructors and destructors). See the `crt0` source code for more information.
 
 
+:sectnums:
+===== Early Trap Handler
+
+The start-up code provides a very basic trap handler for the early boot stage. This handler does nothing but trying to move
+on to the next linear instruction whenever an interrupt or synchronous exception is encountered.
+
+This simple trap handler does not interact with the stack at all as it just uses a single register that is backup-ed
+using the <<_mscratch>> CSR. Furthermore, the information if the trap-causing instruction is compressed or uncompressed
+is **not** determined by loading the instruction from memory. Instead, the transformed instruction word is read from the
+<<_mtinst>> CSRs. These two features allow the trap handler to execute with minimal latency and high robustness.
+
+[NOTE]
+The early-trap handler should be replaced by a more capable / informative one as soon as the application software is started
+(for example by using the <<_neorv32_runtime_environment>>).
+
+
 :sectnums:
 ===== After-Main Handler
 

docs/userguide/adding_custom_hw_modules.adoc

@@ -32,7 +32,7 @@ software handling ("bit-banging" for the GPIO). Hence, it is not recommend to us
 
 === External Bus Interface
 
-The https://stnolting.github.io/neorv32/#_processor_external_memory_interface_wishbone_axi4_lite[External Bus Interface]
+The https://stnolting.github.io/neorv32/#_processor_external_memory_interface_wishbone[External Bus Interface]
 provides the classic approach for attaching custom IP. By default, the bus interface implements the widely adopted
 Wishbone interface standard. This project also includes wrappers to convert to other protocol standards like ARM's
 AXI4-Lite or Intel's Avalon protocols. By using a full-featured bus protocol, complex SoC designs can be implemented
@@ -81,7 +81,7 @@ chip-internal extension options:
 
 * https://stnolting.github.io/neorv32/#_custom_functions_unit_cfu[Custom Functions Unit (CFU)] for CPU-internal custom RISC-V instructions
 * https://stnolting.github.io/neorv32/#_custom_functions_subsystem_cfs[Custom Functions Subsystem (CFS)] for tightly-coupled processor-internal co-processors
-* https://stnolting.github.io/neorv32/#_processor_external_memory_interface_wishbone_axi4_lite[External Bus Interface (WISHBONE)] for processor-external memory-mapped modules
+* https://stnolting.github.io/neorv32/#_processor_external_memory_interface_wishbone[External Bus Interface (WISHBONE)] for processor-external memory-mapped modules
 
 .Comparison of On-Chip Extension Options
 [cols="<1,^1,^1,^1"]

rtl/core/mem/neorv32_dmem.default.vhd

@@ -46,43 +46,19 @@ architecture neorv32_dmem_rtl of neorv32_dmem is
   signal rden  : std_ulogic;
   signal addr  : std_ulogic_vector(index_size_f(DMEM_SIZE/4)-1 downto 0);
 
-  -- -------------------------------------------------------------------------------------------------------------- --
-  -- The memory (RAM) is built from 4 individual byte-wide memories b0..b3, since some synthesis tools have         --
-  -- problems with 32-bit memories that provide dedicated byte-enable signals AND/OR with multi-dimensional arrays. --
-  -- [NOTE] Read-during-write behavior is irrelevant as read and write access are mutually exclusive.               --
-  -- -------------------------------------------------------------------------------------------------------------- --
-
-  -- RAM - not initialized at all --
-  signal mem_ram_b0 : mem8_t(0 to DMEM_SIZE/4-1);
-  signal mem_ram_b1 : mem8_t(0 to DMEM_SIZE/4-1);
-  signal mem_ram_b2 : mem8_t(0 to DMEM_SIZE/4-1);
-  signal mem_ram_b3 : mem8_t(0 to DMEM_SIZE/4-1);
-
-  -- read data --
-  signal mem_ram_b0_rd, mem_ram_b1_rd, mem_ram_b2_rd, mem_ram_b3_rd : std_ulogic_vector(7 downto 0);
+  -- The memory (RAM) is built from 4 individual byte-wide memories because some synthesis
+  -- tools have issues inferring 32-bit memories that provide dedicated byte-enable signals
+  -- and/or with multi-dimensional arrays. [NOTE] Read-during-write behavior is irrelevant
+  -- as read and write accesses are mutually exclusive.
+  signal mem_ram_b0, mem_ram_b1, mem_ram_b2, mem_ram_b3 : mem8_t(0 to DMEM_SIZE/4-1);
 
 begin
 
-  -- Sanity Checks --------------------------------------------------------------------------
-  -- -------------------------------------------------------------------------------------------
-  assert not (is_power_of_two_f(DMEM_SIZE) = false) report
-    "NEORV32 PROCESSOR CONFIG ERROR: Internal DMEM size has to be a power of two!" severity error;
-
-  assert false report
-    "NEORV32 PROCESSOR CONFIG NOTE: Implementing DEFAULT processor-internal DMEM (RAM, " & natural'image(DMEM_SIZE) &
-    " bytes)." severity note;
-
-
-  -- Access Control -------------------------------------------------------------------------
-  -- -------------------------------------------------------------------------------------------
-  addr <= bus_req_i.addr(index_size_f(DMEM_SIZE/4)+1 downto 2); -- word aligned
-
-
   -- Memory Access --------------------------------------------------------------------------
   -- -------------------------------------------------------------------------------------------
   mem_access: process(clk_i)
   begin
-    if rising_edge(clk_i) then
+    if rising_edge(clk_i) then -- no reset to infer block RAM
       if (bus_req_i.stb = '1') and (bus_req_i.rw = '1') then
         if (bus_req_i.ben(0) = '1') then -- byte 0
           mem_ram_b0(to_integer(unsigned(addr))) <= bus_req_i.data(07 downto 00);
@@ -97,32 +73,32 @@ begin
           mem_ram_b3(to_integer(unsigned(addr))) <= bus_req_i.data(31 downto 24);
         end if;
       end if;
-      mem_ram_b0_rd <= mem_ram_b0(to_integer(unsigned(addr)));
-      mem_ram_b1_rd <= mem_ram_b1(to_integer(unsigned(addr)));
-      mem_ram_b2_rd <= mem_ram_b2(to_integer(unsigned(addr)));
-      mem_ram_b3_rd <= mem_ram_b3(to_integer(unsigned(addr)));
+      rdata(07 downto 00) <= mem_ram_b0(to_integer(unsigned(addr)));
+      rdata(15 downto 08) <= mem_ram_b1(to_integer(unsigned(addr)));
+      rdata(23 downto 16) <= mem_ram_b2(to_integer(unsigned(addr)));
+      rdata(31 downto 24) <= mem_ram_b3(to_integer(unsigned(addr)));
     end if;
   end process mem_access;
 
+  -- word aligned access --
+  addr <= bus_req_i.addr(index_size_f(DMEM_SIZE/4)+1 downto 2);
+
 
   -- Bus Feedback ---------------------------------------------------------------------------
   -- -------------------------------------------------------------------------------------------
-  bus_feedback: process(clk_i)
+  bus_feedback: process(rstn_i, clk_i)
   begin
-    if rising_edge(clk_i) then
+    if (rstn_i = '0') then
+      rden          <= '0';
+      bus_rsp_o.ack <= '0';
+    elsif rising_edge(clk_i) then
       rden          <= bus_req_i.stb and (not bus_req_i.rw);
       bus_rsp_o.ack <= bus_req_i.stb;
     end if;
   end process bus_feedback;
 
-  -- pack --
-  rdata <= mem_ram_b3_rd & mem_ram_b2_rd & mem_ram_b1_rd & mem_ram_b0_rd;
-
-  -- output gate --
-  bus_rsp_o.data <= rdata when (rden = '1') else (others => '0');
-
-  -- no access error possible --
-  bus_rsp_o.err <= '0';
+  bus_rsp_o.data <= rdata when (rden = '1') else (others => '0'); -- output gate
+  bus_rsp_o.err  <= '0'; -- no access error possible
 
 
 end neorv32_dmem_rtl;