[doc] Add a sw/device/tests markdown
diff --git a/hw/top_earlgrey/data/standalone_sw_testplan.hjson b/hw/top_earlgrey/data/standalone_sw_testplan.hjson
new file mode 100644
index 0000000..0dd1ead
--- /dev/null
+++ b/hw/top_earlgrey/data/standalone_sw_testplan.hjson
@@ -0,0 +1,32 @@
+{
+ name: "self-contained-tests"
+
+ entries: [
+ {
+ name: flash_ctrl
+ desc: '''This test checks for correct sanity behavior of the flash.
+ It ensures the flash controller is able to program, read, and page erase fixed locations in multiple flash banks.
+ It also performs a sanity region protection check to make sure a protected page cannot be modified.
+ When the test passes, it will output "PASS!".'''
+ milestone: V1
+ tests: ["flash_test"]
+ }
+ {
+ name: hmac
+ desc: '''This test checks for basic functionality of the sha256 engine inside HMAC.
+ It computes the hash of a known input and compares it against the known digest.
+ When the test passes, it will output "PASS!".'''
+ milestone: V1
+ tests: ["sha256_test"]
+ }
+ {
+ name: rv_timer
+ desc: '''This test checks for basic timer and interrupt functionality.
+ The test rests in a loop and does not break out until the interrupt handling routine sets a specific value.
+ If the interrupt handling is incorrect, the test will never complete.
+ When the test passes, it will output "PASS!".'''
+ milestone: V1
+ tests: ["rv_timer_test"]
+ }
+ ]
+}
\ No newline at end of file
diff --git a/sw/device/tests/index.md b/sw/device/tests/index.md
new file mode 100644
index 0000000..d7cb98f
--- /dev/null
+++ b/sw/device/tests/index.md
@@ -0,0 +1,27 @@
+---
+title: "Software Tests Readme"
+---
+
+# Overview
+
+This directory contains a suite of self-contained tests that are capable of running across all of OpenTitan's verification platforms.
+These platforms include - UVM DV, Verilator DV, FPGA, and eventually silicon.
+
+To enable this cross-platform testing, each test is self-contained and do not require additional host or backend resources to verify correct behavior.
+This suggests that any testing that would involve emulation of host capability, such as an external SPI host or an external host to encrypt/decrypt data, is not appropriate for these types of self-contained tests.
+It is assumed those tests will live in a different directory as the host emulation will be different for each verification target.
+For FPGA / silicon this may be a host machine, while for UVM / Verilator this may be some kind of system verilog back-end.
+
+## Self Checking Mechanism
+
+Currently, the self-checking mechanism is accomplished through a console message.
+When the tests pass, it will output `PASS!\r\n`.
+
+The capturing and generation of this message will differ per testing target.
+On FPGA / silicon, they will feed directly to a host machine through a physical UART conection, where the host can decipher the message correctness.
+On Verilator, they will feed to a virtual UART terminal where the host can do the same.
+On DV, they will feed to a fixed memory location where the DV backend can efficiently pick up the message without significant parsing overhead.
+
+# List of Tests
+
+{{< testplan "hw/top_earlgrey/data/standalone_sw_testplan.hjson" >}}
diff --git a/util/build_docs.py b/util/build_docs.py
index 10a010b..a0bb0cc 100755
--- a/util/build_docs.py
+++ b/util/build_docs.py
@@ -76,6 +76,7 @@
"hw/ip/rv_timer/data/rv_timer_testplan.hjson",
"hw/ip/uart/data/uart_testplan.hjson",
"hw/ip/tlul/data/tlul_testplan.hjson",
+ "hw/top_earlgrey/data/standalone_sw_testplan.hjson",
"util/testplanner/examples/foo_testplan.hjson",
],
