kernel_tuning.h#

namespace onnx_light

Alias that makes onnx-light headers compatible with code that references ONNX_LIGHT_NAMESPACE (the macro used in the standard onnx package).

Set to ONNX_LIGHT_NAMESPACE so both names resolve to the same namespace.

Symbol-visibility attribute for the public onnx-light C++ API.

Maps the upstream compatibility macro to onnx-light’s explicit proto ABI annotation. This keeps declarations from vendored ONNX headers visible when lib_onnx_proto uses hidden visibility by default.

Namespace alias so that ONNX C++ code (and consumers such as onnxruntime) that refers to the literal onnx namespace — rather than the ONNX_NAMESPACE macro — resolves to the onnx-light namespace. The standard onnx package lives in namespace onnx; onnx-light uses onnx_light (via ONNX_LIGHT_NAMESPACE), so this alias keeps onnx-light a true drop-in. It is only introduced when the onnx-light namespace differs from onnx.

namespace core

namespace runtime

Typedefs

using TuningValue = std::variant<int64_t, double, bool, std::string>#: Stores one portable scalar tuning value.

using KernelCalibrationFunction = std::function<KernelTuningParameters(const KernelTuningKey&, const CpuExecutionDescriptor&, const CalibrationOptions&, CalibrationReporter&)>#: Calibrates one exact, registered kernel tuning key.

using KernelTuningValidationHook = std::function<void(const KernelTuningParameters&)>#

Validates kernel-specific value ranges and relationships.

A hook throws std::invalid_argument when the complete parameter set is invalid. Generic name, key, presence, and type checks run before the hook.

using KernelTuningQueryValidationHook = std::function<std::optional<std::string>(const KernelTuningParameters&)>#

Validates kernel-specific value ranges without throwing on invalid input.

Returns: std::nullopt when the complete parameter set is valid, otherwise the validation message describing why it is invalid.

Functions

std::string_view TuningValueTypeName(const TuningValue &value) noexcept#

Returns the stable type name of a tuning value.

Returns: One of "int64", "double", "bool", or "string".

KernelTuningRegistry &GetKernelTuningRegistry()#: Returns the process-wide tuning registry.

void RegisterKernelTuningSchema(KernelTuningSchema schema)#: Registers a schema in the process-wide tuning registry.

void RegisterKernelTuningProfile(const KernelTuningKey &key, platform::CpuSelector processors, KernelTuningParameters parameters, int priority = 0)#: Registers a processor-specific profile in the process-wide tuning registry.

void RegisterKernelCalibrationFunction(const KernelTuningKey &key, KernelCalibrationFunction function)#: Registers a trusted calibration callback in the process-wide registry.

std::vector<KernelCalibrationCase> MakeElementwiseCalibrationCases(int32_t element_type, size_t input_count, int64_t first_elements, int64_t maximum_elements, bool include_broadcasting)#

Creates elementwise benchmark cases for unary or binary kernels.

Binary cases include equal-shape inputs and, when requested, scalar and multidirectional broadcasting cases for every problem size.

Returns: Deterministic benchmark cases ordered by increasing problem size.

KernelTuningParameters CalibrateKernelBenchmark(const KernelTuningKey &key, const CpuExecutionDescriptor &execution, const CalibrationOptions &options, CalibrationReporter &reporter, const KernelCalibrationBenchmark &benchmark)#

Runs a bounded, validated crossover search shared by unary and binary kernels.

Returns: A complete parameter set with the selected integer parameter.

CalibrationBatchReport CalibrateRegisteredKernels(const KernelCalibrationSelection &selection = {}, const CalibrationOptions &options = {})#

Runs selected registered callbacks and atomically publishes their profiles.

Unsupported keys have a tuning schema but no callback. only_missing skips keys with an explicitly published profile.

Throws:: std::exception – from a calibration callback or profile validation. No profile is published unless every selected callback succeeds.

struct CalibrationBatchReport#

#include <kernel_tuning.h>

Reports one explicit batch calibration and its atomic publication.

Public Functions

inline std::span<const KernelTuningParameters> successful_profiles() const noexcept#: Returns successfully validated profiles.

Public Members

uint64_t published_generation = 0#

std::vector<KernelTuningParameters> calibrated#

