[proj] Debug Module D1 sign-off

doc/proj/debug_module.md

@@ -0,0 +1,36 @@
+# Debug Module
+
+The Debug Module in Mocha is imported from the [PULP debug module][pulp-debug-repo].
+The documentation for the hardware IP block is located [in the vendored HW directory tree][block doc].
+
+## Design sign-offs
+
+### D1
+
+The Debug Module used for D1 sign-off is revision [358f9011][debug-hash], the same as used in OpenTitan.
+The sign-off checklist items are described in the [D1 design sign-off checklist][D1 checklist].
+
+This D1 signoff is for the non-CHERI version of the debug module currently instantiated in Mocha.
+The only planned changes to the debug module after D1 are modest changes in the debug ROM and debug memory to enable capability-aware debugging.
+
+| Type          | Item                       | Status | Note/Collaterals |
+|---------------|----------------------------|--------|------------------|
+| Documentation | SPEC_COMPLETED             | Done   | [Debug Module specification][block doc].
+| Documentation | CSR_DEFINED                | Done   | The DMI registers are defined here: [DMI registers][dmi-registers]. The memory-mapped registers from the core are defined here: [Debug Memory Map][bus-registers].
+| RTL           | CLKRST_CONNECTED           | Done   | `dm_top` correctly connects `clk_i` and `rst_ni` to `dm_csrs`, `dm_sba`, and `dm_mem`. `dm_csrs` instantiates a `prim_fifo_sync` that connects up the right clock, but changes reset domain to `dmi_rst_ni`, with a comment confirming this is intended. `dm_mem` correctly connects `clk_i` and `rst_ni` to the `debug_rom`. `dm_sba` and `debug_rom` have no further submodules.
+| RTL           | IP_TOP                     | Done   | This module is defined in `dm_top.sv`.
+| RTL           | IP_INSTANTIABLE            | Done   | It is instantiated in top chip system.
+| RTL           | PHYSICAL_MACROS_DEFINED_80 | Done   | The debug module includes a script-generated [Debug ROM][debug-rom]. This is currently 160 bytes.
+| RTL           | FUNC_IMPLEMENTED           | Done   | Debug functionality is already implemented and smoke tested within Mocha. Small changes are expected to support capability debugging.
+| RTL           | ASSERT_KNOWN_ADDED         | Done   | These are patched into the vendored `dm_top.sv`
+| Code Quality  | LINT_SETUP                 | Done   | Verilator linting is performed as part of the Mocha build. Waivers are specified in [pulp_riscv_dbg.vlt][debug-waivers].
+
+
+[block doc]: ../../hw/vendor/pulp_riscv_dbg/doc/debug-system.md
+[pulp-debug-repo]: https://github.com/pulp-platform/riscv-dbg
+[debug-hash]: https://github.com/pulp-platform/riscv-dbg/tree/358f9011
+[dmi-registers]: ../../hw/vendor/pulp_riscv_dbg/doc/debug-system.md#debug-module-registers
+[bus-registers]: ../../hw/vendor/pulp_riscv_dbg/doc/debug-system.md#debug-memory-map
+[D1 checklist]: stages.md#d1-design-sign-off-checklist
+[debug-rom]: ../../hw/vendor/pulp_riscv_dbg/debug_rom/debug_rom.sv
+[debug-waivers]: ../../hw/vendor/lint/pulp_riscv_dbg.vlt

doc/proj/stages.md

@@ -15,7 +15,7 @@ This table shows the current design and verification stage for each block in Moc
 | [AXI crossbar][]      | D1               | V0                     |
 | [Clock manager][]     | D1               | V0                     |
 | [CVA6-CHERI][]        | D1               | V0                     |
-| Debug module          | D0               | V0                     |
+| [Debug module][]      | D1               | V0                     |
 | [Entropy source][]    | D1               | V0                     |
 | [GPIO][]              | D1               | V0                     |
 | [KMAC][]              | D1               | V0                     |
@@ -40,6 +40,7 @@ This table shows the current design and verification stage for each block in Moc
 [I2C]: i2c.md
 [Clock manager]: clkmgr.md
 [CVA6-CHERI]: cva6-cheri.md
