@woosh/meep-engine 3.15.0 → 3.16.0

package/src/shade/renderer/particles/optimizer/particle_program_analysis.js

@@ -0,0 +1,647 @@
+import { CSRGraph } from "../../../../core/graph/csr/CSRGraph.js";
+import { PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
+import {
+    VM_DEST,
+    VM_ISA,
+    VM_OP,
+    VM_OPERAND,
+    vm_decode_op,
+    vm_decode_width,
+    vm_dest_width,
+    vm_operation_width,
+    vm_visit_register_operands,
+} from "../isa/ParticleVMISA.js";
+import { vm_semantics_of, vm_trim_swizzle, vm_trimmed_swizzle_span } from "./particle_vm_semantics.js";
+
+/**
+ * The analysis every optimizer pass reads: instructions decoded into the operand runs they touch,
+ * the def-use graph over those runs, and per-lane liveness.
+ *
+ * Everything here is derived, never authoritative — the instruction words are. A pass rewrites
+ * words and the next one re-derives, which is why there is no incremental update path and no
+ * mutation of an analysis in place: the programs are at most
+ * {@link ../ParticleConstants.js PARTICLE_VM_MAX_INSTRUCTIONS} instructions over
+ * {@link PARTICLE_VM_REGISTER_SLOTS} slots, and re-deriving all of it is cheaper than keeping it
+ * honest.
+ *
+ * ## Lanes, not registers
+ *
+ * A register is one `f32` slot and an operand of width `w` is a RUN of `w` of them, so nothing here
+ * is per-register: a value's producer is per (instruction, lane), and so is its liveness. The rules
+ * for how far an operand reaches are irregular — reductions write one lane, `SCALE` and `CURVE`
+ * have a scalar source, a `SWIZZLE` reads as far as its pattern names, `STORE_ATTR` and `KILL` keep
+ * a *source* in the destination slot — and they are not restated here:
+ * {@link vm_visit_register_operands} is the one place that knows them.
+ */
+
+/**
+ * @typedef {object} ParticleOperandRun
+ * @property {number} operand which operand this is: `-1` for the source that `STORE_ATTR` and
+ *   `KILL` keep in the destination slot, otherwise the source slot `0..2`.
+ * @property {number} base first register slot
+ * @property {number} span consecutive slots the operand reaches
+ */
+
+/**
+ * @typedef {object} ParticleDecodedInstruction
+ * @property {number} index position in the stream
+ * @property {number[]} words the five instruction words
+ * @property {number} op
+ * @property {number} width the encoded width field
+ * @property {number} operation_width lanes the operation spans, after the ISA's fixed-width rules
+ * @property {object} meta the {@link VM_ISA} entry
+ * @property {import("./particle_vm_semantics.js").ParticleOpSemantics} semantics
+ * @property {ParticleOperandRun|null} write destination run, or null when the opcode writes nothing
+ * @property {ParticleOperandRun[]} reads every register run the instruction reads
+ */
+
+/**
+ * Decode one instruction into the runs of register slots it reads and writes.
+ *
+ * @param {ArrayLike<number>} words the five words of a single instruction
+ * @param {number} [index]
+ * @returns {ParticleDecodedInstruction}
+ */
+export function decode_particle_instruction(words, index = 0) {
+    const word0 = words[0];
+    const op = vm_decode_op(word0);
+    const width = vm_decode_width(word0);
+    const meta = VM_ISA.get(op);
+
+    if (meta === undefined) {
+        throw new Error(`particle optimizer: unknown opcode ${op} at instruction ${index}`);
+    }
+
+    // The visitor yields the destination slot first (when the opcode uses one) and then the REG
+    // source slots in order, which is what lets the runs be matched back up to operand positions
+    // without restating how far any of them reaches.
+    /** @type {Array<{base: number, span: number}>} */
+    const visited = [];
+
+    vm_visit_register_operands(words, 0, (base, span) => visited.push({ base, span }));
+
+    /** @type {number[]} source slots that carry a register, in the order the visitor yields them */
+    const register_slots = [];
+
+    for (let slot = 0; slot < 3; slot++) {
+        if (meta.operands[slot] === VM_OPERAND.REG) {
+            register_slots.push(slot);
+        }
+    }
+
+    let cursor = 0;
+    let write = null;
+    /** @type {ParticleOperandRun[]} */
+    const reads = [];
+
+    if (meta.dst) {
+        const run = visited[cursor++];
+
+        if (meta.dest === VM_DEST.NONE) {
+            // STORE_ATTR and KILL: the destination slot holds a source, and the run is what it reads.
+            reads.push({ operand: -1, base: run.base, span: run.span });
+        } else {
+            write = { operand: -1, base: run.base, span: run.span };
+        }
+    }
+
+    for (const slot of register_slots) {
+        const run = visited[cursor++];
+
+        reads.push({ operand: slot, base: run.base, span: run.span });
+    }
+
+    return {
+        index,
+        words: [words[0], words[1], words[2], words[3], words[4]],
+        op,
+        width,
+        operation_width: vm_operation_width(op, width),
+        meta,
+        semantics: vm_semantics_of(op),
+        write,
+        reads,
+    };
+}
+
+/**
+ * @param {ArrayLike<ArrayLike<number>>} instructions five-word tuples
+ * @returns {ParticleDecodedInstruction[]}
+ */
+export function decode_particle_instructions(instructions) {
+    const out = new Array(instructions.length);
+
+    for (let i = 0; i < instructions.length; i++) {
+        out[i] = decode_particle_instruction(instructions[i], i);
+    }
+
+    return out;
+}
+
+/**
+ * Whether an instruction's operands satisfy the rule {@link ../isa/ParticleProgram.js} enforces:
+ * two runs of one instruction name the same slots or disjoint ones, never a partial overlap.
+ *
+ * Every executor reads slot `c` of a source to write slot `c` of the destination, so an exact alias
+ * is fine and a shifted one would read slots the same instruction has already written. A pass that
+ * moves a base or changes a width can turn a legal pair into an illegal one, so each of them checks
+ * its candidate here before keeping it — cheaper than discovering it in `validate()` downstream, and
+ * it keeps the rule stated once.
+ *
+ * @param {ArrayLike<number>} words the five words of a single instruction
+ * @returns {boolean}
+ */
+export function particle_instruction_is_well_formed(words) {
+    const decoded = decode_particle_instruction(words);
+    /** @type {ParticleOperandRun[]} */
+    const runs = decoded.write === null ? decoded.reads : [decoded.write, ...decoded.reads];
+
+    for (const run of runs) {
+        if (run.base < 0 || run.base + run.span > PARTICLE_VM_REGISTER_SLOTS) {
+            return false;
+        }
+    }
+
+    for (let a = 0; a < runs.length; a++) {
+        for (let b = a + 1; b < runs.length; b++) {
+            const x = runs[a];
+            const y = runs[b];
+
+            if (x.base < y.base + y.span && y.base < x.base + x.span && x.base !== y.base) {
+                return false;
+            }
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Def-use over the instruction stream: an edge `i -> j` says instruction `j` reads a slot
+ * instruction `i` last wrote.
+ *
+ * Straight-line code with no control flow, so "last wrote" is exact rather than a may-reach
+ * approximation: one forward scan of a slot-indexed table finds every producer. The result is a
+ * {@link CSRGraph} because that is what the rest of the engine walks — `edge_addresses` /
+ * `adjacency` directly, without a per-vertex closure — and because dead-code elimination is then a
+ * reachability question over it rather than a bespoke container.
+ *
+ * A read of a slot nothing has written yet has no producer and contributes no edge: the register
+ * file starts zeroed on both executors, so such a read is a constant, not a dependency.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} [register_slots]
+ * @returns {CSRGraph} vertices are instructions; vertex `i`'s adjacency lists its consumers
+ */
+export function build_particle_def_use_graph(decoded, register_slots = PARTICLE_VM_REGISTER_SLOTS) {
+    const count = decoded.length;
+    const degree = new Uint32Array(count + 1);
+    /** @type {number[][]} consumer lists, gathered before the CSR is sized */
+    const edges = [];
+
+    const producer = new Int32Array(register_slots).fill(-1);
+
+    for (let i = 0; i < count; i++) {
+        const instruction = decoded[i];
+        /** @type {Set<number>} one edge per producing instruction, however many lanes it feeds */
+        const sources = new Set();
+
+        for (const read of instruction.reads) {
+            for (let lane = 0; lane < read.span; lane++) {
+                const slot = read.base + lane;
+                const from = slot < register_slots ? producer[slot] : -1;
+
+                if (from >= 0) {
+                    sources.add(from);
+                }
+            }
+        }
+
+        for (const from of sources) {
+            edges.push([from, i]);
+            degree[from]++;
+        }
+
+        if (instruction.write !== null) {
+            for (let lane = 0; lane < instruction.write.span; lane++) {
+                const slot = instruction.write.base + lane;
+
+                if (slot < register_slots) {
+                    producer[slot] = i;
+                }
+            }
+        }
+    }
+
+    const graph = new CSRGraph(count, edges.length);
+    const addresses = graph.edge_addresses;
+
+    for (let i = 0; i < count; i++) {
+        addresses[i + 1] = addresses[i] + degree[i];
+    }
+
+    const cursor = addresses.slice(0, count);
+
+    for (const [from, to] of edges) {
+        graph.adjacency[cursor[from]++] = to;
+    }
+
+    graph.edge_weights.fill(1);
+
+    return graph;
+}
+
+/**
+ * @typedef {object} ParticleLaneAnalysis
+ * @property {Uint8Array} keep per instruction: whether it has to survive — it runs, and either it
+ *   has an effect beyond its destination or something reads a lane it writes
+ * @property {Int32Array} width per instruction: the width field it could carry, once the lanes
+ *   nothing reads are dropped. Equal to the encoded one wherever narrowing is not allowed.
+ * @property {Int32Array} pattern per instruction: the swizzle pattern at that width; the encoded
+ *   one for every other opcode.
+ * @property {Uint8Array} live_lanes per instruction: bitmask of destination lanes read later
+ * @property {number} halt_index index of the first `HALT`, or `-1`
+ */
+
+/**
+ * Backward per-lane liveness: which lanes of each instruction's destination anything downstream
+ * actually reads, and therefore how narrow the instruction could be and whether it is needed at all.
+ *
+ * Registers do not outlive a section — both executors start a particle with a zeroed file — so the
+ * walk starts with nothing live and everything a program means has already been written to the
+ * record, the kill flag or the RNG by the time it ends.
+ *
+ * Narrowing is decided inside the same backward pass rather than after it, because an instruction's
+ * reads follow its width: narrowing a broadcast to two lanes shortens the run it reads, which is
+ * what makes the value above it dead. Deciding both at once reaches that fixed point in one sweep.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} [register_slots]
+ * @returns {ParticleLaneAnalysis}
+ */
+export function analyze_particle_lanes(decoded, register_slots = PARTICLE_VM_REGISTER_SLOTS) {
+    const count = decoded.length;
+    const keep = new Uint8Array(count);
+    const width = new Int32Array(count);
+    const pattern = new Int32Array(count);
+    const live_lanes = new Uint8Array(count);
+
+    let halt_index = -1;
+
+    for (let i = 0; i < count; i++) {
+        width[i] = decoded[i].width;
+        pattern[i] = decoded[i].words[3];
+
+        if (halt_index < 0 && decoded[i].op === VM_OP.HALT) {
+            halt_index = i;
+        }
+    }
+
+    // A HALT returns, so nothing past the first one runs — and nothing past it can make a value live.
+    const last = halt_index >= 0 ? halt_index : count - 1;
+    const live = new Uint8Array(register_slots);
+
+    for (let i = last; i >= 0; i--) {
+        const instruction = decoded[i];
+        const semantics = instruction.semantics;
+
+        let mask = 0;
+        let highest_live = -1;
+
+        if (instruction.write !== null) {
+            for (let lane = 0; lane < instruction.write.span; lane++) {
+                if (live[instruction.write.base + lane]) {
+                    mask |= 1 << lane;
+                    highest_live = lane;
+                }
+            }
+        }
+
+        live_lanes[i] = mask;
+
+        if (!semantics.side_effects && highest_live < 0) {
+            continue;
+        }
+
+        keep[i] = 1;
+
+        // Only the lanes below the highest live one have to be computed. Lanes are a contiguous run
+        // from zero, so a live lane 2 holds the width at 3 however dead lanes 0 and 1 are.
+        if (
+            semantics.narrowable
+            && highest_live >= 0
+            && instruction.write !== null
+            && instruction.write.span === instruction.operation_width
+        ) {
+            width[i] = Math.max(highest_live + 1, instruction.meta.min_width);
+        }
+
+        const operation_width = vm_operation_width(instruction.op, width[i]);
+
+        if (instruction.op === VM_OP.SWIZZLE) {
+            pattern[i] = vm_trim_swizzle(instruction.words[3], operation_width);
+        }
+
+        if (instruction.write !== null) {
+            const span = vm_dest_width(instruction.op, width[i]);
+
+            for (let lane = 0; lane < span; lane++) {
+                live[instruction.write.base + lane] = 0;
+            }
+        }
+
+        for (const read of instruction.reads) {
+            const span = read_span_at(instruction, read, operation_width, pattern[i]);
+
+            for (let lane = 0; lane < span; lane++) {
+                live[read.base + lane] = 1;
+            }
+        }
+    }
+
+    return { keep, width, pattern, live_lanes, halt_index };
+}
+
+/**
+ * How far a read reaches once the instruction is narrowed to `operation_width`.
+ *
+ * @param {ParticleDecodedInstruction} instruction
+ * @param {ParticleOperandRun} read
+ * @param {number} operation_width
+ * @param {number} pattern the (possibly trimmed) swizzle pattern
+ * @returns {number}
+ */
+export function read_span_at(instruction, read, operation_width, pattern) {
+    if (instruction.op === VM_OP.SWIZZLE && read.operand === 0) {
+        return vm_trimmed_swizzle_span(pattern, operation_width);
+    }
+
+    if (read.operand >= 0 && instruction.meta.scalar_operands.includes(read.operand)) {
+        return 1;
+    }
+
+    return operation_width;
+}
+
+/**
+ * @param {number} base_a
+ * @param {number} span_a
+ * @param {number} base_b
+ * @param {number} span_b
+ * @returns {boolean} whether the two runs share a slot
+ */
+export function particle_runs_overlap(base_a, span_a, base_b, span_b) {
+    return base_a < base_b + span_b && base_b < base_a + span_a;
+}
+
+/**
+ * Whether anything in `[from, to)` reads or writes any slot of a run.
+ *
+ * What a pass moving an instruction has to ask: a value that nothing in the gap looks at or
+ * disturbs can be produced anywhere in that gap.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} from inclusive
+ * @param {number} to exclusive
+ * @param {number} base
+ * @param {number} span
+ * @returns {boolean}
+ */
+export function particle_run_is_touched_between(decoded, from, to, base, span) {
+    for (let i = from; i < to; i++) {
+        const instruction = decoded[i];
+
+        if (instruction.write !== null
+            && particle_runs_overlap(instruction.write.base, instruction.write.span, base, span)) {
+            return true;
+        }
+
+        for (const read of instruction.reads) {
+            if (particle_runs_overlap(read.base, read.span, base, span)) {
+                return true;
+            }
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Whether every slot of a run is overwritten — or the section ends — before anything reads it again.
+ *
+ * A run that is dead from `index` onwards belongs to nobody, so the instruction that filled it may
+ * be retargeted, folded into its consumer, or dropped.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} index the instruction after which to look
+ * @param {number} base
+ * @param {number} span
+ * @returns {boolean}
+ */
+export function particle_run_is_dead_after(decoded, index, base, span) {
+    const pending = new Set();
+
+    for (let lane = 0; lane < span; lane++) {
+        pending.add(base + lane);
+    }
+
+    for (let i = index + 1; i < decoded.length && pending.size > 0; i++) {
+        const instruction = decoded[i];
+
+        // Nothing past a HALT runs, so nothing past it can want the value.
+        if (instruction.op === VM_OP.HALT) {
+            return true;
+        }
+
+        for (const read of instruction.reads) {
+            for (let lane = 0; lane < read.span; lane++) {
+                if (pending.has(read.base + lane)) {
+                    return false;
+                }
+            }
+        }
+
+        if (instruction.write !== null) {
+            for (let lane = 0; lane < instruction.write.span; lane++) {
+                pending.delete(instruction.write.base + lane);
+            }
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Which value each register slot holds, as a number, and where that value was first computed.
+ *
+ * Two passes ask questions that turn out to be the same question underneath. "Is this register still
+ * the copy it was?" and "has this expression already been evaluated?" both reduce to comparing value
+ * numbers, and both need a copy to carry its source's number across rather than minting a new one —
+ * otherwise a value moved between registers stops being recognisable as itself.
+ *
+ * Numbers are minted per write and inherited by `MOV` and `SWIZZLE`, the only two opcodes that move
+ * a value without changing it. Because a number is never reused, a slot overwritten since simply
+ * fails to match, and there is no invalidation step to get wrong.
+ */
+export class ParticleValueNumbering {
+    /**
+     * @param {number} [slots]
+     */
+    constructor(slots = PARTICLE_VM_REGISTER_SLOTS) {
+        /** @type {number} */
+        this.slots = slots;
+        /** @type {Int32Array} the value in each slot */
+        this.value_id = new Int32Array(slots);
+        /** @type {Int32Array} the slot each value was first computed in */
+        this.home = new Int32Array(slots);
+        /** @type {number} */
+        this.next_id = slots;
+
+        // The file starts zeroed on both executors, but every slot is given a DISTINCT number: they
+        // hold equal values, not the same value, and nothing is gained by conflating them.
+        for (let slot = 0; slot < slots; slot++) {
+            this.value_id[slot] = slot;
+            this.home[slot] = slot;
+        }
+    }
+
+    /**
+     * @param {number} base
+     * @param {number} span
+     * @returns {number[]|null} the numbers in that run, or `null` if it leaves the file
+     */
+    ids_of(base, span) {
+        if (base < 0 || base + span > this.slots) {
+            return null;
+        }
+
+        const ids = new Array(span);
+
+        for (let lane = 0; lane < span; lane++) {
+            ids[lane] = this.value_id[base + lane];
+        }
+
+        return ids;
+    }
+
+    /**
+     * @param {number} base
+     * @param {number[]} ids
+     * @returns {boolean} whether that run still holds exactly those values
+     */
+    holds(base, ids) {
+        if (base < 0 || base + ids.length > this.slots) {
+            return false;
+        }
+
+        for (let lane = 0; lane < ids.length; lane++) {
+            if (this.value_id[base + lane] !== ids[lane]) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Where the values in a run were originally computed, when that is itself a run and still holds
+     * them.
+     *
+     * Two lanes of a broadcast were both computed in the same slot, which is not a run — so a
+     * broadcast as a whole has no origin to be read past, however each of its lanes does.
+     *
+     * @param {number} base
+     * @param {number} span
+     * @returns {number} the origin's base, or `-1`
+     */
+    origin_of(base, span) {
+        if (base < 0 || base + span > this.slots) {
+            return -1;
+        }
+
+        const origin = this.home[base];
+
+        if (origin + span > this.slots) {
+            return -1;
+        }
+
+        for (let lane = 0; lane < span; lane++) {
+            if (this.home[base + lane] !== origin + lane || this.value_id[origin + lane] !== this.value_id[base + lane]) {
+                return -1;
+            }
+        }
+
+        return origin;
+    }
+
+    /**
+     * Record what an instruction leaves in its destination.
+     *
+     * Takes the words as they will be EMITTED rather than as they were read, because a pass may have
+     * moved a source or rewritten the opcode by the time it gets here — the state has to describe
+     * the program that will run.
+     *
+     * @param {ArrayLike<number>} words the five words of a single instruction
+     */
+    publish(words) {
+        const instruction = decode_particle_instruction(words);
+
+        if (instruction.write === null) {
+            return;
+        }
+
+        const base = instruction.write.base;
+        const span = instruction.write.span;
+        const source = words[2];
+
+        /** Gathered before anything is written: the ISA lets a destination alias a source exactly. */
+        const lanes = new Array(span);
+
+        if (instruction.semantics.broadcasts) {
+            // One value in every lane, so lane `i` is a copy of lane 0 and traces back to it — which
+            // is what lets a consumer read the scalar instead of the widened form.
+            const id = this.next_id++;
+
+            lanes.fill({ id, home: base });
+        } else {
+            for (let lane = 0; lane < span; lane++) {
+                const from = carried_lane(instruction.op, words, lane, source);
+
+                lanes[lane] = from >= 0 && from < this.slots
+                    ? { id: this.value_id[from], home: this.home[from] }
+                    : { id: this.next_id++, home: base + lane };
+            }
+        }
+
+        for (let lane = 0; lane < span; lane++) {
+            const slot = base + lane;
+
+            if (slot < this.slots) {
+                this.value_id[slot] = lanes[lane].id;
+                this.home[slot] = lanes[lane].home;
+            }
+        }
+    }
+}
+
+/**
+ * The slot an output lane's value is carried across from, for the two opcodes that move a value
+ * without changing it. `-1` for everything else, which mints a new value.
+ *
+ * @param {number} op
+ * @param {ArrayLike<number>} words
+ * @param {number} lane
+ * @param {number} source
+ * @returns {number}
+ */
+function carried_lane(op, words, lane, source) {
+    if (op === VM_OP.MOV) {
+        return source + lane;
+    }
+
+    if (op === VM_OP.SWIZZLE) {
+        return source + ((words[3] >> (2 * lane)) & 3);
+    }
+
+    return -1;
+}