refactor(dispatch): Generate the dispatch surface from a single declaration

[ahuber21]

The set of distance kernels compiled ahead of time -- extents x ISA levels -- was
written out by hand everywhere it was needed: three extern template blocks,
two per-architecture translation units, and supported_dim_list. Adding an
extent meant editing six lists in agreement, and the preceding commit is what
happens when one of them disagrees.

cmake/dispatch-surface.cmake is now the only place the extent list and the ISA
levels are written down. Everything else is derived from it:

• include/svs/core/distance/dispatch_surface.h, which drives every
  extern template, every explicit instantiation, and supported_dim_list
• the object library each level's translation unit is compiled into, and the
  instruction budget it is compiled at

The generated header is committed as well as generated, so that consuming the
headers with a bare -I include and no CMake keeps working.

Configure now prints the surface in full rather than a count -- every extent,
and for each level its enumerator, its instruction budget and its translation
unit:

-- Dispatch surface: 9 extents x 2 ISA levels
--   extents: 64 96 100 128 160 200 512 768 svs::Dynamic
--   level:   AVX_AVAILABILITY::AVX2 -march=haswell avx2.cpp
--   level:   AVX_AVAILABILITY::AVX512 -march=cascadelake avx512.cpp
--   not in the surface: NONE
--            dispatched to, but compiled by no translation unit, so every
--            consumer instantiates those kernels itself, at its own -march

AVX_AVAILABILITY::NONE is a real hole and is now named as one: the entry points
fall back to it, no translation unit compiles it, so every consumer builds those
kernels itself at whatever -march it happens to use. A baseline translation
unit is its own change, not this one.

Seven ctest tests replace what was a paragraph of nm commands in a review
comment. All of them derive their expectations from the declaration, so they hold
for an overridden surface too:

• dispatch_surface_probe, dispatch_entry_probe -- consumers built at
  -march=x86-64. One names every kernel in the surface directly, the other
  reaches them through the entry points; a declared-but-uninstantiated kernel is
  an undefined symbol in the first, and a kernel the entry points cannot reach is
  one in the second.
• dispatch_surface_linkage -- the archive defines every kernel the probe names,
  nothing more, and the probe instantiated none of them itself: 864 kernels.
• dispatch_surface_declaration -- the same 864, but counted from the three
  hand-written sources (the extent list, the type-pair macros, the enumerator
  order) without consulting the generated header, so a generator bug has nowhere
  to hide: 2 levels x 9 extents x 3 distances x {AVX2: 16, AVX512: 16} pairs.
• dispatch_instructions_avx2, dispatch_instructions_avx512 -- one per level,
  disassembling that level's object file against the instruction budget its
  runtime predicate promises. The AVX2 object must contain ymm and no zmm,
  mask or VNNI encodings; a level that emits what its predicate does not
  guarantee is an illegal-instruction fault on a host the dispatcher considers
  supported, which no symbol-table check can see.
• dispatch_surface_execution -- the only check that observes a run rather than
  a symbol table: gdb breaks on every level's kernel for one extent and reports
  which one a call through the entry points actually enters. A specialization
  that disappears behind an #if still links and still counts.

No behaviour change: the same 864 kernels, at the same instruction budgets, with
the same mangled names. compute() is still compute(); nothing about the call
chain or the runtime dispatch moves.

Part 2 of 4 of the ISA dispatching v2 milestone.

[ahuber21]

@copilot new or modified files should have 2026 in their copyright header. Fix

[Copilot]

@copilot new or modified files should have 2026 in their copyright header. Fix

Updated the headers in 408513c.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[Copilot]

Pull request overview

Centralizes x86 distance-kernel extents and ISA levels into one generated dispatch declaration.

Changes:

