[doc] Various misc doc updates for the new FPGA loading flow

Remove references to splicing bitstreams and update docs where relevant.
Also address some smaller areas of documentation that have fallen out of
date with the current practices. Where necessary, apply relevant OpenTitan
Markdown styling for consistencfy (one sentence per line).

Additionally, add a small note for a needed FIXUP with old CW310
references, which should be replaced with CW340 references (but is
deferred to a separate commit).

Signed-off-by: Alex Jones <alex.jones@lowrisc.org>

Author: AlexJones0

.github/workflows/bitstream.yml

@@ -56,7 +56,7 @@ jobs:
           bitstream_archive=$(./bazelisk.sh outquery "${cached_archive}")
           cp -Lv ${bitstream_archive} build-bin.tar
 
-      - name: Build and splice bitstream with Vivado
+      - name: Build base bitstream with Vivado
         if: steps.strategy.outputs.bitstreamStrategy != 'cached'
         run: |
           bazel_package=//hw/bitstream/vivado

.github/workflows/monthly.yml

@@ -49,7 +49,7 @@ jobs:
             cp -rLvt "$OBJ_DIR/$SUB_PATH/" \
               $(./bazelisk.sh outquery-all ${bitstream_target}) || true
 
-            # TODO: Splice ROM into the bitstream?
+            # TODO: upload the ROM to be spliced as a separate artefact?
             cp -Lv ${bitstream_archive} build-bin.tar
           }
 

ci/scripts/run-fpga-tests.sh

@@ -31,8 +31,8 @@ export BITSTREAM="--offline --list ci_bitstreams"
 # Note that the hyperdebug backend does not have the reset-sam3x command so this will fail but not trigger an error.
 trap './bazelisk.sh run //sw/host/opentitantool -- --rcfile= --interface=${fpga} fpga reset-sam3x || true' EXIT
 
-# In case tests update OTP or otherwise leave state on the FPGA we should start
-# by clearing the bitstream.
+# Running tests will clear all non-volatile memory on the FPGA, but we start by
+# clearing the bitstream to be cautious in case tests leave behind some state.
 # FIXME: #16543 The following step sometimes has trouble reading the I2C we'll
 # log it better and continue even if it fails (the pll is mostly correctly set
 # anyway).

doc/contributing/bazel_notes.md

@@ -245,9 +245,9 @@ bazel run //quality:license_check --test_output=streamed
 Note, to run (software) tests on these OpenTitan hardware platforms **does not** require these Bazel commands be invoked before the test commands above.
 Bazel is aware of all dependency relationships, and knows what prerequisites to build to run a test.
 
