target.h File Reference

Prepared target environments and target lowering pipelines. More...

Go to the source code of this file.

Data Structures
struct	loomc_context_target_options_t
	Context option extension that registers a target environment. More...
struct	loomc_target_specialization_t
	One function version to specialize to one structured target profile. More...
struct	loomc_target_binding_t
	One authored target declaration to bind to one target profile. More...
struct	loomc_target_specialization_options_t
	Option extension carrying target specialization inputs. More...
struct	loomc_target_pipeline_options_t
	Target pipeline creation options. More...

Typedefs
typedef struct loomc_target_environment_t	loomc_target_environment_t
	Prepared immutable target environment.
typedef struct loomc_target_profile_t	loomc_target_profile_t
	Prepared immutable target profile.

Enumerations
enum	loomc_target_fact_state_t { LOOMC_TARGET_FACT_STATE_UNKNOWN = 0 , LOOMC_TARGET_FACT_STATE_FALSE = 1 , LOOMC_TARGET_FACT_STATE_TRUE = 2 }
	Three-valued target fact state. More...
enum	loomc_target_pipeline_kind_t { LOOMC_TARGET_PIPELINE_KIND_PREPARED_LOW = 0 , LOOMC_TARGET_PIPELINE_KIND_SOURCE_LOW = 1 }
	Target lowering pipeline boundary. More...
enum	loomc_target_control_flow_lowering_t { LOOMC_TARGET_CONTROL_FLOW_LOWERING_CFG = 0 , LOOMC_TARGET_CONTROL_FLOW_LOWERING_STRUCTURED_LOW = 1 }
	Control-flow shape selected for source-to-low lowering. More...

Functions
loomc_status_t	loomc_pass_program_create_from_target_pipeline (loomc_context_t *context, const loomc_target_pipeline_options_t *options, loomc_allocator_t allocator, loomc_pass_program_t **out_pass_program, loomc_result_t **out_result)
	Creates a prepared target lowering pass program.
loomc_status_t	loomc_target_profile_select (loomc_target_environment_t *target_environment, loomc_string_view_t specification, loomc_allocator_t allocator, loomc_target_profile_t **out_profile)
	Selects a complete named profile from a target environment.
void	loomc_target_profile_retain (loomc_target_profile_t *profile)
	Retains a target profile for another owner.
void	loomc_target_profile_release (loomc_target_profile_t *profile)
	Releases a target profile from one owner.
loomc_status_t	loomc_target_environment_create (loomc_host_size_t environment_count, loomc_target_environment_t *const *environments, loomc_allocator_t allocator, loomc_target_environment_t **out_target_environment)
	Creates one immutable environment from explicitly selected target packages.
void	loomc_target_environment_retain (loomc_target_environment_t *target_environment)
	Retains a target environment for another owner.
void	loomc_target_environment_release (loomc_target_environment_t *target_environment)
	Releases a target environment from one owner.

Detailed Description

Prepared target environments and target lowering pipelines.

A target environment is the reusable compiler capability package selected by the embedding binary. It describes target dialects, target-low descriptor registries, source-to-low policy tables, target math policies, pass registries, and target-aware pass predicates. It is not a device handle and does not require hardware to exist.

Target environments are prepared before contexts because target dialects must be registered while the context is still mutable. A context created with a target environment can parse and build IR for those target dialects. Prepared compilers and target pipelines created from that context reuse the same environment-derived tables.

A target profile is a reusable, immutable, target-family-typed set of facts for a concrete, partial, saved, or synthetic target. Compile invocations borrow profiles in direct-function and target-declaration binding rows. This lets a JIT share cached device profiles across worker threads while independently choosing the exact target of function roots or authored target declarations in a multi-target module.

Example

Create a context linked with a target environment:

#include "loomc/target/spirv/base.h"
 
loomc_target_environment_t* target_environment = NULL;
loomc_status_t status = loomc_target_environment_create_spirv(
    loomc_allocator_system(), &target_environment);
if (!loomc_status_is_ok(status)) return status;
 
loomc_context_target_options_t target_options = {
    .type = LOOMC_STRUCTURE_TYPE_CONTEXT_TARGET_OPTIONS,
    .structure_size = sizeof(loomc_context_target_options_t),
    .target_environment = target_environment,
};
loomc_context_options_t context_options = {
    .type = LOOMC_STRUCTURE_TYPE_CONTEXT_OPTIONS,
    .structure_size = sizeof(loomc_context_options_t),
    .next = &target_options,
};
 