• Generates kernel declarations, instantiations, and supported dimensions from one CMake surface.
• Adds linkage, instruction, declaration, and runtime dispatch checks.
• Installs the generated header and documents maintenance workflows.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
CMakeLists.txt	Installs the generated surface header.
cmake/AGENTS.md	Documents dispatch ownership.
cmake/dispatch-surface.cmake	Declares extents and ISA levels.
cmake/generate-dispatch-surface.cmake	Validates and generates the surface.
cmake/multi-arch.cmake	Builds ISA objects from the declaration.
cmake/templates/dispatch_surface.h.in	Defines the generated-header template.
cmake/dispatch-checks/README.md	Documents dispatch checks.
cmake/dispatch-checks/check-dispatch-declaration.cmake	Validates declared kernel counts.
cmake/dispatch-checks/check-dispatch-execution.cmake	Verifies runtime routing.
cmake/dispatch-checks/check-dispatch-instructions.cmake	Inspects ISA instruction budgets.
cmake/dispatch-checks/check-dispatch-linkage.cmake	Verifies kernel linkage.
include/svs/core/distance/cosine.h	Generates cosine extern templates.
include/svs/core/distance/dispatch_surface.h	Commits the default generated surface.
include/svs/core/distance/distance_core.h	Generates supported dimensions.
include/svs/core/distance/euclidean.h	Generates L2 extern templates.
include/svs/core/distance/inner_product.h	Generates IP extern templates.
include/svs/multi-arch/x86/avx2.cpp	Generates AVX2 instantiations.
include/svs/multi-arch/x86/avx512.cpp	Generates AVX512 instantiations.
include/svs/multi-arch/x86/preprocessor.h	Defines reusable instantiation macros.
tests/CMakeLists.txt	Enables multi-architecture tests.
tests/multi-arch/CMakeLists.txt	Registers dispatch probes and checks.
tests/multi-arch/x86/entry_probe.cpp	Exercises public dispatch entry points.
tests/multi-arch/x86/host_levels.h	Models host ISA predicates.
tests/multi-arch/x86/link_probe.cpp	References every declared kernel.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ahuber21]

Will be fixed in 375 -- and all PRs will be merged together as a stack.

[rfsaliev]

The change is pretty big with high review/maintenance cost.
It seems like the huge AI generated change to be reviewed by AI.
Scripts should be simplified and well structured.

[rfsaliev]

As I understand, this file is autogenerated from dispatch_surface.h.in.
Why do we need to track it in repository?
Suggesting to remove the file from repository but generate it in binary directory during config/build.

[ahuber21]

I added a default version for reference. If someone researched the code on GH only, or on a fresh checkout without prior compilation there are no missing files.

[rfsaliev]

Seems like files in this directory intended for tests.
IMHO it makes sense to move them to /test

[rfsaliev]

Seems like the cmake code here is pretty complicated.
Writing it in form of straightforward script leads high maintenance costs.
Please, modify the code to make it more structured, e.g. split to functions.

[rfsaliev]

Mangling rules are compiler-specific.
Are you sure that the pattern will work for all supported compilers/versions?

[ahuber21]

It's a concern I raised with the agent. Don't have the exact reply, but it was along the lines of:

• This regex will work for everything we currently use
• Checking our own emitted mangled symbols gives us more visibility/control over what we release. A change here is probably not intentional.

The second point sounded quite reasonable to me. So I figured it's worth giving this a shot. If we find the maintenance cost is too high, we can improve the tests.
From my understand though, these symbols should have been stable for the last few months and I don't see any changes on the horizon.

[rfsaliev]

@copilot, review the PR from readability/maintainability perspective, focus on cmake scripts and suggest changes to make scripts clearer and shorter, propose replacing complicated cmake code blocks with external tools if any or 'probing' sources for existing validation scripts.
Find an opportunity to re-use cmake code in form of functions/macros

[rfsaliev]

Review: readability & maintainability of the CMake scripts

The single-declaration → generated-surface design is sound, but the implementation reimplements a lot of general-purpose logic — C++ name demangling, header parsing, symbol tallying, list truncation, argument validation — in raw cmake -P scripts, and re-codes the same building blocks in each of the four checkers. That's the ~800 lines that are hard to review by hand. The highest-leverage changes:

1. Move the checkers out of CMake into one Python script (biggest win)

check-dispatch-{declaration,linkage,instructions,execution}.cmake are string/regex/list programs that happen to run under cmake -P. Each one:

• shells out to nm/objdump/gdb with the same ~8-line execute_process boilerplate,
• splits output on \n, regex-matches, dedups, and tallies into set(prefix_HAVE_${key} ...) pseudo-dictionaries (CMake has no maps, so this is emulated via variable-name interpolation — the most error-prone pattern here),
• re-implements "show first N, then … and M more".

All of this is a handful of lines each in Python with subprocess, re, collections.Counter, and real dicts. A single dispatch_checks.py with subcommands (linkage, declaration, instructions, execution), invoked via add_test(COMMAND ${Python3_EXECUTABLE} dispatch_checks.py ...), would replace all four .cmake files, be unit-testable on its own, and be human-reviewable. This is the primary recommendation. If a Python dependency is unacceptable, do 2.–5. instead.