-- Build FPGA bitstream with (test) ROM, see [here](../getting_started/setup_fpga.md#build-an-fpga-bitstream).
-- Build FPGA bitstream with (production) ROM, see [here](../getting_started/setup_fpga.md#build-an-fpga-bitstream).
-- Build Verilator simulation binary:
+- Build a base FPGA bitstream with a (test) ROM, see [here](../getting_started/setup_fpga.md#build-an-fpga-bitstream).
+- Build a production ROM and OTP image for the FPGA, see [here](../getting_started/setup_fpga.md#programming-the-fpga-with-rom--otp-images).
+- Build a Verilator simulation binary:
   ```sh
   bazel build //hw:verilator
   ```

doc/contributing/fpga/debugging_with_ila.md

@@ -234,10 +234,10 @@ In practice, we have not seen problems (e.g., due to missing constraints) yet, a
 So you can ignore this warning, but it's worth keeping in mind *if* you should see any problems (e.g., due to timing violations).
 
 
-## Building and splicing bitstreams that include an ILA
+## Building bitstreams that include an ILA
 
 With the steps above complete, building a first bitstream that includes the defined ILAs is as simple as following the [corresponding guide](../../getting_started/setup_fpga.md#build-an-fpga-bitstream).
-The generated and spliced bitstream will include the defined ILAs.
+The generated bitstream will include the defined ILAs.
 
 
 ## Programming the FPGA, controlling the ILA, and running a test

doc/getting_started/build_sw.md

@@ -119,11 +119,12 @@ We maintain or use the following tags to support this:
 * `broken` is used to tag tests that are committed but should not be expected by CI or others to pass.
 * `cw340`, `cw340_test_rom`, and `cw340_rom_with_fake_keys` are used to tag tests that depend on a correctly setup cw340 "Luna Board" to emulate OpenTitan.
   The `cw340` tag may be used in `--test_tag_filters` to enable concise filtering to select tests that run on this board and include or exclude them.
-  Loading the bitstream is the slowest part of the test, so these tags can group tests with common bitstreams to accelerate the tests tagged `cw340_test_rom`.
+  Historically these tests were grouped by execution environment, because this corresponded to a new "spliced" bitstream in the old FPGA testing flow.
+  Loading the bitstream is the slowest part of the test, but this should only need to be done once for the FPGA.
+  These tags are currently retained as a convenient mechanism for grouping tests, but are somewhat arbitrary.
 * `verilator` is used to tag tests that depend on a verilated model of OpenTitan that can take a significant time to build.
   Verilated tests can still be built with `--define DISABLE_VERILATOR_BUILD`, but they will skip the invocation of Verilator and cannot be run.
 * `vivado` is used to tag tests that critically depend on Vivado.
-* `jtag` is used to tag tests that rely on a USB JTAG adapter connected like we have in CI.
 * `manual` is a Bazel builtin that prevents targets from matching wildcards.
   Test suites are typically tagged manual so their contents match, but test suites don't get built or run unless they're intentionally invoked.
   Intermediate build artifacts may also be tagged with manual to prevent them from being unintentionally built if they cause other problems.

doc/getting_started/install_vivado/README.md

@@ -1,13 +1,11 @@
 # Install Vivado
 
-Generating a bitstream for Xilinx devices requires a
-[Vivado](https://www.xilinx.com/products/design-tools/vivado.html) installation.
-Please note that the "WebPACK" edition __does not__ support the Xilinx Kintex
-UltraScale XCKU095 used on the CW341 board.
+Generating a bitstream for Xilinx devices requires a [Vivado](https://www.xilinx.com/products/design-tools/vivado.html) installation.
+Please note that the "WebPACK" edition __does not__ support the Xilinx Kintex UltraScale XCKU095 used on the CW341 board.
 
-For software development, Vivado is still necessary for most workflows.
-However, the (free) Lab Edition is sufficient, and it has a significantly smaller installation footprint.
-For example, Vivado's `updatemem` tool is used to splice ROM images into the bitstream, and this is included in the Lab Edition.
+For software development, Vivado is *not* necessary for most workflows.
+We previously used Vivado's `updatemem` to splice ROM & OTP images into the bitstream, which required the (free) Lab edition of Vivado.
+This has since been migrated to instead use an FPGA-specific IP to program memories over JTAG, and thus is no longer necessary.
 
 ## Install Xilinx Vivado
 
@@ -16,17 +14,12 @@ _**Vivado Version:** The recommendation is to use Vivado {{#tool-version vivado
 Following the arrival of Vivado ML Edition, you will need to follow the links for that, eg. Products -> Hardware Development -> Vivado ML.
 Then click on 'Vivado Archive' in the Version list and locate version {{#tool-version vivado }} of Vivado Design Suite.
 
-See [Download and
-Installation](https://docs.xilinx.com/r/{{#tool-version vivado }}-English/ug973-vivado-release-notes-install-license/Download-and-Installation)
-for installation instructions.
+See [Download and Installation](https://docs.xilinx.com/r/{{#tool-version vivado }}-English/ug973-vivado-release-notes-install-license/Download-and-Installation) for installation instructions.
 
 When asked what edition to install, choose "Vivado HL Design Edition".
-_Note: If you are only developing software, you may select the "Lab Edition" instead._
 On the feature selection screen, select at least the following features:
 
 ![Vivado features selection screen](features.png)
 
-After installing Vivado, you will need to add Vivado's paths to your shell
-environment. See [Launching the Vivado IDE from the Command Line on Windows or
-Linux](https://docs.xilinx.com/r/{{#tool-version vivado }}-English/ug892-vivado-design-flows-overview/Launching-the-Vivado-IDE-from-the-Command-Line-on-Windows-or-Linux)
-for instructions.
+After installing Vivado, you will need to add Vivado's paths to your shell environment.
+See [Launching the Vivado IDE from the Command Line on Windows or Linux](https://docs.xilinx.com/r/{{#tool-version vivado }}-English/ug892-vivado-design-flows-overview/Launching-the-Vivado-IDE-from-the-Command-Line-on-Windows-or-Linux) for instructions.

sw/device/silicon_creator/rom/doc/e2e_tests.md

@@ -5,22 +5,24 @@ This guide will help you to setup an environment to run the ROM E2E tests in an
 The [ROM](../README.md) is the first boot stage of secure boot flow and by nature, it cannot be updated after manufacturing.
 The ROM E2E (End-to-End) tests validates the ROM features and can be used for regression tests.
 Each test is divided into components:
- - **ROM Image**, a C program built by `bazel` and spliced with the bitstream. The ROM is the DUT (Device Under Test) of the ROM E2E tests.
+ - **ROM Image**, a C program built by `bazel` and loaded onto the FPGA. The ROM is the DUT (Device Under Test) of the ROM E2E tests.
  - **OTP image**, contains HW and SW configurations, some of which control execution paths in the ROM, such as the lifecycle stage.
    As a result, we run some tests with several different OTP images to increase coverage of ROM execution paths.
    There is more information in the documentation for the OTP layout.
    That documentation is specialised for the different tops.
    For an example, see earlgrey's [OTP memory map](../../../../../hw/top_earlgrey/ip_autogen/otp_ctrl/README.md#direct-access-memory-map).
  - **FPGA bitstream**, Opentitan Hardware implementation synthesized for the FPGA built by `bazel` and `vivado`.
  - **Device test firmware**, a C program (built by bazel to run on an OpenTitan device) that is loaded into flash, and booted by the ROM stage. It checks the HW registers and/or memory configurations performed by the ROM and relays information to the Host test software.
- - **opentitantool**, a Rust program that provides a common interface to interact with an OpenTitan device. `opentitantool` uses `opentitanlib` which provides the abstractions to communicate with an OpenTitan device.
+ - **opentitantool**, a Rust program that provides a common interface to interact with an OpenTitan device.
+   `opentitantool` uses `opentitanlib` which provides the abstractions to communicate with an OpenTitan device.
  - **Host test software**, any Rust program (built by `bazel` to run on the host platform , e.g. a x86 binary, and linked with `opentitanlib`) that actively interacts with an OpenTitan device over any hardware interface (e.x., UART, SPI or JTAG) to perform the test functions and check their results.
 
 ![Architecture](ROM_E2E_Tests.svg)
 
 All the existing tests are documented in the [ROM E2E Testplan](https://github.com/lowRISC/OpenTitan/blob/master/sw/device/silicon_creator/rom/data/rom_e2e_testplan.hjson).
 ## Hardware setup
 ### FPGA
+<!--FIXME: The below docs should be updated to reference the CW340, since the CW310 is no longer supported.-->
 The E2E ROM tests run on the CW310 FPGA board with the following configuration:
  - The power supply connected to the J11 connector.
  - A USB cable connecting the Host PC to the USB-C Data (J8) connector which is connected to the SAM3U microcontroller on the CW310 FPGA board.
@@ -37,7 +39,6 @@ Some tests will use the JTAG interface to interact with OpenTitan, as the CW310
 The software dependencies are covered by other guides in this book and are linked below.
 - Clone the OpenTitan repository and install the software dependencies: [Get started](../../../../../doc/getting_started/README.md).
 - Setup the FPGA: [FPGA guide](../../../../../doc/getting_started/setup_fpga.md).
-- Install Vivado to be able to splice bitstreams: [Installing Vivado](../../../../../doc/getting_started/install_vivado).
 
 **Note**: Make sure that you added the udev rules for the [FPGA](../../../../../doc/getting_started/install_vivado#device-permissions-udev-rules) board and the [JTAG](../../../../../doc/getting_started/setup_fpga.md#device-permissions-udev-rules) adapter.
 
@@ -51,6 +52,7 @@ Once the hardware setup is done and the FPGA is connected to the USB, the full s
 cd ${REPO_TOP}
 bazel test --define DISABLE_VERILATOR_BUILD=true --define bitstream=gcp --test_tag_filters=-verilator,-dv,-broken --build_tests_only //sw/device/silicon_creator/rom/e2e/...
 ```
-This bazel command will download a bitstream associated with the HEAD commit of the repository, splice it with the different OTP configurations (RMA, DEV, PROD*, TEST*), load the FPGA and run all the tests suites under `sw/device/silicon_creator/rom/e2e`.
+This bazel command will download a bitstream associated with the HEAD commit of the repository, load the FPGA with the bitstream and program it with various different OTP configurations (RMA, DEV, PROD*, TEST*), and run all the tests suites under `sw/device/silicon_creator/rom/e2e`.
 
-**Note**: If you have hardware changes then you can build the bitstream locally by changing the tag `bitstream=` from `gcp` to `vivado`. Although this will take much longer.
+**Note**: If you have hardware changes then you can build the bitstream locally by changing the tag `bitstream=` from `gcp` to `vivado`.
+Although this will take much longer.

sw/device/silicon_creator/rom/e2e/bootstrap/BUILD

@@ -95,7 +95,7 @@ opentitan_test(
         "//hw/top_earlgrey:fpga_cw340_rom_with_fake_keys": None,
     },
     fpga = fpga_params(
-        # Since the bitstream disables bootstrap, there is no firmware to
+        # Since the OTP configuration disables bootstrap, there is no firmware to
         # load into the chip.  However, opentitan_test wants to build a
         # binary target.  We'll build an unsigned do-nothing binary.
         binaries = {

sw/device/silicon_creator/rom/e2e/jtag_inject/BUILD

@@ -32,10 +32,10 @@ package(default_visibility = ["//visibility:public"])
 ]
 
 [
-    # We are using a bitstream with disabled execution so the content of the flash
-    # does not matter but opentitan_test() is unhappy if we don't provide one.
+    # We are using an OTP configuration with disabled execution so the content of the
+    # flash does not matter, but opentitan_test() is unhappy if we don't provide one.
     # Since execution in the ROM is disabled, bootstrap is not possible so we need
-    # to make sure that the test does not try to bootstrap
+    # to make sure that the test does not try to bootstrap.
     opentitan_test(
         name = "sram_program_test_otp_{}".format(lc_state),
         srcs = ["//sw/device/silicon_creator/rom/e2e:empty_test"],