ci.yml

# Copyright lowRISC contributors (OpenTitan project).
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0

name: CI
on:
  pull_request:
  push:
    branches-ignore:
      - "backport-*"
      - "gh-readonly-queue/**"
    tags:
      - "*"
  merge_group:
    types:
      - checks_requested

permissions:
  contents: read
  # Needed for workload identity federation
  id-token: write

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

env:
  VIVADO_VERSION: "2021.1"
  # Release tag from https://github.com/lowRISC/lowrisc-toolchains/releases
  TOOLCHAIN_VERSION: 20220210-1

jobs:
  quick_lint:
    name: Lint (quick)
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # Required so we can lint commit messages.
      - name: Prepare environment
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
      - name: Show environment
        run: ./ci/scripts/show-env.sh
      - name: Commit metadata
        run: ./ci/scripts/lint-commits.sh "$GITHUB_BASE_REF"
        if: ${{ github.event_name == 'pull_request' }}
      - name: License headers
        run: ./ci/scripts/check-licence-headers.sh "$GITHUB_BASE_REF"
        if: ${{ github.event_name == 'pull_request' }}
      - name: Executable bits
        run: ./ci/scripts/exec-check.sh
      - name: Non-ASCII characters
        run: ./ci/scripts/check-ascii.sh
      - name: Python (flake8)
        run: ./ci/scripts/python-lint.sh "$GITHUB_BASE_REF"
        if: ${{ github.event_name == 'pull_request' }}
      - name: Python (mypy)
        run: ./ci/scripts/mypy.sh
      - name: Python (ruff)
        run: ruff check
      - name: Validate testplans with schema
        run: ./ci/scripts/validate_testplans.sh
      - name: C/C++ formatting
        run: ./bazelisk.sh test //quality:clang_format_check
      - name: Rust formatting
        run: ./bazelisk.sh test //quality:rustfmt_check
      - name: Shellcheck
        run: ./bazelisk.sh test //quality:shellcheck_check
      - name: ASM instrumentation
        run: ./util/coverage/asm/run_instrument.sh --check
      - name: Header guards
        run: ./ci/scripts/include-guard.sh "$GITHUB_BASE_REF"
        if: ${{ github.event_name == 'pull_request' }}
      - name: Trailing whitespace
        run: ./ci/scripts/whitespace.sh "$GITHUB_BASE_REF"
        if: ${{ github.event_name == 'pull_request' }}
      - name: Broken links
        run: ./ci/scripts/check-links.sh
      - name: Generated documentation
        run: ./ci/scripts/check-cmdgen.sh
      - name: Lock files
        run: ./ci/scripts/check-lock-files.sh

  slow_lint:
    name: Lint (slow)
    runs-on: ubuntu-22.04
    needs: quick_lint
    if: ${{ github.event_name != 'merge_group' }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # Bitstream cache requires all commits.
      - name: Prepare environment
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
          install-verible: true
      - name: Countermeasures implemented (earlgrey)
        run: ./ci/scripts/check-countermeasures.sh earlgrey
      - name: Countermeasures implemented (englishbreakfast)
        run: ./ci/scripts/check-countermeasures.sh englishbreakfast
      - name: Bazel test suite tags
        run: ./ci/scripts/check_bazel_test_suites.py
        continue-on-error: true
      # See #21973: disabled until Verilator tags are fixed.
      # - name: Check Bazel tags
      #   run: ./ci/scripts/check-bazel-tags.sh
      #   continue-on-error: true
      - name: Banned Bazel rules
        run: ./ci/scripts/check-bazel-banned-rules.sh
      - name: Bazel target names
        run: ./ci/scripts/check_bazel_target_names.py
      - name: DV software images
        run: ./ci/scripts/check_dv_sw_images.sh
        continue-on-error: true
      - name: Generated files
        run: ./ci/scripts/check-generated.sh
        env:
          OT_DESTRUCTIVE: 1 # Required by the script to clean up.
      - name: Buildifier
        run: ./bazelisk.sh test //quality:buildifier_check
      - name: Vendored files
        run: ./ci/scripts/check-vendoring.sh
      - name: Verible RTL earlgrey
        run: ./ci/scripts/verible-lint.sh rtl earlgrey
      - name: Verible DV earlgrey
        run: ./ci/scripts/verible-lint.sh dv earlgrey
      - name: Verible FPV earlgrey
        run: ./ci/scripts/verible-lint.sh fpv earlgrey
      - name: Verible RTL darjeeling
        run: ./ci/scripts/verible-lint.sh rtl darjeeling
      - name: Verible DV darjeeling
        run: ./ci/scripts/verible-lint.sh dv darjeeling
      - name: Verible FPV darjeeling
        run: ./ci/scripts/verible-lint.sh fpv darjeeling
      - name: Validate alert classification for Earl Grey
        run: ./ci/scripts/validate_alert_classification.py hw/top_earlgrey/ip_autogen/alert_handler/data/top_earlgrey_alert_handler.ipconfig.hjson "$(realpath hw/top_earlgrey/data/otp/otp_ctrl_img_owner_sw_cfg.hjson)"
      - name: Validate alert classification for Darjeeling
        run: ./ci/scripts/validate_alert_classification.py hw/top_darjeeling/ip_autogen/alert_handler/data/top_darjeeling_alert_handler.ipconfig.hjson "$(realpath hw/top_darjeeling/data/otp/otp_ctrl_img_owner_sw_cfg.hjson)"

  build_docs:
    name: Build documentation
    runs-on: ubuntu-22.04
    needs: quick_lint
    if: ${{ github.event_name != 'merge_group' }}
    env:
      BUCKET: gold-hybrid-255313-prod
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # Bitstream cache requires all commits.
      - name: Prepare environment
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
      - name: Build documentation
        run: util/site/build-docs.sh build
      - name: Upload files as artifact
        uses: actions/upload-artifact@v7
        with:
          name: docs
          path: build-site/
          overwrite: true
      - name: Upload files
        if: ${{ github.event_name != 'pull_request' && github.ref_name == 'master' }}
        run: |
          echo "::group::Upload all uncompressed files"
          gcloud storage cp -R --gzip-in-flight=js,css,html "build-site/*" gs://$BUCKET
          echo "::endgroup::"

          # This script compresses the searchindex files, replacing the originals in-place.
          # (This is how 'content-encoding'-tagged files should be uploaded to gcloud buckets)
          util/site/post-build.sh compress_br

          search_indexes=$(find build-site/ -type f -name '*searchindex.json')
          for f in $search_indexes; do
              echo "Uploading compressed file ${f}"
              # Get directory of file, relative to the build directory.
              # - var=${var#*//} # removes stuff from the begining up to //
              dir=$(dirname "${f#*build-site/}")
              # When serving from gcloud buckets, file should be uploaded with an identical name as the
              # original, but compressed and with the matching 'content-encoding' and 'content-type' tags applied.
              gcloud storage cp \
                     --content-encoding=br \
                     --content-type=application/json \
                     -R \
                     "$f" "gs://$BUCKET/${dir}/"
          done

  airgapped_build:
    name: Airgapped build
    runs-on: ubuntu-22.04
    needs: quick_lint
    if: ${{ github.event_name != 'merge_group' }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # Bitstream cache requires all commits.
      - name: Prepare environment
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
          configure-bazel: false
      - name: Free disk space
        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be
      - name: Check disk space
        run: |
          df -h
      - name: Prepare airgapped environment
        continue-on-error: true # TODO: the step was running out of memory; fix that issue and remove this line.
        run: ./util/prep-bazel-airgapped-build.sh
      - name: Check disk space
        run: |
          df -h
      - name: Build in the airgapped environment
        continue-on-error: true # See TODO above.
        run: ./ci/scripts/test-airgapped-build.sh

  verible_lint:
    name: Verible lint
    runs-on: ubuntu-24.04
    needs: quick_lint
    if: ${{ github.event_name == 'pull_request' }}
    env:
      verible_config: hw/lint/tools/veriblelint/lowrisc-styleguide.rules.verible_lint
      verible_version: v0.0-3430-g060bde0f
    steps:
      - uses: actions/checkout@v6
      - name: Prepare Verible config
        run: |
          echo "Concatenating Verible waivers"
          find . -type f -name '*.vbl' -exec cat {} \; >> verible_waiver

          echo "::group::Verible config"
          cat "$verible_config"
          echo "::endgroup::"

          echo "::group::Verible waiver"
          cat "verible_waiver"
          echo "::endgroup::"
      - name: Run Verible linter action
        uses: chipsalliance/verible-linter-action@v2.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          verible_version: ${{ env.verible_version }}
          reviewdog_reporter: 'github-pr-check'
          suggest_fixes: 'false'
          config_file: ${{ env.verible_config }}
          extra_args: "--waiver_files=verible_waiver"

  otbn_standalone_tests:
    name: Run OTBN smoke Test
    needs: quick_lint
    runs-on: ubuntu-22.04
    if: ${{ github.event_name != 'merge_group' }}
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # Bitstream cache requires all commits.
      - name: Prepare environment
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
      - name: Install toolchain
        run: |
          TOOLCHAIN_PATH=/tools/riscv
          sudo util/get-toolchain.py \
            --install-dir="$TOOLCHAIN_PATH" \
            --release-version="$TOOLCHAIN_VERSION" \
            --update
          echo "$TOOLCHAIN_PATH/bin" >> $GITHUB_PATH
      - name: Display environment
        run: |
          python3 --version
          fusesoc --version
          verilator --version
      - name: OTBN ISS test
        run: make -C hw/ip/otbn/dv/otbnsim test
      - name: OBTN smoke test
        run: ./hw/ip/otbn/dv/smoke/run_smoke.sh
      - name: Assemble & link code snippets
        run: make -C hw/ip/otbn/util asm-check

  otbn_crypto_tests:
    name: Run OTBN crypto tests
    needs: quick_lint
    runs-on: ubuntu-22.04
    if: ${{ github.event_name != 'merge_group' }}
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # Bitstream cache requires all commits.
      - name: Prepare environment
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
      - name: Execute tests
        run: ./bazelisk.sh test --test_tag_filters=-broken,-skip_in_ci,-nightly //sw/otbn/crypto/...

  verilator_englishbreakfast:
    name: Verilated English Breakfast
    runs-on: ubuntu-22.04
    needs: quick_lint
    if: ${{ github.event_name != 'merge_group' }}
    steps:
      - uses: actions/checkout@v6
      - name: Prepare environment
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
      - name: Build simulator with Verilator
        run: |
          ./bazelisk.sh build --//hw/top=englishbreakfast //hw:verilator_real
          sim_binary_path=$(./bazelisk.sh cquery --//hw/top=englishbreakfast --output=files //hw:verilator_real)
          mkdir -p build-bin/hw/top_englishbreakfast
          cp ${sim_binary_path} build-bin/hw/top_englishbreakfast/
      - name: Upload binary
        uses: actions/upload-artifact@v7
        with:
          name: verilated_englishbreakfast
          path: build-bin/hw/top_englishbreakfast/Vchip_englishbreakfast_verilator
          overwrite: true
      - name: Test
        run: ./ci/scripts/run-english-breakfast-verilator-tests.sh
        # The patching mechanism for english breakfast is incompatible with multitop
        # so this job will fail. At the same time, multitop is not advanced enough
        # that we can compile those tests for EB yet. Ignore this job until we can
        # fix it.
        continue-on-error: true

  verilator_earlgrey:
    name: Verilated Earl Grey
    runs-on: ubuntu-22.04
    needs: quick_lint
    if: ${{ github.event_name != 'merge_group' }}
    timeout-minutes: 240
    steps:
      - uses: actions/checkout@v6
      - name: Prepare environment
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
      - name: Run fast Verilator tests
        run: ./ci/scripts/run-verilator-tests.sh
      - name: Publish Bazel test results
        uses: ./.github/actions/publish-bazel-test-results
        if: ${{ !cancelled() }}
        with:
          artifact-name: verilator_earlgrey-test-results

  chip_earlgrey_cw340:
    name: Earl Grey for CW340
    needs: quick_lint
    uses: ./.github/workflows/bitstream.yml
    secrets: inherit
    with:
      top_name: earlgrey
      design_suffix: cw340

  cache_bitstreams:
    name: Cache bitstreams to GCP
    runs-on: ubuntu-22.04
    needs:
      - chip_earlgrey_cw340
    steps:
      - name: Skipped message
        if: ${{ github.event_name == 'pull_request' }}
        run: |
          echo ":information_source: Bitstream caching is skipped for this pull request job" \
            >> "$GITHUB_STEP_SUMMARY"
      - uses: actions/checkout@v6
        if: ${{ github.event_name != 'pull_request' }}
      - name: Prepare environment
        if: ${{ github.event_name != 'pull_request' }}
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
      - name: Download partial build-bin
        if: ${{ github.event_name != 'pull_request' }}
        uses: ./.github/actions/download-partial-build-bin
        with:
          job-patterns: chip_earlgrey_cw340
      - name: Create bitstream cache archive
        if: ${{ github.event_name != 'pull_request' }}
        run: |
          shopt -s globstar # Allow use of **
          ./bazelisk.sh build //util/py/scripts:bitstream_cache_create
          ./bazelisk.sh run //util/py/scripts:bitstream_cache_create -- \
            --schema $PWD/rules/scripts/bitstreams_manifest.schema.json \
            --stamp-file $PWD/bazel-out/volatile-status.txt \
            --out $PWD/build-bin/bitstream-cache \
            $PWD/build-bin/**/manifest.json
      - name: Upload bitstreams to GCP bucket
        if: ${{ github.event_name != 'pull_request' }}
        run: |
          BUCKET_URI=gs://opentitan-bitstreams/${{ github.ref_name }}
          printf "$(date -u +%Y-%m-%dT%H:%M:%S)\n${{ github.sha }}" > latest.txt
          gcloud storage cp build-bin/bitstream-cache/bitstream-cache.tar.gz $BUCKET_URI/bitstream-${{ github.sha }}.tar.gz
          gcloud storage cp latest.txt $BUCKET_URI/latest.txt
          gcloud storage cp $BUCKET_URI/bitstream-${{ github.sha }}.tar.gz $BUCKET_URI/bitstream-latest.tar.gz

  schedule_fpga_jobs:
    name: Schedule FPGA jobs
    runs-on: ubuntu-22.04
    if: ${{ github.event_name != 'merge_group' }}
    outputs:
      jobs_cw340: ${{ steps.schedule.outputs.jobs_cw340 }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # Required for the bitstream cache
      - name: Prepare environment
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
      - name: Compute job schedule
        id: schedule
        run: |
          jobs_dir=$(mktemp -d)
          echo "jobs_dir=$jobs_dir" >> "$GITHUB_OUTPUT"
          JOBS=$(./ci/scripts/schedule_fpga_jobs.py \
            --out-dir $jobs_dir/ \
            --test_tag_filters=-manual,-broken,-skip_in_ci,-slow_test,fpga \
            "tests(//sw/... union @manufacturer_test_hooks//...)")
          echo "$JOBS"
          echo 'jobs_cw340<<EOF' >> "$GITHUB_OUTPUT"
          echo "$JOBS" | jq '[.[] | select(.board == "cw340")]' >> "$GITHUB_OUTPUT"
          echo EOF >> "$GITHUB_OUTPUT"
      - name: Upload target files
        uses: actions/upload-artifact@v7
        with:
            name: fpga_jobs
            path: ${{ steps.schedule.outputs.jobs_dir }}

  execute_fpga_cw340_jobs:
    name: ${{ matrix.name }}
    needs:
      - schedule_fpga_jobs
      - quick_lint
      - chip_earlgrey_cw340
    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJSON(needs.schedule_fpga_jobs.outputs.jobs_cw340) }}
    uses: ./.github/workflows/fpga.yml
    if: ${{ github.event_name != 'merge_group' }}
    secrets: inherit
    with:
      job_name: ${{ matrix.id }}
      bitstream: chip_earlgrey_cw340
      board: ${{ matrix.board }}
      interface: cw340
      artifact: fpga_jobs
      target_file: ${{ matrix.target_file }}

  build_docker_containers:
    name: Build Docker Containers
    runs-on: ubuntu-22.04
    needs: quick_lint
    if: ${{ github.event_name != 'merge_group' }}
    steps:
      - uses: actions/checkout@v6
      - name: Build Developer Utility Container
        uses: docker/build-push-action@v7.0.0
        env:
          DOCKER_BUILD_SUMMARY: false
          DOCKER_BUILD_RECORD_UPLOAD: false
        with:
          context: .
          file: util/container/Dockerfile

  sw_build_test:
    name: Build and test software
    runs-on: ubuntu-22.04-vivado
    timeout-minutes: 120
    needs: quick_lint
    if: ${{ github.event_name != 'merge_group' }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # Required for bitstream cache to work.
      - name: Prepare environment
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
      - name: Check Bazel build graph
        run: |
          # Test the graph with both an empty and filled bitstream cache.
          ./ci/scripts/test-empty-bitstream-cache.sh
          ./bazelisk.sh build --nobuild //...
      - name: Select software targets
        run: |
          target_pattern_file="$(mktemp)"
          echo "target_pattern_file=${target_pattern_file}" >> "$GITHUB_ENV"

          # Start with building the whole graph.
          echo '//...' > "$target_pattern_file"
          # Exclude some targets:
          #
          # 1. `//hw/...` is out of scope.
          # 2. `//quality/...` is tested by the lint jobs.
          # 3. `//sw/otbn/crypto/...` is tested by the OTBN job.
          # 4. `//third_party/...` which is not our code.
          printf "%s\n"             \
            "-//hw/..."             \
            "-//quality/..."        \
            "-//sw/otbn/crypto/..." \
            "-//third_party/..."    \
            >> "$target_pattern_file"
          # Exclude anything that requires a bitstream splice.
          ./bazelisk.sh cquery                               \
            --noinclude_aspects                              \
            --output=starlark                                \
            --starlark:expr='"-{}".format(target.label)'     \
            --define DISABLE_VERILATOR_BUILD=true            \
            -- "rdeps(//..., kind(bitstream_splice, //...))" \
            >> "$target_pattern_file"
      - name: Build software targets
        run: |
          # Build everything we selected, excluding some tags.
          ./bazelisk.sh build                                \
            --remote_download_outputs=minimal                \
            --build_tests_only=false                         \
            --define DISABLE_VERILATOR_BUILD=true            \
            --test_tag_filters=-broken,-fpga,-verilator,-dv \
            --target_pattern_file="$target_pattern_file"
      - name: Run software unit tests
        run: |
          ./bazelisk.sh test                                          \
            --build_tests_only=true                                   \
            --test_output=errors                                      \
            --define DISABLE_VERILATOR_BUILD=true                     \
            --test_tag_filters=-broken,-fpga,-verilator,-dv,-silicon \
            --target_pattern_file="$target_pattern_file"
      - name: Publish Bazel test results
        uses: ./.github/actions/publish-bazel-test-results
        if: ${{ !cancelled() }}
        with:
          artifact-name: sw_build_test-test-results
      - name: Check for unrunnable tests
        run: ./ci/scripts/check-unrunnable-tests.sh
        continue-on-error: true

  dj_sw_build_test:
    name: Build and test Darjeeling software
    runs-on: ubuntu-22.04-vivado
    timeout-minutes: 120
    needs: quick_lint
    if: ${{ github.event_name != 'merge_group' }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # Required for bitstream cache to work.
      - name: Prepare environment
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
      - name: Check Bazel build graph
        run: |
          # Test the graph with both an empty and filled bitstream cache.
          ./ci/scripts/test-empty-bitstream-cache.sh
          ./bazelisk.sh build --nobuild --//hw/top=darjeeling //...
      - name: Build software targets
        run: |
          # Compile some selected targets
          ./bazelisk.sh build                                \
            --remote_download_outputs=minimal                \
            --build_tests_only=false                         \
            --//hw/top=darjeeling                            \
            //sw/device/tests/...

  qemu_smoketest:
    name: QEMU smoketest
    runs-on: ubuntu-22.04-vivado
    needs: quick_lint
    if: ${{ github.event_name != 'merge_group' }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - name: Prepare environment
        uses: ./.github/actions/prepare-env
        with:
          service_account_json: '${{ secrets.BAZEL_CACHE_CREDS }}'
      - name: Execute QEMU smoketest
        run: |
          ./bazelisk.sh test //sw/device/tests:rom_exit_immediately_sim_qemu_base

  # Single job that we can gate pull requests and merge queues on:
  merge_blocker:
    name: Merge blocker
    runs-on: ubuntu-latest
    needs: cache_bitstreams
    if: ${{ !cancelled() }}
    steps:
      - name: Complete
        run: ${{ needs.cache_bitstreams.result == 'success' }}