launch_config.h File Reference

Compiled kernel launch configurations. More...

Go to the source code of this file.

Data Structures
struct	loomc_launch_config_function_t
	Program-local launch-config function token. More...
struct	loomc_launch_config_t
	Complete concrete configuration for one compiled kernel launch. More...

Macros
#define	LOOMC_LAUNCH_CONFIG_FUNCTION_INVALID_VALUE   UINT64_MAX
	Invalid launch-config function token value.

Typedefs
typedef struct loomc_launch_config_program_t	loomc_launch_config_program_t
	Loaded program containing compiled kernel launch configurations.

Functions
loomc_status_t	loomc_launch_config_program_load (const loomc_artifact_t *artifact, loomc_artifact_release_fn_t release, void *release_user_data, loomc_allocator_t allocator, loomc_launch_config_program_t **out_program)
	Loads and verifies a compiled launch-config program.
void	loomc_launch_config_program_retain (loomc_launch_config_program_t *program)
	Retains program for another owner.
void	loomc_launch_config_program_release (loomc_launch_config_program_t *program)
	Releases program from one owner.
loomc_status_t	loomc_launch_config_program_lookup_function (const loomc_launch_config_program_t *program, loomc_string_view_t export_name, loomc_launch_config_function_t *out_function)
	Resolves a compiled kernel export name to a program-local function token.
loomc_status_t	loomc_launch_config_program_invoke (loomc_launch_config_program_t *program, loomc_launch_config_function_t function, const uint64_t *workload_argument_bits, loomc_host_size_t workload_argument_count, loomc_launch_config_t *out_config)
	Invokes one compiled launch-config function for one kernel workload.

Detailed Description

Compiled kernel launch configurations.

A launch-config program is the host companion produced by one kernel compilation invocation. It contains one function for each exported kernel and evaluates that kernel's authored workload arguments into the complete configuration required to launch the matching compiled entry.

Launch-config programs are compiler products. Loading and invocation do not parse kernel source, apply configuration, select a target, or compile device code. All such decisions were made when the compiled kernel module and its companion launch-config artifact were produced.

Example

Bind a compiled kernel and evaluate its launch configuration:

loomc_launch_config_program_t* launch_program = NULL;
loomc_status_t status = loomc_launch_config_program_load(
    launch_config_artifact, /*release=*/NULL,
    /*release_user_data=*/NULL, loomc_allocator_system(), &launch_program);
if (!loomc_status_is_ok(status)) return status;
 
loomc_launch_config_function_t launch_function =
    loomc_launch_config_function_invalid();
status = loomc_launch_config_program_lookup_function(
    launch_program, kernel_export_name, &launch_function);
if (!loomc_status_is_ok(status)) {
  loomc_launch_config_program_release(launch_program);
  return status;
}
 
const uint64_t workload_argument_bits[] = {element_count};
loomc_launch_config_t launch_config = {
    .type = LOOMC_STRUCTURE_TYPE_LAUNCH_CONFIG,
    .structure_size = sizeof(launch_config),
};
status = loomc_launch_config_program_invoke(
    launch_program, launch_function, workload_argument_bits,
    /*workload_argument_count=*/1, &launch_config);
if (loomc_status_is_ok(status)) {
  // Use launch_config to populate the target launch ABI for the compiled
  // executable entry identified by kernel_export_name.
}
 
loomc_launch_config_program_release(launch_program);
return status;

Typedef Documentation

loomc_launch_config_program_t

typedef struct loomc_launch_config_program_t loomc_launch_config_program_t

Loaded program containing compiled kernel launch configurations.

A program corresponds to one kernel compilation invocation and may describe entries later emitted across multiple executable artifacts. Function names match the public export names in those artifacts; launch-config function tokens and executable function tokens remain local to their respective objects.

Thread safety

Programs are thread-compatible. Invocation reuses program-owned scratch and must not overlap another invocation on the same program. Callers requiring overlapping invocation use distinct loaded programs or externally synchronize access.

Function Documentation

loomc_launch_config_program_invoke()

loomc_status_t loomc_launch_config_program_invoke	(	loomc_launch_config_program_t *	program,
		loomc_launch_config_function_t	function,
		const uint64_t *	workload_argument_bits,
		loomc_host_size_t	workload_argument_count,
		loomc_launch_config_t *	out_config )

Invokes one compiled launch-config function for one kernel workload.

Workload arguments map positionally to the selected kernel entry's authored launch workload. Each slot contains the raw bits of one scalar argument in its least-significant N bits, where N is the scalar bit width; higher bits are ignored. Signed integers and index values use two's-complement representation, offsets use unsigned representation, and floating-point values use their declared FP8, IEEE, or bfloat representation. Index and offset arguments consume all 64 bits. An offset greater than INT64_MAX cannot be represented by the current exact-fact domain and is rejected.

The function token must have been returned by program. Invocation validates argument count, scalar values, and authored value predicates before writing out_config. A successful return provides every launch property required by the compiled kernel entry. The operation performs no source compilation or string lookup. The program caches invocation scratch; an invocation may acquire allocator storage when the selected function requires more scratch than previous invocations.

Parameters

program	Loaded launch-config program.
function	Program-local function to invoke.
workload_argument_bits	Positional raw scalar argument bits, or NULL when workload_argument_count is zero.
workload_argument_count	Number of argument slots.
out_config	Caller-initialized complete result storage.

Returns

OK when invocation produced a complete launch configuration.

loomc_launch_config_program_load()

loomc_status_t loomc_launch_config_program_load	(	const loomc_artifact_t *	artifact,
		loomc_artifact_release_fn_t	release,
		void *	release_user_data,
		loomc_allocator_t	allocator,
		loomc_launch_config_program_t **	out_program )

Loads and verifies a compiled launch-config program.

The artifact must be the launch-config companion emitted from the same kernel compilation used to produce the matching executable artifacts. The loader validates the external bytes and constructs a program ready for invocation.

Parameters

artifact	Launch-config artifact to load. The artifact descriptor and its strings are borrowed for the duration of the call.
release	Optional callback transferring ownership of artifact->contents to the loader. When artifact is non-NULL and the callback is provided, it is invoked exactly once before the call returns, regardless of the load status. When omitted, the contents are borrowed only for the duration of the call and the loader materializes or copies all state needed afterward.
release_user_data	Value passed to release.
allocator	Host allocator used for program-owned state.
out_program	Receives one retained program on success.

Returns

OK when the artifact is valid and every exported function has a complete launch-config contract.

Ownership

The caller releases the returned program with loomc_launch_config_program_release.

loomc_launch_config_program_lookup_function()

loomc_status_t loomc_launch_config_program_lookup_function	(	const loomc_launch_config_program_t *	program,
		loomc_string_view_t	export_name,
		loomc_launch_config_function_t *	out_function )

Resolves a compiled kernel export name to a program-local function token.

Parameters

program	Program to search.
export_name	Exact public name of the matching executable entry. A leading @ is not accepted because artifact export names are not Loom symbol references.
out_function	Receives a program-local token on success.

Returns

OK when the function exists, LOOMC_STATUS_NOT_FOUND when the program has no matching function, or an argument status for malformed input.

loomc_launch_config_program_release()

void loomc_launch_config_program_release

(

loomc_launch_config_program_t *

program

)

Releases program from one owner.

Passing NULL is allowed.

Parameters

program

Program to release. Passing NULL is allowed.

loomc_launch_config_program_retain()

void loomc_launch_config_program_retain

(

loomc_launch_config_program_t *

program

)

Retains program for another owner.

Parameters

program

Program to retain.