Feature gem5

.github/workflows/ci.yml

@@ -65,6 +65,7 @@ jobs:
           ../configure --tooldir=$TOOLDIR
           ci/toolchain_install.sh --all
           ci/sst_install.sh
+          ci/gem5_install.sh
 
       - name: Setup Third Party
         if: steps.cache-thirdparty.outputs.cache-hit != 'true'
@@ -78,6 +79,11 @@ jobs:
           echo "SST_CORE_HOME=$PWD/tools/sst-install/sst-core" >> $GITHUB_ENV
           echo "SST_ELEMENTS_HOME=$PWD/tools/sst-install/sst-elements" >> $GITHUB_ENV
 
+      - name: Export gem5 paths
+        run: |
+          echo "GEM5_HOME=$PWD/tools/gem5" >> $GITHUB_ENV
+          echo "$PWD/tools/gem5/build/X86" >> $GITHUB_PATH
+
   build:
     needs: setup
     strategy:
@@ -137,15 +143,23 @@ jobs:
       matrix:
         os: [ubuntu-24.04]
         # dxa + tensor_wg disabled: features not yet complete (see regression{32,64}_failures.md)
-        name: [regression, amo, mpi, dtm, opencl, cache, config1, config2, debug, scope, stress, synthesis, vm, rvc, cupbop, hip, tensor, tensor_sp, tensor_mx]
+        name: [regression, amo, mpi, dtm, opencl, cache, config1, config2, debug, scope, stress, synthesis, vm, rvc, cupbop, hip, tensor, tensor_sp, tensor_mx, gem5]
         xlen: [32, 64]
         # chipStar's hipcc emits Physical64 SPIR-V; POCL refuses it on
         # rv32 Vortex (CL_INVALID_OPERATION). hip is rv64-only until
         # either chipStar grows --offload=spirv32 or the native
         # HIPVortex toolchain lands (see hip_support_proposal.md).
+        #
+        # gem5 only runs against the rv32 build; the device library
+        # is XLEN-locked by the gem5 install (build/X86/gem5.opt
+        # links against the libvortex-gem5.so the runner builds, and
+        # we only build it once). XLEN=64 entry would just duplicate
+        # the run against an identical setup.
         exclude:
           - name: hip
             xlen: 32
+          - name: gem5
+            xlen: 64
     runs-on: ${{ matrix.os }}
     timeout-minutes: 120
 
@@ -190,6 +204,11 @@ jobs:
           echo "SST_CORE_HOME=$PWD/tools/sst-install/sst-core" >> $GITHUB_ENV
           echo "SST_ELEMENTS_HOME=$PWD/tools/sst-install/sst-elements" >> $GITHUB_ENV
 
+      - name: Export gem5 paths
+        run: |
+          echo "GEM5_HOME=$PWD/tools/gem5" >> $GITHUB_ENV
+          echo "$PWD/tools/gem5/build/X86" >> $GITHUB_PATH
+
       - name: Run tests
         run: |
           cd build${{ matrix.xlen }}

VERSION

@@ -1,2 +1,3 @@
 VORTEX_VERSION=3.0
 TOOLCHAIN_REV=v3.0
+GEM5_REV=v25.0.0.1

ci/gem5_install.sh.in

