Rework (and auto-generate) file-list files (#972)

docs/datasheet/overview.adoc

@@ -168,23 +168,16 @@ neorv32               - Project home folder
 :sectnums:
 === VHDL File Hierarchy
 
-All necessary VHDL hardware description files are located in the project's `rtl/core` folder. The top entity
-of the entire processor including all the required configuration generics is `neorv32_top.vhd`.
-
-.Compile Order / File-List Files
-[IMPORTANT]
-Most of the RTL sources use **entity instantiation**. Hence, the RTL compile order might be relevant.
-Therefore, two file list files (`*.f`) are provided in the `rtl` folder that list all required rtl files
-for the CPU core and for the entire processor and also represent their recommended compile order.
+All necessary VHDL hardware description files are located in the project's `rtl/core` folder.
 
 .VHDL Library
 [IMPORTANT]
 All core VHDL files from the list below have to be assigned to a **new library** named `neorv32`.
 
 ...................................
-neorv32_top.vhd                  - NEORV32 PROCESSOR TOP ENTITY
+neorv32_top.vhd                  - NEORV32 PROCESSOR/SOC TOP ENTITY
 │
-├neorv32_cpu.vhd                 - NEORV32 CPU TOP ENTIT
+├neorv32_cpu.vhd                 - NEORV32 CPU TOP ENTITY
 │├neorv32_cpu_alu.vhd            - Arithmetic/logic unit
 ││├neorv32_cpu_cp_bitmanip.vhd   - Bit-manipulation co-processor (B ext.)
 ││├neorv32_cpu_cp_cfu.vhd        - Custom instructions co-processor (Zxcfu ext.)
@@ -245,6 +238,37 @@ source file in order to use platform-specific features (like advanced memory res
 and/or timing.
 
 
+:sectnums:
+==== File-List Files
+
+Most of the RTL sources use **entity instantiation**. Hence, the RTL compile order might be relevant (depending on
+the synthesis/simulation tool. Therefore, two file-list files are provided in the `rtl` folder that list all required
+HDL files for the CPU core and for the entire processor and also represent their recommended compile order.
+These file-list files can be consumed by EDA tools to simplify project setup.
+
+* `file_list_cpu.f` - HDL files and compile order for the CPU core; top module: `neorv32_cpu`
+* `file_list_soc.f` - HDL files and compile order for the entire processor/SoC; top module: `neorv32_top`
+
+A simple bash script `generate_file_lists.sh` is provided for regenerating the file-lists (using GHDL's _elaborate_ command).
+This script can also be invoked using the default application makefile (see <<_makefile_targets>>).
+
+By default, the file-list files include a _placeholder_ in the path of each included hardware source file.
+These placeholders need to be replaced by the actual path before being used. Example:
+
+* default: `NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_package.vhd`
+* adjusted: `path/to/neorv32/rtl/core/neorv32_package.vhd`
+
+.Processing the file-list files in a makefile
+[source,makefile]
+----
+NEORV32_HOME = path/to/neorv32 <1>
+NEORV32_SOC_FILE = $(shell cat $(NEORV32_HOME)/rtl/file_list_soc.f) <2>
+NEORV32_SOC_SRCS = $(subst NEORV32_RTL_PATH_PLACEHOLDER, $(NEORV32_HOME)/rtl, $(NEORV32_SOC_FILE))) <3>
+----
+<1> Path to the NEORV32 home folder (i.e. the root folder of the GitHub repository).
+<2> Load the content of the `file_list_soc.f` file-list into a new variable `NEORV32_SOC_FILE`.
+<3> Substitute the file-list file's path placeholder "`NEORV32_RTL_PATH_PLACEHOLDER`" by the actual path.
+
 
 <<<
 // ####################################################################################################################

docs/datasheet/software.adoc

@@ -172,6 +172,7 @@ Targets:
   image        - compile and generate VHDL IMEM boot image (for application, no header) in local folder
   install      - compile, generate and install VHDL IMEM boot image (for application, no header)
   sim          - in-console simulation using default/simple testbench and GHDL
+  hdl_lists    - regenerate HDL file-lists in NEORV32_HOME/rtl
   all          - exe + install + hex + bin + asm
   elf_info     - show ELF layout info
   elf_sections - show ELF sections

rtl/README.md

@@ -14,8 +14,12 @@ data memories (IMEM & DMEM). Make sure to add only **one** of each modules to th
 file list. However, these default files can also be replaced by optimized technology-specific memory modules.
 
 > [!TIP]
-> Two file list files (`*.f`) are provided that list all required rtl files for the CPU core and
-for the entire processor including their recommended compile order.
+> Two file-list files (`*.f`) are provided that list all required rtl files for the CPU core and
+for the entire processor including their recommended compile order. Make sure to substitute
+the `NEORV32_RTL_PATH_PLACEHOLDER` placeholder by the actual path to _this_ folder (`path/to/neorv32/rtl`).
+The `*.f` files can be re-generated using the provided GHDL bash script (`generate_file_lists.sh`).
+See the online documentation for more information:
+https://stnolting.github.io/neorv32/#_file_list_files
 
 ### > [`processor_templates`](processor_templates)
 

rtl/file_list_cpu.f

@@ -0,0 +1,17 @@
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_package.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_fifo.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_decompressor.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_control.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_regfile.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_cp_shifter.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_cp_muldiv.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_cp_bitmanip.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_cp_fpu.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_cp_cfu.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_cp_cond.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_alu.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_lsu.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_pmp.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_bootloader_image.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_application_image.vhd

rtl/file_list_soc.f

@@ -0,0 +1,48 @@
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_package.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_clockgate.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_fifo.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_decompressor.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_control.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_regfile.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_cp_shifter.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_cp_muldiv.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_cp_bitmanip.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_cp_fpu.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_cp_cfu.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_cp_cond.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_alu.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_lsu.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu_pmp.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cpu.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_intercon.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cache.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_dma.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_imem.entity.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_dmem.entity.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_boot_rom.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_xip.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_xbus.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_cfs.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_sdi.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_gpio.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_wdt.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_mtime.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_uart.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_spi.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_twi.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_pwm.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_trng.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_neoled.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_xirq.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_gptmr.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_onewire.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_slink.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_crc.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_sysinfo.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_debug_dtm.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_debug_dm.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_top.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_bootloader_image.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/neorv32_application_image.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/mem/neorv32_imem.legacy.vhd
+NEORV32_RTL_PATH_PLACEHOLDER/core/mem/neorv32_dmem.legacy.vhd

rtl/generate_file_lists.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+# Generate file lists for the CPU and the entire processor/SoC
+# using GHDL's elaborate option.
+
+set -e
+
+cd $(dirname "$0")
+
+mkdir -p ~build
+
+ghdl -i --work=neorv32 --workdir=~build core/*.vhd core/mem/*.vhd
+
+echo "Regenerating file_list_cpu.f ..."
+ghdl --elab-order --work=neorv32 --workdir=~build neorv32_cpu > ~file_list_cpu.f
+while IFS= read -r line; do
+  echo "NEORV32_RTL_PATH_PLACEHOLDER/$line"
+done < ~file_list_cpu.f > file_list_cpu.f
+
+echo "Regenerating file_list_soc.f ..."
+ghdl --elab-order --work=neorv32 --workdir=~build neorv32_top > ~file_list_soc.f
+while IFS= read -r line; do
+  echo "NEORV32_RTL_PATH_PLACEHOLDER/$line"
+done < ~file_list_soc.f > file_list_soc.f
+
+rm ~file_list_cpu.f ~file_list_soc.f
+rm -rf ~build

sw/common/common.mk

@@ -55,18 +55,17 @@ NEORV32_INC_PATH = $(NEORV32_HOME)/sw/lib/include
 NEORV32_SRC_PATH = $(NEORV32_HOME)/sw/lib/source
 # Path to NEORV32 executable generator
 NEORV32_EXG_PATH = $(NEORV32_HOME)/sw/image_gen
-# Path to NEORV32 core rtl folder
-NEORV32_RTL_PATH = $(NEORV32_LOCAL_RTL)/core
+# Path to NEORV32 rtl folder
+NEORV32_RTL_PATH = $(NEORV32_LOCAL_RTL)
 # Path to NEORV32 sim folder
 NEORV32_SIM_PATH = $(NEORV32_HOME)/sim/simple
 # Marker file to check for NEORV32 home folder
 NEORV32_HOME_MARKER = $(NEORV32_INC_PATH)/neorv32.h
 
 # Core libraries (peripheral and CPU drivers)
-CORE_SRC  = $(wildcard $(NEORV32_SRC_PATH)/*.c)
+CORE_SRC = $(wildcard $(NEORV32_SRC_PATH)/*.c)
 # Application start-up code
 CORE_SRC += $(NEORV32_COM_PATH)/crt0.S
-
 # Linker script
 LD_SCRIPT ?= $(NEORV32_COM_PATH)/neorv32.ld
 
@@ -221,8 +220,8 @@ $(APP_IMG): main.bin $(IMAGE_GEN)
 # Install VHDL memory initialization file
 install-$(APP_IMG): $(APP_IMG)
 	@set -e
-	@echo "Installing application image to $(NEORV32_RTL_PATH)/$(APP_IMG)"
-	@cp $(APP_IMG) $(NEORV32_RTL_PATH)/.
+	@echo "Installing application image to $(NEORV32_RTL_PATH)/core/$(APP_IMG)"
+	@cp $(APP_IMG) $(NEORV32_RTL_PATH)/core/.
 
 # Generate NEORV32 RAW executable image in plain hex format
 $(APP_HEX): main.bin $(IMAGE_GEN)
@@ -260,8 +259,8 @@ $(BOOT_IMG): main.bin $(IMAGE_GEN)
 
 install-$(BOOT_IMG): $(BOOT_IMG)
 	@set -e
-	@echo "Installing bootloader image to $(NEORV32_RTL_PATH)/$(BOOT_IMG)"
-	@cp $(BOOT_IMG) $(NEORV32_RTL_PATH)/.
+	@echo "Installing bootloader image to $(NEORV32_RTL_PATH)/core/$(BOOT_IMG)"
+	@cp $(BOOT_IMG) $(NEORV32_RTL_PATH)/core/.
 
 # Just an alias
 bl_image: $(BOOT_IMG)
@@ -306,6 +305,13 @@ sim: $(APP_IMG) install
 	@sh $(NEORV32_SIM_PATH)/ghdl.sh $(GHDL_RUN_FLAGS)
 
 
+# -----------------------------------------------------------------------------
+# Regenerate HDL file lists
+# -----------------------------------------------------------------------------
+hdl_lists:
+	@sh $(NEORV32_RTL_PATH)/generate_file_lists.sh
+
+
 # -----------------------------------------------------------------------------
 # Show final ELF details (just for debugging)
 # -----------------------------------------------------------------------------
@@ -395,6 +401,7 @@ help:
 	@echo "  image        - compile and generate VHDL IMEM boot image (for application, no header) in local folder"
 	@echo "  install      - compile, generate and install VHDL IMEM boot image (for application, no header)"
 	@echo "  sim          - in-console simulation using default/simple testbench and GHDL"
+	@echo "  hdl_lists    - regenerate HDL file-lists (*.f) in NEORV32_HOME/rtl"
 	@echo "  all          - exe + install + hex + bin + asm"
 	@echo "  elf_info     - show ELF layout info"
 	@echo "  elf_sections - show ELF sections"