Support alternate memory system via '+is_discrete_debug_module' opt

hcallahan-lowrisc · hcallahan-lowrisc · commit 7a66bf9a71b4 · 2025-07-01T13:40:17.000Z
When passing +is_discrete_debug_module to 'sim_opts' in the riscv-dv testlist
(dv/uvm/core_ibex/riscv_dv_extension/testlist.yaml), this now results in the test
being compiled and loaded into the simulation memory models in a way that mimics
a discrete debug module mapped away from the main processor memory. Up to this
point, the riscv-dv binaries generate debug rom sections which are simply placed
within a single monolithic code section.

This requires a bit of machinery to achieve:

- A new linker script to compile our test software for this layout
  (riscv_dv_extension/link.ld
- Test binaries output into multiple binaries which are loaded seperately to
  initialize the sparse memory space. Two regions are supported, 'main' and 'dm'.
- Initialize more testbench parameters via CLI args. This allows their values
  to be chosen dynamically in the future and to be test-dependent. For now, the
  various address / mask parameters are still set to fixed values for all tests.

One slightly unclean implementation detail is that the cosimulation model's
memory is loaded via binary .bin files, while the simulator's memory model is
loaded via verilog .vmem memory files. Ideally we would use .vmem files for
both, but the interface to the cosimulation model via DPI only implements
byte-writes, so loading a raw binary file is more convenient for that interface.

Signed-off-by: Harry Callahan &lt;hcallahan@lowrisc.org&gt;
diff --git a/dv/uvm/core_ibex/ibex_dv.f b/dv/uvm/core_ibex/ibex_dv.f
@@ -2,15 +2,6 @@
 // Licensed under the Apache License, Version 2.0, see LICENSE for details.
 // SPDX-License-Identifier: Apache-2.0
 
-// The boot address is specified as a hex number and is used in SystemVerilog
-// code like this: 32'h `BOOT_ADDR.
-//
-// We can't put a ' character in the constant, because Riviera's TCL machinery
-// doesn't support them in defines. We also can't just use the decimal value
-// (2147483648), because an undecorated integer literal is interpreted as a
-// signed 32-bit integer.
-+define+BOOT_ADDR=8000_0000
-
 // Until this list is generated by FuseSoC, we have to use manually generated
 // wrappers around the prim_* modules to instantiate the prim_generic_* ones,
 // see https://github.com/lowRISC/ibex/issues/893.
diff --git a/dv/uvm/core_ibex/riscv_dv_extension/ddm_link.ld b/dv/uvm/core_ibex/riscv_dv_extension/ddm_link.ld
@@ -0,0 +1,66 @@
+/* Copyright lowRISC contributors.
+   Licensed under the Apache License, Version 2.0, see LICENSE for details.
+   SPDX-License-Identifier: Apache-2.0 */
+
+/*
+ * This linker script maps the generated debug test code into a discrete region
+ * of the address space, representative of an external discrete debug module (ddm).
+ * i.e. when +discrete_debug_module=1
+ *
+ * It also provisions space for a debug module "scratch" area that follows the debug
+ * ROM. This allows us to test stores into the debug module without modifying
+ * the test program.
+ */
+
+OUTPUT_ARCH( "riscv" )
+ENTRY(_start)
+
+MEMORY
+{
+  main : ORIGIN = 0x80000000, LENGTH = 0x100000
+  dm   : ORIGIN = 0x1A110000, LENGTH = 0x1000
+}
+
+_dm_scratch_len = 0x100;
+
+SECTIONS
+{
+  .text : {
+    *(.text)
+    . = ALIGN(0x1000);
+  } >main
+  .tohost : {
+    . = ALIGN(4);
+    *(.tohost)
+    . = ALIGN(0x1000);
+  } >main
+  .page_table : {
+    *(.page_table)
+  } >main
+  .data : {
+    *(.data)
+  } >main
+  .user_stack : {
+    *(.user_stack)
+  } >main
+  .kernel_data : {
+    *(.kernel_data)
+  } >main
+  .kernel_stack : {
+    *(.kernel_stack)
+  } >main
+  .bss : {
+    *(.bss)
+  } >main
+
+  _end = .;
+
+  .debug_module : {
+    *(.debug_module)
+  } >dm
+  .dm_scratch : {
+    . = ALIGN(4);
+    . = . + _dm_scratch_len ;
+    . = ALIGN(4);
+    } >dm =0
+}
diff --git a/dv/uvm/core_ibex/scripts/compile_tb.py b/dv/uvm/core_ibex/scripts/compile_tb.py
@@ -114,8 +114,25 @@ def _main() -> int:
             'core_ibex': md.ibex_dv_root,
             'tb_dir': md.dir_tb,
             'tb_build_log': md.tb_build_log,
-            'cmp_opts': get_compile_opts(md.ibex_config,
-                                         md.simulator),
+            'cmp_opts':
+                get_compile_opts(md.ibex_config, md.simulator) + \
+                # Base address of the debug module. This is passed as a parameter
+                # at compile time as the PMP module must always allow debug mode
+                # accesses to it.
+                r" -define DM_ADDR=1A11_0000 " + \
+                r" -define DM_ADDR_MASK=0000_0FFF" + \
+                r" -define BOOT_ADDR=8000_0000 " + \
+                # Spike sets the following parameters via the preprocessor defines
+                # DEBUG_ROM_ENTRY and DEBUG_ROM_TVEC.
+                # As they cannot be moved without recompiling the ISS, treat them as
+                # hardcoded here too, for now. These addresses are placed right at
+                # BOOT_ADDR location, which is the location of the start of the
+                # default vector table. (The reset vector is BOOT_ADDR/256b + 0x80)
+                # The generated RISCV-DV assembly programs move the default vector
+                # table (via MTVEC), and place jump instructions at these two
+                # addresses to the generated debug test sections.
+                r" -define DEBUG_MODE_HALT_ADDR=8000_0000 " + \
+                r" -define DEBUG_MODE_EXCEPTION_ADDR=8000_0004 ",
             'dir_shared_cov': (md.dir_shared_cov if md.cov else ''),
             'xlm_cov_cfg_file': f"{md.ot_xcelium_cov_scripts}/cover.ccf",
             'dut_cov_rtl_path': md.dut_cov_rtl_path
diff --git a/dv/uvm/core_ibex/scripts/compile_test.py b/dv/uvm/core_ibex/scripts/compile_test.py
@@ -12,10 +12,11 @@
 import sys
 import tempfile
 import pathlib3x as pathlib
+import itertools
 
 from scripts_lib import run_one, format_to_cmd, read_yaml
 import riscvdv_interface
-from test_entry import read_test_dot_seed
+from test_entry import read_test_dot_seed, get_test_entry
 from metadata import RegressionMetadata
 from test_run_result import TestRunResult, TestType
 
@@ -85,6 +86,66 @@ def get_riscvdv_compile_cmds(md: RegressionMetadata, trr: TestRunResult) -> List
             new_cmd.append(word)
         new_cmds.append(new_cmd)
 
+
+    if (trr.testtype == TestType.RISCVDV and trr.is_discrete_debug_module):
+        logger.warning(f"Using discrete debug module memory layout.")
+
+        # Remove the objdump command for the single contiguous memory region.
+        # (If debug module address is far from the boot_address, a single loadable
+        # .bin file can be very large (roughly 1.6Gb for the default address params))
+        new_cmds.pop()
+
+        # Replace default riscv-dv linker script with custom script
+        for cmd in new_cmds:
+            for index, token in enumerate(cmd):
+                if token.startswith("-T"):
+                    cmd[index] = "-T" + str(md.ibex_riscvdv_customtarget / 'ddm_link.ld')
+
+        # Generate binary outputs for the different LOADABLE memory regions (main, dm).
+        # The linker script places some sections inside the 'dm' memory region,
+        # which may be quite far away from the 'main' memory. To avoid
+        # generating a very large uncompressed binary file to LOAD both
+        # segments, we probably want to use the .vmem format passed to
+        # $readmemh to initialize the RTL-side memory model. However, as the
+        # cosim memory model is initialized over the DPI interface, and may be
+        # comprised of multiple 'memories' rather than a single contiguous
+        # space, we can't simply rely on $readmemh to automatically partition a
+        # single file across multiple arrays. Hence for it's initialization,
+        # generate raw .bin files which will be loaded via the base address of
+        # each section.
+
+        # The following sections are within the loadable 'dm' region
+        dm_sections = [".debug_module", ".dm_scratch"]
+
+        # The following objcopy arguments generate outputs with only a subset of the sections
+        # present in the object file.
+        flatten_list = lambda unflat_list: list(itertools.chain(*unflat_list))
+        only_sections = flatten_list([["--only-section", s] for s in dm_sections])
+        remove_sections = flatten_list([["--remove-section", s] for s in dm_sections])
+
+        env = os.environ.copy()
+        objcopy = env.get('RISCV_OBJCOPY')
+
+        # Generate verilog memory formatted outputs (.vmem)
+
+        trr.vmem_main = trr.dir_test / "test.main.vmem"
+        trr.vmem_dm = trr.dir_test / "test.dm.vmem"
+        vmem_dm_cmd = \
+            [objcopy, "-O", "verilog", *only_sections, f"{trr.objectfile}", f"{trr.vmem_dm}"]
+        vmem_main_cmd = \
+            [objcopy, "-O", "verilog", *remove_sections, f"{trr.objectfile}", f"{trr.vmem_main}"]
+
+        # Generate binary-formatted outputs (.bin)
+
+        trr.binary_main = trr.dir_test / "test.main.bin"
+        trr.binary_dm = trr.dir_test / "test.dm.bin"
+        bin_dm_cmd = \
+            [objcopy, "-O", "binary", *only_sections, f"{trr.objectfile}", f"{trr.binary_dm}"]
+        bin_main_cmd = \
+            [objcopy, "-O", "binary", *remove_sections, f"{trr.objectfile}", f"{trr.binary_main}"]
+
+        new_cmds.extend([vmem_dm_cmd, vmem_main_cmd, bin_dm_cmd, bin_main_cmd])
+
     return new_cmds
 
 
diff --git a/dv/uvm/core_ibex/scripts/metadata.py b/dv/uvm/core_ibex/scripts/metadata.py
@@ -29,6 +29,7 @@
 import ibex_config
 import lib as riscvdv_lib
 from test_run_result import TestRunResult, TestType
+from test_entry import get_test_entry
 import directed_test_schema
 
 import logging
@@ -256,7 +257,7 @@ def construct_from_metadata_dir(cls, dir_metadata: pathlib.Path):
         md = cls.construct_from_pickle(md_pickle)
         return md
 
-    def get_tests_and_counts(self) -> List[Tuple[str, int, TestType]]:
+    def get_tests_and_counts(self) -> List[Tuple[Tuple[str, int, TestType], object]]:
         """Get a list of tests and the number of iterations to run of each.
 
         ibex_config should be the name of the Ibex configuration to be tested.
@@ -287,12 +288,12 @@ def get_tests_and_counts(self) -> List[Tuple[str, int, TestType]]:
             name, iterations = (test['test'], test['iterations'])
             assert isinstance(name, str) and isinstance(iterations, int) \
                                          and iterations > 0
-            ret.append((name, iterations, TestType.RISCVDV))
+            ret.append(((name, iterations, TestType.RISCVDV), test))
         for test in directed_filtered_list:
             name, iterations = (test['test'], test['iterations'])
             assert isinstance(name, str) and isinstance(iterations, int) \
                                          and iterations > 0
-            ret.append((name, iterations, TestType.DIRECTED))
+            ret.append(((name, iterations, TestType.DIRECTED), test))
 
         return ret
 
@@ -374,7 +375,8 @@ def _main():
         # Setup the tests/counts we are going to use, by parsing the
         # riscv-dv/directed-test structured data.
         # eg. testlist.yaml / directed_testlist.yaml
-        md.tests_and_counts = md.get_tests_and_counts()
+        tests_and_counts = md.get_tests_and_counts()
+        md.tests_and_counts = [tctt for (tctt, obj) in tests_and_counts]
         if not md.tests_and_counts:
             raise RuntimeError("md.tests_and_counts is empty, cannot get TEST.SEED strings.")
 
@@ -383,7 +385,8 @@ def _main():
         # constructed above, so we can easily find and import them later, and
         # give each test object a link back to this top-level object that
         # defines the wider regression.
-        for test, count, testtype in md.tests_and_counts:
+        for tctt, obj in tests_and_counts:
+            test, count, testtype = tctt
             for testseed in range(md.seed, md.seed + count):
                 tds_str = f"{test}.{testseed}"
 
@@ -402,6 +405,21 @@ def _main():
                     pickle_file=md.dir_metadata/(tds_str + ".pickle"),
                     yaml_file=md.dir_tests/tds_str/'trr.yaml')
 
+                if testtype == TestType.RISCVDV:
+                    # Copy the test options into the object, to make it easier to fetch later.
+                    shlex_if_not_empty = lambda field: shlex.split(obj.get(field) or "")
+                    trr.gen_test = shlex_if_not_empty('gen_test')
+                    trr.gen_opts = shlex_if_not_empty('gen_opts')
+                    trr.rtl_test = shlex_if_not_empty('rtl_test')
+                    trr.sim_opts = shlex_if_not_empty('sim_opts')
+
+                    # If the +discrete_debug_module=1 argument is passed via sim_opts, a alternate
+                    # memory heirarchy is enabled which seperates the debug rom memory sections
+                    # from the main binary, emulating an external debug module
+                    for plusarg, val in (trr.split('=') for trr in trr.sim_opts):
+                        if plusarg == "+discrete_debug_module":
+                            trr.is_discrete_debug_module = False if '' else bool(int(val))
+
                 # Get the data from the directed test yaml that we need to construct the command.
                 if testtype == TestType.DIRECTED:
                     trr.directed_data = (next(filter(
diff --git a/dv/uvm/core_ibex/scripts/run_rtl.py b/dv/uvm/core_ibex/scripts/run_rtl.py
@@ -39,18 +39,20 @@ def _main() -> int:
     trr.rtl_test = testopts['rtl_test']
     trr.timeout_s = testopts.get('timeout_s') or md.run_rtl_timeout_s
 
-    if not os.path.exists(trr.binary):
-        raise RuntimeError(
-            "When computing simulation command for running "
-            f"seed {trr.seed} of test {trr.testname}, cannot find the "
-            f"expected binary at {trr.binary!r}.")
-
     # Each test in testlist.yaml can (optionally) specify 'sim_opts'
     # which are to be passed to the simulator when running the test.
     sim_opts = ''
     sim_opts_raw = testopts.get('sim_opts')
     if sim_opts_raw:
         sim_opts += sim_opts_raw.replace('\n', '')
+    # If discrete_debug_module is enabled, pass some extra sim_opts
+    trr.ddm_sim_opts = ''
+    if (trr.testtype == TestType.RISCVDV and trr.is_discrete_debug_module):
+        trr.ddm_sim_opts = \
+            f" +vmem_main={trr.vmem_main}\n" + \
+            f" +vmem_dm={trr.vmem_dm}\n" + \
+            f" +bin_main={trr.binary_main}\n" + \
+            f" +bin_dm={trr.binary_dm}\n"
 
     trr.rtl_log         = trr.dir_test / 'rtl_sim.log'
     trr.rtl_trace       = trr.dir_test / 'trace_core_00000000.log'
@@ -71,6 +73,7 @@ def _main() -> int:
         'sim_opts': (f"+signature_addr={md.signature_addr}\n" +
                      f"+test_timeout_s={trr.timeout_s}\n" +
                      f"{get_sim_opts(md.ibex_config, md.simulator)}\n" +
+                     trr.ddm_sim_opts +
                      sim_opts)
     }
 
diff --git a/dv/uvm/core_ibex/scripts/test_run_result.py b/dv/uvm/core_ibex/scripts/test_run_result.py
@@ -58,11 +58,19 @@ class TestRunResult(scripts_lib.testdata_cls):
     rtl_simulator: Optional[str] = None   # Which simulator is used
     iss_cosim: Optional[str] = None       # Which ISS are we cosimulating with?
 
+    # Options for discrete debug module memory heirarchy
+    is_discrete_debug_module: Optional[bool] = None
+    binary_main: Optional[pathlib.Path] = None
+    binary_dm: Optional[pathlib.Path] = None
+    vmem_main: Optional[pathlib.Path] = None
+    vmem_dm: Optional[pathlib.Path] = None
+    ddm_sim_opts: Optional[List[str]] = None
+
     # RISCV_DV specific test parameters
-    gen_test: Optional[str] = None
-    gen_opts: Optional[str] = None
-    rtl_test: Optional[str] = None
-    sim_opts: Optional[str] = None
+    gen_test: Optional[List[str]] = None
+    gen_opts: Optional[List[str]] = None
+    rtl_test: Optional[List[str]] = None
+    sim_opts: Optional[List[str]] = None
 
     # Directed Test specific parameters
     directed_data: Optional[dict] = None
diff --git a/dv/uvm/core_ibex/tb/core_ibex_tb_top.sv b/dv/uvm/core_ibex/tb/core_ibex_tb_top.sv
@@ -50,6 +50,7 @@ module core_ibex_tb_top;
     `define IBEX_CFG_RegFile ibex_pkg::RegFileFF
   `endif
 
+  // Ibex Parameters
   parameter bit          PMPEnable        = 1'b0;
   parameter int unsigned PMPGranularity   = 0;
   parameter int unsigned PMPNumRegions    = 4;
@@ -67,6 +68,12 @@ module core_ibex_tb_top;
   parameter bit SecureIbex                = 1'b0;
   parameter bit ICacheScramble            = 1'b0;
   parameter bit DbgTriggerEn              = 1'b0;
+  parameter int unsigned DmBaseAddr       = 32'h`DM_ADDR;
+  parameter int unsigned DmAddrMask       = 32'h`DM_ADDR_MASK;
+  parameter int unsigned DmHaltAddr       = 32'h`DEBUG_MODE_HALT_ADDR;
+  parameter int unsigned DmExceptionAddr  = 32'h`DEBUG_MODE_EXCEPTION_ADDR;
+  // Ibex Inputs
+  parameter int unsigned BootAddr         = 32'h`BOOT_ADDR; // ResetVec = BootAddr/256b + 0x80
 
   // Scrambling interface instantiation
   logic [ibex_pkg::SCRAMBLE_KEY_W-1:0]   scramble_key;
@@ -84,10 +91,6 @@ module core_ibex_tb_top;
   assign {scramble_key, scramble_nonce} = scrambling_key_if.d_data;
 
   ibex_top_tracing #(
-    .DmBaseAddr       (32'h`BOOT_ADDR       ),
-    .DmAddrMask       (32'h0000_0007        ),
-    .DmHaltAddr       (32'h`BOOT_ADDR + 'h0 ),
-    .DmExceptionAddr  (32'h`BOOT_ADDR + 'h4 ),
     .PMPEnable        (PMPEnable        ),
     .PMPGranularity   (PMPGranularity   ),
     .PMPNumRegions    (PMPNumRegions    ),
@@ -104,7 +107,11 @@ module core_ibex_tb_top;
     .SecureIbex       (SecureIbex       ),
     .ICacheScramble   (ICacheScramble   ),
     .BranchPredictor  (BranchPredictor  ),
-    .DbgTriggerEn     (DbgTriggerEn     )
+    .DbgTriggerEn     (DbgTriggerEn     ),
+    .DmBaseAddr       (DmBaseAddr       ),
+    .DmAddrMask       (DmAddrMask       ),
+    .DmHaltAddr       (DmHaltAddr       ),
+    .DmExceptionAddr  (DmExceptionAddr  )
 
   ) dut (
     .clk_i                  (clk                        ),
@@ -115,7 +122,7 @@ module core_ibex_tb_top;
     .ram_cfg_i              ('b0                        ),
 
     .hart_id_i              (32'b0                      ),
-    .boot_addr_i            (32'h`BOOT_ADDR             ), // align with spike boot address
+    .boot_addr_i            (BootAddr                   ),
 
     .instr_req_o            (instr_mem_vif.request      ),
     .instr_gnt_i            (instr_mem_vif.grant        ),
diff --git a/dv/uvm/core_ibex/tests/core_ibex_base_test.sv b/dv/uvm/core_ibex/tests/core_ibex_base_test.sv
