dymokomi/luce-kernel
Source of release 0.1.1
0.1.1 / src / engine / builder.lucb
# Building a program. The lowering (and tests) call one method per operation; each returns
# its result register. Registers are SSA by default: every result is a fresh register,
# and `assign` is the one way to change a register already written (a variable in a
# masked branch or a loop). A builder's mistakes are sticky: the first is kept, later
# calls do nothing, and `finish` reports it, so the lowering checks once at the end.
## A place in the program for jumps; `bind` sets it once, before or after the jumps.
pub struct Label:
let id: u32
## Makes one program. A zero value is ready; `finish` hands the program over, `destroy`
## drops an unfinished one.
pub struct Builder:
var program: Program
var labels: collections.List[u32]
var line: u32
var column: u32
var failed: bool
var failure: str
## Instructions emitted from now on came from `line` and `column` of the user's text.
pub func at(line: u32, column: u32):
self.line = line
self.column = column
## Whether a call so far was refused (`finish` says why).
pub func has_failed() -> bool:
return self.failed
## Why the first refused call was refused ("" when none was).
pub func refusal() -> str:
return self.failure
# mark: Registers ========================================================================
## A fresh register of `kind`.
pub func register(kind: Kind) -> u16:
return self.vector(kind, 1)
## `width` fresh consecutive registers of `kind` (a vector, an array): the first.
pub func vector(kind: Kind, width: usize) -> u16:
let first = self.program.kinds.length()
if self.failed or width == 0 or first + width >= (usize)no_register:
self.fail("too many registers")
return no_register
for _ in 0..<width:
self.program.kinds.append(kind) catch failure:
self.fail("out of memory")
return no_register
return (u16)first
## Consecutive fresh registers of the given kinds (a record's lanes): the first.
pub func record(kinds: const Kind[]) -> u16:
if kinds.length == 0:
self.fail("a record of no lanes")
return no_register
let first = self.vector(kinds[0], kinds.length)
if self.failed:
return no_register
for (at, kind) in kinds.indexed():
self.program.kinds.set((usize)first + at, kind)
return first
## The kind of `register`, if it exists.
pub func kind_of(register: u16) -> Kind?:
return self.program.kind(register)
## A register holding `value` on every lane (equal constants share one register).
pub func constant_f32(value: f32) -> u16:
return self.constant(.f32, (u64)value.bits())
## An f64 constant.
pub func constant_f64(value: f64) -> u16:
return self.constant(.f64, value.bits())
## An i32 constant.
pub func constant_i32(value: i32) -> u16:
return self.constant(.i32, (u64)(u32)value)
## An i64 constant.
pub func constant_i64(value: i64) -> u16:
return self.constant(.i64, (u64)value)
## A u32 constant.
pub func constant_u32(value: u32) -> u16:
return self.constant(.u32, (u64)value)
## A u64 constant.
pub func constant_u64(value: u64) -> u16:
return self.constant(.u64, value)
## A mask constant: every lane true or every lane false.
pub func constant_mask(value: bool) -> u16:
return self.constant(.mask, 1 if value else 0)
## A constant of `kind` from its bits (`f32.bits()` widened, an integer's two's
## complement).
pub func constant(kind: Kind, bits: u64) -> u16:
for preset in self.program.presets.view():
let scalar = self.program.scalars.at((usize)preset.scalar)
if scalar.kind == kind and scalar.bits == bits:
return preset.register
let register = self.register(kind)
if self.failed:
return no_register
let index = (u32)self.program.scalars.length()
self.program.scalars.append(Scalar(kind = kind, bits = bits)) catch failure:
self.fail("out of memory")
return no_register
self.program.presets.append(Preset(register = register, scalar = index)) catch failure:
self.fail("out of memory")
return no_register
return register
## A register holding uniform `name` on every lane: the host's value for the run, or
## `default`. Asking again for the same name gives the same register.
pub func uniform_f32(name: str, default: f32) -> u16:
return self.uniform(name, .f32, (u64)default.bits())
## An f64 uniform.
pub func uniform_f64(name: str, default: f64) -> u16:
return self.uniform(name, .f64, default.bits())
## An i32 uniform.
pub func uniform_i32(name: str, default: i32) -> u16:
return self.uniform(name, .i32, (u64)(u32)default)
## An i64 uniform.
pub func uniform_i64(name: str, default: i64) -> u16:
return self.uniform(name, .i64, (u64)default)
## A mask uniform.
pub func uniform_mask(name: str, default: bool) -> u16:
return self.uniform(name, .mask, 1 if default else 0)
## A uniform of `kind` with default bits.
pub func uniform(name: str, kind: Kind, default: u64) -> u16:
for slot in self.program.uniform_slots.view():
if slot.name == name:
if slot.kind != kind: self.fail("a uniform asked for in two kinds")
return slot.register
let register = self.register(kind)
let kept = self.keep(name)
if self.failed:
return no_register
self.program.uniform_slots.append(UniformSlot(name = kept, kind = kind, register = register, default = default)) catch failure:
self.fail("out of memory")
return register
## A register holding component `component` of the host's input column `name` (the
## same register when asked again). It must not be written: copy it to change it.
pub func input(name: str, component: usize, kind: Kind) -> u16:
for entry in self.program.input_slots.view():
if entry.name == name and (usize)entry.component == component:
if entry.kind != kind: self.fail("an input asked for in two kinds")
return entry.register
let register = self.register(kind)
let kept = self.keep(name)
if self.failed or component > 65535:
self.fail("an input component out of range")
return no_register
self.program.input_slots.append(Binding(name = kept, component = (u16)component, kind = kind, register = register)) catch failure:
self.fail("out of memory")
return register
## The output slot for component `component` of the host's output column `name`, for
## `store` (the same slot when asked again).
pub func output(name: str, component: usize, kind: Kind) -> u16:
for (at, entry) in self.program.output_slots.view().indexed():
if entry.name == name and (usize)entry.component == component:
if entry.kind != kind: self.fail("an output asked for in two kinds")
return (u16)at
let slot = self.program.output_slots.length()
let kept = self.keep(name)
if self.failed or component > 65535 or slot >= 65535:
self.fail("an output out of range")
return no_register
self.program.output_slots.append(Binding(name = kept, component = (u16)component, kind = kind, register = no_register)) catch failure:
self.fail("out of memory")
return (u16)slot
# mark: Operations =======================================================================
## Emit one instruction as given. Jumps go through `jump` and its siblings instead.
pub func emit(op: Op, kind: Kind, dst: u16, a: u16, b: u16, c: u16):
let shape = op.shape()
if shape == .jump or shape == .branch:
self.fail("jumps are emitted with jump and a label")
return
self.append(op, kind, dst, a, b, c, "")
## d = a op b (`add`, `mul`, `min`, `shl`, ...), of a's kind.
pub func binary(op: Op, a: u16, b: u16) -> u16:
let kind = self.kind_or_fail(a)
let dst = self.register(kind)
self.emit(op, kind, dst, a, b, 0)
return dst
## d = op a (`neg`, `sqrt`, `sin`, `floor`, ...), of a's kind.
pub func unary(op: Op, a: u16) -> u16:
let kind = self.kind_or_fail(a)
let dst = self.register(kind)
self.emit(op, kind, dst, a, 0, 0)
return dst
## d = op(a, b, c) (`mul_add`, `lerp`, `clamp`, `smooth`, `fit01`), of a's kind.
pub func ternary(op: Op, a: u16, b: u16, c: u16) -> u16:
let kind = self.kind_or_fail(a)
let dst = self.register(kind)
self.emit(op, kind, dst, a, b, c)
return dst
## mask d = a op b (`eq`, `lt`, ...).
pub func compare(op: Op, a: u16, b: u16) -> u16:
let kind = self.kind_or_fail(a)
let dst = self.register(.mask)
self.emit(op, kind, dst, a, b, 0)
return dst
## mask d = op a (`isnan`, `isinf`, `isfinite`).
pub func classify(op: Op, a: u16) -> u16:
let kind = self.kind_or_fail(a)
let dst = self.register(.mask)
self.emit(op, kind, dst, a, 0, 0)
return dst
## d = then_value where `mask`, else else_value.
pub func select(mask: u16, then_value: u16, else_value: u16) -> u16:
let kind = self.kind_or_fail(then_value)
let dst = self.register(kind)
self.emit(.select, kind, dst, mask, then_value, else_value)
return dst
## A fresh copy of `a`.
pub func copy(a: u16) -> u16:
let kind = self.kind_or_fail(a)
let dst = self.register(kind)
self.emit(.copy, kind, dst, a, 0, 0)
return dst
## to_register = a on the active lanes (the exec mask's); the rest keep their value.
pub func assign(to_register: u16, a: u16):
self.emit(.assign, self.kind_or_fail(to_register), to_register, a, 0, 0)
## Base's checked `kind(a)`: a value that does not fit faults.
pub func convert(a: u16, kind: Kind) -> u16:
let dst = self.register(kind)
self.emit(.convert, kind, dst, a, 0, 0)
return dst
## Base's C cast `(kind)a`: truncating, saturating, never faulting.
## The constant `register` holds, or none (it is computed, or a uniform).
pub func constant_of(register: u16) -> Scalar?:
return self.program.constant_of(register)
pub func cast(a: u16, kind: Kind) -> u16:
let dst = self.register(kind)
self.emit(.cast, kind, dst, a, 0, 0)
return dst
## The lane's element number, as `kind`.
pub func index(kind: Kind) -> u16:
let dst = self.register(kind)
self.emit(.index, kind, dst, 0, 0, 0)
return dst
## VEX `fit`: x clamped to the old range, mapped onto the new one.
pub func fit(x: u16, old_low: u16, old_high: u16, new_low: u16, new_high: u16) -> u16:
let kind = self.kind_or_fail(x)
let at = self.program.extras.length()
for operand in [old_low, old_high, new_low, new_high]:
self.program.extras.append(operand) catch failure:
self.fail("out of memory")
if at >= 65535:
self.fail("too many extra operands")
let dst = self.register(kind)
self.emit(.fit, kind, dst, x, (u16)at, 0)
return dst
## The dot product of two `width`-lane vectors (registers a.. and b..).
pub func dot(a: u16, b: u16, width: usize) -> u16:
return self.vector_to_scalar(.dot, a, b, width)
## The cross product of two 3-lane vectors: the first of three result registers.
pub func cross(a: u16, b: u16) -> u16:
let kind = self.kind_or_fail(a)
let dst = self.vector(kind, 3)
self.emit(.cross, kind, dst, a, b, 3)
return dst
## The length of a vector.
pub func length(a: u16, width: usize) -> u16:
return self.vector_to_scalar(.length, a, a, width)
## The squared length of a vector.
pub func length2(a: u16, width: usize) -> u16:
return self.vector_to_scalar(.length2, a, a, width)
## The distance between two points.
pub func distance(a: u16, b: u16, width: usize) -> u16:
return self.vector_to_scalar(.distance, a, b, width)
## The squared distance between two points.
pub func distance2(a: u16, b: u16, width: usize) -> u16:
return self.vector_to_scalar(.distance2, a, b, width)
## `a` scaled to length 1 (zero stays zero): the first of `width` result registers.
pub func normalize(a: u16, width: usize) -> u16:
let kind = self.kind_or_fail(a)
let dst = self.vector(kind, width)
self.emit(.normalize, kind, dst, a, 0, (u16)width)
return dst
## Perlin noise in `0..1` of the `dimensions`-lane point in registers from `point`.
pub func noise(point: u16, dimensions: usize) -> u16:
return self.noise_of(.noise, point, dimensions)
## Signed Perlin noise in `-1..1`.
pub func snoise(point: u16, dimensions: usize) -> u16:
return self.noise_of(.snoise, point, dimensions)
## `rand_stream(seed, stream)` in `[0, 1)` as `kind` (f32 or f64); `seed` is i64.
pub func rand(seed: u16, kind: Kind, stream: u16) -> u16:
let dst = self.register(kind)
self.emit(.rand, kind, dst, seed, 0, stream)
return dst
## Register (first + index) of `count` registers, lane by lane; an index outside
## `0..<count` faults with bounds.
pub func pick(first: u16, count: usize, index: u16) -> u16:
let kind = self.kind_or_fail(first)
let dst = self.register(kind)
self.emit(.pick, kind, dst, first, index, (u16)count)
return dst
## Register (first + index) of `count` registers = value, on the active lanes.
pub func place(first: u16, count: usize, index: u16, value: u16):
self.emit(.place, self.kind_or_fail(value), first, index, value, (u16)count)
## Write `value`'s active lanes to output slot `slot`.
pub func store(slot: u16, value: u16):
self.emit(.store, self.kind_or_fail(value), slot, value, 0, 0)
## Call host builtin `builtin` on `arguments`: the first of its consecutive result
## registers.
pub func call(builtin: Builtin, arguments: const u16[]) -> u16:
return self.call_with_texts(builtin, arguments, no_texts())
## `call` with literal text arguments (attribute names), which `Call.text` gives.
pub func call_with_texts(builtin: Builtin, arguments: const u16[], texts: const str[]) -> u16:
if arguments.length != builtin.argument_count or arguments.length > most_arguments or builtin.result_count == 0 or builtin.result_count > most_results or texts.length > most_texts:
self.fail("a builtin called with the wrong number of arguments")
return no_register
let results = self.vector(builtin.results[0], builtin.result_count)
if self.failed:
return no_register
# The results may differ in kind: give each its own.
for at in 1..<builtin.result_count:
self.program.kinds.set((usize)results + at, builtin.results[at])
var registers: u16[32]
for (at, register) in arguments.indexed():
registers[at] = register
var kept: str[4] = ["", "", "", ""]
for (at, text) in texts.indexed():
kept[at] = self.keep(text)
let site = Site(builtin = builtin, number = self.program.sites.length(), arguments = registers, results = results, texts = kept, text_count = texts.length)
let index = self.program.sites.length()
self.program.sites.append(site) catch failure:
self.fail("out of memory")
return no_register
self.emit(.call, builtin.results[0], (u16)index, 0, 0, 0)
return results
# mark: Control ==========================================================================
## A new, unbound label.
pub func label() -> Label:
let id = (u32)self.labels.length()
self.labels.append(0xFFFFFFFF) catch failure:
self.fail("out of memory")
return Label(id = id)
## Bind `label` to the next instruction.
pub func bind(label: Label):
if (usize)label.id >= self.labels.length() or self.labels.at((usize)label.id) != 0xFFFFFFFF:
self.fail("a label bound twice or not made here")
return
self.labels.set((usize)label.id, (u32)self.program.code.length())
## Jump to `label`.
pub func jump(label: Label):
self.append(.jump, .mask, 0, (u16)label.id, 0, 0, "")
## Jump to `label` when lane 0 of `mask` is set: a uniform branch (the mask must be
## the same on every lane).
pub func jump_if_true(mask: u16, label: Label):
self.append(.jump_if_true, .mask, 0, (u16)label.id, mask, 0, "")
## Jump to `label` when lane 0 of `mask` is clear: a uniform branch.
pub func jump_if_false(mask: u16, label: Label):
self.append(.jump_if_false, .mask, 0, (u16)label.id, mask, 0, "")
## Jump to `label` when any live lane of `mask` is set (a masked loop's latch).
pub func jump_if_any(mask: u16, label: Label):
self.append(.jump_if_any, .mask, 0, (u16)label.id, mask, 0, "")
## Jump to `label` when no live lane of `mask` is set (skip a branch nobody takes).
## The skipped code must leave the exec mask as it found it (end a branch with `exec`
## of the enclosing mask, never `exec_all` inside another branch), so skipping it
## changes nothing.
pub func jump_if_none(mask: u16, label: Label):
self.append(.jump_if_none, .mask, 0, (u16)label.id, mask, 0, "")
## Make `mask` the exec mask: faults, stores and `assign` act on its lanes only.
pub func exec(mask: u16):
self.emit(.exec, .mask, 0, mask, 0, 0)
## Every lane active again.
pub func exec_all():
self.emit(.exec_all, .mask, 0, 0, 0, 0)
## A fresh loop slot, which counts one loop's rounds.
pub func loop_slot() -> u16:
let slot = self.program.loop_slots
if slot >= 65534:
self.fail("too many loops")
return 0
self.program.loop_slots += 1
return slot
## Start counting the rounds of loop `slot` (before the loop's top).
pub func loop_start(slot: u16):
self.emit(.loop_start, .mask, 0, slot, 0, 0)
## Count one round of loop `slot` for the lanes in `mask` (`no_register`: every
## lane); past the run's cap the lowest such lane faults. Comes right before every
## jump back to the loop's top.
pub func loop_step(slot: u16, mask: u16):
self.emit(.loop_step, .mask, 0, slot, mask, 0)
## Fault on the active lanes where `mask` is false: Base's `assert`, with `message`
## (empty for "assert failed").
pub func check(mask: u16, message: str):
let kept = self.keep(message)
self.append(.check, .mask, 0, mask, 0, 0, kept)
## Fault on the lowest active lane: Base's `trap(message)`.
pub func trap(message: str):
let kept = self.keep(message)
self.append(.trap, .mask, 0, 0, 0, 0, kept)
# mark: Finishing ========================================================================
## The program, verified and ready to run; the builder is empty afterwards. The first
## refused call, an unbound label, or a program `verify` rejects is an error.
pub func finish() -> Program!:
if self.failed:
error(bad_program, self.failure)
for at in 0..<self.program.code.length():
let ins = self.program.code.at(at)
let shape = ins.op.shape()
if shape != .jump and shape != .branch:
continue
let target = self.labels.at((usize)ins.a)
if target == 0xFFFFFFFF:
error(bad_program, "a jump to a label never bound")
self.program.code.set(at, Instruction(op = ins.op, kind = ins.kind, dst = ins.dst, a = (u16)target, b = ins.b, c = ins.c))
var program = self.program
self.program = Program()
self.labels.destroy()
errdefer program.destroy()
try verify(&program)
return program
## Drop an unfinished program.
pub func destroy():
self.program.destroy()
self.labels.destroy()
# mark: Helpers ==========================================================================
func append(op: Op, kind: Kind, dst: u16, a: u16, b: u16, c: u16, message: str):
if self.failed:
return
self.program.code.append(Instruction(op = op, kind = kind, dst = dst, a = a, b = b, c = c)) catch failure:
self.fail("out of memory")
return
self.program.sources.append(Source(line = self.line, column = self.column, message = message)) catch failure:
self.fail("out of memory")
func vector_to_scalar(op: Op, a: u16, b: u16, width: usize) -> u16:
let kind = self.kind_or_fail(a)
let dst = self.register(kind)
self.emit(op, kind, dst, a, b, (u16)width)
return dst
## Library field `code` (`field_curl` ...) of the f32 point in consecutive registers
## from `point`: the first of its consecutive f32 results.
pub func field(code: u16, point: u16) -> u16:
let (inputs, results) = field_shape(code)
_ = inputs
let dst = self.vector(.f32, (usize)results)
self.emit(.field, .f32, dst, point, 0, code)
return dst
func noise_of(op: Op, point: u16, dimensions: usize) -> u16:
let kind = self.kind_or_fail(point)
let dst = self.register(kind)
self.emit(op, kind, dst, point, 0, (u16)dimensions)
return dst
func kind_or_fail(register: u16) -> Kind:
if let kind = self.program.kind(register):
return kind
self.fail("an operand register that does not exist")
return .f32
func keep(text: str) -> str:
if text.length == 0 or self.failed:
return ""
return self.program.texts.keep_text(text.bytes) catch failure:
self.fail("out of memory")
recover ""
func fail(message: str):
if self.failed:
return
self.failed = true
self.failure = message
## No literal texts.
func no_texts() -> const str[]:
var none_given: const str[]
return none_given