iree_hal.h File Reference

Optional compiler integration for IREE HAL devices. More...

Go to the source code of this file.

Data Structures
struct	loomc_iree_hal_target_selection_t
	One compiler-and-loader target selected from an IREE HAL device. More...
struct	loomc_iree_hal_target_provider_t
	One linked IREE HAL target provider. More...
struct	loomc_iree_hal_target_options_t
	IREE HAL target-routing options. More...

Typedefs
typedef loomc_status_t(*	loomc_iree_hal_target_provider_fn_t) (void *user_data, loomc_target_environment_t *target_environment, const loomc_iree_hal_target_options_t *options, loomc_allocator_t allocator, bool *out_supported, loomc_iree_hal_target_selection_t *out_selection, loomc_result_t **out_result)
	Attempts to select a compiler-and-loader target from an IREE HAL device.

Functions
loomc_status_t	loomc_iree_hal_module_query_runtime_features (const loomc_module_t *module, const loomc_sanitizer_options_t *sanitizer_options, const loomc_string_view_t *root_symbols, loomc_host_size_t root_symbol_count, iree_hal_device_runtime_feature_flags_t *out_runtime_features)
	Queries HAL runtime services required by a module and sanitizer policy.
loomc_status_t	loomc_target_select_iree_hal (loomc_target_environment_t *target_environment, const loomc_iree_hal_target_options_t *options, loomc_allocator_t allocator, loomc_iree_hal_target_selection_t *out_selection, loomc_result_t **out_result)
	Selects a compiler-and-loader target from an IREE HAL device.

Detailed Description

Optional compiler integration for IREE HAL devices.

This leaf is for hosts that compile Loom modules for IREE HAL devices. It projects source-module requirements into device creation and selects the compiler target and HAL loader target as one operation. Core Loom C API headers stay free of IREE HAL types; embedders opt in by linking this leaf and one or more target-family provider leaves.

A successful selection preserves the exact executable-target row used to derive or validate the Loom profile. Callers compile with target_profile and load the resulting executable with executable_target; they never need to repeat target selection after compilation.

Routing is explicit and ordered. Callers pass the provider table selected by the linked binary. A provider that cannot handle the requested profile or device returns a route miss. A provider that recognizes the request returns a normal Loom result so unsupported device capabilities and incompatible targets are reported as structured diagnostics.

Typedef Documentation

loomc_iree_hal_target_provider_fn_t

typedef loomc_status_t(* loomc_iree_hal_target_provider_fn_t) (void *user_data, loomc_target_environment_t *target_environment, const loomc_iree_hal_target_options_t *options, loomc_allocator_t allocator, bool *out_supported, loomc_iree_hal_target_selection_t *out_selection, loomc_result_t **out_result)

Attempts to select a compiler-and-loader target from an IREE HAL device.

Parameters

user_data	Provider-owned pointer from loomc_iree_hal_target_provider_t::user_data.
target_environment	Target environment that owns profile semantics.
options	Router options borrowed for the duration of the call.
allocator	Host allocator used for result and profile storage.
out_supported	Receives true when this provider handled the request.
out_selection	Receives a complete selection when supported and the provider's result succeeds. Receives zero on route miss or failed result.
out_result	Receives the provider result when supported. Receives NULL on route miss.

Returns

OK when the provider completed far enough to report whether it supports the request. Non-OK statuses represent API misuse or infrastructure failures before a result could be produced.

Ownership

Providers transfer one retained result through out_result only when out_supported is true. A successful result transfers one retained target profile through out_selection; the executable target remains borrowed from options->device.

Thread safety

Provider callbacks must be thread-compatible. They may be called concurrently for unrelated invocations. Any shared provider state reachable through user_data must be immutable or internally synchronized.

Function Documentation

loomc_iree_hal_module_query_runtime_features()

loomc_status_t loomc_iree_hal_module_query_runtime_features	(	const loomc_module_t *	module,
		const loomc_sanitizer_options_t *	sanitizer_options,
		const loomc_string_view_t *	root_symbols,
		loomc_host_size_t	root_symbol_count,
		iree_hal_device_runtime_feature_flags_t *	out_runtime_features )

Queries HAL runtime services required by a module and sanitizer policy.

Call this after parsing and linking the source module and before creating the HAL device that will execute it. sanitizer_options must be the same descriptor, if any, supplied to compilation. The query accounts for both authored sanitizer operations and sanitizer instrumentation requested by the caller. Nonempty roots restrict the query to their dependency closure. Reachable template families conservatively include all available providers before target/value specialization. The query does not compile or mutate IR.

Parameters

module	Source module that will be compiled and executed.
sanitizer_options	Sanitizer compilation options, or NULL when no instrumentation is requested.
root_symbols	Executable root names, optionally prefixed with '@'. Borrowed for this call. An empty list queries every function in the module.
root_symbol_count	Number of entries in root_symbols.
out_runtime_features	Receives the required HAL runtime feature bits. Receives IREE_HAL_DEVICE_RUNTIME_FEATURE_FLAG_NONE on failure.

Returns

OK when the requirements were queried. Non-OK statuses represent API misuse, missing roots, or allocation failures.

Thread safety

The query holds no mutable process-global state. It may run concurrently with other read-only module operations when no mutation is active.

loomc_target_select_iree_hal()

loomc_status_t loomc_target_select_iree_hal	(	loomc_target_environment_t *	target_environment,
		const loomc_iree_hal_target_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_iree_hal_target_selection_t *	out_selection,
		loomc_result_t **	out_result )

Selects a compiler-and-loader target from an IREE HAL device.

Parameters

target_environment	Target environment whose provider package understands the returned profile.
options	Routing options.
allocator	Host allocator used for result and profile storage.
out_selection	Receives a complete selection when routing succeeds and the selected provider result succeeds. Receives zero on failed result.
out_result	Receives a retained result for the routing operation.

Returns

OK when routing completed far enough to report a result. Non-OK statuses represent API misuse or infrastructure failures before a result could be produced.

Ownership

The caller owns out_result on an OK return and releases it with loomc_result_release. The caller releases a returned target profile with loomc_target_profile_release. The executable target remains borrowed from options->device.

Thread safety

The router holds no mutable process-global state. It may be called from many threads when the supplied providers meet the callback contract.