ci.yml

name: CI

on:
  push:
    branches: [ master, main ]
  pull_request:
    branches: [ master, main ]

jobs:
  build:
    runs-on: ubuntu-latest  # Standard runners: 2 cores, 7GB RAM
    strategy:
      matrix:
        os: [ubuntu-20.04, ubuntu-22.04, ubuntu-24.04]

    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      with:
        submodules: recursive

    - name: NAND media-layer unit tests
      run: |
        # Milliseconds, no QEMU build needed, so failures show up before the
        # 20-minute build rather than after it.
        make -C hw/femu/tests check

    - name: Install dependencies
      run: |
        sudo apt update
        sudo apt install -y build-essential pkg-config libglib2.0-dev \
          libpixman-1-dev libfdt-dev zlib1g-dev libaio-dev \
          libcap-ng-dev libattr1-dev ninja-build python3-pip \
          libslirp-dev libseccomp-dev libcurl4-gnutls-dev \
          libiscsi-dev libnfs-dev librbd-dev librados-dev \
          libssh-dev liblzo2-dev libsnappy-dev libbz2-dev \
          liblzma-dev libzstd-dev libgcrypt20-dev libgnutls28-dev \
          uuid-dev libcap-dev libxml2-dev libmount-dev \
          liburing-dev flex bison

    - name: Setup FEMU build environment
      run: |
        mkdir build-femu
        cd build-femu
        cp ../femu-scripts/femu-copy-scripts.sh .
        ./femu-copy-scripts.sh .

    - name: Build FEMU using official script
      run: |
        cd build-femu
        echo "GitHub Actions runner info:"
        echo "  Available CPU cores (nproc): $(nproc)"
        echo "  Available CPU cores (femu method): $(cat /proc/cpuinfo | grep "vendor_id" | wc -l)"
        echo "  Memory: $(free -h | grep '^Mem:' | awk '{print $2}')"
        echo ""
        echo "Starting parallel FEMU build at $(date)"
        time ./femu-compile.sh
        echo "Build completed at $(date)"

    - name: Run the FEMU unit tests through meson
      run: |
        cd build-femu
        # The same tests the standalone step ran, now built with QEMU's own
        # flags and headers, so a test that only passes against the stub
        # osdep.h is caught here.
        ./pyvenv/bin/meson test test-femu-nand-media test-femu-pqueue \
          --print-errorlogs

    - name: Verify FEMU device registration
      run: |
        cd build-femu
        ./qemu-system-x86_64 -device help | grep -q "femu" || exit 1
        echo "✓ FEMU device successfully registered"

    - name: Run basic functionality test
      run: |
        cd build-femu
        # The listing has to list something. Discarding the outcome meant this
        # step passed on an empty listing, or on no listing at all.
        out=$(timeout 10s ./qemu-system-x86_64 -device femu,help 2>&1 || true)
        echo "$out" | head -20
        for prop in femu_mode devsz_mb namespaces; do
          echo "$out" | grep -q "^  ${prop}=" || {
            echo "device help did not list ${prop}"; exit 1; }
        done
        echo "✓ FEMU device parameters accessible"

    - name: Check FEMU modes
      run: |
        cd build-femu
        # Every mode must come up. The process is expected to run until the
        # timeout kills it (124); any other exit is a failure. This used to
        # accept every outcome, which hid that an unprivileged runner could
        # not pin the memory backend and the device aborted in every mode.
        for mode in 0 1 2 3 4 5; do
          extra=""
          # computational storage refuses to start without a data memory size
          [ "$mode" -eq 4 ] && extra=",fdm_size=64"
          rc=0
          timeout 10s ./qemu-system-x86_64 \
            -device "femu,devsz_mb=1024,femu_mode=${mode},serial=test${mode}${extra}" \
            -nographic -M accel=qtest || rc=$?
          if [ "$rc" -ne 124 ] && [ "$rc" -ne 0 ]; then
            echo "mode ${mode} exited with ${rc}"; exit "$rc"
          fi
          echo "✓ FEMU mode ${mode} ran until timeout"
        done

    - name: Run the FEMU qtests
      run: |
        cd build-femu
        # Drives the controller through the doorbell registers alone and then
        # through the shadow doorbell buffer; neither needs KVM or a guest.
        QTEST_QEMU_BINARY=./qemu-system-x86_64 ./tests/qtest/qos-test -m quick \
          -p /x86_64/pc/i440FX-pcihost/pci-bus-pc/pci-bus/femu/femu-tests

    - name: Validate the config-file interface
      run: |
        chmod +x hw/femu/scripts/ssd-config.sh hw/femu/scripts/ssd-config-test.sh
        # Expands every example config and checks FEMU accepts the result, so a
        # property that is renamed or removed breaks here rather than in
        # somebody's run script. Carries its own negative control, so a check
        # that stopped detecting bad arguments fails instead of passing
        # everything. Runs here rather than in compatibility-test because that
        # job installs no dependencies, so the binary cannot start there.
        ./hw/femu/scripts/ssd-config-test.sh "$PWD/build-femu/qemu-system-x86_64"

    - name: Check the guest device test parses
      run: bash -n hw/femu/scripts/femu-test.sh

    - name: Archive build artifacts
      uses: actions/upload-artifact@v4
      if: success()
      with:
        name: femu-binary-${{ matrix.os }}
        path: |
          build-femu/qemu-system-x86_64
          build-femu/config-host.mak
          build-femu/run-*.sh
        retention-days: 7

  # A second build with the FTL's invariant checks compiled in and the address
  # and undefined-behaviour sanitizers on. In the normal build ftl_assert() is
  # empty, so a bound violation in the FTL corrupts state silently; here it
  # aborts, and so does a heap overrun in the controller.
  debug-build:
    runs-on: ubuntu-24.04

    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      with:
        submodules: recursive

    - name: Install dependencies
      run: |
        sudo apt update
        sudo apt install -y build-essential pkg-config libglib2.0-dev \
          libpixman-1-dev libfdt-dev zlib1g-dev libaio-dev \
          libcap-ng-dev libattr1-dev ninja-build python3-pip \
          libslirp-dev libseccomp-dev libcurl4-gnutls-dev \
          libssh-dev liblzo2-dev libsnappy-dev libbz2-dev \
          liblzma-dev libzstd-dev libgcrypt20-dev libgnutls28-dev \
          uuid-dev libcap-dev libxml2-dev libmount-dev \
          liburing-dev flex bison

    - name: Build with FTL asserts and sanitizers
      run: |
        mkdir build-debug
        cd build-debug
        ../configure --enable-kvm --target-list=x86_64-softmmu --enable-slirp \
          --disable-libnfs --disable-libiscsi --disable-curl \
          --enable-asan --enable-ubsan --extra-cflags=-DFEMU_FTL_ASSERT
        make -j "$(nproc)"

    - name: Run the FEMU unit tests under the sanitizers
      run: |
        cd build-debug
        ./pyvenv/bin/meson test test-femu-nand-media test-femu-pqueue \
          --print-errorlogs

    - name: Instantiate every mode with the checks armed
      env:
        # QEMU frees little at exit by design; only real errors should fail.
        ASAN_OPTIONS: detect_leaks=0
        UBSAN_OPTIONS: print_stacktrace=1:halt_on_error=1
      run: |
        cd build-debug
        # Plain `timeout` reports 124 whenever it had to signal the child, so a
        # child that dies of SIGABRT while handling SIGTERM -- an armed
        # assertion firing on the way out -- is indistinguishable from a clean
        # run. --preserve-status passes the child's own status through instead:
        # 143 is our SIGTERM, 0 is an early clean exit, and anything else, 134
        # for an abort above all, is a failure. The output is checked as well,
        # because a sanitizer reports without dying.
        for mode in 0 1 2 3 4 5; do
          extra=""
          # computational storage refuses to start without a data memory size
          [ "$mode" -eq 4 ] && extra=",fdm_size=64"
          rc=0
          timeout --preserve-status 20s ./qemu-system-x86_64 \
            -device "femu,devsz_mb=1024,femu_mode=${mode},serial=dbg${mode}${extra}" \
            -nographic -M accel=qtest > mode${mode}.log 2>&1 || rc=$?
          if [ "$rc" -ne 143 ] && [ "$rc" -ne 0 ]; then
            echo "mode ${mode} exited with ${rc}"; cat mode${mode}.log; exit 1
          fi
          if grep -qE "Sanitizer|runtime error:|Assertion.*failed" mode${mode}.log; then
            echo "mode ${mode} reported an error:"; cat mode${mode}.log; exit 1
          fi
          echo "mode ${mode} came up with the checks armed"
        done

    - name: Run the FEMU qtests under the sanitizers
      env:
        # abort_on_error is what makes a report a failure. Without it the
        # sanitizer prints the diagnosis and the test still says ok, which is
        # how a use-after-free on the queue-delete path went unnoticed.
        ASAN_OPTIONS: detect_leaks=0:abort_on_error=1
        UBSAN_OPTIONS: print_stacktrace=1:halt_on_error=1
      run: |
        cd build-debug
        # The same tests the release job runs, on a binary that reports a bad
        # access instead of continuing past it. This is what makes an
        # out-of-bounds index deterministic: without the sanitizers it lands
        # somewhere in the allocator and the test still passes.
        QTEST_QEMU_BINARY=./qemu-system-x86_64 ./tests/qtest/qos-test -m quick \
          -p /x86_64/pc/i440FX-pcihost/pci-bus-pc/pci-bus/femu/femu-tests

    - name: Expand every example config with the checks armed
      env:
        # QEMU builds without -fno-sanitize-recover, so an undefined-behaviour
        # report would otherwise print and let the process exit 0. The script
        # turns leak detection off itself: QEMU frees little at exit by design.
        UBSAN_OPTIONS: print_stacktrace=1:halt_on_error=1
      run: |
        chmod +x hw/femu/scripts/ssd-config.sh hw/femu/scripts/ssd-config-test.sh
        ./hw/femu/scripts/ssd-config-test.sh "$PWD/build-debug/qemu-system-x86_64"

  compatibility-test:
    runs-on: ubuntu-latest  # Standard runners
    needs: build
    if: success()

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Download build artifacts
      uses: actions/download-artifact@v4
      with:
        name: femu-binary-ubuntu-22.04
        path: build-femu/

    - name: Install the libraries the binary links against
      run: |
        # This job runs a binary built on another runner image and installed
        # nothing for it, so it could not load at all. Every step that ran it
        # discarded the outcome, so nothing said so. Install exactly what the
        # build job installs: the runtime libraries come with those packages,
        # and their own names differ between releases.
        sudo apt update
        sudo apt install -y build-essential pkg-config libglib2.0-dev \
          libpixman-1-dev libfdt-dev zlib1g-dev libaio-dev \
          libcap-ng-dev libattr1-dev ninja-build python3-pip \
          libslirp-dev libseccomp-dev libcurl4-gnutls-dev \
          libiscsi-dev libnfs-dev librbd-dev librados-dev \
          libssh-dev liblzo2-dev libsnappy-dev libbz2-dev \
          liblzma-dev libzstd-dev libgcrypt20-dev libgnutls28-dev \
          uuid-dev libcap-dev libxml2-dev libmount-dev \
          liburing-dev flex bison

    - name: Make binary executable
      run: chmod +x build-femu/qemu-system-x86_64

    - name: Check the binary can run at all
      run: |
        cd build-femu
        # Everything below runs this binary. If it cannot load its libraries,
        # say so here rather than in the middle of a device test.
        ./qemu-system-x86_64 --version

    - name: Test run scripts syntax
      run: |
        cd build-femu
        # Check syntax of run scripts (already copied by build job)
        for script in run-*.sh; do
          bash -n "$script"
          echo "✓ $script syntax check passed"
        done

    - name: Validate FEMU configuration parameters
      run: |
        cd build-femu
        # A geometry the device refuses has to fail this step. Backgrounding
        # the process, sleeping and killing it reported success whether or not
        # the device ever realized. As above, the timeout killing it (124) is
        # the expected outcome and anything else is a failure.
        # femu_mode=1 so the geometry is the black-box FTL's and actually
        # gets checked; the default mode ignores it entirely.
        # The artifact is the binary alone. It finds its firmware through a
        # link tree in the build directory that is not part of the artifact,
        # so name the images in the source this job checks out; without that
        # it cannot start a machine at all.
        rc=0
        timeout 10s ./qemu-system-x86_64 -L "$GITHUB_WORKSPACE/pc-bios" \
          -device femu,devsz_mb=2048,femu_mode=1,secsz=512,secs_per_pg=8,pgs_per_blk=256 \
          -M accel=qtest -nographic || rc=$?
        if [ "$rc" -ne 124 ] && [ "$rc" -ne 0 ]; then
          echo "the device did not accept the geometry (exit ${rc})"; exit "$rc"
        fi
        echo "✓ FEMU SSD parameter validation completed"

  code-quality:
    runs-on: ubuntu-latest  # Lightweight job, standard runner sufficient

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Check code style
      run: |
        # Check for trailing whitespace in FEMU source files
        ! find hw/femu -name "*.c" -o -name "*.h" | xargs grep -l '[[:space:]]$'
        echo "✓ No trailing whitespace found"

        # Check for C++ style comments in C files
        ! find hw/femu -name "*.c" -o -name "*.h" | xargs grep '//'
        echo "✓ No C++ style comments found in C files"

    - name: Check build system consistency
      run: |
        # Verify FEMU is properly integrated in build system
        grep -q "config FEMU_PCI" hw/femu/Kconfig
        grep -q "source femu/Kconfig" hw/Kconfig
        echo "✓ Build system integration verified"

    - name: Validate documentation
      run: |
        # Check that README references are valid
        [ -f "README.md" ] && echo "✓ README.md exists"
        [ -d "hw/femu" ] && echo "✓ FEMU source directory exists"
        [ -f "hw/femu/meson.build" ] && echo "✓ FEMU meson.build exists"