v.ssa #

Copyright (c) 2026 Alexander Medvednikov. All rights reserved. Use of this source code is governed by an MIT license that can be found in the LICENSE file.

fn build(a_ &flat.FlatAst) &Module

build supports build handling for ssa.

fn build_with_options(a_ &flat.FlatAst, used_fns map[string]bool, tc &types.TypeChecker, opts BuildOptions) &Module

build_with_options builds with options data for ssa.

fn build_with_used(a_ &flat.FlatAst, used_fns map[string]bool, tc &types.TypeChecker) &Module

build_with_used builds with used data for ssa.

fn parse_native_inline_asm(source string) ?InlineAsmSpec

parse_native_inline_asm lowers the preserved raw source of an asm block into an InlineAsmSpec. The grammar mirrors the C backend's parser in v.gen.c.stmt (sections split on unquoted ;, [alias] constraint (expr) operand entries): it stays text-based, because V assembly is line-sensitive and cannot be reconstructed from the token stream alone.

fn AtomicOrdering.from[W](input W) !AtomicOrdering

from returns the AtomicOrdering value of an integer or of a field name, or an error if there is none.

fn CallConv.from[W](input W) !CallConv

from returns the CallConv value of an integer or of a field name, or an error if there is none.

fn InlineHint.from[W](input W) !InlineHint

from returns the InlineHint value of an integer or of a field name, or an error if there is none.

fn Linkage.from[W](input W) !Linkage

from returns the Linkage value of an integer or of a field name, or an error if there is none.

fn Module.new() &Module

new creates a Module value for ssa.

fn OpCode.from[W](input W) !OpCode

from returns the OpCode value of an integer or of a field name, or an error if there is none.

fn TypeKind.from[W](input W) !TypeKind

from returns the TypeKind value of an integer or of a field name, or an error if there is none.

fn TypeStore.new() TypeStore

new creates a TypeStore value for ssa.

fn ValueKind.from[W](input W) !ValueKind

from returns the ValueKind value of an integer or of a field name, or an error if there is none.

type BlockID = int

BlockID aliases block id values used by ssa.

type TypeID = int

TypeID aliases type id values used by ssa.

type ValueID = int

ValueID aliases value id values used by ssa.

enum AtomicOrdering {
	not_atomic
	unordered
	monotonic
	acquire
	release
	acq_rel
	seq_cst
}

AtomicOrdering lists atomic ordering values used by ssa.

enum CallConv {
	c_decl
	fast_call
	wasm_std
}

CallConv lists call conv values used by ssa.

enum InlineHint {
	none_  // No hint, let optimizer decide
	always // Always inline (e.g. V's [inline] attribute)
	never  // Never inline (e.g. V's [noinline] attribute)
	hint   // Suggest inlining (optimizer may ignore)
}

InlineHint lists inline hint values used by ssa.

enum Linkage {
	external
	private
	internal
}

Linkage lists linkage values used by ssa.

enum OpCode {
	// Terminators
	ret
	br
	jmp
	switch_ // Multi-way branch: switch_ %val, default_block, [case_val, block]...
	unreachable
	// Binary (integer)
	add
	sub
	mul
	sdiv
	srem
	udiv
	urem
	// Binary (float)
	fadd
	fsub
	fmul
	fdiv
	frem
	// Bitwise
	shl
	ashr
	lshr
	and_
	or_
	xor
	// Memory
	alloca
	load
	store
	get_element_ptr
	heap_alloc // Heap allocate memory for a type (malloc+zero): returns ptr
	fence      // Memory ordering barrier
	cmpxchg    // Atomic compare-exchange
	atomicrmw  // Atomic read-modify-write
	// Comparisons
	lt
	gt
	le
	ge
	ult
	ugt
	ule
	uge
	eq
	ne
	// Other
	call
	call_indirect // Indirect call through function pointer
	call_sret     // Call with struct return (x8 indirect return on ARM64)
	neg
	trunc
	sext
	zext
	fptoui
	fptosi
	uitofp
	sitofp
	bitcast
	phi
	select
	inline_asm         // Inline assembly block for the target ISA
	assign             // Copy op used during phi elimination
	inline_string_init // Build a string struct by value: (string){str, len}
	// Concurrency
	go_call    // Launch goroutine: go_call fn_ref, args...
	spawn_call // Launch OS thread: spawn_call fn_ref, args...
	// Aggregate (struct/tuple) operations
	extractvalue
	insertvalue
	struct_init
}

