[image_generator, makefile] Update "raw" executable formats

CHANGELOG.md

@@ -32,6 +32,7 @@ mimpid = 0x01040312 => 01.04.03.12 => Version 01.04.03.12 => v1.4.3.12
 
 | Date (*dd.mm.yyyy*) | Version | Comment |
 |:----------:|:-------:|:--------|
+| 08.07.2022 | 1.7.3.5 | Update "raw" executable generation options of makefile and image generator; [#360](https://github.com/stnolting/neorv32/pull/360) |
 | 05.07.2022 | 1.7.3.4 | add "infrastructure" for cached (burst) bus accesses; [#359](https://github.com/stnolting/neorv32/pull/359) |
 | 01.07.2022 | 1.7.3.3 | minor rtl cleanups; [#357](https://github.com/stnolting/neorv32/pull/357) |
 | 29.06.2022 | 1.7.3.2 | :test_tube: add experimental core complex wrapper for integration into the [**LiteX**](https://github.com/enjoy-digital/litex) SoC builder framework; [#353](https://github.com/stnolting/neorv32/pull/353) |

docs/datasheet/software.adoc

@@ -154,17 +154,18 @@ Make sure to add the bin folder of RISC-V GCC to your PATH variable.
  help         - show this text
  check        - check toolchain
  info         - show makefile/toolchain configuration
- exe          - compile and generate <neorv32_exe.bin> executable for upload via bootloader
- hex          - compile and generate <neorv32_exe.hex> executable raw file
- image        - compile and generate VHDL IMEM boot image (for application) in local folder
- install      - compile, generate and install VHDL IMEM boot image (for application)
+ exe          - compile and generate <neorv32_exe.bin> executable for upload via default bootloader (binary file, with header)
+ bin          - compile and generate <neorv32_raw_exe.bin> RAW executable file (hex char file, no header)
+ hex          - compile and generate <neorv32_raw_exe.hex> RAW executable file (binary file, no header)
+ 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
- all          - exe + hex + install
+ all          - exe + install + hex + bin
  elf_info     - show ELF layout info
  clean        - clean up project home folder
  clean_all    - clean up whole project, core libraries and image generator
- bl_image     - compile and generate VHDL BOOTROM boot image (for bootloader only!) in local folder
- bootloader   - compile, generate and install VHDL BOOTROM boot image (for bootloader only!)
+ bl_image     - compile and generate VHDL BOOTROM boot image (for bootloader only, no header) in local folder
+ bootloader   - compile, generate and install VHDL BOOTROM boot image (for bootloader only, no header)
 
 == Variables ==
  USER_FLAGS   - Custom toolchain flags [append only], default ""
@@ -420,29 +421,33 @@ is available in `sw/example/demo_newlib`
 ==== Executable Image Generator
 
 The `main.bin` file is packed by the NEORV32 image generator (`sw/image_gen`) to generate the final executable file.
-
-[NOTE]
-The sources of the image generator are automatically compiled when invoking the makefile.
-
-The image generator can generate three types of executables, selected by a flag when calling the generator:
+The image generator can generate several types of executables selected by a flag when calling the generator:
 
 [cols="<1,<9"]
 [grid="none"]
 |=======================
-| `-app_bin` | Generates an executable binary file `neorv32_exe.bin` (for UART uploading via the bootloader).
-| `-app_hex` | Generates a plain ASCII hex-char file `neorv32_exe.hex` that can be used to initialize custom (instruction-) memories (in synthesis/simulation).
-| `-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.
-| `-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.
+| `-app_bin` | Generates an executable binary file `neorv32_exe.bin` (including header) for UART uploading via the bootloader.
+| `-app_img` | Generates an executable VHDL memory initialization image (no header) for the processor-internal IMEM. This option generates the `rtl/core/neorv32_application_image.vhd` file.
+| `-raw_hex` | Generates a plain ASCII hex-char file `neorv32_raw_exe.hex` (no header) for custom purpose.
+| `-raw_bin` | Generates a plain binary file `neorv32_raw_exe.bin` (no header) for custom purpose.
+| `-bld_img` | Generates an executable VHDL memory initialization image (no header) for the processor-internal BOOT ROM. This option generates the `rtl/core/neorv32_bootloader_image.vhd` file.
 |=======================
 
-All these options are managed by the makefile. The _normal application_ compilation flow will generate the `neorv32_exe.bin`
-executable to be upload via UART to the NEORV32 bootloader.
+All these options are managed by the makefile. The "normal application2 compilation flow will generate the `neorv32_exe.bin`
+executable for uploading via UART to the default NEORV32 bootloader.
 
+.Image Generator Compilation
+[NOTE]
+The sources of the image generator are automatically compiled when invoking the makefile (requiring a native GCC installation).
+
+.Executable Header
+[NOTE]
 The image generator add a small header to the `neorv32_exe.bin` executable, which consists of three 32-bit words located right at the
 beginning of the file. The first word of the executable is the signature word and is always `0x4788cafe`. Based on this word the bootloader
 can identify a valid image file. The next word represents the size in bytes of the actual program
 image in bytes. A simple "complement" checksum of the actual program image is given by the third word. This
-provides a simple protection against data transmission or storage errors.
+provides a simple protection against data transmission or storage errors. **Note that this executable format cannot be used for _direct_
+execution (e.g. via XIP or direct memory access).**
 
 
 :sectnums:

rtl/core/neorv32_package.vhd

@@ -68,7 +68,7 @@ package neorv32_package is
   -- Architecture Constants (do not modify!) ------------------------------------------------
   -- -------------------------------------------------------------------------------------------
   constant data_width_c : natural := 32; -- native data path width - do not change!
-  constant hw_version_c : std_ulogic_vector(31 downto 0) := x"01070304"; -- NEORV32 version - no touchy!
+  constant hw_version_c : std_ulogic_vector(31 downto 0) := x"01070305"; -- NEORV32 version - no touchy!
   constant archid_c     : natural := 19; -- official RISC-V architecture ID - hands off!
 
   -- Check if we're inside the Matrix -------------------------------------------------------

sw/common/common.mk

@@ -90,7 +90,8 @@ LD_SCRIPT = $(NEORV32_COM_PATH)/neorv32.ld
 
 # Main output files
 APP_EXE  = neorv32_exe.bin
-APP_HEX  = neorv32_exe.hex
+APP_HEX  = neorv32_raw_exe.hex
+APP_BIN  = neorv32_raw_exe.bin
 APP_ASM  = main.asm
 APP_IMG  = neorv32_application_image.vhd
 BOOT_IMG = neorv32_bootloader_image.vhd
@@ -139,10 +140,11 @@ CC_OPTS += $(USER_FLAGS)
 # 'compile' is still here for compatibility
 exe:     $(APP_ASM) $(APP_EXE)
 hex:     $(APP_ASM) $(APP_HEX)
+bin:     $(APP_ASM) $(APP_BIN)
 compile: $(APP_ASM) $(APP_EXE)
 image:   $(APP_ASM) $(APP_IMG)
 install: image install-$(APP_IMG)
-all:     $(APP_ASM) $(APP_EXE) $(APP_IMG) $(APP_HEX) install
+all:     $(APP_ASM) $(APP_EXE) $(APP_IMG) install hex bin
 
 # Check if making bootloader
 # Use different base address and length for instruction memory/"rom" (BOOTROM instead of IMEM)
@@ -199,7 +201,7 @@ main.bin: main.elf $(APP_ASM)
 
 
 # -----------------------------------------------------------------------------
-# Application targets: Generate binary executable, install (as VHDL file)
+# Application targets: Generate executable formats
 # -----------------------------------------------------------------------------
 # Generate NEORV32 executable image for upload via bootloader
 $(APP_EXE): main.bin $(IMAGE_GEN)
@@ -213,15 +215,21 @@ $(APP_IMG): main.bin $(IMAGE_GEN)
 	@set -e
 	@$(IMAGE_GEN) -app_img $< $@ $(shell basename $(CURDIR))
 
+# 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)/.
 
-# Generate NEORV32 executable image in plain hex format
+# Generate NEORV32 RAW executable image in plain hex format
 $(APP_HEX): main.bin $(IMAGE_GEN)
 	@set -e
-	@$(IMAGE_GEN) -app_hex $< $@ $(shell basename $(CURDIR))
+	@$(IMAGE_GEN) -raw_hex $< $@ $(shell basename $(CURDIR))
+
+# Generate NEORV32 RAW executable image in binary format
+$(APP_BIN): main.bin $(IMAGE_GEN)
+	@set -e
+	@$(IMAGE_GEN) -raw_bin $< $@ $(shell basename $(CURDIR))
 
 
 # -----------------------------------------------------------------------------
@@ -337,17 +345,18 @@ help:
 	@echo " help         - show this text"
 	@echo " check        - check toolchain"
 	@echo " info         - show makefile/toolchain configuration"
-	@echo " exe          - compile and generate <neorv32_exe.bin> executable for upload via bootloader"
-	@echo " hex          - compile and generate <neorv32_exe.hex> executable raw file"
-	@echo " image        - compile and generate VHDL IMEM boot image (for application) in local folder"
-	@echo " install      - compile, generate and install VHDL IMEM boot image (for application)"
+	@echo " exe          - compile and generate <neorv32_exe.bin> executable for upload via default bootloader (binary file, with header)"
+	@echo " bin          - compile and generate <neorv32_raw_exe.bin> RAW executable file (hex char file, no header)"
+	@echo " hex          - compile and generate <neorv32_raw_exe.hex> RAW executable file (binary file, no header)"
+	@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 " all          - exe + hex + install"
+	@echo " all          - exe + install + hex + bin"
 	@echo " elf_info     - show ELF layout info"
 	@echo " clean        - clean up project home folder"
 	@echo " clean_all    - clean up whole project, core libraries and image generator"
-	@echo " bl_image     - compile and generate VHDL BOOTROM boot image (for bootloader only!) in local folder"
-	@echo " bootloader   - compile, generate and install VHDL BOOTROM boot image (for bootloader only!)"
+	@echo " bl_image     - compile and generate VHDL BOOTROM boot image (for bootloader only, no header) in local folder"
+	@echo " bootloader   - compile, generate and install VHDL BOOTROM boot image (for bootloader only, no header)"
 	@echo ""
 	@echo "== Variables =="
 	@echo " USER_FLAGS   - Custom toolchain flags [append only], default \"$(USER_FLAGS)\""

sw/image_gen/image_gen.c

@@ -49,8 +49,9 @@ int main(int argc, char *argv[]) {
            "Three arguments are required.\n"
            "1st: Option\n"
            " -app_bin : Generate application executable binary (binary file, little-endian, with header) \n"
-           " -app_hex : Generate application raw executable (ASCII hex file, no header)\n"
            " -app_img : Generate application raw executable memory image (vhdl package body file, no header)\n"
+           " -raw_hex : Generate application raw executable (ASCII hex file, no header)\n"
+           " -raw_bin : Generate application raw executable (binary file, no header)\n"
            " -bld_img : Generate bootloader raw executable memory image (vhdl package body file, no header)\n"
            "2nd: Input file (raw binary image)\n"
            "3rd: Output file\n"
@@ -72,8 +73,10 @@ int main(int argc, char *argv[]) {
     option = 2;
   else if (strcmp(argv[1], "-bld_img") == 0)
     option = 3;
-  else if (strcmp(argv[1], "-app_hex") == 0)
+  else if (strcmp(argv[1], "-raw_hex") == 0)
     option = 4;
+  else if (strcmp(argv[1], "-raw_bin") == 0)
+    option = 5;
   else {
     printf("Invalid option!");
     return 1;
@@ -350,7 +353,7 @@ int main(int argc, char *argv[]) {
 
 
 // ------------------------------------------------------------
-// Generate APPLICATION's executable ASCII hex file (no header!!!)
+// Generate raw APPLICATION's executable ASCII hex file (no header!!!)
 // ------------------------------------------------------------
   if (option == 4) {
 
@@ -359,7 +362,6 @@ int main(int argc, char *argv[]) {
     buffer[1] = 0;
     buffer[2] = 0;
     buffer[3] = 0;
-    i = 0;
 
     while(fread(&buffer, sizeof(unsigned char), 4, input) != 0) {
       tmp  = (uint32_t)(buffer[0] << 0);
@@ -371,6 +373,35 @@ int main(int argc, char *argv[]) {
     }
   }
 
+
+// ------------------------------------------------------------
+// Generate raw APPLICATION's executable binary file (no header!!!)
+// ------------------------------------------------------------
+  if (option == 5) {
+
+    // data
+    buffer[0] = 0;
+    buffer[1] = 0;
+    buffer[2] = 0;
+    buffer[3] = 0;
+
+    while(fread(&buffer, sizeof(unsigned char), 4, input) != 0) {
+      tmp  = (uint32_t)(buffer[0] << 0);
+      tmp |= (uint32_t)(buffer[1] << 8);
+      tmp |= (uint32_t)(buffer[2] << 16);
+      tmp |= (uint32_t)(buffer[3] << 24);
+      fputc(buffer[0], output);
+      fputc(buffer[1], output);
+      fputc(buffer[2], output);
+      fputc(buffer[3], output);
+    }
+  }
+
+
+// ------------------------------------------------------------
+// Done, clean up
+// ------------------------------------------------------------
+
   fclose(input);
   fclose(output);