From 3dbb5508be35e51c20163b8fdd1957a08e885f39 Mon Sep 17 00:00:00 2001 From: Jerry Zhao Date: Wed, 25 Sep 2019 12:39:17 -0700 Subject: [PATCH 1/2] [docs][ci skip] Information on debug methodology --- docs/Chipyard-Basics/Debugging-RTL.rst | 85 ++++++++++++++++++++++++++ docs/Chipyard-Basics/index.rst | 3 + docs/Simulation/index.rst | 1 + 3 files changed, 89 insertions(+) create mode 100644 docs/Chipyard-Basics/Debugging-RTL.rst diff --git a/docs/Chipyard-Basics/Debugging-RTL.rst b/docs/Chipyard-Basics/Debugging-RTL.rst new file mode 100644 index 00000000..36e101ea --- /dev/null +++ b/docs/Chipyard-Basics/Debugging-RTL.rst @@ -0,0 +1,85 @@ +Debugging RTL +====================== + +While the packaged Chipyard configs and RTL have been tested to work, +users will typically want to build custom chips by adding their own +IP, or by modifying existing Chisel generators. Such changes might introduce +bugs. This section aims to run through a typical debugging flow +using Chipyard. We assume the user has a custom SoC configuration, +and is trying to verify functionality by running some software test. + +Waveforms +--------------------------- + +The default SW simulators do not dump waveforms during execution. To build +simulators with wave dump capabilities use must use the ``debug`` make target. +For example: + +.. code-block:: shell + + make CONFIG=CustomConfig debug + +The ``run-binary-debug`` rule will also automatically build a simulator, +run it on a custom binary, and generate a waveform. For example, to run a +test on ``helloworld.riscv``, use + +.. code-block:: shell + + make CONFIG=CustomConfig run-binary-debug BINARY=helloworld.riscv + +VCS and Verilator also support many additional flags. For example, specifying +the ``+vpdfilesize`` flag in VCS will treat the output file as a circular +buffer, saving disk space for long-running simulations. Refer to the VCS +and Verilator manuals for more information You may use the ``SIM_FLAGS`` +make variable to set additional simulator flags: + +.. code-block:: shell + + make CONFIG=CustomConfig run-binary-debug BINARY=linux.riscv SIM_FLAGS=+vpdfilesize=1024 + +Print Output +--------------------------- + +Both Rocket and BOOM can be configured with varying levels of print output. +For information see the Rocket core source code, or the BOOM `documentation +`__ .website. In addition, developers +may insert arbitrary printfs at arbitrary conditions within the Chisel g +enerators. See the Chisel documentation for information on this. + +Once the cores have been configured with the desired print statements, the +``+verbose`` flag will cause the simulator to print the statements. The following +commands will all generate desired print statements: + +.. code-block:: shell + + make CONFIG=CustomConfig run-binary-debug BINARY=helloworld.riscv + # The below command does the same thing + ./simv-CustomConfig-debug +verbose helloworld.riscv + +Both cores can be configured to print out commit logs, which can then be compared +against a Spike commit log to verify correctness. + +Basic tests +--------------------------- +``riscv-tests`` includes basic ISA-level tests and basic benchmarks. These +are used in Chipyard CI, and should be the first step in verifying a chip's +functionality. The make rule is + +.. code-block:: shell + + make CONFIG=CustomConfig run-asm-tests run-bmark-tests + + +Torture tests +--------------------------- +The RISC-V torture utility generates random RISC-V assembly streams, compiles them, +runs them on both the Spike functional model and the SW simulator, and verifies +identical program behavior. The torture utility can also be configured to run +continuously for stress-testing. The torture utility exists within the ``utilities`` +directory. + +Firesim Debugging +--------------------------- +Chisel printfs, asserts, and waveform generation are also available in FireSim +FPGA-accelerated simulation. See the FireSim docs for more detail. + diff --git a/docs/Chipyard-Basics/index.rst b/docs/Chipyard-Basics/index.rst index 5c97f0ac..4ca236c4 100644 --- a/docs/Chipyard-Basics/index.rst +++ b/docs/Chipyard-Basics/index.rst @@ -18,3 +18,6 @@ Hit next to get started! Chipyard-Components Configs-Parameters-Mixins Initial-Repo-Setup + Debugging-RTL + + diff --git a/docs/Simulation/index.rst b/docs/Simulation/index.rst index fe0fa161..8341c7ae 100644 --- a/docs/Simulation/index.rst +++ b/docs/Simulation/index.rst @@ -20,3 +20,4 @@ Click next to see how to run a simulation. Software-RTL-Simulation FPGA-Accelerated-Simulators + From 48c8e0f571e973115fc52a6bbaeb34e7b59c91fa Mon Sep 17 00:00:00 2001 From: Jerry Zhao Date: Sat, 28 Sep 2019 18:17:42 -0700 Subject: [PATCH 2/2] [docs][ci skip] Address comments --- .../Debugging-RTL.rst | 12 ++++++++---- docs/Advanced-Concepts/index.rst | 1 + docs/Chipyard-Basics/index.rst | 1 - 3 files changed, 9 insertions(+), 5 deletions(-) rename docs/{Chipyard-Basics => Advanced-Concepts}/Debugging-RTL.rst (87%) diff --git a/docs/Chipyard-Basics/Debugging-RTL.rst b/docs/Advanced-Concepts/Debugging-RTL.rst similarity index 87% rename from docs/Chipyard-Basics/Debugging-RTL.rst rename to docs/Advanced-Concepts/Debugging-RTL.rst index 36e101ea..464c5571 100644 --- a/docs/Chipyard-Basics/Debugging-RTL.rst +++ b/docs/Advanced-Concepts/Debugging-RTL.rst @@ -7,13 +7,16 @@ IP, or by modifying existing Chisel generators. Such changes might introduce bugs. This section aims to run through a typical debugging flow using Chipyard. We assume the user has a custom SoC configuration, and is trying to verify functionality by running some software test. +We also assume the software has already been verified on a functional +simulator, such as Spike or QEMU. This section will focus on debugging +hardware. Waveforms --------------------------- -The default SW simulators do not dump waveforms during execution. To build -simulators with wave dump capabilities use must use the ``debug`` make target. -For example: +The default software RTL simulators do not dump waveforms during execution. +To build simulators with wave dump capabilities use must use the ``debug`` +make target. For example: .. code-block:: shell @@ -81,5 +84,6 @@ directory. Firesim Debugging --------------------------- Chisel printfs, asserts, and waveform generation are also available in FireSim -FPGA-accelerated simulation. See the FireSim docs for more detail. +FPGA-accelerated simulation. See the FireSim +`documentation `__ for more detail. diff --git a/docs/Advanced-Concepts/index.rst b/docs/Advanced-Concepts/index.rst index 2994899c..8194fe1f 100644 --- a/docs/Advanced-Concepts/index.rst +++ b/docs/Advanced-Concepts/index.rst @@ -10,4 +10,5 @@ They expect you to know about Chisel, Parameters, Configs, etc. Top-Testharness Chip-Communication + Debugging-RTL Resources diff --git a/docs/Chipyard-Basics/index.rst b/docs/Chipyard-Basics/index.rst index 4ca236c4..467f147a 100644 --- a/docs/Chipyard-Basics/index.rst +++ b/docs/Chipyard-Basics/index.rst @@ -18,6 +18,5 @@ Hit next to get started! Chipyard-Components Configs-Parameters-Mixins Initial-Repo-Setup - Debugging-RTL