Merge pull request #268 from stnolting/bootloader_lto_test

🧪 Using LTO (link-time-optimization) for bootloader + console improvements

CHANGELOG.md

@@ -32,6 +32,7 @@ The version number is globally defined by the `hw_version_c` constant in the mai
 
 | Date (*dd.mm.yyyy*) | Version | Comment |
 |:----------:|:-------:|:--------|
+| 03.02.2022 | 1.6.7.3 | using `LTO` (link-time-optimization) option for **bootloader**; improved bootloader user console; see [PR #268](https://github.com/stnolting/neorv32/pull/268) |
 | 31.01.2022 | 1.6.7.2 | :bug: fixed minor bug in **bootloader'd MTIME handling** (bootloader crashed if `Zicntr` ISA extension not enabled), fixed minor issues in MTIME and `time` CSRs handling; added MTIME example program; see [PR #267](https://github.com/stnolting/neorv32/pull/267) |
 | 30.01.2022 | 1.6.7.1 | :sparkles: added **`Zxcfu` ISA extension for user-defined custom RISC-V instructions**; see [PR #264](https://github.com/stnolting/neorv32/pull/264) |
 | 28.01.2022 |[**:rocket:1.6.7**](https://github.com/stnolting/neorv32/releases/tag/v1.6.7) | **New release** |

docs/datasheet/software.adoc

@@ -405,35 +405,42 @@ int __neorv32_crt0_after_main(int32_t return_code) {
 === Bootloader
 
 [NOTE]
-This section illustrated the **default** bootloader from the repository. The bootloader can be customized
+This section refers to the **default** bootloader from the repository. The bootloader can be customized
 to target application-specific scenarios. See User Guide section
 https://stnolting.github.io/neorv32/ug/#_customizing_the_internal_bootloader[Customizing the Internal Bootloader]
 for more information.
 
-The default NEORV32 bootloader (source code `sw/bootloader/bootloader.c`) provides a build-in firmware that
-allows to upload new application executables via UART at every time and to optionally store/boot them to/from
-an external SPI flash. It features a simple "automatic boot" feature that will try to fetch an executable
-from SPI flash if there is _no_ UART user interaction. This allows to build processor setup with
-non-volatile application storage, which can be updated at any time.
+The NEORV32 bootloader (source code `sw/bootloader/bootloader.c`) provides an optional build-in firmware that
+allows to upload new application executables without the need to re-synthesize the FPGA's bitstream.
+A UART connection is used to provide a simple text-based user interface that allows to upload executables.
 
-The bootloader is only implemented if the <<_int_bootloader_en>> generic is _true_. This will
-select the <<_indirect_boot>> boot configuration.
+Furthermore, the bootloader provides options to program executable to a processor-external SPI flash.
+An "auto boot" feature can optionally fetch this executable
+right after reset if there is no user interaction via UART. This allows to build processor setup with
+non-volatile application storage, which can still be updated at any time.
 
-.Hardware requirements of the _default_ NEORV32 bootloader
+The bootloader is implemented if the <<_int_bootloader_en>> generic is _true_ (default). This will automatically
+select the CPU's <<_indirect_boot>> boot configuration.
+
+.Hardware Requirements for the _Default_ NEORV32 Bootloader
 [IMPORTANT]
-**REQUIRED**: The bootloader requires the CSR access CPU extension (<<_cpu_extension_riscv_zicsr>> generic is _true_)
+**REQUIRED**: The bootloader requires the privileged architecture CPU extension
+(<<_zicsr_control_and_status_register_access_privileged_architecture>>)
 and at least 512 bytes of data memory (processor-internal DMEM or external DMEM). +
  +
-_RECOMMENDED_: For user interaction via UART (like uploading executables) the primary UART (UART0) has to be
-implemented (<<_io_uart0_en>> generic is _true_). Without UART the bootloader does not make much sense. However, auto-boot
-via SPI is still supported but the bootloader should be customized (see User Guide) for this purpose. +
+**RECOMMENDED**: For user interaction via UART (like uploading executables) the primary UART
+(<<_primary_universal_asynchronous_receiver_and_transmitter_uart0>>) has to be implemented.
+Without UART0 the auto-boot via SPI is still supported but the bootloader should be customized
+(see User Guide) for this purpose. +
+ +
+**RECOMMENDED**: The default bootloader uses bit 0 of the GPIO controller's
+(<<_general_purpose_input_and_output_port_gpio>>) output port to drive a high-active "heart beat" status LED. +
  +
-_OPTIONAL_: The default bootloader uses bit 0 of the GPIO output port as "heart beat" and status LED if the
-GPIO controller is implemented (<<_io_gpio_en>> generic is _true_). +
+**RECOMMENDED**: The MTIME machine timer (<<_machine_system_timer_mtime>> generic is _true_) is used to control
+blinking of the status LED and also to automatically trigger the auto-boot sequence. +
  +
-_OPTIONAL_: The MTIME machine timer (<<_io_mtime_en>> generic is _true_) and the SPI controller
-(<<_io_spi_en>> generic is _true_) are required in order to use the bootloader's auto-boot feature
-(automatic boot from external SPI flash if there is no user interaction via UART).
+**OPTIONAL**: The SPI controller (<<_serial_peripheral_interface_controller_spi>>) is required
+to store/load executable from external flash (for the auto boot feature).
 
 To interact with the bootloader, connect the primary UART (UART0) signals (`uart0_txd_o` and
 `uart0_rxd_o`) of the processor's top entity via a serial port (-adapter) to your computer (hardware flow control is
@@ -447,32 +454,32 @@ Terminal console settings (`19200-8-N-1`):
 * no parity bit
 * 1 stop bit
 * newline on `\r\n` (carriage return, newline)
-* no transfer protocol / control flow protocol - just the raw byte stuff
+* no transfer protocol / control flow protocol - just raw bytes
 
 [IMPORTANT]
 _Any_ terminal program that can connect to a serial port should work. However, make sure the program
 can transfer data in _raw_ byte mode without any protocol overhead around it. Some terminal programs struggle with
 transmitting files larger than 4kB (see https://github.com/stnolting/neorv32/pull/215). Try a different program
-if uploading a binary does not work (terminal stall).
+if uploading a binary does not work.
 
-The bootloader uses the LSB of the top entity's `gpio_o` output port as high-active status LED (all other
-output pin are set to low level by the bootloader). After reset, this LED will start blinking at ~2Hz and the
+The bootloader uses the LSB of the top entity's `gpio_o` output port as high-active **status LED** (all other
+output pin are set to low level). After reset, this LED will start blinking at ~2Hz and the
 following intro screen should show up in your terminal:
 
 [source]
 ----
 << NEORV32 Bootloader >>
 
-BLDV: Mar 23 2021
-HWV:  0x01050208
-CLK:  0x05F5E100
-MISA: 0x40901105
-CPU:  0x00000023
-SOC:  0x0EFF0037
+BLDV: Feb  3 2022
+HWV:  0x01060703
+CLK:  0x05f5e100
+MISA: 0x40901107
+CPU:  0xc00006ab
+SOC:  0x7b7f402f
 IMEM: 0x00004000 bytes @ 0x00000000
 DMEM: 0x00002000 bytes @ 0x80000000
 
-Autoboot in 8s. Press key to abort.
+Autoboot in 8s. Press any key to abort.
 ----
 
 This start-up screen also gives some brief information about the bootloader and several system configuration parameters:
@@ -490,38 +497,37 @@ This start-up screen also gives some brief information about the bootloader and
 | `DMEM` | DMEM memory base address and size in byte (from the _MEM_INT_DMEM_SIZE_ generic).
 |=======================
 
-Now you have 8 seconds to press any key. Otherwise, the bootloader starts the auto boot sequence. When
+Now you have 8 seconds to press _any_ key. Otherwise, the bootloader starts the <<_auto_boot_sequence>>. When
 you press any key within the 8 seconds, the actual bootloader user console starts:
 
 [source]
 ----
 << NEORV32 Bootloader >>
 
-BLDV: Mar 23 2021
-HWV:  0x01050208
-CLK:  0x05F5E100
-USER: 0x10000DE0
-MISA: 0x40901105
-CPU:  0x00000023
-SOC:  0x0EFF0037
+BLDV: Feb  3 2022
+HWV:  0x01060703
+CLK:  0x05f5e100
+MISA: 0x40901107
+CPU:  0xc00006ab
+SOC:  0x7b7f402f
 IMEM: 0x00004000 bytes @ 0x00000000
 DMEM: 0x00002000 bytes @ 0x80000000
 
-Autoboot in 8s. Press key to abort.
-Aborted.
+Autoboot in 8s. Press any key to abort.
+Aborted. <1>
 
 Available commands:
-h: Help
-r: Restart
-u: Upload
-s: Store to flash
-l: Load from flash
-e: Execute
+ h: Help
+ r: Restart
+ u: Upload
+ s: Store to flash
+ l: Load from flash
+ e: Execute
 CMD:>
 ----
+<1> Auto boot sequence aborted due to user console input.
 
-The auto-boot countdown is stopped and now you can enter a command from the list to perform the
-corresponding operation:
+The auto boot countdown is stopped and the bootloader's user console is ready to receive one of the following commands:
 
 * `h`: Show the help text (again)
 * `r`: Restart the bootloader and the auto-boot sequence
@@ -546,6 +552,7 @@ https://stnolting.github.io/neorv32/ug/#_programming_an_external_spi_flash_via_t
 
 :sectnums:
 ==== Auto Boot Sequence
+
 When you reset the NEORV32 processor, the bootloader waits 8 seconds for a UART console input before it
 starts the automatic boot sequence. This sequence tries to fetch a valid boot image from the external SPI
 flash, connected to SPI chip select `spi_csn_o(0)`. If a valid boot image is found that can be successfully
@@ -556,21 +563,20 @@ is no valid boot image found, and error code will be shown.
 :sectnums:
 ==== Bootloader Error Codes
 
-If something goes wrong during bootloader operation, an error code is shown. In this case the processor
-stalls, a bell command and one of the following error codes are send to the terminal, the bootloader status
-LED is permanently activated and the system must be manually reset.
+If something goes wrong during bootloader operation, an error code and a short message is shown. In this case the processor
+stalls,, the bootloader status LED is permanently activated and the processor must be reset manually.
 
 [TIP]
 In many cases the error source is just _temporary_ (like some HF spike during an UART upload). Just try again.
 
-[cols="<2,<13"]
+[cols="<2,<8"]
 [grid="rows"]
 |=======================
 | **`ERROR_0`** | If you try to transfer an invalid executable (via UART or from the external SPI flash), this error message shows up. There might be a transfer protocol configuration error in the terminal program. Also, if no SPI flash was found during an auto-boot attempt, this message will be displayed.
 | **`ERROR_1`** | Your program is way too big for the internal processor’s instructions memory. Increase the memory size or reduce your application code.
 | **`ERROR_2`** | This indicates a checksum error. Something went wrong during the transfer of the program image (upload via UART or loading from the external SPI flash). If the error was caused by a UART upload, just try it again. When the error was generated during a flash access, the stored image might be corrupted.
 | **`ERROR_3`** | This error occurs if the attached SPI flash cannot be accessed. Make sure you have the right type of flash and that it is properly connected to the NEORV32 SPI port using chip select #0.
-| **`ERR 0x???????? 0x???????? 0x????????`** | The bootloader encountered an exception during operation. This might be caused when it tries to access peripherals that were not implemented during synthesis. Example: executing `l` or `s` (SPI flash operations) without the SPI module beeing implemented.
+| **`ERROR - Unexpected exception!`** | The bootloader encountered an exception during operation. This might be caused when it tries to access peripherals that were not implemented during synthesis. Example: executing commands `l` or `s` (SPI flash operations) without the SPI module beeing implemented.
 |=======================
 
 

docs/userguide/executable_upload.adoc

@@ -49,25 +49,25 @@ automatic boot sequence and to start the actual bootloader user interface consol
 ----
 << NEORV32 Bootloader >>
 
-BLDV: Mar 23 2021
-HWV:  0x01050208
-CLK:  0x05F5E100
-MISA: 0x40901105
-ZEXT: 0x00000023
-PROC: 0x0EFF0037
+BLDV: Feb  3 2022
+HWV:  0x01060703
+CLK:  0x05f5e100
+MISA: 0x40901107
+CPU:  0xc00006ab
+SOC:  0x7b7f402f
 IMEM: 0x00004000 bytes @ 0x00000000
 DMEM: 0x00002000 bytes @ 0x80000000
 
-Autoboot in 8s. Press key to abort.
+Autoboot in 8s. Press any key to abort.
 Aborted.
 
 Available commands:
-h: Help
-r: Restart
-u: Upload
-s: Store to flash
-l: Load from flash
-e: Execute
+ h: Help
+ r: Restart
+ u: Upload
+ s: Store to flash
+ l: Load from flash
+ e: Execute
 CMD:>
 ----