OpCode lists op code values used by ssa.

enum TypeKind {
	void_t
	int_t
	float_t
	ptr_t
	array_t
	struct_t
	func_t
	label_t
	metadata_t
}

TypeKind lists type kind values used by ssa.

enum ValueKind {
	unknown
	constant
	argument
	global
	instruction
	phi_result
	basic_block
	string_literal   // V string struct literal (by value)
	c_string_literal // C string literal (raw char pointer)
	func_ref
}

ValueKind lists value kind values used by ssa.

struct BasicBlock {
pub mut:
	id     BlockID
	val_id ValueID // SSA value representing the block (0 in v3's raw-block-id model)
	name   string
	parent int
	instrs []ValueID
	preds  []BlockID
	succs  []BlockID
	// Dominators
	idom     BlockID
	dom_tree []BlockID
}

BasicBlock represents basic block data used by ssa.

struct BuildOptions {
pub:
	hot_fn                 string   // build only this function's body (hot reload)
	skip_fn_bodies         bool     // register signatures only, mark them prototypes
	skip_modules           []string // skip all functions declared in these modules
	track_uses             bool = true            // build optimizer/verifier use lists
	thread_stack_size      int  = 8 * 1024 * 1024 // zero uses the pthread default
	test_files             []string                     // driver-selected test file paths; enables a test entrypoint
	test_run_only          []string                     // bare or qualified function-name globs
	target                 TargetData                   // target memory layout, defaults to 64-bit pointers
	source_modules         map[string]string            // source filename -> full module path
	source_imports         map[string]map[string]string // source filename -> import alias -> full module path
	exact_used_fns         bool                         // materialize only source functions listed in used_fns
	allow_missing_fn_stubs bool                         // native compile-only fallback for checker-validated calls
	use_native_c_sources   bool                         // link V-shipped C implementations instead of SSA replacements
}

BuildOptions controls which functions a build materializes. The zero value reproduces the default whole-program build.