2. Extract the duplicated checker helpers into one shared module

If the scripts stay in CMake, factor the repeats into cmake/dispatch-checks/lib.cmake and include() it. These appear in near-identical form in 2–4 files each:

• Required-arg validation — the foreach(required ...) if(NOT ${required}) message(FATAL_ERROR ...) block and its EXISTS twin (all four checkers).
• nm symbol extraction — svs_symbols() is defined twice with different signatures (linkage uses cmake_parse_arguments, declaration uses a positional arg), and the execution check inlines a third copy.
• "report first N" — svs_report_symbols (linkage) and svs_report_first (declaration) are the same function.

# cmake/dispatch-checks/lib.cmake
include_guard(GLOBAL)

function(svs_require)          # svs_require(SVS_NM SVS_ARCHIVE ...)
  foreach(var IN LISTS ARGN)
    if(NOT ${var})
      message(FATAL_ERROR "${var} is not set.")
    endif()
  endforeach()
endfunction()

function(svs_require_files)    # svs_require_files(SVS_ARCHIVE SVS_CONSUMER_OBJECT)
  foreach(var IN LISTS ARGN)
    if(NOT EXISTS "${${var}}")
      message(FATAL_ERROR "${var} does not exist: ${${var}}")
    endif()
  endforeach()
endfunction()

# Mangled names of symbols in <file> matching <regex>.
function(svs_nm_symbols out_var file regex)
  cmake_parse_arguments(arg "" "" "NM_ARGS" ${ARGN})
  execute_process(COMMAND "${SVS_NM}" ${arg_NM_ARGS} "${file}"
    OUTPUT_VARIABLE raw ERROR_VARIABLE err RESULT_VARIABLE status)
  if(NOT status EQUAL 0)
    message(FATAL_ERROR "${SVS_NM} failed on ${file}: ${err}")
  endif()
  set(symbols "")
  string(REPLACE "\n" ";" lines "${raw}")
  foreach(line IN LISTS lines)
    if(line MATCHES "${regex}")
      string(REGEX MATCH "[^ \t]+$" symbol "${line}")
      list(APPEND symbols "${symbol}")
    endif()
  endforeach()
  list(REMOVE_DUPLICATES symbols)
  set(${out_var} "${symbols}" PARENT_SCOPE)
endfunction()

function(svs_report_first list_var limit)
  set(shown ${${list_var}})
  list(LENGTH shown count)
  if(count GREATER limit)
    list(SUBLIST shown 0 ${limit} shown)
  endif()
  foreach(entry IN LISTS shown)
    message("    ${entry}")
  endforeach()
  if(count GREATER limit)
    math(EXPR rest "${count} - ${limit}")
    message("    ... and ${rest} more")
  endif()
endfunction()

That removes ~120 duplicated lines and gives one definition of "read symbols from a file."

3. Stop reconstructing mangled names in check-dispatch-declaration.cmake

This is the file that most needs attention (346 lines). It rebuilds Itanium ABI mangled names in CMake:

set(svs_mangled_classes)           # "<len><class>", e.g. 5L2Impl
foreach(class IN LISTS svs_distance_classes)
  string(LENGTH "${class}" len)
  list(APPEND svs_mangled_classes "${len}${class}")
endforeach()
set(svs_expected_extents ${SVS_SUPPORTED_DIMS} "18446744073709551615")  # Dynamic == SIZE_MAX
set(svs_kernel_regex "^_ZN3svs8distance([0-9]+...)ILm([0-9]+)E.*AVX_AVAILABILITYE([0-9]+)E")

This hard-codes the Itanium ABI (_ZN, length-prefixing, Lm…E for size_t, positional enum digit) into the test — exactly the compiler-specific fragility already raised in the inline thread. It silently doesn't apply to MSVC and depends on GCC/Clang keeping this scheme. Two simplifications:

• Compare counts, not reconstructed names. The declaration's purpose ("a generator bug that drops an extent drops it from both probe and archive") is satisfied by an independent count: expected = levels × extents × distances × pairs_per_level, all known numbers (the type-pair count is one grep). Assert the archive defines exactly that many distance...Impl...compute symbols and no foreign ones — no length-prefixing, no Lm…E, no SIZE_MAX literal. If per-(level,extent) presence is still wanted, check it on demangled output via c++filt using readable substrings like L2Impl<64, and AVX_AVAILABILITY::AVX2.
• This checker also largely re-does what check-dispatch-linkage.cmake already does with a compiled probe. Consider whether both are needed, or reduce declaration to just the independent count linkage can't provide.

