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.
typedef uint32_t	loomc_source_to_low_diagnostic_flags_t
	Bitmask of loomc_source_to_low_diagnostic_flag_bits_t values.

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 , LOOMC_TARGET_PIPELINE_KIND_SOURCE_LOW_ARTIFACTS = 2 }
	Target lowering pipeline boundary. More...
enum	loomc_source_to_low_diagnostic_flag_bits_t { LOOMC_SOURCE_TO_LOW_DIAGNOSTIC_MEMORY_ACCESS = 1u << 0 , LOOMC_SOURCE_TO_LOW_DIAGNOSTIC_OPERAND_FORM = 1u << 1 , LOOMC_SOURCE_TO_LOW_DIAGNOSTIC_ALL }
	Optional source-to-low diagnostic flag bits. 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.
loomc_status_t	loomc_target_profile_refine_execution_unit_count (loomc_target_profile_t *base_profile, uint32_t execution_unit_count, loomc_allocator_t allocator, loomc_target_profile_t **out_profile)
	Refines a complete profile with a known deployment execution-unit count.
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.
bool	loomc_target_profile_equal (const loomc_target_profile_t *lhs, const loomc_target_profile_t *rhs)
	Compares exact immutable profile inputs without allocating or compiling.
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.
loomc_host_size_t	loomc_target_environment_artifact_format_count (const loomc_target_environment_t *target_environment)
	Returns the number of public artifact formats in a target environment.
loomc_string_view_t	loomc_target_environment_artifact_format_at (const loomc_target_environment_t *target_environment, loomc_host_size_t ordinal)
	Returns a public artifact format by ordinal.
loomc_host_size_t	loomc_target_environment_target_family_count (const loomc_target_environment_t *target_environment)
	Returns the number of target families in a target environment.
loomc_string_view_t	loomc_target_environment_target_family_at (const loomc_target_environment_t *target_environment, loomc_host_size_t ordinal)
	Returns a target family name by ordinal.
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_source_to_low_diagnostic_flag_bits_t

enum loomc_source_to_low_diagnostic_flag_bits_t

Optional source-to-low diagnostic flag bits.

Enumerator
LOOMC_SOURCE_TO_LOW_DIAGNOSTIC_MEMORY_ACCESS	Emit target source-memory decision remarks, including access, cache-policy, and prefetch selection when supported by the target.
LOOMC_SOURCE_TO_LOW_DIAGNOSTIC_OPERAND_FORM	Emit target operand-form selection remarks when supported by the target.
LOOMC_SOURCE_TO_LOW_DIAGNOSTIC_ALL	All source-to-low diagnostic flags known to this header.

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.
LOOMC_TARGET_PIPELINE_KIND_SOURCE_LOW_ARTIFACTS	Lower source/kernel IR to target-low IR prepared for human-facing target-low assembly printing. This stops at the source-low boundary while allowing targets to remove generated-only presentation artifacts.

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

loomc_string_view_t loomc_target_environment_artifact_format_at	(	const loomc_target_environment_t *	target_environment,
		loomc_host_size_t	ordinal )

Returns a public artifact format by ordinal.

Parameters

target_environment	Environment to inspect.
ordinal	Zero-based artifact format ordinal.

Returns

Borrowed artifact format name, or an empty view when ordinal is out of range.

Lifetime

The returned view remains valid while target_environment is retained.

loomc_target_environment_artifact_format_count()

loomc_host_size_t loomc_target_environment_artifact_format_count

(

const loomc_target_environment_t *

target_environment

)

Returns the number of public artifact formats in a target environment.

Each format names one linked emitter and may be passed to artifact-emission APIs. Formats preserve target provider composition order.

Parameters

target_environment

Environment to inspect, or NULL.

Returns

Artifact format count, or zero for a NULL environment.

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

loomc_string_view_t loomc_target_environment_target_family_at	(	const loomc_target_environment_t *	target_environment,
		loomc_host_size_t	ordinal )

Returns a target family name by ordinal.

Parameters

target_environment	Environment to inspect.
ordinal	Zero-based target family ordinal.

Returns

Borrowed target family name, or an empty view when ordinal is out of range.

Lifetime

The returned view remains valid while target_environment is retained.

loomc_target_environment_target_family_count()

loomc_host_size_t loomc_target_environment_target_family_count

(

const loomc_target_environment_t *

target_environment

)

Returns the number of target families in a target environment.

Each family names one linked target profile provider. Families preserve target provider composition order. Family-owned profile selectors are not enumerated by this target-neutral query.

Parameters

target_environment

Environment to inspect, or NULL.

Returns

Target family count, or zero for a NULL environment.

loomc_target_profile_equal()

bool loomc_target_profile_equal	(	const loomc_target_profile_t *	lhs,
		const loomc_target_profile_t *	rhs )

Compares exact immutable profile inputs without allocating or compiling.

Equal profiles have compatible compiler environments, identical diagnostic identifiers, and identical common and family-specific facts, including unknown or explicitly supplied fields. This is stronger than executable compatibility: a stronger target is not equal to a weaker one. NULL equals only NULL. The query is safe from multiple threads.

Profiles are only one part of a compilation identity. Reusing artifacts also requires identical sources, roots, compiler configuration, and emit options.

Parameters

lhs	First profile to compare, or NULL. Borrowed for this call.
rhs	Second profile to compare, or NULL. Borrowed for this call.

Returns

True when the profiles have equal immutable inputs or both are NULL; false otherwise.

loomc_target_profile_refine_execution_unit_count()

loomc_status_t loomc_target_profile_refine_execution_unit_count	(	loomc_target_profile_t *	base_profile,
		uint32_t	execution_unit_count,
		loomc_allocator_t	allocator,
		loomc_target_profile_t **	out_profile )

Refines a complete profile with a known deployment execution-unit count.

The count describes available units in the deployment scope, such as a queue's selected CUs or SMs. It is not kernel occupancy or a workgroup budget. Unknown capacity is represented by leaving the profile unrefined. A count supplied here must be nonzero and agree with any count already in the profile. Named architecture profiles ordinarily leave this fact unknown.

Parameters

base_profile	Complete profile to refine, borrowed for this call.
execution_unit_count	Known available execution-unit count.
allocator	Host allocator used for the refined profile.
out_profile	Receives one retained immutable profile on success.

Returns

OK on success, invalid argument for an incomplete profile, zero count, or conflicting count, and an allocation failure if storage is needed.

Ownership

Refinement preserves all common and family-specific facts without mutating the base. The result retains its backing storage independently of the base handle's caller. Release the result with loomc_target_profile_release.

Thread safety

Refinement may run concurrently with queries or other refinements.

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.