std::vector<KernelTuningKey> skipped#

std::vector<KernelTuningKey> unsupported#

std::vector<KernelCalibrationDiagnostic> diagnostics#

std::vector<KernelCalibrationResourceUsage> resources#

struct CalibrationInputSpec#

#include <kernel_tuning.h>

Describes one deterministic input generated for a calibration benchmark.

Public Members

int32_t element_type = 0#

Shape shape#

uint64_t seed = 0#

struct CalibrationOptions#

#include <kernel_tuning.h>

Bounds one explicit calibration request. Zero means callback-defined.

Public Members

std::optional<CpuExecutionDescriptor> execution#

uint64_t maximum_duration_ms = 0#

uint64_t maximum_memory_bytes = 0#

std::optional<uint32_t> maximum_threads#

class CalibrationReporter#

#include <kernel_tuning.h>

Collects diagnostics emitted by one calibration callback.

Public Functions

void AddDiagnostic(std::string message)#: Appends one diagnostic message.

void RecordBenchmark(uint64_t memory_bytes, uint64_t duration_ns)#: Records resources consumed by one completed benchmark case.

inline const std::vector<std::string> &diagnostics() const noexcept#: Returns callback diagnostics in emission order.

inline uint64_t benchmark_cases() const noexcept#: Returns the number of benchmark cases measured by the callback.

inline uint64_t peak_memory_bytes() const noexcept#: Returns the largest live input/output allocation measured by the callback.

inline uint64_t measured_duration_ns() const noexcept#: Returns the accumulated benchmark measurement duration.

Private Members

std::vector<std::string> diagnostics_#

uint64_t benchmark_cases_ = 0#

uint64_t peak_memory_bytes_ = 0#

uint64_t measured_duration_ns_ = 0#

struct CpuExecutionDescriptor#

#include <kernel_tuning.h>

Describes the stable execution properties used to resolve a processor profile.

Public Functions

bool operator==(const CpuExecutionDescriptor&) const = default#

Public Members

platform::CpuDescriptor processor#

uint32_t effective_threads = 0#

struct KernelCalibrationBenchmark#

#include <kernel_tuning.h>

Defines a bounded crossover search for one integer tuning parameter.

Cases with the same problem_size form one benchmark group. A group wins only when the candidate reaches minimum_speedup in every case.

Public Members

KernelTuningParameters portable_parameters#

std::string parameter_name#

int64_t serial_parameter_value = std::numeric_limits<int64_t>::max()#

std::vector<KernelCalibrationCase> cases#

KernelCalibrationRunner reference#

KernelCalibrationRunner candidate#

int repetitions = 5#

int required_consecutive_wins = 2#

double minimum_speedup = 0.05#

uint64_t default_maximum_duration_ms = 250#

uint64_t default_maximum_memory_bytes = uint64_t{64} << 20#

std::function<bool(const Tensor&, const Tensor&)> validate_output#

struct KernelCalibrationCase#

#include <kernel_tuning.h>

Describes one kernel-specific benchmark case and its expected output.

Public Members

std::string name#

uint64_t problem_size = 0#

std::vector<CalibrationInputSpec> inputs#

int32_t output_element_type = 0#

Shape output_shape#

struct KernelCalibrationDiagnostic#

#include <kernel_tuning.h>

Associates one calibration diagnostic with its exact key.

Public Members

KernelTuningKey key#

std::string message#

struct KernelCalibrationResourceUsage#

#include <kernel_tuning.h>

Reports resources consumed while calibrating one exact key.

Public Members

KernelTuningKey key#

uint64_t benchmark_cases = 0#

uint64_t peak_memory_bytes = 0#

uint64_t measured_duration_ns = 0#

struct KernelCalibrationRunner#

#include <kernel_tuning.h>

Configures and runs one reference or candidate kernel instance.

Public Members

std::function<void(int64_t)> configure#

std::function<void(std::span<const Tensor>, Tensor&)> run#

struct KernelCalibrationSelection#

#include <kernel_tuning.h>

Filters tuning keys. Non-empty fields combine with logical AND.

Public Functions

bool Matches(const KernelTuningKey &key) const#: Returns whether an exact key satisfies this selection.

Public Members