loomc_context_t* context = NULL;
status = loomc_context_create(&context_options, loomc_allocator_system(),
                              &context);
loomc_target_environment_release(target_environment);
if (!loomc_status_is_ok(status)) return status;
 
// `context` can now parse SPIR-V target records and create target
// pipelines backed by the prepared target environment.

Example

Specialize one function during a compile invocation:

#include "loomc/target/spirv/profile.h"
 
loomc_spirv_profile_options_t profile_options = {
    .type = LOOMC_STRUCTURE_TYPE_SPIRV_PROFILE_OPTIONS,
    .structure_size = sizeof(loomc_spirv_profile_options_t),
    .identifier = loomc_make_cstring_view("offline-vulkan13"),
    .preset = LOOMC_SPIRV_PROFILE_PRESET_VULKAN_1_3_BDA,
};
loomc_target_profile_t* profile = NULL;
loomc_result_t* profile_result = NULL;
loomc_status_t status = loomc_target_profile_create_spirv(
    target_environment, &profile_options, loomc_allocator_system(),
    &profile, &profile_result);
if (!loomc_status_is_ok(status)) return status;
if (!loomc_result_succeeded(profile_result)) {
  // Inspect structured target-profile diagnostics.
}
loomc_result_release(profile_result);
 
loomc_target_specialization_t specialization = {
    .function_symbol = loomc_make_cstring_view("dispatch"),
    .target_profile = profile,
};
loomc_target_specialization_options_t target_options = {
    .type = LOOMC_STRUCTURE_TYPE_TARGET_SPECIALIZATION_OPTIONS,
    .structure_size = sizeof(loomc_target_specialization_options_t),
    .specializations = &specialization,
    .specialization_count = 1,
};
loomc_compile_options_t compile_options = {
    .type = LOOMC_STRUCTURE_TYPE_COMPILE_OPTIONS,
    .structure_size = sizeof(loomc_compile_options_t),
    .next = &target_options,
};
// Pass compile_options to loomc_compile_module.
loomc_target_profile_release(profile);

Typedef Documentation

loomc_target_environment_t

typedef struct loomc_target_environment_t loomc_target_environment_t

Prepared immutable target environment.

A target environment owns target provider composition selected by the linked binary. It should be created once per target provider set and reused across contexts, compilers, pass programs, and worker threads.

Thread safety

Target environments are immutable after creation and may be shared across threads. Retain/release operations are safe from multiple threads.

loomc_target_profile_t

typedef struct loomc_target_profile_t loomc_target_profile_t

Prepared immutable target profile.

A target profile owns normalized target facts and any target-family payload needed by compiler passes or emitters. Profiles are separate from contexts and compilers so embedders can cache one profile per device, saved hardware profile, or cross-compilation bucket.

Thread safety

Target profiles are immutable after creation and may be shared across threads. Retain/release operations are safe from multiple threads.

Enumeration Type Documentation

loomc_target_control_flow_lowering_t

enum loomc_target_control_flow_lowering_t

Control-flow shape selected for source-to-low lowering.

Enumerator
LOOMC_TARGET_CONTROL_FLOW_LOWERING_CFG	Lower source structured control flow to explicit CFG before source-to-low.
LOOMC_TARGET_CONTROL_FLOW_LOWERING_STRUCTURED_LOW	Preserve supported structured control flow into target-low IR.

loomc_target_fact_state_t

enum loomc_target_fact_state_t

Three-valued target fact state.

Target profiles distinguish unavailable, available, and not-yet-known facts because partial targets are valid inputs. Unknown is not false: a later live probe, saved profile, or user override may refine it.

Enumerator
LOOMC_TARGET_FACT_STATE_UNKNOWN	No fact has been supplied yet.
LOOMC_TARGET_FACT_STATE_FALSE	The fact is known to be unavailable or false.
LOOMC_TARGET_FACT_STATE_TRUE	The fact is known to be available or true.

loomc_target_pipeline_kind_t

enum loomc_target_pipeline_kind_t

Target lowering pipeline boundary.

Enumerator
LOOMC_TARGET_PIPELINE_KIND_PREPARED_LOW	Lower source/kernel IR to target-low IR prepared for target emission.
LOOMC_TARGET_PIPELINE_KIND_SOURCE_LOW	Lower source/kernel IR to target-low IR before target ABI/resource materialization and packetization preparation.

Function Documentation

