iree_hal.h File Reference

Optional target-profile router for IREE HAL devices. More...

Go to the source code of this file.

Data Structures
struct	loomc_iree_hal_profile_provider_t
	One linked IREE HAL profile provider. More...
struct	loomc_iree_hal_profile_options_t
	IREE HAL target-profile routing options. More...

Typedefs
typedef loomc_status_t(*	loomc_iree_hal_profile_provider_fn_t) (void *user_data, loomc_target_environment_t *target_environment, const loomc_iree_hal_profile_options_t *options, loomc_allocator_t allocator, bool *out_supported, loomc_target_profile_t **out_profile, loomc_result_t **out_result)
	Attempts to create a target profile from an IREE HAL device.

Functions
loomc_status_t	loomc_target_profile_create_iree_hal (loomc_target_environment_t *target_environment, const loomc_iree_hal_profile_options_t *options, loomc_allocator_t allocator, loomc_target_profile_t **out_profile, loomc_result_t **out_result)
	Routes an IREE HAL device through the linked target-profile providers.

Detailed Description

Optional target-profile router for IREE HAL devices.

This leaf is for hosts that already own an iree_hal_device_t and want a Loom target profile without coupling callsites to a specific HAL backend. 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.

Routing is explicit and ordered. Callers pass the provider table selected by the linked binary, and the router asks each provider whether it can describe the device. A provider that does not recognize the device returns a route miss, not an error. A provider that recognizes the device returns the normal Loom operation result so unsupported device capabilities, missing executable formats, or incomplete facts are reported as structured diagnostics.

Example

Route an IREE HAL Vulkan device through the linked SPIR-V provider:

#include "loomc/target/iree_hal.h"
#include "loomc/target/spirv/iree_hal.h"
 
const loomc_iree_hal_profile_provider_t* providers[] = {
    loomc_spirv_iree_hal_profile_provider(),
};
loomc_iree_hal_profile_options_t options = {
    .type = LOOMC_STRUCTURE_TYPE_IREE_HAL_PROFILE_OPTIONS,
    .structure_size = sizeof(loomc_iree_hal_profile_options_t),
    .identifier = loomc_make_cstring_view("jit-device"),
    .device = device,
    .physical_device_affinity = 0,
    .providers = providers,
    .provider_count = 1,
};
loomc_target_profile_t* profile = NULL;
loomc_result_t* result = NULL;
loomc_status_t status = loomc_target_profile_create_iree_hal(
    target_environment, &options, loomc_allocator_system(), &profile,
    &result);
if (!loomc_status_is_ok(status)) return status;
if (!loomc_result_succeeded(result)) {
  // Inspect diagnostics. `profile` is NULL when no route succeeded.
}
loomc_result_release(result);

Typedef Documentation

loomc_iree_hal_profile_provider_fn_t

typedef loomc_status_t(* loomc_iree_hal_profile_provider_fn_t) (void *user_data, loomc_target_environment_t *target_environment, const loomc_iree_hal_profile_options_t *options, loomc_allocator_t allocator, bool *out_supported, loomc_target_profile_t **out_profile, loomc_result_t **out_result)

Attempts to create a target profile from an IREE HAL device.

Parameters

user_data	Provider-owned pointer from loomc_iree_hal_profile_provider_t::user_data.
target_environment	Target environment that will own the profile.
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 device.
out_profile	Receives one retained profile when supported and the provider's result succeeds. Receives NULL 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 device. 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. Providers transfer one retained profile through out_profile only when the result succeeds.

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_target_profile_create_iree_hal()

loomc_status_t loomc_target_profile_create_iree_hal	(	loomc_target_environment_t *	target_environment,
		const loomc_iree_hal_profile_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_target_profile_t **	out_profile,
		loomc_result_t **	out_result )

Routes an IREE HAL device through the linked target-profile providers.

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_profile	Receives one retained profile when routing succeeds and the selected provider result succeeds. Receives NULL 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. When a profile is produced, the caller owns the returned reference and releases it with loomc_target_profile_release.

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.