Subversion Repositories neorv32

<<<
: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).
. 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: Feb 16 2022
HWV:  0x01060709
CLK:  0x05f5e100
ISA:  0x40901107 + 0xc000068b
SOC:  0x7b7f402f
IMEM: 0x00008000 bytes @0x00000000
DMEM: 0x00004000 bytes @0x80000000

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
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:

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