litex

name: ci

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-22.04
    # Four-way test split: each shard installs LiteX once and runs a
    # quarter of the test suite with pytest-xdist `-n auto` on top. On a
    # 4-core runner that means 16 effective workers across the four shards.
    # test_integration's ~30 parametrized boot tests — which dominate
    # wall-clock — end up ~7-8 per shard instead of ~30, roughly quartering
    # the test phase. No cross-job orchestration needed (no artifact,
    # shared state only via the Verilator / OSS CAD Suite caches).
    strategy:
      fail-fast: false
      matrix:
        group: [1, 2, 3, 4]
    steps:
      # Checkout Repository
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup CCache
        uses: hendrikmuhs/ccache-action@v1.2

      # Install Tools
      - name: Install Tools
        run: |
          sudo apt-get install wget build-essential ninja-build help2man
          sudo apt-get install libevent-dev libjson-c-dev flex bison
          sudo apt-get install libfl-dev libfl2 zlib1g-dev

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.9"
          cache: "pip"
          cache-dependency-path: "setup.py"

      - name: Install Python dependencies
        run: |
          python3 -m pip install setuptools requests pexpect meson pytest pytest-xdist pytest-split

      # Install (n)Migen / LiteX / Cores
      - name: Install LiteX
        run: |
          python3 litex_setup.py --config=full --init --install --user --dev

      # Install GCC Toolchains (cached). The four packages below are what
      # `litex_setup.py --gcc={riscv,openrisc,powerpc}` resolves to on
      # Ubuntu — bypass litex_setup here so the cache action can see the
      # concrete package list and handle restore. On cache hit the .debs
      # are replayed from cache; on miss apt install runs and repopulates.
      - name: Install GCC Toolchains
        uses: awalsh128/cache-apt-pkgs-action@v1
        with:
          packages: gcc-riscv64-unknown-elf gcc-or1k-elf gcc-powerpc64le-linux-gnu binutils-multiarch
          version: 1.0

      # Cache OSS CAD Suite (keyed on pinned release version — cache hit
      # skips the ~500 MB download from the YosysHQ release bucket).
      - name: Cache OSS CAD Suite
        id: oss-cache
        uses: actions/cache@v4
        with:
          path: ~/oss-cad-suite
          key: oss-cad-suite-2025-05-30-ubuntu22

      # Install OSS CAD Suite (only on cache miss). Direct curl to $HOME —
      # deterministic install path, no tool-cache indirection.
      - name: Install OSS CAD Suite
        if: steps.oss-cache.outputs.cache-hit != 'true'
        run: |
          URL="https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2025-05-30/oss-cad-suite-linux-x64-20250530.tgz"
          curl -fsSL "$URL" | tar xz -C "$HOME"

      # Forward OSS CAD Suite env (PATH / LD_LIBRARY_PATH / GHDL_PREFIX / etc.)
      # to subsequent steps. Runs whether cache hit or miss.
      - name: Export OSS CAD Suite env
        run: |
          source "$HOME/oss-cad-suite/environment"
          {
            echo "PATH=$PATH"
            for v in LD_LIBRARY_PATH PKG_CONFIG_PATH GHDL_PREFIX PY_VCD_PATH YOSYSHQ_ROOT; do
              if [ -n "${!v:-}" ]; then
                echo "$v=${!v}"
              fi
            done
          } >> "$GITHUB_ENV"

#      # Build / Install GHDL
#      - name: Build GHDL
#        run: |
#          sudo apt-get install gnat llvm
#          git clone https://github.com/ghdl/ghdl.git
#          cd ghdl
#          git checkout 1fc1bccd1a7c256c531bdd6dc8f9641f90eb8ea0
#          ./configure --with-llvm-config
#          make
#          sudo make install

      # Cache Verilator install (keyed on pinned commit SHA — cache hit
      # skips the ~15 min build. Bumping the SHA invalidates the cache).
      - name: Cache Verilator install
        id: verilator-cache
        uses: actions/cache@v4
        with:
          path: /tmp/verilator-install
          key: verilator-ubuntu22-7d2d32420a630befa4097170ecbf227e04e32522

      # Build / Install Verilator (only on cache miss). `--prefix` under /tmp
      # so the install tree is a self-contained cacheable directory.
      - name: Build Verilator
        if: steps.verilator-cache.outputs.cache-hit != 'true'
        run: |
          export PATH="/usr/lib/ccache:/usr/local/opt/ccache/libexec:$PATH"
          git clone https://github.com/verilator/verilator
          cd verilator
          git checkout 7d2d32420a630befa4097170ecbf227e04e32522
          autoconf
          ./configure --prefix=/tmp/verilator-install
          make -j$(nproc)
          make install

      # Copy verilator (cached or freshly built) into the standard location.
      - name: Install Verilator into /usr/local
        run: sudo cp -a /tmp/verilator-install/. /usr/local/

      # Install Project
      - name: Install Project
        run: python3 setup.py develop --user

      # Generate .test_durations so pytest-split's least_duration algorithm
      # can pack shards optimally (longest tests first, fill remaining
      # capacity with small tests). The alternative was a committed JSON
      # with one entry per test — it would rot every time a test was added
      # or renamed. Instead we emit it fresh each run from a tiny per-CPU
      # duration table. Unknown CPUs default to a medium cost so new
      # additions to TESTED_CPUS don't break balancing — they just aren't
      # optimally placed until added here.
      - name: Generate .test_durations
        run: |
          python3 - <<'PY'
          import json, subprocess
          out = subprocess.check_output(
              ["python3", "-m", "pytest", "--collect-only", "-q"]
          ).decode()
          tests = [l.strip() for l in out.splitlines()
                   if l.startswith("test/") and "::" in l]
          # Rough per-CPU boot-time estimates (seconds). Order of magnitude
          # matters more than precision — least_duration only uses these
          # to rank. Refine from `--durations=0` log output if desired.
          BOOT_TIMES = {
              "femtorv":      60, "firev":        60, "serv":         45,
              "sentinel":    120, "minerva":     120, "marocchino":  120,
              "vexriscv":    120, "neorv32":     150, "ibex":        150,
              "naxriscv":    240, "vexiiriscv":  240, "vexriscv_smp":360,
          }
          d = {}
          for t in tests:
              if "::test_cpu[" in t:
                  cpu = t.split("[", 1)[1].rstrip("]")
                  d[t] = float(BOOT_TIMES.get(cpu, 120))
              elif "::test_buses[" in t:
                  d[t] = 100.0  # same default CPU, different bus cfg
              else:
                  d[t] = 1.0    # in-process Migen sims are near-instant
          with open(".test_durations", "w") as f:
              json.dump(d, f, indent=2, sort_keys=True)
          print(f"generated .test_durations for {len(d)} tests")
          PY

      # Test: pytest-xdist `-n auto` distributes across the runner's 4
      # cores inside each shard; pytest-split `--splits 4 --group N`
      # distributes across the four matrix shards using the .test_durations
      # generated above. `--durations=0` logs every test's runtime — use
      # it to refine the BOOT_TIMES table above if the shards are uneven.
      - name: Run Tests (shard ${{ matrix.group }}/4)
        run: |
          python3 -m pytest -v -n auto --durations=0 \
            --splits 4 --group ${{ matrix.group }} \
            --splitting-algorithm least_duration