+[Debug module]: debug_module.md
 [SRAM]: sram.md
 [GPIO]: gpio.md
 [Entropy source]: entropy_src.md

hw/vendor/patches/pulp_riscv_dbg/0007-assert-known.patch

@@ -0,0 +1,37 @@
+diff --git a/src/dm_top.sv b/src/dm_top.sv
+index c21e58d..89a5814 100644
+--- a/src/dm_top.sv
++++ b/src/dm_top.sv
+@@ -17,6 +17,8 @@
+ *              SW infrastructure re-use. As of version 0.13
+ */
+
++`include "prim_assert.sv"
++
+ module dm_top #(
+   parameter int unsigned        NrHarts          = 1,
+   parameter int unsigned        BusWidth         = 32,
+@@ -69,6 +71,23 @@ module dm_top #(
+   output dm::dmi_resp_t         dmi_resp_o
+ );
+
++  ////////////////
++  // Assertions //
++  ////////////////
++  `ASSERT_KNOWN(DbgKnown_ndmreset, ndmreset_o)
++  `ASSERT_KNOWN(DbgKnown_dmactive, dmactive_o)
++  `ASSERT_KNOWN(DbgKnown_debug_req, debug_req_o)
++  // Note that slave_rdata_o is only used if there was a slave_req last cycle.
++  // However, so long as all the req fields are known even when no request is made,
++  // the rdata should be too.
++  `ASSERT_KNOWN(DbgKnown_slave_rdata, slave_rdata_o)
++  `ASSERT_KNOWN(DbgKnown_master_req, master_req_o)
++  `ASSERT_KNOWN_IF(DbgKnown_master_req_fields, {master_add_o, master_we_o}, master_req_o)
++  `ASSERT_KNOWN_IF(DbgKnown_master_req_write_fields, {master_wdata_o, master_be_o}, master_req_o & master_we_o)
++  `ASSERT_KNOWN(DbgKnown_dmi_req_ready, dmi_req_ready_o)
++  `ASSERT_KNOWN(DbgKnown_dmi_resp_valid, dmi_resp_valid_o)
++  `ASSERT_KNOWN_IF(DbgKnown_dmi_resp, dmi_resp_o, dmi_resp_valid_o)
++
+   // Debug CSRs
+   logic [NrHarts-1:0]               halted;
+   // logic [NrHarts-1:0]               running;

hw/vendor/pulp_riscv_dbg/src/dm_top.sv

@@ -17,6 +17,8 @@
 *              SW infrastructure re-use. As of version 0.13
 */
 
+`include "prim_assert.sv"
+
 module dm_top #(
   parameter int unsigned        NrHarts          = 1,
   parameter int unsigned        BusWidth         = 32,
@@ -70,6 +72,23 @@ module dm_top #(
   output dm::dmi_resp_t         dmi_resp_o
 );
 
+  ////////////////
+  // Assertions //
+  ////////////////
+  `ASSERT_KNOWN(DbgKnown_ndmreset, ndmreset_o)
+  `ASSERT_KNOWN(DbgKnown_dmactive, dmactive_o)
+  `ASSERT_KNOWN(DbgKnown_debug_req, debug_req_o)
+  // Note that slave_rdata_o is only used if there was a slave_req last cycle.
+  // However, so long as all the req fields are known even when no request is made,
+  // the rdata should be too.
+  `ASSERT_KNOWN(DbgKnown_slave_rdata, slave_rdata_o)
+  `ASSERT_KNOWN(DbgKnown_master_req, master_req_o)
+  `ASSERT_KNOWN_IF(DbgKnown_master_req_fields, {master_add_o, master_we_o}, master_req_o)
+  `ASSERT_KNOWN_IF(DbgKnown_master_req_write_fields, {master_wdata_o, master_be_o}, master_req_o & master_we_o)
+  `ASSERT_KNOWN(DbgKnown_dmi_req_ready, dmi_req_ready_o)
+  `ASSERT_KNOWN(DbgKnown_dmi_resp_valid, dmi_resp_valid_o)
+  `ASSERT_KNOWN_IF(DbgKnown_dmi_resp, dmi_resp_o, dmi_resp_valid_o)
+
   // Debug CSRs
   logic [NrHarts-1:0]               halted;
   // logic [NrHarts-1:0]               running;