feature: Add validation layer Timing Checker for host-side API timing

[MichalMrozek]

Summary

Adds a new validation-layer checker, enabled with ZEL_ENABLE_TIMING_CHECKER=1, that measures the host-side (CPU) duration of every Level Zero API call and aggregates per-API statistics: call count, total, min, max, average, and percentage share of total host time.

For each API the checker stamps a high-resolution monotonic timestamp in the Prologue and reads it again in the Epilogue (QueryPerformanceCounter on Windows, clock_gettime(CLOCK_MONOTONIC_RAW) elsewhere). The measured span is dominated by the underlying driver call and is consistent across calls, making it suitable for relative host-cost analysis.

Output

Output is written directly to stderr and is independent of the loader logging system, so the ZEL_*_LOGGING variables are not required. Summary rows are sorted by percentage share of total host time, highest first.

Variable	Default	Effect
ZEL_ENABLE_TIMING_CHECKER	0	Enable; a per-API summary table is printed at teardown
ZEL_TIMING_CHECKER_CSV=<path>	(unset)	Also export per-API stats to a CSV (process id appended to the filename)
ZEL_TIMING_CHECKER_LIVE	0	Also print each call's duration as it happens

Example summary:

==== Level Zero Host API Timing (ns) ====
Function                          Calls   Total      Min   Max        Avg          %
zeInitDrivers                     2       56190355   671   56189684   28095177   90.49%
zeCommandListCreateImmediate      1       3324663    ...   ...        3324663     5.35%

Changes

• New checker under source/layers/validation/checkers/timing/ (engine, registration, CMake) and a usage guide timing_checker.md, referenced from the validation-layer README.
• The per-API override headers are produced at build time from scripts/templates/validation/timing.h.mako (wired into scripts/generate_code.py) and are not checked in.
• Unit tests in test/loader_validation_layer.cpp covering result transparency and per-API timing data.

[Copilot]

Pull request overview

Adds a new validation-layer “Timing Checker” that measures host-side (CPU) duration of Level Zero API calls and reports per-API aggregated statistics, with optional live stderr logging and CSV export. This fits into the validation layer’s existing checker framework (global checker registration + generated per-API overrides).

Changes:

• Introduces a new timing checker (engine + registration) that records Prologue/Epilogue timestamps and aggregates per-function timing stats, printing a teardown summary and optionally exporting CSV.
• Wires build-time generation of per-API timing override headers via a new Mako template and updates the code generator to ensure output directories exist.
• Adds documentation and loader/validation-layer unit tests to validate transparency and live per-call timing output.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/loader_validation_layer.cpp	Adds gtest coverage for timing checker transparency and live per-call output parsing
test/CMakeLists.txt	Registers new timing-checker-focused CTest entries with required env vars
source/layers/validation/README.md	Documents enabling and usage of the new timing checker mode
source/layers/validation/checkers/timing/zel_timing_checker.h	Declares timing checker and generated entrypoint wrappers
source/layers/validation/checkers/timing/zel_timing_checker.cpp	Implements timestamping, aggregation, stderr output, CSV writing, and handler registration
source/layers/validation/checkers/timing/zel_global_timing_state.h	Defines shared aggregation state and APIs for timing collection/output
source/layers/validation/checkers/timing/timing_checker.md	Adds detailed user documentation and examples for summary/CSV/live modes
source/layers/validation/checkers/timing/CMakeLists.txt	Adds timing checker sources to the validation layer build
source/layers/validation/checkers/CMakeLists.txt	Hooks the new timing checker subdirectory into the checker build
scripts/templates/validation/timing.h.mako	Adds generated Prologue/Epilogue overrides that call into GlobalTimingState
scripts/generate_code.py	Registers timing template output and ensures generated output subdirs are created

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[MichalMrozek]

Fixed in d50e8a3. The Windows path now converts ticks to nanoseconds without truncation or overflow by splitting into whole seconds plus the sub-second remainder: (t / freq) * NSEC_IN_SEC + ((t % freq) * NSEC_IN_SEC) / freq. This stays exact when the counter frequency does not evenly divide 1e9 and avoids the ticks * 1e9 overflow.

[MichalMrozek]

Fixed in d50e8a3. The checker is now inserted at the front of validationHandlers (handlers.insert(handlers.begin(), &timing_checker)) instead of push_back, so its Prologue/Epilogue run first and every call is measured even when a later handler's Epilogue returns a non-success result.

[rwmcguir]

While this works, we have typically put putting the environ config within the CMakeFile.txt within the /test folder. So this may be duplicated.