loomc_pass_program_create_from_target_pipeline()

loomc_status_t loomc_pass_program_create_from_target_pipeline	(	loomc_context_t *	context,
		const loomc_target_pipeline_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_pass_program_t **	out_pass_program,
		loomc_result_t **	out_result )

Creates a prepared target lowering pass program.

The context must have been created with a target environment using loomc_context_target_options_t. The returned pass program is an ordinary loomc_pass_program_t and is passed to loomc_compile_module like any other prepared pipeline.

Parameters

context	Context whose target environment selects the target package.
options	Target pipeline options, or NULL for defaults.
allocator	Host allocator used for pass-program and result storage.
out_pass_program	Receives one retained pass program when the result succeeds. Receives NULL when target pipeline preparation fails.
out_result	Receives a retained result containing pipeline preparation diagnostics and operation state.

Returns

OK when the creation operation 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 pass program is produced, the caller owns the returned reference and releases it with loomc_pass_program_release.

Thread safety

The returned pass program is immutable and may be shared across worker threads.

Sanitizer Assertions

loomc_sanitizer_options_t may be attached to loomc_target_pipeline_options_t::next. Nonzero check bits insert sanitizer pass slots at the target pipeline's semantic assertion boundary.

loomc_target_environment_create()

loomc_status_t loomc_target_environment_create	(	loomc_host_size_t	environment_count,
		loomc_target_environment_t *const *	environments,
		loomc_allocator_t	allocator,
		loomc_target_environment_t **	out_target_environment )

Creates one immutable environment from explicitly selected target packages.

The result retains every input environment and includes each identical provider contribution once, in first-occurrence order. Distinct providers claiming the same target family or artifact format are rejected. An empty list creates an environment with no target providers. The input array is borrowed only for this call; no element may be NULL.

Create profiles against the resulting environment before using them with its contexts and compilers. Composition does not change the compatibility domain of profiles previously created against an input environment.

Parameters

environment_count	Number of input target environments.
environments	Input environments to compose. May be NULL when environment_count is zero.
allocator	Host allocator used for target-environment storage.
out_target_environment	Receives one retained environment on success, or NULL on failure.

Returns

OK when the target environment was created.

Ownership

The caller releases the returned reference with loomc_target_environment_release. The result retains the input environments without transferring the caller's references.

loomc_target_environment_release()

void loomc_target_environment_release

(

loomc_target_environment_t *

target_environment

)

Releases a target environment from one owner.

Parameters

target_environment

Target environment to release. Passing NULL is allowed.

Thread safety

Retain/release operations are safe from multiple threads. The environment is destroyed when the final reference is released.

loomc_target_environment_retain()

void loomc_target_environment_retain

(

loomc_target_environment_t *

target_environment

)

Retains a target environment for another owner.

Parameters

target_environment

Target environment to retain.

Thread safety

Retain/release operations are safe from multiple threads.

loomc_target_profile_release()

void loomc_target_profile_release

(

loomc_target_profile_t *

profile

)

Releases a target profile from one owner.

Parameters

profile

Target profile to release. Passing NULL is allowed.

Thread safety

Retain/release operations are safe from multiple threads. The profile is destroyed when the final reference is released.

loomc_target_profile_retain()

void loomc_target_profile_retain

(

loomc_target_profile_t *

profile

)

Retains a target profile for another owner.

Parameters

profile

Target profile to retain.

Thread safety

Retain/release operations are safe from multiple threads.

loomc_target_profile_select()

loomc_status_t loomc_target_profile_select	(	loomc_target_environment_t *	target_environment,
		loomc_string_view_t	specification,
		loomc_allocator_t	allocator,
		loomc_target_profile_t **	out_profile )

Selects a complete named profile from a target environment.

The specification uses Loom's family:selector spelling, such as vm:core or wasm:simd128. The target environment must contain exactly one provider for the named family, and that provider must expose the named process-lifetime profile. This operation performs no hardware discovery.

Parameters

target_environment	Environment containing the target family.
specification	Complete family:selector target specification. The view need not be NUL-terminated.
allocator	Host allocator used for profile-handle storage.
out_profile	Receives one retained profile on success.

Returns

OK when the profile was selected; invalid argument for malformed or unavailable families, not found for an unknown family-owned selector, and unimplemented when the family has no named profiles.

Ownership

The caller releases the returned reference with loomc_target_profile_release. The handle copies the specification and retains the target environment. It borrows immutable process-lifetime target facts owned by the selected provider.