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_specialization_options_t
	Option extension carrying per-function target specializations. 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.
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.
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 per-function specialization rows. This lets a JIT share cached device profiles across worker threads while independently choosing the exact target of every function version 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_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.