76 lines
4.4 KiB
Plaintext
76 lines
4.4 KiB
Plaintext
|
<<<
|
||
|
|
:sectnums:
|
||
|
|
== Customizing the Internal Bootloader
|
||
|
|
|
||
|
|
The NEORV32 bootloader provides several options to configure and customize it for a certain application setup.
|
||
|
|
This configuration is done by passing _defines_ when compiling the bootloader. Of course you can also
|
||
|
|
modify to bootloader source code to provide a setup that perfectly fits your needs.
|
||
|
|
|
||
|
|
[IMPORTANT]
|
||
|
|
Each time the bootloader sources are modified, the bootloader has to be re-compiled (and re-installed to the
|
||
|
|
bootloader ROM) and the processor has to be re-synthesized.
|
||
|
|
|
||
|
|
[NOTE]
|
||
|
|
Keep in mind that the maximum size for the bootloader is limited to 8kB and it should be compiled using the
|
||
|
|
minimal base & privileged ISA `rv32i_zicsr_zifencei` only to ensure it can work independently of the actual CPU configuration.
|
||
|
|
|
||
|
|
.Bootloader configuration parameters
|
||
|
|
[cols="<2,^1,^2,<6"]
|
||
|
|
[options="header", grid="rows"]
|
||
|
|
|=======================
|
||
|
|
| Parameter | Default | Legal values | Description
|
||
|
|
4+^| Memory layout
|
||
|
|
| `EXE_BASE_ADDR` | `0x00000000` | _any_ | Base address / boot address for the executable (see section "Address Space" in the NEORV32 data sheet)
|
||
|
|
4+^| Serial console interface
|
||
|
|
| `UART_EN` | `1` | `0`, `1` | Set to `0` to disable UART0 (no serial console at all)
|
||
|
|
| `UART_BAUD` | `19200` | _any_ | Baud rate of UART0
|
||
|
|
| `UART_HW_HANDSHAKE_EN` | `0` | `0`, `1` | Set to `1` to enable UART0 hardware flow control
|
||
|
|
4+^| Status LED
|
||
|
|
| `STATUS_LED_EN` | `1` | `0`, `1` | Enable bootloader status led ("heart beat") at `GPIO` output port pin #`STATUS_LED_PIN` when `1`
|
||
|
|
| `STATUS_LED_PIN` | `0` | `0` ... `31` | `GPIO` output pin used for the high-active status LED
|
||
|
|
4+^| Auto-boot configuration
|
||
|
|
| `AUTO_BOOT_TIMEOUT` | `8` | _any_ | Time in seconds after the auto-boot sequence starts (if there is no UART input by the user); set to 0 to disabled auto-boot sequence
|
||
|
|
4+^| SPI configuration
|
||
|
|
| `SPI_EN` | `1` | `0`, `1` | Set `1` to enable the usage of the SPI module (including load/store executables from/to SPI flash options)
|
||
|
|
| `SPI_FLASH_CS` | `0` | `0` ... `7` | SPI chip select output (`spi_csn_o`) for selecting flash
|
||
|
|
| `SPI_FLASH_ADDR_BYTES` | `3` | `2`, `3`, `4` | SPI flash address size in number of bytes (2=16-bit, 3=24-bit, 4=32-bit)
|
||
|
|
| `SPI_FLASH_SECTOR_SIZE` | `65536` | _any_ | SPI flash sector size in bytes
|
||
|
|
| `SPI_FLASH_CLK_PRSC` | `CLK_PRSC_8` | `CLK_PRSC_2` `CLK_PRSC_4` `CLK_PRSC_8` `CLK_PRSC_64` `CLK_PRSC_128` `CLK_PRSC_1024` `CLK_PRSC_2024` `CLK_PRSC_4096` | SPI clock pre-scaler (dividing main processor clock)
|
||
|
|
| `SPI_BOOT_BASE_ADDR` | `0x00400000` | _any_ 32-bit value | Defines the _base_ address of the executable in external flash
|
||
|
|
4+^| XIP configuration
|
||
|
|
| `XIP_EN` | `0` | `0`, `1` | Set `1` to enable the XIP options
|
||
|
|
|=======================
|
||
|
|
|
||
|
|
[NOTE]
|
||
|
|
The XIP options re-use the "SPI configuration" options for configuring the XIP's SPI connection.
|
||
|
|
|
||
|
|
Each configuration parameter is implemented as C-language `define` that can be manually overridden (_redefined_) when
|
||
|
|
invoking the bootloader's makefile. The according parameter and its new value has to be _appended_
|
||
|
|
(using `+=`) to the makefile `USER_FLAGS` variable. Make sure to use the `-D` prefix here.
|
||
|
|
|
||
|
|
For example, to configure a UART Baud rate of 57600 and redirecting the status LED to GPIO output pin 20
|
||
|
|
use the following command:
|
||
|
|
|
||
|
|
.Example: customizing, re-compiling and re-installing the bootloader
|
||
|
|
[source,console]
|
||
|
|
----
|
||
|
|
sw/bootloader$ make USER_FLAGS+=-DUART_BAUD=57600 USER_FLAGS+=-DSTATUS_LED_PIN=20 clean_all bootloader
|
||
|
|
----
|
||
|
|
|
||
|
|
[NOTE]
|
||
|
|
The `clean_all` target ensure that all libraries are re-compiled. The `bootloader` target will automatically
|
||
|
|
compile and install the bootloader to the HDL boot ROM (updating `rtl/core/neorv32_bootloader_image.vhd`).
|
||
|
|
|
||
|
|
:sectnums:
|
||
|
|
=== Auto-Boot Configuration
|
||
|
|
|
||
|
|
The default bootloader provides a UART-based user interface that allows to upload new executables
|
||
|
|
at any time. Optionally, the executable can also be programmed to an external SPI flash by the bootloader (see
|
||
|
|
section <<_programming_an_external_spi_flash_via_the_bootloader>>).
|
||
|
|
|
||
|
|
The bootloader also provides an _automatic boot sequence_ (auto-boot) which will start copying an executable
|
||
|
|
from external SPI flash to IMEM using the default SPI configuration. By this, the default bootloader
|
||
|
|
provides a "non-volatile program storage" mechanism that automatically boots from external SPI flash
|
||
|
|
(after `AUTO_BOOT_TIMEOUT`) while still providing the option to re-program the SPI flash at any time
|
||
|
|
via the UART console.
|