Extend simulation utilities (#78)

* utils/sim: Add MkDocs documentation

* utils/sim: Improve extensibility by using `kwargs` in constructors

* util/container: Upgrade to Python 3.9.12

* util/container: Install `ca-certificates` to fix curl error 77

* util/container: Install `make` and `gcc`

* util/sim: Add per-simulation run directory and dry-run options

* target: Selectively disable full RTL visibility and wave logging

This is used to speed up simulation time. By default, full RTL visibility
in Questasim (+acc flag) is not enabled. By compiling the hardware with
DEBUG=ON (`make DEBUG=ON bin/snitch_cluster.vsim`) it is enabled and all
waves are logged.

Makefile

@@ -17,9 +17,7 @@ clean: clean-docs
 doc-srcs: $(GENERATED_DOC_SRCS)
 
 docs: doc-srcs
-	@if mkdocs build | grep -q "ERROR"; then \
-		exit 1; \
-	fi
+	mkdocs build
 
 clean-docs:
 	rm -rf $(GENERATED_DOCS_DIR)

apt-requirements.txt

@@ -6,8 +6,4 @@
 clang-format
 device-tree-compiler
 graphviz
-python3
-python3-pip
-python3-setuptools
-python3-wheel
 tar

docs/requirements.txt

@@ -4,7 +4,8 @@
 
 # Keep sorted.
 mkdocs
-# Last version compatible with python-3.6 (default on Ubuntu 18.04)
-mkdocs-material <= 8.2.11
+mkdocs-material
 mkdocs-include-markdown-plugin
-mkdocs-macros-plugin
+mkdocs-macros-plugin
+mkdocstrings
+mkdocstrings-python

docs/rm/sim/Simulation.md

@@ -0,0 +1 @@
+::: Simulation

docs/rm/sim/Simulator.md

@@ -0,0 +1 @@
+::: Simulator

docs/rm/sim/sim_utils.md

@@ -0,0 +1 @@
+::: sim_utils

mkdocs.yml

@@ -22,6 +22,10 @@ markdown_extensions:
       emoji_generator: !!python/name:materialx.emoji.to_svg
 plugins:
   - include-markdown
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [util/sim]
   - macros:
       on_error_fail: true
 use_directory_urls: false
@@ -49,10 +53,15 @@ nav:
           - Custom Instructions: rm/custom_instructions.md
           # - Solder: rm/solder.md
       - Software:
-          - Pages: runtime/Pages/index.md
-          - Files: runtime/Files/index.md
-          - Classes: runtime/Classes/index.md
-          - Examples: runtime/Examples/index.md
-          - Modules: runtime/Modules/index.md
-          - Namespaces: runtime/Namespaces/index.md
+          - Simulation Utilities:
+              - sim_utils: rm/sim/sim_utils.md
+              - rm/sim/Simulation.md
+              - rm/sim/Simulator.md
+          - Snitch Runtime:
+              - Pages: runtime/Pages/index.md
+              - Files: runtime/Files/index.md
+              - Classes: runtime/Classes/index.md
+              - Examples: runtime/Examples/index.md
+              - Modules: runtime/Modules/index.md
+              - Namespaces: runtime/Namespaces/index.md
   - Publications: publications.md

target/common/common.mk

@@ -2,6 +2,10 @@
 # Licensed under the Apache License, Version 2.0, see LICENSE for details.
 # SPDX-License-Identifier: Apache-2.0
 
+# Makefile invocation
+DEBUG ?= OFF  # ON to turn on wave logging
+
+# Directories
 LOGS_DIR ?= logs
 TB_DIR   ?= $(SNITCH_ROOT)/target/common/test
 UTIL_DIR ?= $(SNITCH_ROOT)/util
@@ -41,7 +45,13 @@ SED_SRCS  := sed -e ${MATCH_END} -e ${MATCH_BGN}
 VSIM_BENDER   += -t test -t rtl -t simulation -t vsim
 VSIM_SOURCES   = $(shell ${BENDER} script flist ${VSIM_BENDER} | ${SED_SRCS})
 VSIM_BUILDDIR ?= work-vsim
+VSIM_FLAGS    += -t 1ps
+ifeq ($(DEBUG), ON)
+VSIM_FLAGS    += -do "log -r /*; run -a"
 VOPT_FLAGS     = +acc
+else
+VSIM_FLAGS    += -do "run -a"
+endif
 
 # VCS_BUILDDIR should to be the same as the `DEFAULT : ./work-vcs`
 # in target/snitch_cluster/synopsys_sim.setup

target/snitch_cluster/Makefile

@@ -9,7 +9,7 @@
 # Makefile invocation #
 #######################
 
-DEBUG          ?= OFF  # ON to turn on debugging symbols
+DEBUG          ?= OFF  # ON to turn on debugging symbols and wave logging
 CFG_OVERRIDE   ?=      # Override default config file
 SELECT_RUNTIME ?=      # Select snRuntime implementation: "banshee" or "rtl" (default)
 
@@ -68,8 +68,6 @@ QUESTA_64BIT = -64
 VLOG_64BIT   = -64
 
 VSIM_FLAGS += ${QUESTA_64BIT}
-VSIM_FLAGS += -t 1ps
-VSIM_FLAGS += -do "log -r /*; run -a"
 
 VLOG_FLAGS += -svinputport=compat
 VLOG_FLAGS += -override_timescale 1ns/1ps

target/snitch_cluster/run.py

@@ -24,12 +24,12 @@
 
 def main():
     args = parser('vsim', SIMULATORS.keys()).parse_args()
-    simulations = get_simulations(args.testlist, SIMULATORS[args.simulator])
+    simulations = get_simulations(args.testlist, SIMULATORS[args.simulator], args.run_dir)
     return run_simulations(simulations,
                            n_procs=args.n_procs,
-                           run_dir=Path(args.run_dir),
                            dry_run=args.dry_run,
-                           early_exit=args.early_exit)
+                           early_exit=args.early_exit,
+                           verbose=args.verbose)
 
 
 if __name__ == '__main__':

