Simplified CI for tutorials + Tutorial Docs

.github/workflows/chipyard-tutorials.yml

@@ -0,0 +1,65 @@
+name: chipyard-tutorials
+
+# TODO: figure out when to run tutorials
+on:
+  # run ci on pull requests targeting following branches (runs on the merge commit)
+  pull_request:
+    branches:
+      - main
+      - '1.[0-9]*.x'
+
+# nicer shell to run commands in
+defaults:
+  run:
+    shell: bash -leo pipefail {0}
+
+jobs:
+  cancel-prior-workflows:
+    name: Cancel Prior Workflows
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/[email protected]
+        with:
+          access_token: ${{ github.token }}
+
+  # example of running a tutorial given a pre-made script
+  first-verilog-build-tutorial:
+    name: First Verilog Build Tutorial
+    needs: [cancel-prior-workflows]
+    runs-on: as4
+    env:
+      CHIPYARD_DIR: ${{ github.workspace }}
+    steps:
+      # workaround actions/checkout not 'cleaning' submodules on new checkouts. see https://github.com/actions/checkout/issues/358
+      - name: Delete old checkout
+        run: |
+          rm -rf ${{ github.workspace }}/* || true
+          rm -rf ${{ github.workspace }}/.* || true
+      - uses: actions/checkout@v3
+      # a script with all the tutorial commands
+      - name: Run tutorial
+        run: |
+          scripts/tutorial-first-verilog-build.sh
+
+  # example of running a tutorial from an auto-generated script built from .rst
+  first-verilog-build-automated-tutorial:
+    name: First Verilog Build Automated Tutorial
+    needs: [cancel-prior-workflows]
+    runs-on: as4
+    env:
+      CHIPYARD_DIR: ${{ github.workspace }}
+    steps:
+      # workaround actions/checkout not 'cleaning' submodules on new checkouts. see https://github.com/actions/checkout/issues/358
+      - name: Delete old checkout
+        run: |
+          rm -rf ${{ github.workspace }}/* || true
+          rm -rf ${{ github.workspace }}/.* || true
+      - uses: actions/checkout@v3
+      # run the autogenerated script with all the tutorial commands
+      - name: Run tutorial
+        run: |
+          scripts/generate-script-from-tutorial-rst.py docs/Tutorials/First-Verilog-Build.rst tutorial.sh
+          echo "Created tutorial.sh >>>" && cat tutorial.sh && echo "<<< Done tutorial.sh"
+          chmod +x tutorial.sh
+          ./tutorial.sh

docs/Tutorials/First-Verilog-Build.rst

@@ -0,0 +1,53 @@
+First Verilog Build
+===================
+
+This tutorial guides you through setting up Chipyard for the first time and building Verilog (specifically a Rocket core SoC).
+
+First navigate to the Chipyard directory.
+Ensure that ``$CHIPYARD_DIR`` is set to the top-level directory.
+
+.. code-block:: shell
+
+    cd $CHIPYARD_DIR
+
+.. only:: replace-code-above
+
+    cd $CHIPYARD_DIR
+    export MAKEFLAGS="-j32"
+
+Next, run the Chipyard setup script.
+
+.. code-block:: shell
+
+    ./build-setup.sh
+
+.. only:: replace-code-above
+
+    ./build-setup.sh -f -v
+
+Chipyard should be setup.
+Next, source the ``env.sh`` script to setup your ``PATH`` and other environment variables.
+
+.. code-block:: shell
+
+    source env.sh
+
+Next, let's build some Verilog specifically the default SoC which includes a Rocket in-order core.
+
+.. code-block:: shell
+
+    cd sims/verilator
+    make verilog
+
+Next, let's build the Verilator simulator binary of that SoC that can run a RISC-V binary (like a "Hello, World" program).
+
+.. code-block:: shell
+
+    make
+
+Finally, look at the ``generated-src`` directory which holds the Verilog sources and the ``simulator-*`` file which is the compiled Verilator binary.
+
+.. code-block:: shell
+
+    ls -alh generated-src
+    ls -alh simulator*

docs/Tutorials/index.rst

@@ -0,0 +1,13 @@
+Tutorials
+================
+
+This section holds various tutorials for specific features, workflows, and more within Chipyard.
+Each requires you to checkout the Chipyard repo and set the ``CHIPYARD_DIR`` environment variable before continuing on.
+
+.. Warning:: Tutorials are only guaranteed to work on released versions of Chipyard.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials:
+
+   First-Verilog-Build

docs/index.rst

@@ -43,6 +43,8 @@ Table of Contents
 
    Prototyping/index
 
+   Tutorials/index
+
 
 Indices and tables
 ==================

scripts/generate-script-from-tutorial-rst.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python
+
+import sys
+
+# $1 - rst file to parse
+# $2 - output bash file to write
+
+if len(sys.argv) != 3:
+    sys.exit("[ERROR] Incorrect # of args.")
+
+rstFile = sys.argv[1]
+bashFile = sys.argv[2]
+
+codeBlocks = [] # ordered list of blocks, each block is (type: String, lines: List[Strings])
+
+with open(rstFile, 'r') as rstF:
+    inBlock = False
+    skipEmpty = False
+    curBlockType = ""
+    curBlockLines = []
+    for line in rstF.readlines():
+        if inBlock:
+            if len(line) == 1 and line == '\n':
+                # empty line
+                if not skipEmpty:
+                    # empty line (done with block)
+                    inBlock = False
+                    codeBlocks.append((curBlockType, curBlockLines))
+                    curBlockType = ""
+                    curBlockLines = []
+                skipEmpty = False
+            else:
+                assert (line[0:4] == ' ' * 4), "Must only strip whitespace (ensure RST only has 4 spaces before code lines)"
+                curBlockLines.append(line[4:]) # strip the first 4 spaces (indent)
+        else:
+            if ".. code-block:: shell" in line:
+                inBlock = True
+                curBlockType = "code-block"
+                skipEmpty = True
+            elif ".. only:: replace-code-above" in line:
+                inBlock = True
+                curBlockType = "replace-above"
+                skipEmpty = True
+
+idxToDelete = []
+for idx, cb in enumerate(codeBlocks):
+    if cb[0] == "replace-above":
+        idxToDelete.append(idx)
+
+# TODO: could check that replace-code-above directives cannot follow one another
+
+idxToDelete.reverse()
+for idx in idxToDelete:
+    assert idx - 1 >= 0, "replace-code-above directives must come after a code-block directive"
+    codeBlocks.pop(idx - 1)
+
+with open(bashFile, 'w') as bashF:
+    header = """#!/usr/bin/env bash
+
+# exit script if any command fails
+set -e
+set -o pipefail
+
+# $CHIPYARD_DIR should be defined and pointing to the top-level folder in Chipyard
+if [[ -z "${CHIPYARD_DIR}" ]]; then
+  echo "Environment variable \$CHIPYARD_DIR is undefined. Unable to run script."
+  exit 1
+fi
+"""
+    bashF.writelines([header, '\n'])
+    for cb in codeBlocks:
+        bashF.writelines(cb[1])

scripts/tutorial-first-verilog-build.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+# exit script if any command fails
+set -e
+set -o pipefail
+
+# $CHIPYARD_DIR should be defined and pointing to the top-level folder in Chipyard
+if [[ -z "${CHIPYARD_DIR}" ]]; then
+  echo "Environment variable \$CHIPYARD_DIR is undefined. Unable to run script."
+  exit 1
+fi
+
+cd $CHIPYARD_DIR
+
+# speed up setup
+export MAKEFLAGS="-j32"
+
+# run setup
+./build-setup.sh -f -v
+
+# use chipyard env
+source env.sh
+
+# build first set of verilog
+cd sims/verilator
+make verilog
+
+# build and make verilator binary for verilog built
+make
+
+# see verilog
+ls -alh generated-src
+
+# see verilator binary
+ls -alh simulator*