std::optional<std::string> library#

std::vector<std::string> kernels#

std::vector<std::string> implementations#

std::vector<int32_t> element_types#

std::optional<Device> device#

bool only_missing = false#

struct KernelTuningKey#

#include <kernel_tuning.h>

Identifies one tunable kernel implementation and element type.

tuning_abi must change whenever persisted parameters for the implementation become incompatible.

Public Functions

bool operator==(const KernelTuningKey&) const = default#

Public Members

std::string library#

std::string kernel#

std::string implementation#

int32_t element_type = 0#

Device device = Device::kUndefined#

uint32_t tuning_abi = 0#

struct KernelTuningKeyHash#

#include <kernel_tuning.h>

Hashes every field of a :cpp:class:KernelTuningKey.

Public Functions

size_t operator()(const KernelTuningKey &key) const noexcept#

struct KernelTuningParameters#

#include <kernel_tuning.h>

Stores the named values associated with an exact tuning key.

Public Functions

bool Contains(std::string_view name) const#: Returns whether a named value is present.

template<typename T> inline const T *TryGet(std::string_view name) const noexcept#

Returns a named value with its exact scalar type, or nullptr.

This query-style accessor returns nullptr when the name is absent or when it exists with another scalar type.

Returns: A pointer to the requested value, or nullptr.

template<typename T> inline const T &Get(std::string_view name) const#

Returns a named value with its exact scalar type.

Returns: The requested value.

Throws:: std::invalid_argument – if the name is absent or has another type.

Public Members

KernelTuningKey key#

std::unordered_map<std::string, TuningValue> values#

Private Static Functions

template<typename T> static inline constexpr std::string_view TuningTypeName()#

static void ThrowMissingValue(std::string_view name)#

static void ThrowWrongType(std::string_view name, std::string_view expected, std::string_view actual)#

class KernelTuningRegistry#

#include <kernel_tuning.h>

Registers tuning schemas and atomically publishes immutable parameter sets.

Publication validates the complete batch before making any value visible.

Public Functions

KernelTuningRegistry()#

~KernelTuningRegistry()#

KernelTuningRegistry(const KernelTuningRegistry&) = delete#

KernelTuningRegistry &operator=(const KernelTuningRegistry&) = delete#

void RegisterSchema(KernelTuningSchema schema)#

Registers one schema and its portable defaults.

Throws:: std::invalid_argument – if its key is already registered.

void RegisterProfile(const KernelTuningKey &key, platform::CpuSelector processors, KernelTuningParameters parameters, int priority = 0)#

Registers one validated processor-specific profile.

Exact vendor/family/model selectors outrank processor-list and microarchitecture selectors, which outrank instruction-set selectors. Priority only distinguishes profiles at the same specificity.

Throws:: std::invalid_argument – for an invalid selector, parameters that do not match the schema, or a selector ambiguous with an existing profile.

void RegisterProfiles(std::span<const ProcessorKernelTuningProfile> profiles)#

Registers processor-specific profiles in one immutable generation.

Validation or ambiguity in any profile leaves the registry unchanged.

void RegisterCalibrationFunction(const KernelTuningKey &key, KernelCalibrationFunction function)#

Registers one trusted native calibration callback.

Throws:: std::invalid_argument – when the key has no schema, the callback is empty, or another callback is already registered for the key.

KernelTuningRegistrySnapshot Snapshot() const noexcept#: Returns the current immutable registry generation.

KernelTuningRegistryAccessCounts AccessCounts() const noexcept#

Returns monotonic cold-path access counters for diagnostics and benchmarks.

Kernel execution does not touch these counters because kernels receive their immutable typed configuration before their first run.

void PublishProfiles(std::span<const KernelTuningParameters> profiles, std::span<const KernelTuningKey> reset_keys = {})#

Publishes a validated batch and resets selected keys to portable defaults.

Every replacement and reset key must be registered. Validation failure leaves the current generation unchanged.

void PublishCalibratedProfiles(std::span<const KernelTuningParameters> profiles, const CpuExecutionDescriptor &execution, std::span<const KernelTuningKey> reset_keys = {})#

Publishes profiles scoped to one exact execution descriptor.

Other execution descriptors and universal overrides remain unchanged.