struct Builder {
mut:
	m                  &Module            = unsafe { nil }
	a                  &flat.FlatAst      = unsafe { nil }
	tc                 &types.TypeChecker = unsafe { nil }
	used_fns           map[string]bool
	used_fn_normalized map[string]bool
	used_fn_suffixes   map[string]bool
	cur_module         string
	cur_func           int
	cur_func_ret_type  u32
	cur_block          BlockID
	vars               map[string]ValueID
	global_vars        map[string]ValueID
	global_type_names  flat.TypeTextBindings
	global_imports     map[string]string
	global_aliases     map[string]string
	var_type_names     flat.TypeTextBindings
	// C extern declarations shadowed by the freestanding runtime's own
	// `@[export]` functions (C name -> the internal V fn's SSA name).
	export_fn_c_names map[string]string
	// Every V function declaration's SSA name, so a C name that a V function
	// already owns is never rebound to an exported body.
	v_fn_decl_names          map[string]bool
	mut_pointer_params       map[string]TypeID
	mut_param_names          map[string]bool
	sum_guard_variants       map[ValueID]u32
	i64_type                 TypeID
	i32_type                 TypeID
	i8_type                  TypeID
	i1_type                  TypeID
	u64_type                 TypeID
	u32_type                 TypeID
	u16_type                 TypeID
	u8_type                  TypeID
	f32_type                 TypeID
	f64_type                 TypeID
	void_type                TypeID
	str_type                 TypeID
	array_type               TypeID
	map_type                 TypeID
	map_state_type           TypeID
	wide_int_type            TypeID
	fn_types                 map[string]TypeID
	fn_ids                   map[string]int
	const_exprs              map[string]flat.NodeId
	native_initializers      map[string]NativeInitializer
	native_initializer_order []string
	// Exact declaration and tuple C spellings index SSA layouts; the values belong
	// to this module's distinct semantic TypeID namespace.
	struct_types             map[u32]TypeID
	multi_return_types       map[u32]TypeID
	multi_return_field_types map[u32]map[string]u32
	ssa_type_names           map[TypeID]string
	interface_types          map[string]TypeID
	interface_type_names     map[TypeID]string
	sum_types_registering    map[TypeID]bool
	struct_field_types       flat.TypeTextBindings
	struct_field_defaults    map[string]NativeFieldDefault
	struct_embeds            map[TypeID][]int
	default_struct_types     map[TypeID]bool
	option_types             map[u32]TypeID
	sum_type_variants        flat.SourceTypeListBindings
	sum_type_canonical       flat.SourceTypeBindings
	enum_types               map[u32]bool
	flag_enum_types          map[u32]bool
	enum_values              map[string]int
	enum_member_values       map[string]int
	enum_member_dupes        map[string]bool
	c_fn_ids                 map[string]int
	c_fn_types               map[string]TypeID
	label_blocks             map[string]BlockID
	defer_body_ids           []flat.NodeId
	defer_active_slots       map[flat.NodeId]ValueID
	pending_loop_label       string
	loop_targets             []LoopTargets
	top_level_main           bool
	thread_stack_size        int
	source_fn_names          map[string]bool
	runtime_fn_ids           map[string]int
	runtime_fn_types         map[string]TypeID
	break_targets            []BlockID
	continue_targets         []BlockID
	break_labels             map[string]BlockID
	continue_labels          map[string]BlockID
	// --- Build-control machinery (ported from v2 build_all) ---
	// When set, build_functions only materializes this one function body (hot reload).
	hot_fn string
	// When set, build_functions registers signatures only and marks them prototypes.
	skip_fn_bodies bool
	// When non-empty, all functions declared in these modules are skipped (dead
	// code elimination for unused backends/modules).
	skip_modules map[string]bool
	// SSA-level source spelling ID -> resolved base TypeID. Supplements the checker's
	// alias map (used when building without a checker).
	type_aliases map[u32]TypeID
	// File-scoped names preserve distinct nested modules that share a leaf name.
	source_modules         map[string]string
	source_imports         map[string]map[string]string
	exact_used_fns         bool
	allow_missing_fn_stubs bool
	use_native_c_sources   bool
}

Builder stores state for SSA construction.

fn (value &Builder) cur_func_ret_type_text() string

cur_func_ret_type_text resolves the indexed source type spelling.

struct ConstantData {
pub:
	int_val   i64
	float_val f64
	str_val   string
}

ConstantData carries the typed payload of a constant value. It mirrors v2's representation so backends can recover the original int/float/string value instead of re-parsing Value.name.

struct FuncSSAData {
pub:
	func_idx int       // index into the main module's funcs[]
	blocks   []BlockID // worker-local block ids
	params   []ValueID // worker-local param value ids
}

FuncSSAData holds the SSA a worker produced for a single function.

struct Function {
pub mut:
	id             int
	name           string
	typ            TypeID
	blocks         []BlockID
	params         []ValueID
	is_c_extern    bool // C-language extern function (no V body)
	is_variadic    bool
	variadic_start int
	is_prototype   bool // Registered declaration/signature whose body is not materialized yet
	linkage        Linkage
	call_conv      CallConv
}

Function represents function data used by ssa.

struct GlobalVar {
pub mut:
	name          string
	typ           TypeID
	linkage       Linkage
	alignment     int
	is_constant   bool
	initial_value i64  // For constants/enums, the initial integer value
	initial_data  []u8 // For constant arrays: serialized element data
}

GlobalVar represents global var data used by ssa.

