Skip to content

Commit

Permalink
[doc] update section "Executable Image Format"
Browse files Browse the repository at this point in the history
cleanups and add support for mif file type
  • Loading branch information
stnolting committed Jul 11, 2024
1 parent 0ca6454 commit 412f3c2
Showing 1 changed file with 28 additions and 18 deletions.
46 changes: 28 additions & 18 deletions docs/datasheet/software.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -163,10 +163,12 @@ Targets:
gdb - run GNU debugging session
asm - compile and generate <main.asm> assembly listing file for manual debugging
elf - compile and generate <main.elf> ELF file
bin - compile and generate <neorv32_raw_exe.bin> RAW executable file (binary file, no header)
hex - compile and generate <neorv32_raw_exe.hex> RAW executable file (hex char file, no header)
coe - compile and generate <neorv32_raw_exe.coe>> RAW executable file (COE file, no header)
mem - compile and generate <neorv32_raw_exe.mem>> RAW executable file (MEM file, no header)
exe - compile and generate <neorv32_exe.bin> executable image file for upload via default bootloader (binary file)
bin - compile and generate <neorv32_raw_exe.bin> RAW executable memory image (binary file)
hex - compile and generate <neorv32_raw_exe.hex> RAW executable memory image (hex char file)
coe - compile and generate <neorv32_raw_exe.coe> RAW executable memory image (COE file)
mem - compile and generate <neorv32_raw_exe.mem> RAW executable memory image (MEM file)
mif - compile and generate <neorv32_raw_exe.mif> RAW executable memory image (MIF file)
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
Expand Down Expand Up @@ -288,7 +290,7 @@ The makefile's `CC_OPTS` is exported as **define** to be available within a C pr
| `-g` | Include debugging information/symbols in ELF.
| `-mstrict-align` | Unaligned memory accesses cannot be resolved by the hardware and require emulation.
| `-mbranch-cost=10` | Branching costs a lot of cycles.
| `-ffp-contract=off` | Do not allow contraction of floatind-point operations (no fused operations as they are not supported).
| `-ffp-contract=off` | Do not allow contraction of floating-point operations (no fused operations as they are not supported).
|=======================
:sectnums:
Expand Down Expand Up @@ -321,15 +323,23 @@ override USER_FLAGS += "-g -Wl,--__neorv32_heap_size,__heap_size=4096"
=== Executable Image Format

In order to generate an executable for the processors all source files have to be compiled, linked
and packed into a final executable.
and packed into a final executable. This executable can be further converted into several image formats.

.Memory Image Formats
[TIP]
The NEORV32 software framework includes an <<_executable_image_generator>> than can convert an application
into several different file formats. These include raw hex files, a proprietary format for uploading via the
default <<_bootloader>> as well as several standard FPGA memory initialization file types (e.g. `*.coe`,
`*.mem` and `*.mif`). These image file formats are generated by the according <<_makefile_targets>>.


:sectnums:
==== Linker Script

After all the application sources have been compiled, they need to be _linked_.
For this purpose the makefile uses the NEORV32-specific linker scThe linker script defines several sections
For this purpose the makefile uses the NEORV32-specific linker script. This linker script defines several sections
for the final executable (compare with <<_address_space>>). However, only the `ram` and `rom` sections are
relevant for the executable itself; the raining sections are just listed fro completeness.
relevant for the executable itself; the remaining sections are just listed for completeness.

.Linker script - memory sections
[cols="<2,<8"]
Expand Down Expand Up @@ -486,21 +496,21 @@ The image generator can generate several types of executable file formats select
[cols="<2,<8"]
[grid="none"]
|=======================
| `-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.
| `-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.
| `-raw_hex` | Generates a plain 8x 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.
| `-raw_coe` | Generates a COE file `neorv32_raw_exe.coe` (no header) for FPGA memory initialization.
| `-raw_mem` | Generates a MEM file `neorv32_raw_exe.mem` (no header) for FPGA memory initialization.
| `-app_bin` | Generates an executable binary file `neorv32_exe.bin` (including bootloader header) for uploading via the bootloader.
| `-app_img` | Generates an executable VHDL memory initialization image for the processor-internal IMEM. This option regenerates 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 regenerates the `rtl/core/neorv32_bootloader_image.vhd` file.
| `-raw_hex` | Generates a raw 8x ASCII hex-char file `neorv32_raw_exe.hex` for custom purpose.
| `-raw_bin` | Generates a raw binary file `neorv32_raw_exe.bin` for custom purpose.
| `-raw_coe` | Generates a raw COE file `neorv32_raw_exe.coe` for FPGA memory initialization.
| `-raw_mem` | Generates a raw MEM file `neorv32_raw_exe.mem` for FPGA memory initialization.
| `-raw_mif` | Generates a raw MIF file `neorv32_raw_exe.mif` for FPGA memory initialization.
|=======================
All these options are managed by the makefile. The normal application compilation flow will generate the `neorv32_exe.bin`
executable designated for uploading via the default NEORV32 bootloader.
**All these options are managed by the makefile (see <<_makefile_targets>>).**
.Image Generator Compilation
[NOTE]
The sources of the image generator are automatically compiled when invoking the makefile (requiring a native GCC installation).
The sources of the image generator are automatically compiled when invoking the makefile (requiring a _native_ GCC installation).

.Executable Header
[NOTE]
Expand Down

0 comments on commit 412f3c2

Please sign in to comment.