4. Parse the ISA-level table once — reuse via a function

SVS_ISA_LEVELS rows ("AVX2|haswell|avx2") are split with string(REPLACE "|" ";") + list(GET ...) in five places: twice in generate-dispatch-surface.cmake (validation + generation loops), in multi-arch.cmake, in tests/multi-arch/CMakeLists.txt, and inside the declaration checker. Same for the derived SVS_DISPATCH_TU_SPECS. Provide one parser:

function(svs_parse_isa_level spec out_level out_arch out_infix)
  string(REPLACE "|" ";" f "${spec}")
  list(LENGTH f n)
  if(NOT n EQUAL 3)
    message(FATAL_ERROR "Malformed ISA level '${spec}': expected <level>|<arch>|<infix>.")
  endif()
  list(GET f 0 v0)  list(GET f 1 v1)  list(GET f 2 v2)
  set(${out_level} "${v0}" PARENT_SCOPE)
  set(${out_arch}  "${v1}" PARENT_SCOPE)
  set(${out_infix} "${v2}" PARENT_SCOPE)
endfunction()

The "|"-joined encoding (structs-as-strings) is itself a smell; parallel lists (SVS_ISA_LEVEL_NAMES, _ARCHS, _INFIXES) indexed together would remove the encode/decode entirely.

5. Emit a machine-readable manifest from the generator; stop re-parsing headers in tests

generate-dispatch-surface.cmake and check-dispatch-declaration.cmake both regex-parse C++ headers:

• enum class AVX_AVAILABILITY[ \t\r\n]*{([^}]*)} from distance_core.h,
• #define SVS_TYPE_PAIRS_... bodies (with line-continuation folding and one-level alias following) from preprocessor.h.

Regex-parsing C++ to recover enum order and macro arity is inherently brittle. The generator already holds the authoritative extent list, level list, and type-pair count at configure time — write them once to a generated dispatch_surface.manifest.cmake (or JSON) and have every test read that instead. One parser, one source of truth; the "ground truth 2/3" sections of the declaration checker disappear.

6. generate-dispatch-surface.cmake: split into functions (per the inline comment)

It's a 250-line straight-line script mixing validation, header emission, and reporting. Structure it as:

svs_validate_extents(SVS_SUPPORTED_DIMS)
svs_validate_levels(SVS_ISA_LEVELS)     # dedup names + infixes, field count
svs_emit_dispatch_header(...)           # configure_file into build (+ optional source)
svs_report_surface(...)                 # the STATUS block

The two separate foreach(level_spec ...) passes then collapse into one now that svs_parse_isa_level exists.

7. Smaller points

• multi-arch.cmake: lib_name is keyed by infix but obj_name by arch (${arch}_obj). If two levels ever share a -march, the object target name collides. Key both by infix, or assert arch uniqueness.
• Committed generated header (dispatch_surface.h): the "refresh committed copy + clang-format off to avoid a regenerate loop" mechanism is a maintenance trap. Prefer generating only into the build tree and dropping the committed copy; if it must stay for bare -I include use, add a CI check that fails when it's stale rather than silently rewriting it every configure.
• cmake/dispatch-checks/ location: these are test drivers and belong under tests (per the existing inline comment). Keep only surface generation under cmake.
• tests/multi-arch/CMakeLists.txt: the CMAKE_NM/CMAKE_OBJDUMP "use if defined else find_program" pattern repeats; wrap in a small svs_tool(out CACHEVAR NAMES ...) helper.
• Comment volume: several files are >50% prose (dispatch-surface.cmake ~85% comments). Move the multi-paragraph rationale into the existing README.md and keep inline comments to one-line "why," so the logic is visible without scrolling.

Suggested priority

1. 1 (Python) or 2 (shared cmake module) — removes the bulk of the duplication.
2. 4 + 5 — one parser, one manifest; deletes most of the header-regex and level-splitting.
3. 3 — kills the hand-rolled mangling in the declaration checker (also resolves the compiler-portability thread).
4. 6, 7 — structural polish.

Net effect: the four checkers collapse toward one tool + one shared library, the ISA table is parsed in exactly one place, and no test re-derives C++ mangling or re-parses headers.