<<<
:sectnums:
== Uploading and Starting of a Binary Executable Image via UART

Follow this guide to use the bootloader to upload an executable via UART.

[NOTE]
This concept uses the default "Indirect Boot" scenario that uses the bootloader to upload new executables.
See datasheet section https://stnolting.github.io/neorv32/#_indirect_boot[Indirect Boot] for more information.

[IMPORTANT]
If your FPGA board does not provide such an interface - don't worry!
Section <<_installing_an_executable_directly_into_memory>> shows how to
run custom programs on your FPGA setup without having a UART.

[start=1]
. Connect the primary UART (UART0) interface of your FPGA board to a serial port of your host computer.
. Start a terminal program. In this tutorial, I am using TeraTerm for Windows. You can download it for free
from https://ttssh2.osdn.jp/index.html.en . On Linux you could use `cutecom` (recommended) or `GTKTerm`,
which you can get here https://github.com/Jeija/gtkterm.git (or install via your package manager).

[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).

[start=3]
. Open a connection to the the serial port your UART is connected to. Configure the terminal setting according to the
following parameters:

* 19200 Baud
* 8 data bits
* 1 stop bit
* no parity bits
* _no_ transmission/flow control protocol
* receiver (host computer) newline on `\r\n` (carriage return & newline)

[start=4]
. Also make sure that single chars are send from your computer _without_ any consecutive "new line" or "carriage
return" commands. This is highly dependent on your terminal application of choice, TeraTerm only
sends the raw chars by default. In `cutecom`, change `LF` to `None` in the dropdown menu 
next to the input text box.
. Press the NEORV32 reset button to restart the bootloader. The status LED starts blinking and the
bootloader intro screen appears in your console. Hurry up and press any key (hit space!) to abort the
automatic boot sequence and to start the actual bootloader user interface console.

.Bootloader console; aborted auto-boot sequence
[source,bash]
----
<< NEORV32 Bootloader >>

BLDV: Mar  7 2023
HWV:  0x01080107
CID:  0x00000000
CLK:  0x05f5e100
MISA: 0x40901106
XISA: 0xc0000fab
SOC:  0xffff402f
IMEM: 0x00008000 bytes @0x00000000
DMEM: 0x00002000 bytes @0x80000000

Autoboot in 8s. Press any key to abort.
Aborted.

Available CMDs:
 h: Help
 r: Restart
 u: Upload
 s: Store to flash
 l: Load from flash
 x: Boot from flash (XIP)
 e: Execute
CMD:>
----

[start=6]
. Execute the "Upload" command by typing `u`. Now the bootloader is waiting for a binary executable to be send.

[source,bash]
----
CMD:> u
Awaiting neorv32_exe.bin...
----

[start=7]
. Use the "send file" option of your terminal program to send a NEORV32 executable (`neorv32_exe.bin`).
. Again, make sure to transmit the executable in raw binary mode (no transfer protocol).
When using TeraTerm, select the "binary" option in the send file dialog.
. If everything went fine, OK will appear in your terminal:

[IMPORTANT]
Make sure to upload the NEORV32 executable `neorv32_exe.bin`. Uploading any other file (like `main.bin`)
will cause an `ERR_EXE` bootloader error (see https://stnolting.github.io/neorv32/#_bootloader_error_codes).

[source,bash]
----
CMD:> u
Awaiting neorv32_exe.bin... OK
----

[start=10]
. The executable is now in the instruction memory of the processor. To execute the program right
now run the "Execute" command by typing `e`:

[source,bash]
----
CMD:> u
Awaiting neorv32_exe.bin... OK
CMD:> e
Booting...
Blinking LED demo program
----

[start=11]
. If everything went fine, you should see the LEDs blinking.

[NOTE]
The bootloader will print error codes if something went wrong.
See section https://stnolting.github.io/neorv32/#_bootloader[Bootloader] of the NEORV32 datasheet for more information.

[TIP]
See section <<_programming_an_external_spi_flash_via_the_bootloader>> to learn how to use an external SPI
flash for nonvolatile program storage.

[TIP]
Executables can also be uploaded via the **on-chip debugger**.
See section <<_debugging_with_gdb>> for more information.