struct InlineAsmIO {
pub:
	alias       string
	constraint  string
	child_index int
}

InlineAsmIO describes one inline-asm input or output operand: the constraint string as written (for example =r, 0, D, g) and the block template alias that instructions reference. child_index names the .asm_stmt's parsed expression child in source order (outputs first, then inputs).

struct InlineAsmSpec {
pub:
	arch        string // canonical arch of the block as named in the source
	is_volatile bool
	is_intel    bool
	is_raw      bool
	insts       []string      // template lines, one per instruction
	ios         []InlineAsmIO // outputs then inputs, in source order
	clobbered   []string
}

InlineAsmSpec lowers one asm block into a target-neutral description the native emitters can consume. Instructions stay as written in the V source, so the structured "destination-first" operand syntax survives; every operand reference names an InlineAsmIO by its alias.

fn (spec &InlineAsmSpec) asm_output_alias() string

asm_output_alias finds the declared alias for the first output operand, the value an inline_asm instruction defines.

fn (spec &InlineAsmSpec) asm_input_start() int

asm_input_start returns the index of the first input operand in spec.ios.

fn (spec &InlineAsmSpec) asm_input_count() int

asm_input_count returns how many input operands spec.ios declares. The builder stores that many input values before the secondary-output pointers, so it is the offset of the first pointer operand; asm_input_start is the output count.

struct Instruction {
pub mut:
	op         OpCode
	operands   []ValueID
	block      BlockID
	typ        TypeID
	pos        token.Pos
	atomic_ord AtomicOrdering
	inline     InlineHint // Inline hint for call instructions
	asm_id     int        // Inline-asm spec: 1-based index into Module.asm_specs, 0 = none
}

Instruction represents instruction data used by ssa.

fn (i &Instruction) is_block_operand(idx int) bool

is_block_operand reports whether operand idx names a basic block rather than an SSA value. Keep all mixed-layout instruction knowledge here so CFG, optimizer, verifier, and worker code cannot disagree about operand roles.

fn (i &Instruction) is_value_operand(idx int) bool

is_value_operand reports whether operand idx names an SSA value.

fn (i &Instruction) is_definition_operand(idx int) bool

is_definition_operand reports whether operand idx is defined by an instruction rather than read by it. Phi lowering represents copies as assign destination, source, so the destination must never participate in use lists or replacement walks.

fn (i &Instruction) is_successor_operand(idx int) bool

is_successor_operand reports whether operand idx is a CFG successor. Phi block operands are predecessors, so they intentionally do not match here.

struct Module {
pub mut:
	name string
	// errors contains unsupported source expressions encountered during SSA construction.
	errors     []string
	target     TargetData
	track_uses bool = true
	type_store TypeStore
	values     []Value
	instrs     []Instruction
	blocks     []BasicBlock
	funcs      []Function
	globals    []GlobalVar
	// C struct names: TypeID -> C struct name (e.g. for `struct stat`). Used by
	// codegen to emit `typedef struct <name> ...;` and preserve the C layout.
	c_struct_names map[int]string
	// C structs marked @[typedef] — already a C typedef, not a struct tag.
	c_typedef_structs map[int]bool
	// Constant cache: "type:name" -> ValueID for deduplication.
	const_cache map[string]ValueID
	// Inline-asm block specs lowered from V `asm` sources. The field is
	// separate so no instruction carries its whole spec; see asm_id.
	asm_specs []InlineAsmSpec
	// Freestanding `@[export]` shadow table: C name -> the internal V fn's
	// SSA name. Native codegen resolves libc-shaped calls against the binary's
	// own bodies with this instead of an undefined reference.
	export_c_names map[string]string
mut:
	// Layout queries are hot in both SSA construction and native codegen. Keep
	// their scratch and completed sizes on the module instead of allocating two
	// type-table-sized arrays for every query.
	type_size_cache    []int
	type_size_visiting []bool
	type_align_cache   []int
	field_offset_cache map[u64]int
	field_size_cache   map[u64]int
	type_layout_frozen bool
}

