OpenTitan: Document and support flashing apps

OpenTitan needs the apps built into the binary. Add a section to the
documentation on how to do this and add a target to the Makefile.

We need to use the GCC objcopy as the LLVM one doesn't support updating
sections.

Signed-off-by: Alistair Francis <alistair.francis@wdc.com>

boards/opentitan/Makefile

@@ -14,4 +14,9 @@ qemu-app: $(TOCK_ROOT_DIRECTORY)target/$(TARGET)/release/$(PLATFORM).elf
 	qemu-system-riscv32 -M opentitan -kernel $^ -bios $(OPENTITAN_BOOT_ROM) -device loader,file=$(APP),addr=0x20030000 -nographic -serial mon:stdio
 
 flash: $(TOCK_ROOT_DIRECTORY)target/$(TARGET)/release/$(PLATFORM).bin
-	$(OPENTITAN_TREE)/sw/host/spiflash/spiflash --input=$(TOCK_ROOT_DIRECTORY)target/$(TARGET)/release/$(PLATFORM).bin
+	$(OPENTITAN_TREE)/build-out/sw/host/spiflash/spiflash --input=$(TOCK_ROOT_DIRECTORY)target/$(TARGET)/release/$(PLATFORM).bin
+
+flash-app: $(TOCK_ROOT_DIRECTORY)target/$(TARGET)/release/$(PLATFORM).elf
+	riscv32-none-elf-objcopy --update-section .apps=$(APP) $^ $(TOCK_ROOT_DIRECTORY)target/$(TARGET)/release/$(PLATFORM)-app.elf
+	$(OBJCOPY) --output-target=binary $(TOCK_ROOT_DIRECTORY)target/$(TARGET)/release/$(PLATFORM)-app.elf $(TOCK_ROOT_DIRECTORY)target/$(TARGET)/release/$(PLATFORM)-app.bin
+	$(OPENTITAN_TREE)/build-out/sw/host/spiflash/spiflash --input=$(TOCK_ROOT_DIRECTORY)target/$(TARGET)/release/$(PLATFORM)-app.bin

boards/opentitan/README.md

@@ -50,22 +50,58 @@ You can also just use the `spiflash` program manually to download the image to t
 
 NOTE: You will need to download the Tock binary after every power cycle.
 
+Programming Apps
+----------------
+
+Tock apps for OpenTitan must be included in the Tock binary file flashed with the steps mentioned above.
+
+Apps are built out of tree. Currently [libtock-rs](https://github.com/tock/libtock-rs) apps work well while [libtock-c](https://github.com/tock/libtock-c) apps require a special branch and complex work arounds. It is recomended that libtock-rs apps are used.
+
+Once an app is built and a tbf file is generated, you can use `riscv32-none-elf-objcopy` with `--update-section` to create an ELF image with the
+apps included.
+
+```shell
+$ riscv32-oe-elf-objcopy \
+    --update-section .apps=<...>/libtock-rs/target/riscv32imc-unknown-none-elf/tab/opentitan/hello_world/rv32imc.tbf \
+    <...>/tock/target/riscv32imc-unknown-none-elf/release/opentitan.elf\
+    <...>/tock/target/riscv32imc-unknown-none-elf/release/opentitan-app.elf
+```
+
+You will then need to convert this new elf to a binary file.
+
+```shell
+$ riscv32-oe-elf-objcopy \
+    --output-target=binary \
+    <...>/tock/target/riscv32imc-unknown-none-elf/release/opentitan-app.elf \
+    <...>/tock/target/riscv32imc-unknown-none-elf/release/opentitan-app.bin
+
+```
+
+The OpenTitan Makefile can also handle this process automatically. Follow the steps above but instead run the `flash-app` make target.
+
+```shell
+$ make flash-app APP=<...> OPENTITAN_TREE=/home/opentitan/
+```
+
+You will need to have the GCC version of RISC-V 32-bit objcopy installed as the LLVM one doesn't support updating sections.
+
+
 Running in QEMU
 ---------------
 
 The OpenTitan application can be run in the QEMU emulation platform, allowing quick and easy testing.
 
 QEMU can be started with Tock using the `qemu` make target:
 
-```bash
+```shell
 $ make OPENTITAN_BOOT_ROM=<path_to_opentitan>/sw/device/boot_rom/boot_rom_fpga_nexysvideo.elf qemu
 ```
 
 Where OPENTITAN_BOOT_ROM is set to point to the OpenTitan ELF file. This is usually located at `sw/device/boot_rom/boot_rom_fpga_nexysvideo.elf` in the OpenTitan build output.
 
 QEMU can be started with Tock and a userspace app with the `qemu-app` make target:
 
-```bash
+```shell
 $ make OPENTITAN_BOOT_ROM=<path_to_opentitan/sw/device/boot_rom/boot_rom_fpga_nexysvideo.elf> APP=/path/to/app.tbf qemu-app
 ```