open-standards/.github/workflows/wai-quantum-fpga.yml

name: wai-quantum FPGA member

# The fabric's FPGA member, simulated: the gate datapath in Verilog, compiled at
# run time by Verilator into a cycle-accurate simulation and certified
# bit-exact against the CPU reference's pinned corpus digests. Its certificates
# say they were earned in a simulator.
#
# - fpga-sim (the macOS runner, which has Verilator and Yosys): the device
#   tests must find exactly the declared simulation, agree with the CPU on the
#   arithmetic probe and on random states (out-of-range runs included),
#   reproduce all four pinned certificates, and catch every datapath mutant;
#   and the datapath must elaborate for synthesis with no latch and no check
#   failure.
# - fpga-absent (a container with no Verilator): the same build finds no member
#   and says why, rather than failing; the device tests run over no member with
#   the declaration `none`.

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

on:
  push:
    branches: [main]
    paths:
      - 'wai/wai-quantum/**'
      - 'rust-toolchain.toml'
      - '.github/workflows/wai-quantum-fpga.yml'
  pull_request:
    paths:
      - 'wai/wai-quantum/**'
      - 'rust-toolchain.toml'
      - '.github/workflows/wai-quantum-fpga.yml'

jobs:
  # Does this pull request's own diff touch the paths below? This forge matches a
  # workflow's `paths:` against the push, so a merge of main into a branch fires the
  # workflow whatever the pull request changes; every job here waits on this answer.
  # A push to main, a schedule, or anything the script cannot determine answers
  # `true` (scripts/pr-touches-paths.py).
  relevant:
    name: does this change touch it
    runs-on: linux-arm64
    outputs:
      run: ${{ steps.gate.outputs.run }}
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - id: gate
        run: |
          set -euo pipefail
          r=$(python3 scripts/pr-touches-paths.py .github/workflows/wai-quantum-fpga.yml \
                "${{ github.event.pull_request.base.sha }}" \
                "${{ github.event.pull_request.head.sha }}")
          echo "this change touches wai-quantum-fpga: $r"
          echo "run=$r" >> "$GITHUB_OUTPUT"

  fpga-sim:
    name: member · FPGA datapath, simulated (macos)
    needs: relevant
    if: needs.relevant.outputs.run == 'true'
    runs-on: macos
    timeout-minutes: 90
    env:
      WAI_QUANTUM_FPGA_EXPECT: fpga-sim-verilator
    steps:
      - uses: actions/checkout@v5
      # launchd's PATH omits cargo and the package manager's tools on the macOS
      # host runner.
      - name: Put cargo and the simulator on PATH
        shell: bash
        run: |
          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
          echo "/opt/homebrew/bin" >> "$GITHUB_PATH"
      - name: The datapath elaborates for synthesis
        shell: bash
        working-directory: wai/wai-quantum/src/quantum_fabric
        run: |
          set -euo pipefail
          yosys -p 'read_verilog lanes64.v; chparam -set AW 6 wq_lanes64; hierarchy -top wq_lanes64; proc; flatten; opt; memory -nomap; check -assert; stat' 2>&1 | tee "$RUNNER_TEMP/yosys.log"
          ! grep -q 'Latch inferred' "$RUNNER_TEMP/yosys.log" || { echo "::error::the datapath infers a latch"; exit 1; }
          grep -qE '^ +68 +\$mul$' "$RUNNER_TEMP/yosys.log" || { echo "::error::the datapath is not 17 products of four 16-bit partials"; exit 1; }
      - name: The member's unit tests
        shell: bash
        working-directory: wai/wai-quantum
        run: |
          set -euo pipefail
          nice -n 10 cargo test --locked --features quantum_fabric_fpga --lib -- quantum_fabric_fpga:: quantum_fabric::fpga:: 2>&1 | tee "$RUNNER_TEMP/unit.log"
          grep -qE '^test result: ok\. [1-9][0-9]* passed; 0 failed' "$RUNNER_TEMP/unit.log" || { echo "::error::no unit test ran"; exit 1; }
      - name: The member's device tests
        shell: bash
        working-directory: wai/wai-quantum
        run: |
          set -euo pipefail
          report="$RUNNER_TEMP/fpga-report.txt"; : > "$report"
          export WAI_QUANTUM_FPGA_CACHE="$RUNNER_TEMP/fpga-cache"
          WAI_QUANTUM_FPGA_REPORT="$report" nice -n 10 \
            cargo test --locked --release --features quantum_fabric_fpga --test fpga_member -- --test-threads=1 2>&1 | tee "$RUNNER_TEMP/device.log"
          grep -qE '^test result: ok\. 9 passed; 0 failed' "$RUNNER_TEMP/device.log" || { echo "::error::not every device test ran and passed"; exit 1; }
          cat "$report"
          key="$WAI_QUANTUM_FPGA_EXPECT"
          grep -qx "fpga devices: as declared ($key)" "$report" || { echo "::error::the simulation found is not the declared one"; exit 1; }
          n="$(grep -c "^fpga certified: key=$key .* parity=bit-exact provenance=simulator:verilator " "$report")"
          [ "$n" = 4 ] || { echo "::error::$n of 4 certificates were earned"; exit 1; }
          grep -qx "fpga mutants: key=$key killed 6 of 6" "$report" || { echo "::error::a datapath mutant survived"; exit 1; }

  fpga-absent:
    name: member · FPGA simulation absent (linux)
    needs: relevant
    if: needs.relevant.outputs.run == 'true'
    runs-on: linux
    timeout-minutes: 60
    env:
      WAI_QUANTUM_FPGA_EXPECT: none
    steps:
      - uses: actions/checkout@v5
      - name: Install Rust 1.98.0
        shell: bash
        run: |
          export PATH="$HOME/.cargo/bin:$PATH"
          command -v rustup >/dev/null 2>&1 || \
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain 1.98.0
          rustup toolchain install 1.98.0 --profile minimal
          rustup default 1.98.0
          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
      - name: No simulator here, and the member says so
        shell: bash
        working-directory: wai/wai-quantum
        run: |
          set -euo pipefail
          ! command -v verilator >/dev/null || { echo "::error::this container has Verilator; the absent case needs one without"; exit 1; }
          report="$RUNNER_TEMP/fpga-report.txt"; : > "$report"
          WAI_QUANTUM_FPGA_REPORT="$report" cargo test --locked --features quantum_fabric_fpga --test fpga_member -- --test-threads=1 2>&1 | tee "$RUNNER_TEMP/device.log"
          grep -qE '^test result: ok\. 9 passed; 0 failed' "$RUNNER_TEMP/device.log" || { echo "::error::not every device test ran and passed"; exit 1; }
          grep -qx 'fpga devices: as declared (none)' "$report" || { echo "::error::the absent case was not established"; exit 1; }