test(dispatch): Add a link probe that checks the dispatch surface

.github/scripts/check_dispatch_surface.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+# Copyright 2025 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Runs cmake/validate-dispatch-surface.cmake over the fixtures in
+# tests/cmake/dispatch-surface and checks each verdict.
+#
+#   valid-*.cmake    must be accepted.
+#   invalid-*.cmake  must be rejected, with a message containing the substring
+#                    given by that fixture's `# EXPECT-ERROR:` line.
+#
+# Needs nothing but cmake -- no compiler, no dependencies, no build directory.
+
+set -uo pipefail
+
+root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
+fixtures="${root}/tests/cmake/dispatch-surface"
+validator="${root}/cmake/validate-dispatch-surface.cmake"
+x86_src_dir="${root}/include/svs/multi-arch/x86"
+
+if [[ ! -d ${fixtures} ]]; then
+    echo "no fixture directory: ${fixtures}" >&2
+    exit 1
+fi
+
+# The default declaration must itself be valid -- checked as its own case so that
+# a broken default is reported here rather than only at configure time.
+run_validator() {
+    cmake "-DSVS_DISPATCH_SURFACE_FILE=$1" "-DSVS_X86_SRC_DIR=${x86_src_dir}" \
+        -P "${validator}" 2>&1
+}
+
+# CMake indents and line-wraps error text, so compare against a whitespace-
+# collapsed copy of the output.
+flatten() { tr '\n' ' ' | tr -s '[:space:]' ' '; }
+
+failures=0
+checked=0
+
+check_accepted() {
+    local fixture=$1 name=$2 output status
+    output=$(run_validator "${fixture}")
+    status=$?
+    if ((status != 0)); then
+        echo "FAIL ${name}: expected to be accepted, but validation failed:" >&2
+        echo "${output}" | sed 's/^/    /' >&2
+        ((failures++))
+    else
+        echo "ok   ${name}: accepted"
+    fi
+    ((checked++))
+}
+
+check_rejected() {
+    local fixture=$1 name=$2 expected output status
+    expected=$(sed -n 's/^# EXPECT-ERROR: *//p' "${fixture}")
+    if [[ -z ${expected} ]]; then
+        echo "FAIL ${name}: fixture has no '# EXPECT-ERROR:' line" >&2
+        ((failures++))
+        ((checked++))
+        return
+    fi
+
+    output=$(run_validator "${fixture}")
+    status=$?
+    if ((status == 0)); then
+        echo "FAIL ${name}: expected rejection, but validation succeeded" >&2
+        ((failures++))
+    elif [[ $(printf '%s' "${output}" | flatten) != *"${expected}"* ]]; then
+        echo "FAIL ${name}: rejected, but not for the stated reason." >&2
+        echo "    expected: ${expected}" >&2
+        echo "${output}" | sed 's/^/    actual:   /' >&2
+        ((failures++))
+    else
+        echo "ok   ${name}: rejected (${expected})"
+    fi
+    ((checked++))
+}
+
+check_accepted "${root}/cmake/dispatch-surface.cmake" "dispatch-surface.cmake (default)"
+
+for fixture in "${fixtures}"/*.cmake; do
+    name=$(basename "${fixture}")
+    case ${name} in
+    valid-*) check_accepted "${fixture}" "${name}" ;;
+    invalid-*) check_rejected "${fixture}" "${name}" ;;
+    *)
+        echo "FAIL ${name}: fixture name must start with valid- or invalid-" >&2
+        ((failures++))
+        ((checked++))
+        ;;
+    esac
+done
+
+echo
+if ((failures != 0)); then
+    echo "${failures} of ${checked} dispatch-surface checks failed" >&2
+    exit 1
+fi
+echo "all ${checked} dispatch-surface checks passed"

.github/workflows/dispatch-surface.yml

@@ -0,0 +1,106 @@
+# Copyright 2025 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# The set of distance kernels compiled ahead of time is declared once, in
+# cmake/dispatch-surface.cmake, and generated from there. Two things have to stay
+# true for that to be worth anything: the declaration must be checked rather than
+# trusted, and it must be genuinely configurable -- a knob nobody turns is a knob
+# that quietly stops working.
+
+name: Dispatch Surface
+
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  declaration:
+    name: declaration is checked, committed header is current
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v6
+
+    # Every fixture in tests/cmake/dispatch-surface, plus the default
+    # declaration. Needs nothing but cmake.
+    - name: Accept and reject declarations
+      run: .github/scripts/check_dispatch_surface.sh
+
+    # include/svs/core/distance/dispatch_surface.h is generated but committed, so
+    # that a bare `-I include` compile works without cmake. A configure refreshes
+    # it; if that produces a diff, either the declaration changed without a
+    # reconfigure or the header was edited by hand.
+    - name: Configure with the default surface
+      run: |
+        cmake -B "${{ runner.temp }}/build" -S "${GITHUB_WORKSPACE}" \
+              -DCMAKE_BUILD_TYPE=Release \
+              -DSVS_BUILD_TESTS=NO \
+              -DSVS_BUILD_BINARIES=NO
+
+    - name: Committed header matches the declaration
+      run: |
+        if ! git diff --exit-code -- include/svs/core/distance/dispatch_surface.h; then
+            echo "::error::include/svs/core/distance/dispatch_surface.h is stale." \
+                 "It is generated from cmake/dispatch-surface.cmake -- re-run cmake" \
+                 "and commit the result. Do not edit it by hand."
+            exit 1
+        fi
+
+  non-default-surface:
+    name: builds and tests with a non-default surface
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v6
+
+    # valid-reduced.cmake shares no extent with the default declaration, so a
+    # build that silently fell back to the committed header would fail to
+    # compile rather than pass by accident.
+    - name: Configure
+      run: |
+        cmake -B "${{ runner.temp }}/build" -S "${GITHUB_WORKSPACE}" \
+              -DCMAKE_BUILD_TYPE=Release \
+              -DSVS_BUILD_TESTS=YES \
+              -DSVS_BUILD_BINARIES=NO \
+              -DSVS_DISPATCH_SURFACE_FILE="${GITHUB_WORKSPACE}/tests/cmake/dispatch-surface/valid-reduced.cmake"
+
+    - name: Build
+      working-directory: ${{ runner.temp }}/build
+      run: make -j$(nproc)
+
+    # Correctness must not depend on which extents have a fixed-extent kernel:
+    # an extent without one is served by the svs::Dynamic kernel instead. The
+    # long-running tests are covered by the default-surface build.
+    - name: Run tests
+      env:
+        CTEST_OUTPUT_ON_FAILURE: 1
+      working-directory: ${{ runner.temp }}/build/tests
+      run: ctest -C Release -LE long
+
+    # Overriding the surface for one build must not rewrite the committed header.
+    - name: Committed header was left alone
+      run: |
+        if ! git diff --exit-code -- include/svs/core/distance/dispatch_surface.h; then
+            echo "::error::A build with an overridden dispatch surface rewrote the" \
+                 "committed header. Only the default declaration may refresh it."
+            exit 1
+        fi

.pre-commit-config.yaml

@@ -34,3 +34,14 @@ repos:
         args: [--markdown-linebreak-ext=md]
         exclude: .*\.svg$
       - id: mixed-line-ending
+
+  - repo: local
+    hooks:
+      # Cheap enough to run on every touch of the declaration, and it needs
+      # nothing but cmake -- no compiler, no build directory.
+      - id: dispatch-surface
+        name: dispatch surface declaration
+        entry: .github/scripts/check_dispatch_surface.sh
+        language: script
+        pass_filenames: false
+        files: ^(cmake/(dispatch-surface|validate-dispatch-surface)\.cmake|tests/cmake/dispatch-surface/.*\.cmake|\.github/scripts/check_dispatch_surface\.sh)$

cmake/check-dispatch-linkage.cmake

@@ -0,0 +1,163 @@
+# Copyright 2025 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+#####
+##### Checks the dispatch surface against the symbols that were actually built.
+#####
+##### Run in script mode:
+#####
+#####   cmake -DSVS_PROBE_OBJECT=<link_probe.cpp.o> \
+#####         -DSVS_ARCHIVE=<libsvs_x86_objects.a> \
+#####         -DSVS_NM=<nm> \
+#####         -P cmake/check-dispatch-linkage.cmake
+#####
+##### The probe object names every kernel the surface declares and nothing else
+##### (see tests/multi-arch/x86/link_probe.cpp), so the kernels it *references*
+##### are exactly the kernels the archive must *define* -- and it must define no
+##### others. Both directions are checked, plus that the probe defines none of
+##### its own.
+#####
+
+foreach(required SVS_PROBE_OBJECT SVS_ARCHIVE SVS_NM)
+    if(NOT ${required})
+        message(FATAL_ERROR "${required} is not set.")
+    endif()
+endforeach()
+foreach(required SVS_PROBE_OBJECT SVS_ARCHIVE)
+    if(NOT EXISTS "${${required}}")
+        message(FATAL_ERROR "${required} does not exist: ${${required}}")
+    endif()
+endforeach()
+
+# Distance kernels, and nothing else in the archive. Mangled names are used
+# throughout: demangled ones carry `[clone .isra.0]` suffixes that differ between
+# a local instantiation and an explicit one.
+set(svs_kernel_regex "_ZN3svs8distance.*Impl")
+
+# Returns the mangled names of the matching symbols, one per list element.
+function(svs_symbols out_var)
+    cmake_parse_arguments(arg "" "FILE" "NM_ARGS" ${ARGN})
+    execute_process(
+        COMMAND "${SVS_NM}" ${arg_NM_ARGS} "${arg_FILE}"
+        OUTPUT_VARIABLE raw
+        ERROR_VARIABLE err
+        RESULT_VARIABLE status
+    )
+    if(NOT status EQUAL 0)
+        message(FATAL_ERROR "${SVS_NM} failed on ${arg_FILE}: ${err}")
+    endif()
+
+    set(symbols)
+    string(REPLACE "\n" ";" lines "${raw}")
+    foreach(line IN LISTS lines)
+        if(line MATCHES "${svs_kernel_regex}")
+            # The mangled name is the last whitespace-separated field.
+            string(REGEX MATCH "[^ \t]+$" symbol "${line}")
+            list(APPEND symbols "${symbol}")
+        endif()
+    endforeach()
+    list(REMOVE_DUPLICATES symbols)
+    list(SORT symbols)
+    set(${out_var} "${symbols}" PARENT_SCOPE)
+endfunction()
+
+# Shows up to `limit` entries of a list. The names stay mangled -- pipe them
+# through c++filt to read them.
+function(svs_report_symbols symbols limit)
+    list(LENGTH symbols count)
+    set(shown ${symbols})
+    if(count GREATER limit)
+        list(SUBLIST shown 0 ${limit} shown)
+    endif()
+    foreach(symbol IN LISTS shown)
+        message("      ${symbol}")
+    endforeach()
+    if(count GREATER limit)
+        math(EXPR rest "${count} - ${limit}")
+        message("      ... and ${rest} more")
+    endif()
+endfunction()
+
+svs_symbols(probe_defines FILE "${SVS_PROBE_OBJECT}" NM_ARGS --defined-only)
+svs_symbols(probe_references FILE "${SVS_PROBE_OBJECT}" NM_ARGS --undefined-only)
+svs_symbols(archive_defines FILE "${SVS_ARCHIVE}" NM_ARGS --defined-only)
+
+list(LENGTH probe_defines n_probe_defines)
+list(LENGTH probe_references n_probe_references)
+list(LENGTH archive_defines n_archive_defines)
+
+set(errors 0)
+
+# A probe that names nothing is not a passing probe. This is what an LTO build
+# looks like here, since the object holds IR rather than symbols.
+if(n_probe_references EQUAL 0 AND n_probe_defines EQUAL 0)
+    message("${SVS_PROBE_OBJECT} names no distance kernels at all.")
+    message("Nothing can be concluded from it. If this is a link-time-optimized")
+    message("build, nm cannot see the symbols and this check does not apply.")
+    message(FATAL_ERROR "dispatch linkage check found no symbols to check")
+endif()
+
+# The probe compiles at -march=x86-64 and guarantees nothing about the host, so a
+# kernel it defines itself is a kernel some other consumer would also define
+# itself -- at whatever -march that consumer happens to use.
+if(NOT n_probe_defines EQUAL 0)
+    message("${n_probe_defines} kernels are instantiated by the probe itself.")
+    message("Each is missing its `extern template` declaration, so every consumer")
+    message("of the headers instantiates it locally, from the generic primary")
+    message("template, at the consumer's own -march. Declare them: the extern")
+    message("blocks in the distance headers must cover the whole surface.")
+    message("    Instantiated locally:")
+    svs_report_symbols("${probe_defines}" 10)
+    math(EXPR errors "${errors} + 1")
+endif()
+
+# Declared but never instantiated. The link should already have failed, so this
+# only fires when the object is inspected without being linked.
+set(missing ${probe_references})
+if(archive_defines)
+    list(REMOVE_ITEM missing ${archive_defines})
+endif()
+list(LENGTH missing n_missing)
+if(NOT n_missing EQUAL 0)
+    message("${n_missing} kernels are declared but never instantiated.")
+    message("They are declared `extern template` in the distance headers but no")
+    message("translation unit defines them, so linking against the library fails.")
+    message("    Undefined:")
+    svs_report_symbols("${missing}" 10)
+    math(EXPR errors "${errors} + 1")
+endif()
+
+# Instantiated but unreachable through the surface: dead weight in the archive.
+set(unreachable ${archive_defines})
+if(probe_references)
+    list(REMOVE_ITEM unreachable ${probe_references})
+endif()
+list(LENGTH unreachable n_unreachable)
+if(NOT n_unreachable EQUAL 0)
+    message("${n_unreachable} kernels are instantiated but are not part of the")
+    message("dispatch surface. Nothing declares them, so no consumer reaches")
+    message("them; they only add to the size of the library.")
+    message("    Unreachable:")
+    svs_report_symbols("${unreachable}" 10)
+    math(EXPR errors "${errors} + 1")
+endif()
+
+if(NOT errors EQUAL 0)
+    message(FATAL_ERROR "dispatch linkage check failed")
+endif()
+
+message(
+    "dispatch linkage: ${n_archive_defines} kernels declared, instantiated and "
+    "reachable; none instantiated by the consumer"
+)