ci.yml

# Copyright 2020 ETH Zurich and University of Bologna.
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0

# Run regression tests on Snitch's Docker container.
# Pull requests from forks cannot deploy the Docker container due to missing
# secrets, thus we only enable this workflow on push triggers.
name: ci
on: [push]

env:
  FORCE_COLOR: 1

# Cancel any in-progress runs on new push to the same branch
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:

  ##########################
  # Build Docker Container #
  ##########################

  docker-meta:
    name: Define Docker image names
    runs-on: ubuntu-22.04
    outputs:
      hw_image_name: ${{ steps.meta.outputs.hw_image_name }}
      sw_image_name: ${{ steps.meta.outputs.sw_image_name }}
    steps:
      - id: meta
        run: |
          SANITIZED_REF_NAME="${GITHUB_REF_NAME//\//-}"
          SANITIZED_REPO_NAME="$(echo "${GITHUB_REPOSITORY}" | tr '[:upper:]' '[:lower:]')"

          echo "Sanitized GITHUB_REF_NAME: $SANITIZED_REF_NAME"
          echo "Sanitized GITHUB_REPOSITORY: $SANITIZED_REPO_NAME"

          HW_IMAGE_NAME="ghcr.io/${SANITIZED_REPO_NAME}-hw:${SANITIZED_REF_NAME}"
          SW_IMAGE_NAME="ghcr.io/${SANITIZED_REPO_NAME}-sw:${SANITIZED_REF_NAME}"

          {
            echo "hw_image_name=$HW_IMAGE_NAME"
            echo "sw_image_name=$SW_IMAGE_NAME"
          } >> "$GITHUB_OUTPUT"

  build-hw-image:
    name: Deploy hardware development image
    runs-on: ubuntu-22.04
    needs: [docker-meta]
    outputs:
      hw_image_name: ${{ needs.docker-meta.outputs.hw_image_name }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
      - uses: ./.github/actions/docker-build-push
        with:
          target: snitch_cluster-hw
          tags: ${{ needs.docker-meta.outputs.hw_image_name }}
          token: ${{ secrets.GITHUB_TOKEN }}

  build-sw-image:
    name: Deploy software development image
    runs-on: ubuntu-22.04
    needs: [docker-meta]
    outputs:
      sw_image_name: ${{ needs.docker-meta.outputs.sw_image_name }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
      - uses: ./.github/actions/docker-build-push
        with:
          target: snitch_cluster-sw
          tags: ${{ needs.docker-meta.outputs.sw_image_name }}
          token: ${{ secrets.GITHUB_TOKEN }}

  ########
  # Docs #
  ########

  build-docs:
    name: Build documentation
    runs-on: ubuntu-22.04
    needs: [docker-meta, build-sw-image]
    container:
      image: ${{ needs.docker-meta.outputs.sw_image_name }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: 'recursive'
      - uses: ./.github/actions/setup-python
      - name: Build docs
        run: make docs

  deploy-docs:
    name: Deploy documentation
    runs-on: ubuntu-22.04
    needs: [docker-meta, build-sw-image]
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    container:
      image: ${{ needs.docker-meta.outputs.sw_image_name }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: 'recursive'
      - uses: ./.github/actions/setup-python
      # For some reason, the checkout is done by a different user
      # than that deploying to Github (root, possibly due to Docker).
      # So we need to set the repository as a safe directory.
      - name: Git config safe.directory
        run: |
          git config --global --add safe.directory $GITHUB_WORKSPACE
      - name: Generate documentation sources
        run: |
          make doc-srcs
          make doxygen-docs
      - name: Build and deploy documentation
        run: mkdocs gh-deploy --force

  #####################
  # Python unit tests #
  #####################

  pytest:
    name: Python unit tests
    runs-on: ubuntu-22.04
    needs: [docker-meta, build-sw-image]
    container:
      image: ${{ needs.docker-meta.outputs.sw_image_name }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: 'recursive'
      - uses: ./.github/actions/setup-python
      - name: Run pytest
        run: pytest

  ##############################################
  # Simulate SW on Snitch Cluster w/ Verilator #
  ##############################################

  snitch-cluster-vlt:
    name: Build Snitch Cluster w/ Verilator
    runs-on: ubuntu-22.04
    needs: [docker-meta, build-hw-image]
    container:
      image: ${{ needs.docker-meta.outputs.hw_image_name }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: 'recursive'
      - uses: ./.github/actions/setup-python
      - name: Hash Verilator prerequisites
        id: verilator-hash
        run: |
          hash=$(list-make-prerequisites verilator --recursive --hash)
          echo "hash=$hash" >> "$GITHUB_OUTPUT"
      - name: Set up cache for Verilator build
        id: verilator-cache
        uses: actions/cache@v4
        with:
          path: target/sim/build/bin
          key: verilator-${{ steps.verilator-hash.outputs.hash }}
          restore-keys: |
            verilator-
      - name: Build Hardware
        if: steps.verilator-cache.outputs.cache-hit != 'true'
        run: |
          make CFG_OVERRIDE=cfg/github-ci.json verilator

  sw-snitch-cluster-vlt:
    name: Simulate SW on Snitch Cluster w/ Verilator
    runs-on: ubuntu-22.04
    needs: [docker-meta, build-sw-image]
    container:
      image: ${{ needs.docker-meta.outputs.sw_image_name }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: 'recursive'
      - uses: ./.github/actions/setup-python
      - name: Build Software
        run: |
          make sw -j
      - name: Run Tests
        working-directory: test
        run: |
          ../util/experiments/run.py run.yaml --simulator verilator -j
          ../util/experiments/run.py riscv_tests_isa.yaml --simulator verilator -j
      - name: Annotate traces
        # Build the traces using the --permissive flag, since the Verilator
        # testbench does not wait until all the instructions are retired
        # (compiler introduces few instructions after exit routine).
        run: |
          make SIM_DIR=./test/runs/simple DEBUG=ON annotate -j

  ########################################################
  # Simulate SW on Snitch Cluster (Mempool) w/ Verilator #
  ########################################################

  snitch-mempool-cluster-vlt:
    name: Build and Simulate Mempool Snitch Cluster w/ Verilator
    runs-on: ubuntu-22.04
    needs: [docker-meta, build-hw-image]
    container:
      image: ${{ needs.docker-meta.outputs.hw_image_name }}
      volumes:
        - ${{ github.workspace }}:/repo
    defaults:
      run:
        working-directory: /repo
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: 'recursive'
      - uses: ./.github/actions/setup-python
      - name: Hash Verilator prerequisites
        id: verilator-hash
        run: |
          hash=$(list-make-prerequisites verilator --recursive --hash)
          echo "hash=$hash" >> "$GITHUB_OUTPUT"
      - name: Set up cache for Verilator build
        id: verilator-cache
        uses: actions/cache@v4
        with:
          path: |
            /repo/target/sim/build/bin
          key: verilator-mempool-${{ steps.verilator-hash.outputs.hash }}
          restore-keys: |
            verilator-mempool-
      - name: Build Hardware
        if: steps.verilator-cache.outputs.cache-hit != 'true'
        run: |
          make CFG_OVERRIDE=cfg/mempool.json verilator
      - name: Build Software for mempool tests
        run: |
          make sw CFG_OVERRIDE=cfg/mempool.json SN_MCPU=snitch-mempool -j
      - name: Run Tests
        run: |
          cd test
          ../util/experiments/run.py mempool.yaml --simulator verilator -j
      - name: Annotate traces
        # Build the traces using the --permissive flag, since the Verilator
        # testbench does not wait until all the instructions are retired
        # (compiler introduces few instructions after exit routine).
        run: |
          make SIM_DIR=./test/runs/simple SN_MCPU=snitch-mempool DEBUG=ON annotate -j

  #############
  # Synthesis #
  #############

  synthesis:
    name: Synthesis w/ Yosys
    runs-on: ubuntu-22.04
    needs: [docker-meta, build-hw-image]
    container:
      image: ${{ needs.docker-meta.outputs.hw_image_name }}
      volumes:
        - ${{ github.workspace }}:/repo
    defaults:
      run:
        working-directory: /repo
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: 'recursive'
      - uses: ./.github/actions/setup-python
      - name: Run Synthesis
        run: |
          make CFG_OVERRIDE=cfg/yosys-ci.json yosys

  ######################
  # Sources Up-to-Date #
  ######################

  sources-up-to-date:
    name: Check Sources Up-to-Date
    runs-on: ubuntu-22.04
    needs: [docker-meta, build-hw-image]
    container:
      image: ${{ needs.docker-meta.outputs.hw_image_name }}
      volumes:
        - ${{ github.workspace }}:/repo
    defaults:
      run:
        working-directory: /repo
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: 'recursive'
      - uses: ./.github/actions/setup-python
      - name: Generate opcodes
        run: |
          ./util/clustergen/generate-opcodes.sh
      - name: Generate RTL sources
        run: |
          make rtl
      # For some reason, the checkout is done by a different user,
      # than that running `git diff` (root, possibly due to Docker).
      # So we need to set the repository as a safe directory.
      - name: Git config safe.directory
        run: |
          git config --global --add safe.directory $GITHUB_WORKSPACE
      - name: Diff porcelain
        uses: mmontes11/diff-porcelain@v0.0.1
        with:
          message: Found differences, please update all sources