WIP rework READMEs related to osflow and to the examples

boards/osflow/README.md

@@ -0,0 +1,50 @@
+# NEORV32 Example Setup for the tinyVision.ai Inc. "UPduino v3.0" FPGA Board
+
+This setup is similar to the other UPduino v3.0 one, but building of the FW is done by free & open source toolchain consisting of [GHDL](https://github.com/ghdl/ghdl), [Yosys](https://github.com/YosysHQ/yosys) & [nextPNR](https://github.com/YosysHQ/nextpnr).
+
+* Toolchain: GHDL-Yosys-NextPNR
+(instantiates NEORV32 top entity)
+* Pre-compiled bitstreams available as artifacts of Continuous Integration [Implementation](https://github.com/stnolting/neorv32/actions?query=workflow%3AImplementation) workflow runs.
+
+### Processor Configuration
+
+:information_source: This setup uses optimized platform-specific memory modules for the internal data and instruction memories (DMEM & IMEM). Each memory uses two
+UltraPlus SPRAM primitives (total memory size per memory = 2 x 32kB = 64kB). VHDL source file for platform-specific IMEM: [`neorv32_imem.ice40up_spram.vhd`](https://github.com/stnolting/neorv32/blob/master/boards/UPduino_v3_ghdl-yosys-nextpnr/neorv32_imem.ice40up_spram.vhd);
+VHDL source file for platform-specific DMEM: [`neorv32_dmem.ice40up_spram.vhd`](https://github.com/stnolting/neorv32/blob/master/boards/UPduino_v3_ghdl-yosys-nextpnr/neorv32_dmem.ice40up_spram.vhd).
+These platform-specific memories are used *instead* of the default platform-agnostic modules from the core's `rtl/core` folder.
+
+## How To Run
+
+#### FPGA Setup
+
+1. Run `make`
+2. When done start Radiant in GUI mode and open the programmer (for example via "Tools" -> "Programmer"); you will need a programmer configuration, which will be created in the next steps
+3. in the programmer double click on the field under "Operation" (_fast configuration_ should be the default) and select "External SPI Memory" as "Target Memory"
+4. select "SPI Serial Flash" under "SPI Flash Options / Family"
+5. select "WinBond" under "SPI Flash Options / Vendor"
+6. select "W25Q32" under "SPI Flash Options / Device"
+7. close the dialog by clicking "ok"
+8. click on "Program Device"
+
+
+#### NEORV32 Software Framework Modification
+
+In order to use the features provided by this setup, minor *optional* changes can be made to the default NEORV32 setup.
+
+To use the full 64kB capacity of the DMEM and IMEM, the linker script has to be modified. Open the linker script (`sw/common/neorv32.ld`) and change the default `LENGTH` assignments of `rom` and `ram` to 64kB (modify the RIGHT-most value only, see below):
+
+```
+rom  (rx) : ORIGIN = DEFINED(make_bootloader) ? 0xFFFF0000 : 0x00000000, LENGTH = DEFINED(make_bootloader) ? 4*1024 : 64*1024
+ram (rwx) : ORIGIN = 0x80000000, LENGTH = 64*1024
+```
+
+If you want to use the on-board SPI flash also for storing (and automatically booting) NEORV32 software applications you need to configure the default bootloader base address of the
+software image in order to prevent overriding the FPGA bitstream. Open the bootloader source code (`sw/bootloader/bootloader.c`) and modify the following definition (see below).
+You will need to re-compile (and re-install) the bootloader. This will also require to rerun synthesis.
+
+```c
+/** SPI flash boot image base address (warning! address might wrap-around!) */
+#define SPI_FLASH_BOOT_ADR (0x00020000)
+```
+
+You will need to recompile the bootloader and re-do FPGA synthesis.

boards/osflow/UPduino_v3/README.md → examples/README.md

@@ -1,19 +1,20 @@
-# NEORV32 Example Setup for the tinyVision.ai Inc. "UPduino v3.0" FPGA Board
-
-
-This example setup turns the UPduino v3.0 board, which features a Lattice iCE40 UltraPlus FPGA, into a medium-scale NEORV32 *microcontroller*.
-The processor setup provides 64kB of data and instruction memory, an RTOS-capable CPU (privileged architecture) and a set of standard peripherals like UART, TWI and SPI.
-This setup is similar to the other UPduino v3.0 one, but building of the FW is done by free & open source toolchain consisting of [GHDL](https://github.com/ghdl/ghdl), [Yosys](https://github.com/YosysHQ/yosys) & [nextPNR](https://github.com/YosysHQ/nextpnr).
+# Examples
 
+## UPduino v3.0
 
 * FPGA Board: :books: [tinyVision.ai Inc. UPduino v3 FPGA Board (GitHub)](https://github.com/tinyvision-ai-inc/UPduino-v3.0/), :credit_card: buy on [Tindie](https://www.tindie.com/products/tinyvision_ai/upduino-v30-low-cost-lattice-ice40-fpga-board/)
 * FPGA: Lattice iCE40 UltraPlus 5k `iCE40UP5K-SG48I`
-* Toolchain: GHDL-Yosys-NextPNR
-* Top entity: [`neorv32_upduino_v3_top.vhd`](https://github.com/stnolting/neorv32/blob/master/boards/UPduino_v3_ghdl-yosys-nextpnr/neorv32_upduino_v3_top.vhd) (instantiates NEORV32 top entity)
-* Pre-compiled bitstream available: `neorv32_upduino_v3_impl_1.bin`
 
 
-### Processor Configuration
+### [`neorv32_UPduino_v3_BoardTop_MinimalProcessor.vhd`](https://github.com/stnolting/neorv32/blob/master/examples/neorv32_UPduino_v3_BoardTop_MinimalProcessor.vhd)
+
+Minimal *blinky* example.
+
+### [`neorv32_UPduino_v3_BoardTop_SmallProcessor.vhd`](https://github.com/stnolting/neorv32/blob/master/examples/neorv32_UPduino_v3_BoardTop_SmallProcessor.vhd)
+
+This example setup turns the UPduino v3.0 into an RTOS capable NEORV32 *microcontroller*, along with a set of standard peripherals like UART, TWI and SPI.
+
+#### Processor Configuration
 
 * CPU: `rv32imac_Zicsr` (reduced CPU `[m]instret` & `[m]cycle` counter width!)
 * Memory: 64 kB instruction memory (internal IMEM), 64 kB data memory (internal DMEM), 4 kB bootloader ROM
@@ -23,15 +24,9 @@ This setup is similar to the other UPduino v3.0 one, but building of the FW is d
 * Tested with version [`1.5.5.5`](https://github.com/stnolting/neorv32/blob/master/CHANGELOG.md)
 * On-board FPGA bitstream flash storage can also be used to store/load NEORV32 application software (via the bootloader)
 
-:information_source: This setup uses optimized platform-specific memory modules for the internal data and instruction memories (DMEM & IMEM). Each memory uses two
-UltraPlus SPRAM primitives (total memory size per memory = 2 x 32kB = 64kB). VHDL source file for platform-specific IMEM: [`neorv32_imem.ice40up_spram.vhd`](https://github.com/stnolting/neorv32/blob/master/boards/UPduino_v3_ghdl-yosys-nextpnr/neorv32_imem.ice40up_spram.vhd);
-VHDL source file for platform-specific DMEM: [`neorv32_dmem.ice40up_spram.vhd`](https://github.com/stnolting/neorv32/blob/master/boards/UPduino_v3_ghdl-yosys-nextpnr/neorv32_dmem.ice40up_spram.vhd).
-These platform-specific memories are used *instead* of the default platform-agnostic modules from the core's `rtl/core` folder.
+#### Interface Signals
 
-
-### Interface Signals
-
-:information_source: See [`neorv32_upduino_v3.pcf`](https://github.com/stnolting/neorv32/blob/master/boards/UPduino_v3_ghdl-yosys-nextpnr/neorv32_upduino_v3.pcf)
+:information_source: See [`upduino_v3.pcf`](https://github.com/stnolting/neorv32/blob/master/boards/osflow/UPduino_v3/upduino_v3.pcf)
 for the FPGA pin mapping.
 
 | Top Entity Signal             | FPGA Pin   | Package Pin  | Board Header Pin |
@@ -64,8 +59,7 @@ for the FPGA pin mapping.
 
 :information_source: The TWI signals (`twi_sda_io` and `twi_scl_io`) and the reset input (`rstn_i`) require an external pull-up resistor. GPIO output 0 (`gpio_o(0)`) is used as output for a high-active status LED driven by the bootloader.
 
-
-### FPGA Utilization
+#### FPGA Utilization
 
 ```
 Device utilisation:
@@ -85,39 +79,3 @@ Device utilisation:
            SB_RGBA_DRV:     1/    1   100%
         ICESTORM_SPRAM:     4/    4   100%
 ```
-
-## How To Run
-
-#### FPGA Setup
-
-1. Run `make`
-2. When done start Radiant in GUI mode and open the programmer (for example via "Tools" -> "Programmer"); you will need a programmer configuration, which will be created in the next steps
-3. in the programmer double click on the field under "Operation" (_fast configuration_ should be the default) and select "External SPI Memory" as "Target Memory"
-4. select "SPI Serial Flash" under "SPI Flash Options / Family"
-5. select "WinBond" under "SPI Flash Options / Vendor"
-6. select "W25Q32" under "SPI Flash Options / Device"
-7. close the dialog by clicking "ok"
-8. click on "Program Device"
-
-
-#### NEORV32 Software Framework Modification
-
-In order to use the features provided by this setup, minor *optional* changes can be made to the default NEORV32 setup.
-
-To use the full 64kB capacity of the DMEM and IMEM, the linker script has to be modified. Open the linker script (`sw/common/neorv32.ld`) and change the default `LENGTH` assignments of `rom` and `ram` to 64kB (modify the RIGHT-most value only, see below):
-
-```
-rom  (rx) : ORIGIN = DEFINED(make_bootloader) ? 0xFFFF0000 : 0x00000000, LENGTH = DEFINED(make_bootloader) ? 4*1024 : 64*1024
-ram (rwx) : ORIGIN = 0x80000000, LENGTH = 64*1024
-```
-
-If you want to use the on-board SPI flash also for storing (and automatically booting) NEORV32 software applications you need to configure the default bootloader base address of the
-software image in order to prevent overriding the FPGA bitstream. Open the bootloader source code (`sw/bootloader/bootloader.c`) and modify the following definition (see below).
-You will need to re-compile (and re-install) the bootloader. This will also require to rerun synthesis.
-
-```c
-/** SPI flash boot image base address (warning! address might wrap-around!) */
-#define SPI_FLASH_BOOT_ADR (0x00020000)
-```
-
-You will need to recompile the bootloader and re-do FPGA synthesis.

rtl/templates/README.md

@@ -1,27 +1,36 @@
-## Top Templates
+# Top Templates
 
 The top entity of the NEORV32 processor is `rtl/core/neorv32_top.vhd`. This folder provides additional
 top entities/wrappers that instantiate the processor's top entity to provide a different interface.
 
 If you want to use one of the provided top entities from this folder, *also* add the according file to the project's
 HDL file list and select the according top_template file as top entity or instatiate the top_template within in your design.
 
+## Processor
 
-### [`neorv32_test_setup.vhd`](https://github.com/stnolting/neorv32/blob/master/rtl/top_templates/neorv32_test_setup.vhd)
+### [`neorv32_ProcessorTop_Minimal.vhd`](https://github.com/stnolting/neorv32/blob/master/rtl/templates/processor/neorv32_ProcessorTop_Minimal.vhd)
+
+This setup provides the minimal I/O, for testing the smallest possible design on new boards.
+
+### [`neorv32_ProcessorTop_Small.vhd`](https://github.com/stnolting/neorv32/blob/master/rtl/templates/processor/neorv32_ProcessorTop_Small.vhd)
+
+This processor setup provides 64kB of data and instruction memory, an RTOS-capable CPU (privileged architecture) and a set of standard peripherals like UART, TWI and SPI.
+
+### [`neorv32_ProcessorTop_Test.vhd`](https://github.com/stnolting/neorv32/blob/master/rtl/templates/processor/neorv32_ProcessorTop_Test.vhd)
 
 This entity is intended as "FPGA hello world" example for playing with the NEORV32. It uses only some of the
 provided peripherals and provides a very simple and basic interface - only the clock, reset, UART and a subset
 of the GPIO output port are propagated to the outer world.
 
+### [`neorv32_ProcessorTop_stdlogic.vhd`](https://github.com/stnolting/neorv32/blob/master/rtl/templates/processor/neorv32_ProcessorTop_stdlogic.vhd)
+
+Same entity (generics and interface ports) as the default NEORV32 Processor top entity (`rtl/core/neorv32_top.vhd`),
+but with _resolved_ port signals: All ports are of type `std_logic` or `std_logic_vector`, respectively.
 
-### [`neorv32_top_axi4lite.vhd`](https://github.com/stnolting/neorv32/blob/master/rtl/top_templates/neorv32_top_axi4lite)
+## System
+
+### [`neorv32_ProcessorTop_axi4lite.vhd`](https://github.com/stnolting/neorv32/blob/master/rtl/templates/system/neorv32_ProcessorTop_axi4lite)
 
 This setup provides all the peripheal/IO signals of the default processor top entity, but features an **AXI4-Lite**-compatible bus interface
 instead of the default Wishbone b4 interface. The AXI signal naming corresponds to the Xilinx user guide. The Xilinx Vivado IP packer
 is able to automatically detect the AXI interface ports. All ports signals of this top entity are of type `std_logic` or `std_logic_vector`, respectively.
-
-
-### [`neorv32_top_stdlogic.vhd`](https://github.com/stnolting/neorv32/blob/master/rtl/top_templates/neorv32_top_stdlogic.vhd)
-
-Same entity (generics and interface ports) as the default NEORV32 Processor top entity (`rtl/core/neorv32_top.vhd`),
-but with _resolved_ port signals: All ports are of type `std_logic` or `std_logic_vector`, respectively.