target/snitch_cluster/sw/run.yaml

@@ -68,7 +68,7 @@ runs:
   - elf: tests/build/varargs_2.elf
   - elf: tests/build/zero_mem.elf
   - elf: tests/build/non_null_exitcode.elf
-    exit_code: 14
+    retcode: 14
   - elf: apps/blas/axpy/build/axpy.elf
     cmd: [../../../sw/blas/axpy/verify.py, "${sim_bin}", "${elf}"]
   - elf: apps/blas/gemm/build/gemm.elf

util/container/Dockerfile

@@ -7,7 +7,11 @@
 # 1. Stage
 FROM ubuntu:18.04 AS builder
 ARG CMAKE_VERSION=3.19.4
+ARG PYTHON_VERSION=3.9.12
+# Run dpkg without interactive dialogue
+ARG DEBIAN_FRONTEND=noninteractive
 
+# Install APT requirements
 COPY apt-requirements.txt /tmp/apt-requirements.txt
 RUN apt-get update && \
     sed 's/#.*//' /tmp/apt-requirements.txt \
@@ -20,8 +24,26 @@ RUN apt-get update && \
         lsb-release \
         software-properties-common \
         unzip \
-        wget \
-        zlib1g-dev
+        wget
+# Required to install Python
+RUN apt-get update && apt-get install -y \
+        zlib1g-dev \
+        libreadline-gplv2-dev \
+        libncursesw5-dev \
+        libssl-dev \
+        libsqlite3-dev \
+        tk-dev \
+        libgdbm-dev \
+        libc6-dev \
+        libbz2-dev \
+        libffi-dev
+
+# Install Python
+RUN wget https://www.python.org/ftp/python/${PYTHON_VERSION}/Python-${PYTHON_VERSION}.tgz
+RUN tar xzf Python-${PYTHON_VERSION}.tgz
+RUN cd Python-${PYTHON_VERSION} && \
+    ./configure --enable-optimizations --prefix=/opt/python/ && \
+    make install -j
 
 # Build Rust tools
 RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
@@ -37,6 +59,7 @@ RUN wget https://apt.llvm.org/llvm.sh
 RUN chmod +x llvm.sh
 RUN ./llvm.sh 12
 
+# Change working directory
 WORKDIR /tools
 
 # Install a newer version of cmake (we need this for banshee)
@@ -73,9 +96,11 @@ RUN apt-get update && \
     sed 's/#.*//' /tmp/apt-requirements.txt \
         | xargs apt-get install -y && \
     apt-get install -y --no-install-recommends \
+        ca-certificates \
         gnupg2 \
         curl \
         wget \
+        build-essential \
         git && \
     apt-get clean ; \
     rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*
@@ -88,12 +113,6 @@ RUN echo 'deb http://download.opensuse.org/repositories/home:/phiwag:/edatools/x
     rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*
 ENV VLT_ROOT "/usr/share/verilator"
 
-# Install Python requirements
-COPY python-requirements.txt /tmp/python-requirements.txt
-COPY docs/requirements.txt /tmp/docs/requirements.txt
-COPY sw/dnn/requirements.txt /tmp/sw/dnn/requirements.txt
-RUN pip3 install -r /tmp/python-requirements.txt
-
 # Get the precompiled LLVM toolchain
 RUN latest_tag=`curl -s -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/pulp-platform/llvm-project/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/'` && \
     echo "SNITCH_LLVM_VERSION=${SNITCH_LLVM_VERSION} LLVM_TAR=${LLVM_TAR} latest_tag=${latest_tag}" && \
@@ -120,6 +139,17 @@ RUN apt-get update && apt-get install software-properties-common -y && \
 # Copy artifacts from stage 1.
 COPY --from=builder /root/.cargo/bin/bender bin/
 COPY --from=builder /root/.cargo/bin/banshee bin/
+COPY --from=builder /opt/python /opt/python
+
+# Create and activate virtual environment
+ENV VIRTUAL_ENV "/root/.venvs/snitch_cluster"
+RUN /opt/python/bin/python3 -m venv ${VIRTUAL_ENV}
+ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
+# Install Python requirements
+COPY python-requirements.txt /tmp/python-requirements.txt
+COPY docs/requirements.txt /tmp/docs/requirements.txt
+COPY sw/dnn/requirements.txt /tmp/sw/dnn/requirements.txt
+RUN pip install -r /tmp/python-requirements.txt
 
 # Set locale to UTF-8, required because Python 3.6 defaults on ASCII encoding.
 # See https://click.palletsprojects.com/en/8.1.x/unicode-support/