Merge pull request #1438 from ucb-bar/tcdtm

ELF-based-loadmem | architectural restartable checkpoints

docs/Advanced-Concepts/Architectural-Checkpoints.rst

@@ -0,0 +1,39 @@
+.. _checkpointing:
+
+Architectural Checkpoints
+=========================
+
+Chipyard supports generating architectural checkpoints using Spike.
+These checkpoints contain a snapshot of the architectural state of a RISC-V SoC at some point in the execution of a program.
+The checkpoints include the contents of cacheable memory, core architectural registers, and core CSRs.
+RTL simulations of SoCs can resume execution from checkpoints after restoring the architectural state.
+
+.. note::
+   Currently, only checkpoints of single-core systems are supported
+
+Generating Checkpoints
+------------------------
+
+``scripts/generate-ckpt.sh`` is a script that runs spike with the right commands to generate an architectural checkpoint
+``scripts/generate-ckpt.sh -h`` lists options for checkpoint generation.
+
+Example: run the ``hello.riscv`` binary for 1000 instructions before generating a checkpoint.
+This should produce a directory named ``hello.riscv.0x80000000.1000.loadarch``
+
+.. code::
+
+   scripts/generate-ckpt.sh -b tests/hello.riscv -i 1000
+
+
+Loading Checkpoints in RTL Simulation
+--------------------------------------
+
+Checkpoints can be loaded in RTL simulations with the ``LOADARCH`` flag.
+The target config **MUST** use dmi-based bringup (as opposed to the default TSI-based bringup), and support fast ``LOADMEM``.
+The target config should also match the architectural configuration of however spike was configured when generating the checkpoint.
+
+.. code::
+
+   cd sims/vcs
+   make CONFIG=dmiRocketConfig run-binary LOADARCH=../../hello.riscv.0x80000000.1000.loadarch
+

docs/Advanced-Concepts/index.rst

@@ -16,3 +16,4 @@ They expect you to know about Chisel, Parameters, configs, etc.
    CDEs
    Harness-Clocks
    Managing-Published-Scala-Dependencies
+   Architectural-Checkpoints

docs/Simulation/Software-RTL-Simulation.rst

@@ -151,25 +151,17 @@ Fast Memory Loading
 -------------------
 
 The simulator loads the program binary over a simulated serial line. This can be quite slow if there is a lot of static data, so the simulator also allows data to be loaded from a file directly into the DRAM model.
+Loadmem files should be ELF files. In the most common use case, this can be the binary.
 
 .. code-block:: shell
 
-    make run-binary BINARY=test.riscv LOADMEM=testdata.hex LOADMEM_ADDR=81000000
+    make run-binary BINARY=test.riscv LOADMEM=test.riscv
 
-The ``.hex`` file should be a text file with a hexadecimal number on each line.
-
-.. code-block:: text
-
-    deadbeef
-    0123
-
-Each line uses little-endian order, so this file would produce the bytes "ef be ad de 01 23". ``LOADMEM_ADDR`` specifies which address in memory (in hexadecimal) to write the first byte to. The default is 0x81000000.
-
-A special target that facilitates automatically generating a hex file for an entire elf RISC-V exectuable and then running the simulator with the appropriate flags is also available.
+Usually the ``LOADMEM`` ELF is the same as the ``BINARY`` ELF, so ``LOADMEM=1`` can be used as a shortcut.
 
 .. code-block:: shell
 
-    make run-binary-hex BINARY=test.riscv
+   make run-binary BINARY=test.riscv LOADMEM=1
 
 Generating Waveforms
 -----------------------

docs/Software/Spike.rst

@@ -43,7 +43,7 @@ Spike-as-a-Tile can be configured with custom IPC, commit logging, and other beh
 
 ..  code-block:: shell
 
-    make CONFIG=SpikeUltraFastConfig run-binary-hex BINARY=hello.riscv EXTRA_SPIKE_FLAGS="+spike-ipc=10000 +spike-fast-clint +spike-debug"
+    make CONFIG=SpikeUltraFastConfig run-binary BINARY=hello.riscv EXTRA_SPIKE_FLAGS="+spike-ipc=10000 +spike-fast-clint +spike-debug" LOADMEM=1
 
 
 * ``+spike-ipc=``: Sets the maximum number of instructions Spike can retire in a single "tick", or cycle of the uncore simulation.