Merge #3411

3411: Update OpenTitan Makefile and build examples r=hudson-ayers a=jwnrt ## Pull Request Overview This pull updates parts of OpenTitan's Makefile and README that I ran into when trying to build and run Tock: ## Disable default board configuration Disabled the default `fpga_cw310` Cargo feature when a `BOARD_CONFIGURATION` is specified. Previously, both `fpga_cw310` and `sim_verilator` would be set, leading to conflicting `const CONFIG` definitions in `chips/earlgrey`. ### Objcopy binary The Makefile is using `riscv64-linux-gnu-objcopy` as documented in #2104. The reasoning was that `llvm-objcopy` wasn't providing correct output. From #2104 it looks like `riscv64-linux-gnu` was chosen because users were likely to have it installed. `riscv32-unknown-elf-objcopy` is provided by the lowRISC toolchain used for building OpenTitan software, so I thought developers would be more likely to have this already installed. Happy not to include this change, though. I also haven't checked whether the `llvm-objcopy` bug is now resolved and that could be used instead. ### README examples The QEMU examples in the README were outdated, possibly since `libtock-rs` has updated. Updated these examples, and tidied up some Markdown along the way. ## Testing Strategy This pull request was tested by running the updated README examples and make rules. ## TODO or Help Wanted Any thoughts on using `riscv32-unknown-elf-objcopy` by default over `riscv64-linux-gnu`? ## Documentation Updated - [x] Updated the relevant files in `/docs`, or no updates are required. - [x] Updated example commands in OpenTitan's README ## Formatting - [x] Ran `make prepush`. Co-authored-by: James Wainwright <james.wainwright@lowrisc.org>
tock · Apr 19, 2023 · 0503b8d · 0503b8d
2 parents 1406643 + 42f0789
commit 0503b8d
Show file tree

Hide file tree

Showing 2 changed files with 47 additions and 42 deletions.
diff --git a/boards/opentitan/README.md b/boards/opentitan/README.md
@@ -18,6 +18,7 @@ for more details.
 
 Programming
 -----------