Module represents module data used by ssa.

fn (m &Module) asm_spec(instr &Instruction) ?&InlineAsmSpec

asm_spec resolves the spec an inline_asm instruction points at. The id is 1-based so the zero value means "no spec" without a lookup.

fn (mut m Module) add_inline_asm_spec(spec InlineAsmSpec) int

add_inline_asm_spec registers a parsed asm block and returns its 1-based id.

fn (mut m Module) instruction_set_asm_id(val_id ValueID, spec_id int)

instruction_set_asm_id attaches an inline-asm spec id to the instruction that defines val_id. asm_id is 1-based; 0 leaves the spec unset.

fn (mut m Module) release_codegen_analysis_metadata()

release_codegen_analysis_metadata drops SSA analysis data that direct backends do not read. Keeping a use-list allocation for every value through large native self-host emission can otherwise retain several gigabytes after the optimizer has finished.

fn (mut m Module) add_value(kind ValueKind, typ TypeID, name string, index int) ValueID

add_value updates add value state for Module.

fn (mut m Module) add_instr(op OpCode, block BlockID, typ TypeID, operands []ValueID) ValueID

add_instr updates add instr state for Module.

fn (mut m Module) add_instr_front(op OpCode, block BlockID, typ TypeID, operands []ValueID) ValueID

add_instr_front creates an instruction and prepends it to the block (used for phi insertion by mem2reg, which requires phis at the top of a block).

fn (mut m Module) append_phi_operands(phi_val_id ValueID, val ValueID, block_id BlockID)

append_phi_operands appends a (val, block_id) pair to a phi instruction.

fn (mut m Module) remove_value_user(value_id ValueID, user_id ValueID)

remove_value_user removes one instruction from a value's unique user list.

fn (mut m Module) add_value_user(value_id ValueID, user_id ValueID)

add_value_user records one instruction in a value's unique user list.

fn (mut m Module) rewrite_instruction(value_id ValueID, op OpCode, operands []ValueID)

rewrite_instruction changes an instruction while maintaining its value-use edges. CFG edges remain the responsibility of callers that change a terminator; they can rebuild or update the CFG once after batching edits.

fn (mut m Module) detach_instruction_uses(value_id ValueID)

detach_instruction_uses removes every use edge contributed by an instruction that is about to leave its block.

fn (mut m Module) discard_emission_since(value_count int, instruction_count int, block_count int)

discard_emission_since removes transient SSA emitted after the supplied module sizes while retaining type registrations performed during parsing.

fn (mut m Module) add_block(func_id int, name string) BlockID

add_block updates add block state for Module.

fn (mut m Module) new_function(name string, ret TypeID) int

new_function supports new function handling for Module.

fn (mut m Module) add_function(name string, ret TypeID) int

add_function appends a function when the caller already maintains a unique name index and therefore does not need new_function's linear duplicate scan.

fn (mut m Module) func_add_param(func_id int, param_val ValueID)

func_add_param supports func add param handling for Module.

fn (mut m Module) func_set_c_extern(func_id int, val bool)

func_set_c_extern supports func set c extern handling for Module.

fn (mut m Module) func_set_prototype(func_id int, val bool)

func_set_prototype supports func set prototype handling for Module.

fn (mut m Module) block_add_succ(from BlockID, to BlockID)

block_add_succ supports block add succ handling for Module.

fn (mut m Module) block_add_pred(to BlockID, from BlockID)

block_add_pred supports block add pred handling for Module.

fn (mut m Module) add_global(name string, typ TypeID) ValueID

add_global updates add global state for Module.

fn (mut m Module) add_global_with_data(name string, elem_type TypeID, is_const bool, data []u8) ValueID

add_global_with_data registers a private global initialized from raw bytes (used for const arrays serialized to element data).

fn (mut m Module) add_external_global(name string, typ TypeID) ValueID

add_external_global registers (or reuses) a global defined outside this module (e.g. C runtime globals such as __stdoutp). Returns the global pointer value.