std::vector<KernelTuningKey> RegisteredKeys() const#: Returns the registered keys.

std::shared_ptr<const KernelTuningSchema> FindSchema(const KernelTuningKey &key) const#: Returns the schema for a registered key, or nullptr.

KernelCalibrationFunction FindCalibrationFunction(const KernelTuningKey &key) const#: Returns the callback registered for a key, or an empty function.

Private Members

std::unique_ptr<Impl> impl_#

struct KernelTuningRegistryAccessCounts#

#include <kernel_tuning.h>

Counts cold-path accesses to one kernel tuning registry.

Public Functions

bool operator==(const KernelTuningRegistryAccessCounts&) const = default#

Public Members

uint64_t snapshots = 0#

uint64_t lookups = 0#

uint64_t resolutions = 0#

class KernelTuningRegistrySnapshot#

#include <kernel_tuning.h>

Holds one immutable generation of resolved kernel tuning parameters.

A snapshot remains valid after later registrations or cache loads publish a newer generation.

Public Functions

uint64_t generation() const noexcept#: Returns the registry generation captured by this snapshot.

const KernelTuningParameters *Find(const KernelTuningKey &key) const noexcept#

Finds the resolved parameters for an exact tuning key.

This lookup does not select an execution-specific calibrated profile; use :cpp:func:Resolve when an execution descriptor is available.

Returns: The parameters, or nullptr when the key is not registered.

bool HasPublishedProfile(const KernelTuningKey &key, const CpuExecutionDescriptor &execution) const noexcept#: Returns whether a compatible cached, calibrated, or override profile exists.

const KernelTuningParameters *Resolve(const KernelTuningKey &key, const CpuExecutionDescriptor &execution) const noexcept#

Resolves the highest-precedence profile matching an execution descriptor.

Explicitly published parameters take precedence over registered processor profiles, which in turn take precedence over portable defaults.

Returns: The resolved parameters, or nullptr when the key is not registered.

Private Functions

inline explicit KernelTuningRegistrySnapshot(std::shared_ptr<const State> state)#

Private Members

std::shared_ptr<const State> state_#

Friends

friend class KernelTuningRegistry

class KernelTuningSchema#

#include <kernel_tuning.h>

Defines one kernel’s portable defaults and validation contract.

Construction validates the key, names, and portable defaults immediately. Every subsequently validated parameter set must contain exactly the same names and scalar types, so no tunable value can exist without a compiled portable fallback.

Public Functions

explicit KernelTuningSchema(KernelTuningParameters portable_defaults, KernelTuningValidationHook validation_hook = {})#

inline const KernelTuningKey &key() const noexcept#: Returns the exact kernel key described by this schema.

inline const KernelTuningParameters &portable_defaults() const noexcept#: Returns the validated, hard-coded portable parameter set.

void Validate(const KernelTuningParameters &parameters) const#

Validates a complete parameter set against this schema.

Throws:: std::invalid_argument – for a mismatched key, unknown or missing name, wrong scalar type, or a kernel-specific validation failure.

bool TryValidate(const KernelTuningParameters &parameters, std::string *error_message = nullptr) const#

Validates a complete parameter set without throwing on invalid input.

Returns: true when the parameters satisfy the schema. Otherwise returns false and stores the validation message in error_message when it is not nullptr.

Public Static Functions

static KernelTuningSchema WithQueryValidation(KernelTuningParameters portable_defaults, KernelTuningQueryValidationHook validation_hook)#

Creates a schema from a non-throwing validation query hook.

Returns: A schema whose validation hook returns std::nullopt on success or a diagnostic message on invalid input.

Private Functions

KernelTuningSchema(KernelTuningParameters portable_defaults, QueryValidationTag, KernelTuningQueryValidationHook validation_hook)#

std::optional<std::string> ValidationError(const KernelTuningParameters &parameters) const#

Private Members

KernelTuningParameters portable_defaults_#

KernelTuningQueryValidationHook validation_hook_#

struct QueryValidationTag#

struct ProcessorKernelTuningProfile#

#include <kernel_tuning.h>

Associates validated parameters with one deployment processor selector.

Public Members

KernelTuningParameters parameters#

platform::CpuSelector processors#

int priority = 0#