+
 The latest supported version (commit SHA) of OpenTitan is specified in the [OPENTITAN_SUPPORTED_SHA](https://github.com/tock/tock/blob/master/boards/opentitan/earlgrey-cw310/Makefile) make variable found:
 >  boards/opentitan/earlgrey-cw310/Makefile
 
@@ -95,7 +96,7 @@ Then you need to flash the bitstream with:
 
 After which you should see some output in the serial window.
 
-Then in the Tock board directoty export the `OPENTITAN_TREE` environment
+Then in the Tock board directory export the `OPENTITAN_TREE` environment
 variable to point to the OpenTitan tree.
 
 ```shell
@@ -111,7 +112,7 @@ Opentitan is supported on both an FPGA and in Verilator. Slightly different
 versions of the EarlGrey chip implementation are required for the different
 platforms. By default the kernel is compiled for the FPGA.
 
-## Setting up Verilator
+### Setting up Verilator
 
 For a full guide see the official [OpenTitan Verilator documentation](https://docs.opentitan.org/doc/ug/getting_started_verilator/)
 
@@ -123,13 +124,13 @@ Build **only the targets** we care about. To speed up the building, multi-thread
 
 ```shell
 # To build the test-ROM
-$ ./bazelisk.sh build //sw/device/lib/testing/test_rom:test_rom
+./bazelisk.sh build //sw/device/lib/testing/test_rom:test_rom
 
 # To build OTP
-$ ./bazelisk.sh build //hw/ip/otp_ctrl/...
+./bazelisk.sh build //hw/ip/otp_ctrl/...
 
 # To build FuseSOC
-$ ./bazelisk.sh build //hw:verilator
+./bazelisk.sh build //hw:verilator
 ```
 
 ### Test Verilator
@@ -143,7 +144,6 @@ You can use the following to automatically build the relevant targets and run a
 or manually with
 
 ```shell
-
 bazel-out/k8-fastbuild/bin/hw/build.verilator_real/sim-verilator/Vchip_sim_tb \
                                     --meminit=rom,./bazel-out/k8-fastbuild-ST-97f470ee3b14/bin/sw/device/lib/testing/test_rom/test_rom_sim_verilator.scr.39.vmem \
                                     --meminit=otp,./bazel-out/k8-fastbuild/bin/hw/ip/otp_ctrl/data/rma_image_verilator.vmem
@@ -192,7 +192,7 @@ ${OPENTITAN_TREE}/bazel-out/k8-fastbuild/bin/hw/build.verilator_real/sim-verilat
     --meminit=rom,${OPENTITAN_TREE}/bazel-out/k8-fastbuild-ST-97f470ee3b14/bin/sw/device/lib/testing/test_rom/test_rom_sim_verilator.scr.39.vmem \
     --meminit=flash,./binary.64.vmem \
     --meminit=otp,${OPENTITAN_TREE}/bazel-out/k8-fastbuild/bin/hw/ip/otp_ctrl/data/rma_image_verilator.vmem
-````
+```
 
 In both cases expect Verilator to run for **tens of minutes** before you see anything.
 
@@ -208,7 +208,7 @@ 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/
+make flash-app APP=<...> OPENTITAN_TREE=/home/opentitan/
 ```
 
 You will need to have the GCC version of [RISC-V 32-bit objcopy](https://github.com/riscv-collab/riscv-gnu-toolchain/blob/master/README.md) installed as
@@ -219,25 +219,27 @@ the LLVM one doesn't support updating sections.
 A **single app** in `.tbf (tock binary format)` can be bundled and loaded with the kernel into Verilator with:
 
 ```shell
-$ APP=<...> make BOARD_CONFIGURATION=sim_verilator verilator
+make APP=<...> BOARD_CONFIGURATION=sim_verilator verilator
 ```
 
 ### Libtock-C App Verilator Example
 
 To load a libtock-c app, we can do the following to load the `c_hello` sample app:
 
 **Build app:**
-```
-$ git clone https://github.com/tock/libtock-c.git
-$ cd libtock-c/examples/c_hello/
-$ make RISCV=1
+```shell
+git clone https://github.com/tock/libtock-c.git
+cd libtock-c/examples/c_hello/
+make RISCV=1
 ```
 **Load and Run:**
 
 Now, in the Opentitan board directory in tock (`tock/boards/opentitan/earlgrey-cw310`)
+
+```shell
+make APP=<PATH_TO_LIBTOCK-C>/examples/c_hello/build/rv32imc/rv32imc.0x20030080.0x10005000.tbf BOARD_CONFIGURATION=sim_verilator verilator
 ```
-$ APP=<PATH_TO_LIBTOCK-C>/examples/c_hello/build/rv32imc/rv32imc.0x20030080.0x10005000.tbf make BOARD_CONFIGURATION=sim_verilator verilator
-```
+
 Note: be sure to use the correct `tbf` file here, that is,
 > use: `rv32imc.0x20030080.0x10005000.tbf`
 
@@ -248,7 +250,7 @@ as this falls within the supported app flash region (0x20030080) and ram (0x1000
 To see the output, when Verilator loads up it will show the endpoint for the
 pseudoterminal slave, something like `UART: Created /dev/pts/7 for uart0`.
 
-```
+```console
 $ screen /dev/pts/7
 .
 ...
@@ -271,25 +273,24 @@ follow the steps.
 QEMU can be started with Tock using the `qemu` make target:
 
 ```shell
-$ make qemu
+make qemu
 ```
 
 QEMU can be started with Tock and a userspace app with the `qemu-app` make
 target:
 
 ```shell
-$ make APP=/path/to/app.tbf qemu-app
+make APP=/path/to/app.tbf qemu-app
 ```
 
 The TBF must be compiled for the OpenTitan board. For example, you can build
 the Hello World example app from the libtock-rs repository by running:
 
-```
-$ cd [LIBTOCK-RS-DIR]
-$ make flash-opentitan
-$ tar xf target/riscv32imac-unknown-none-elf/tab/opentitan/hello_world.tab
-$ cd [TOCK_ROOT]/boards/opentitan
-$ make APP=[LIBTOCK-RS-DIR]/rv32imac.tbf qemu-app
+```shell
+cd "$libtock_rs_dir"
+make opentitan EXAMPLE=console
+cd "${tock_dir}/boards/opentitan/earlgrey-cw310"
+make APP=$"{libtock_rs_dir}/target/tbf/opentitan/console.tbf" qemu-app
 ```
 
 QEMU GDB Debugging [**earlgrey-cw310**]
@@ -302,44 +303,44 @@ Start by installing the respective version of gdb.
 **Arch**:
 
 ```shell
-$ sudo pacman -S riscv32-elf-gdb    
+sudo pacman -S riscv32-elf-gdb
 ```
 **Ubuntu**:
 ```shell
-$ sudo apt-get install gdb-multiarch
+sudo apt-get install gdb-multiarch
 ```
 
 In the board directory, QEMU can be started in a suspended state with gdb ready to be connected. 
 
 ```shell
-$ make qemu-gdb
+make qemu-gdb
 ```
 
 or with an app ready to be loaded.
 
 ```shell
-$ make APP=/path/to/app.tbf qemu-app-gdb
+make APP=/path/to/app.tbf qemu-app-gdb
 ```
 
 In a separate shell, start gdb
 
 **Arch**
 
-```shell
+```console
 $ riscv32-elf-gdb [/path/to/tock.elf]
 > target remote:1234            #1234 is the specified default port
 ```
 
 **Ubuntu**
 
-```shell
+```console
 $ gdb-multiarch [/path/to/tock.elf]
 > set arch riscv
 > target remote:1234            #1234 is the specified default port
 ```
 
 Once attached, standard gdb functionality is available. Additional debug symbols can be added with.
-```
+```console
 add-symbol-file <tock.elf>
 add-symbol-file <app.elf>
 ```
@@ -351,7 +352,7 @@ The Tock OpenTitan boards include automated unit tests to test the kernel.
 To run the unit tests on QEMU, just run:
 
 ```shell
-$ make test
+make test
 ```
 
 in the specific board directory.
@@ -365,22 +366,26 @@ source <path_to_installation>/Xilinx/Vivado_Lab/2020.2/settings64.sh
 ```
 We can now build the `rsa.elf` with:
 ```shell
-$ cd ${OPENTITAN_TREE}
+cd "${OPENTITAN_TREE}"
 # Build OTBN Binary
-$ ./bazelisk.sh build //sw/device/tests:otbn_rsa_test
-```
+./bazelisk.sh build //sw/device/tests:otbn_rsa_test
 
-```shell
-$ elf2tab --verbose -n "otbn-rsa" --kernel-minor 0 --kernel-major 2 --disable --app-heap 0 --kernel-heap 0 --stack 0 ./bazel-out/k8-fastbuild-ST-2cc462681f62/bin/sw/otbn/crypto/rsa.elf
+# Package binary as a Tock app
+elf2tab --verbose -n "otbn-rsa" --kernel-minor 0 --kernel-major 2 --disable --app-heap 0 --kernel-heap 0 --stack 0 ./bazel-out/k8-fastbuild-ST-2cc462681f62/bin/sw/otbn/crypto/rsa.elf
 
-$ OPENTITAN_TREE=<...> APP=${OPENTITAN_TREE}/build-out/sw/otbn/rsa.tbf make test-hardware
+# Run on hardware
+cd "${tock_dir}/boards/opentitan/earlgrey-cw310"
+make APP="${OPENTITAN_TREE}/bazel-out/sw/otbn/rsa.tbf" test-hardware
 ```
+
 ### For Verilator
+
 To load the OTBN binary and run it on Verilator, use:
+
 ```shell
-$ elf2tab --verbose -n "otbn-rsa" --kernel-minor 0 --kernel-major 2 --disable --app-heap 0 --kernel-heap 0 --stack 0 ./bazel-out/k8-fastbuild-ST-2cc462681f62/bin/sw/otbn/crypto/rsa.elf
+elf2tab --verbose -n "otbn-rsa" --kernel-minor 0 --kernel-major 2 --disable --app-heap 0 --kernel-heap 0 --stack 0 ./bazel-out/k8-fastbuild-ST-2cc462681f62/bin/sw/otbn/crypto/rsa.elf
 
-$ APP=${OPENTITAN_TREE}/bazel-out/k8-fastbuild-ST-2cc462681f62/bin/sw/otbn/crypto/rsa.tbf make BOARD_CONFIGURATION=sim_verilator test-verilator
+make APP="${OPENTITAN_TREE}/bazel-out/k8-fastbuild-ST-2cc462681f62/bin/sw/otbn/crypto/rsa.tbf" BOARD_CONFIGURATION=sim_verilator test-verilator
 ```
 
 The output on a CW310 should look something like this:
@@ -442,7 +447,7 @@ trivial assertion...
 The tests can also be run on Verilator with:
 
 ```shell
-$ make BOARD_CONFIGURATION=sim_verilator test-verilator
+make BOARD_CONFIGURATION=sim_verilator test-verilator
 ```
 
 Note that the Verilator tests can take hours to complete.
diff --git a/boards/opentitan/earlgrey-cw310/Makefile b/boards/opentitan/earlgrey-cw310/Makefile
@@ -24,7 +24,7 @@ include ../../Makefile.common
 # Pass OpenTitan board configuration option in `BOARD_CONFIGURATION` through
 # Cargo `--features`. Please see `Cargo.toml` for available options.
 ifneq ($(BOARD_CONFIGURATION),)
-	CARGO_FLAGS += --features=$(BOARD_CONFIGURATION)
+	CARGO_FLAGS += --no-default-features --features=$(BOARD_CONFIGURATION)
 endif
 
 # Build test crates with the `panic = "abort"` strategy. Tests use `unwind` by