fn (mut m Module) get_or_add_const(typ TypeID, name string) ValueID

get_or_add_const returns get or add const data for Module.

fn (m &Module) get_block_from_val(val_id int) int

get_block_from_val converts a basic-block value operand to its block index.

fn (m &Module) type_size(typ_id TypeID) int

type_size returns the byte size for an SSA type on the current target.

fn (m &Module) freeze_type_layouts()

freeze_type_layouts precomputes layout data so concurrent code generators can query it without mutating the shared module.

fn (m &Module) type_align(typ_id TypeID) int

type_align returns the ABI alignment for an SSA type on the current target.

fn (mut m Module) replace_uses(old_id ValueID, new_id ValueID)

replace_uses supports replace uses handling for Module.

fn (m &Module) struct_field_offset(typ_id TypeID, field_idx int) int

struct_field_offset returns the byte offset of a field in a struct type.

fn (m &Module) struct_field_size(typ_id TypeID, field_idx int) int

struct_field_size returns the byte size of a field in a struct type.

fn (mut m Module) new_worker_module() &Module

new_worker_module creates a lightweight Module for parallel SSA building. The worker gets a deep copy of the type store and is seeded with the main module's values/instrs/blocks so ids produced in earlier (serial) phases stay valid.

fn (mut m Module) merge_worker_module(w &Module, func_data []FuncSSAData, seed_values int, seed_instrs int, seed_blocks int, seed_types int, seed_funcs int)

merge_worker_module folds a worker's freshly-built SSA (everything beyond the seed lengths) back into the main module, remapping type/value/instr/block/func ids. func_data carries each built function's worker-local blocks/params.

struct TargetData {
pub:
	ptr_size      int  = 8
	endian_little bool = true
	// os / arch are the target (pref.Target.os: 'linux', 'macos', ...;
	// .arch: 'amd64', 'arm64'); empty means the compiler host, for callers
	// that never cross-compile.
	os   string
	arch string
}

TargetData represents target data data used by ssa.

fn (t TargetData) is_linux() bool

is_linux reports whether the target OS is Linux. The native libc ABI overrides (struct stat/dirent/flock offsets, errno and stdio symbols) follow the target, so a Linux-hosted compiler emitting a macOS binary gets Darwin's layouts.

struct Type {
pub:
	kind        TypeKind
	width       int
	is_unsigned bool
	elem_type   TypeID // For Ptr, Array
	len         int    // For Array
	fields      []TypeID
	field_names []string
	params      []TypeID
	ret_type    TypeID
	is_c_struct bool // True for C interop structs (raw field names, typedef to C struct)
	is_union    bool // True for union types (all fields overlap at offset 0)
	is_packed   bool // True when struct fields have byte alignment
	alignment   int  // Explicit aggregate alignment in bytes; 0 uses the natural alignment
}

Type represents type data used by ssa.

struct TypeStore {
pub mut:
	types []Type
	cache map[string]TypeID
}

TypeStore represents type store data used by ssa.

fn (mut ts TypeStore) get_int(width int) TypeID

get_int returns get int data for TypeStore.

fn (mut ts TypeStore) get_uint(width int) TypeID

get_uint returns get uint data for TypeStore.

fn (mut ts TypeStore) get_float(width int) TypeID

get_float returns get float data for TypeStore.

fn (mut ts TypeStore) get_ptr(elem TypeID) TypeID

get_ptr returns get ptr data for TypeStore.

fn (mut ts TypeStore) get_array(elem TypeID, length int) TypeID

get_array returns the cached fixed-array type for (elem, length).

fn (mut ts TypeStore) get_tuple(elem_types []TypeID) TypeID

get_tuple returns a cached anonymous struct type holding the given element types.

fn (mut ts TypeStore) register(t Type) TypeID

register supports register handling for TypeStore.

struct Value {
pub mut:
	id    ValueID
	kind  ValueKind
	typ   TypeID
	name  string
	index int
	uses  []ValueID
}

Value represents value data used by ssa.