internationalcolorconsortium/iccdev/avx2-clut-diagnostics

AVX2 CLUT Diagnostics

Use this skill for source-level AVX2 CLUT debugging and performance handoff. Do not use diagnostic traces as throughput benchmarks.

1. Build the Diagnostic Configuration

On Windows:

cmake --preset vs2022-clangcl-x64-avx2-diagnostics -S Build/Cmake -B out/vs2022-clangcl-x64-avx2-diagnostics
cmake --build out/vs2022-clangcl-x64-avx2-diagnostics --config Debug -- /m /maxcpucount

On Linux, configure with -DICCDEV_ENABLE_AVX2=ON and -DICC_AVX2_CLUT_DEBUG=ON.

The default ci-regression-checks build does not enable ICCDEV_ENABLE_AVX2; it validates the portable fallback rather than the AVX2 kernel. The Windows PR ClangCL lane enables AVX2, but use this explicit diagnostic configuration when trace evidence is required.

2. Inspect the Dispatch

Set breakpoints in IccTraceAvx2ClutDispatch() and IccTraceAvx2ClutKernel() in IccProfLib/IccSignatureUtils.h. Confirm AVX2 is selected only with CPU support and the measured winning output count: 15. Record offsets, weights, vector outputs, masked outputs, and elapsed time.

3. Validate Behavior

ctest --test-dir out/vs2022-clangcl-x64-avx2-diagnostics -C Debug --output-on-failure --no-tests=error -R "^iccdev\.clut-eight-output-regression$"

The eight-, nine-, eleven-, and fourteen-output fixtures pin SSE2 fallback behavior. The fifteen-output fixture exercises a full AVX2 vector plus a seven-output masked tail.

4. Measure Separately

Reconfigure with ICC_AVX2_CLUT_DEBUG=OFF before measuring. Preserve CPUID, XGETBV, scalar/SSE fallback behavior, and bit-exact per-lane regression output.

Use the interleaved native benchmark for the performance decision:

.github\scripts\iccdev-windows-clut-avx2-benchmark.ps1 `
  -BaselineBuildDir C:\path\to\baseline-build `
  -Avx2BuildDir C:\path\to\avx2-build `
  -Iterations 20000000 -Repetitions 11

Measure output counts 8 through 16. Windows AVX2 measurements use ClangCL; native MSVC remains on SSE2 because its AVX2 implementation regressed. Require output_vector_match=True for every result row.

On Linux, make a separate Release monitoring build with -DICCDEV_ENABLE_TELEMETRY=ON. Then collect a pinned timing distribution, hardware counters, syscall summary, and optional FlameGraph inputs:

ICCDEV_CLUT_PROFILE_AFFINITY=0 \
ICCDEV_CLUT_PROFILE_RUNS=21 \
ICCDEV_CLUT_PROFILE_FLAMEGRAPH=1 \
ICCDEV_FLAMEGRAPH_DIR=/path/to/FlameGraph \
./.github/scripts/iccdev-clut-profile.sh out/clut-avx2 out/clut-profile

Inside the unified container, use its preconfigured pinned ICCDEV_FLAMEGRAPH_DIR without overriding it.

The script preserves a telemetry file per measured CTest run. Do not enable ICC_AVX2_CLUT_DEBUG, coverage, or strace while comparing cycle counts. Record clut_timing_stride with each counter report. The default of 1 times every CLUT call; use a power-of-two ICC_PERF_CLUT_TIMING_STRIDE up to 1024 when lower overhead matters, and treat elapsed fields as estimates then. Call counters remain exact. Keep instrumented timings separate from the ordinary throughput baseline.

Handoff

Provide the branch and commit, target CPU, compiler, diagnostic trace summary, debug and release validation results, measurement command, p50/p95 timing, telemetry, perf, syscall, and FlameGraph artifacts, and any pending Windows-specific investigation.

Reference

../../../docs/avx2-clut-diagnostics.md