@@ -0,0 +1,119 @@
+#!/bin/bash
+
+# Copyright © 2019-2023
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# gem5 install for the Vortex integration — see
+# docs/proposals/gem5_v2_cp_migration_proposal.md for the design,
+# docs/gem5_integration.md for the operator manual.
+#
+# Fetches a pinned gem5 release, installs build deps + the AArch64
+# cross-toolchain (used by the ARM regression matrix), and builds
+# gem5.opt for the selected ISA targets (X86 + ARM by default). The
+# Vortex SimObject is installed separately via
+# `sim/simx/gem5/install.sh` — that step has to re-run whenever the
+# SimObject sources change, but it does NOT need a fresh gem5 clone.
+#
+# Idempotent: re-running with the same GEM5_REV is a no-op once
+# $GEM5_HOME/build/<target>/gem5.opt exists.
+
+# exit when any command fails
+set -e
+
+GEM5_REV=${GEM5_REV:=@GEM5_REV@}
+TOOLDIR=${TOOLDIR:=@TOOLDIR@}
+GEM5_HOME=$TOOLDIR/gem5
+GEM5_REPO=https://github.com/gem5/gem5.git
+
+# Build deps. gem5 documents these at https://www.gem5.org/documentation/general_docs/building
+# AArch64 cross-toolchain (gcc/g++-aarch64-linux-gnu) is needed for
+# the ARM regression matrix: cross-compiles libvortex-gem5-aarch64.so
+# and vecadd-aarch64 / sgemm-aarch64. Installing it here keeps the
+# one-time setup self-contained.
+DEBIAN_FRONTEND=noninteractive sudo apt install -y \
+    scons \
+    python3 python3-dev python3-pip python3-venv \
+    libprotobuf-dev protobuf-compiler libprotoc-dev \
+    libgoogle-perftools-dev \
+    m4 \
+    libboost-all-dev \
+    libhdf5-serial-dev \
+    libpng-dev \
+    pkg-config \
+    gcc-aarch64-linux-gnu g++-aarch64-linux-gnu \
+    build-essential git wget
+
+mkdir -p "$TOOLDIR"
+
+# Fetch (or update) gem5 working tree at the pinned revision.
+if [ -d "$GEM5_HOME/.git" ]; then
+    echo "gem5 working tree exists at $GEM5_HOME"
+    pushd "$GEM5_HOME" > /dev/null
+    current_rev=$(git describe --tags --always 2>/dev/null || echo "unknown")
+    if [ "$current_rev" != "$GEM5_REV" ]; then
+        echo "checked-out rev $current_rev != pinned $GEM5_REV; refetching"
+        git fetch --depth=1 origin "tag" "$GEM5_REV"
+        git checkout "$GEM5_REV"
+    fi
+    popd > /dev/null
+else
+    echo "cloning gem5 $GEM5_REV into $GEM5_HOME"
+    git clone --depth=1 --branch "$GEM5_REV" "$GEM5_REPO" "$GEM5_HOME"
+fi
+
+# Build the ARM variant. -j$(nproc) on the self-hosted runner; cap at 4
+# on hosted runners to avoid OOM (gem5 link uses ~4 GB peak).
+JOBS=$(nproc)
+if [ -n "$GITHUB_ACTIONS" ] && [ -z "$VORTEX_SELF_HOSTED" ]; then
+    JOBS=4
+fi
+
+# Build both X86 (default host ISA — easier, no cross-compile needed)
+# and ARM (used by the cross-arch regression matrix). Either can be
+# selected at test-config time via GEM5_BIN=$GEM5_HOME/build/{X86,ARM}/gem5.opt.
+# Default targets can be overridden via GEM5_TARGETS="X86" or "ARM" or
+# "X86 ARM" (space-separated). Both is the default.
+GEM5_TARGETS=${GEM5_TARGETS:-"X86 ARM"}
+
+cd "$GEM5_HOME"
+for target in $GEM5_TARGETS; do
+    if [ ! -x "$GEM5_HOME/build/$target/gem5.opt" ]; then
+        echo "building gem5.opt ($target) with -j$JOBS"
+        scons "build/$target/gem5.opt" -j"$JOBS"
+    else
+        echo "gem5.opt ($target) already built at $GEM5_HOME/build/$target/gem5.opt"
+    fi
+done
+
+# Persist GEM5_HOME for subsequent shells (idempotent).
+if ! grep -q "^export GEM5_HOME=" ~/.bashrc 2>/dev/null; then
+    echo "export GEM5_HOME=$GEM5_HOME" >> ~/.bashrc
+fi
+export GEM5_HOME
+
+# GitHub Actions: propagate to subsequent steps.
+if [ -n "$GITHUB_ENV" ]; then
+    echo "GEM5_HOME=$GEM5_HOME" >> "$GITHUB_ENV"
+fi
+if [ -n "$GITHUB_PATH" ]; then
+    for target in $GEM5_TARGETS; do
+        echo "$GEM5_HOME/build/$target" >> "$GITHUB_PATH"
+    done
+fi
+
+echo ""
+echo "gem5 $GEM5_REV installed at $GEM5_HOME"
+for target in $GEM5_TARGETS; do
+    echo "  binary: $GEM5_HOME/build/$target/gem5.opt"
+done
+echo "  GEM5_HOME exported (re-source ~/.bashrc to pick up in new shells)"