@jhlagado/azm 0.2.7 → 0.2.8

package/dist/src/register-contracts/constants.js

@@ -0,0 +1,51 @@
+import { applyBinaryOperator, applyByteFunction, applyUnaryOperator, } from '../semantics/constant-operators.js';
+export function evaluateKnownConstant(expression, constants) {
+    switch (expression.kind) {
+        case 'number':
+            return expression.value;
+        case 'symbol':
+            return constants.get(expression.name);
+        case 'unary':
+            return evaluateUnaryConstant(expression, constants);
+        case 'binary':
+            return evaluateBinaryConstant(expression, constants);
+        case 'byte-function': {
+            const value = evaluateKnownConstant(expression.expression, constants);
+            if (value === undefined)
+                return undefined;
+            return applyByteFunction(expression.function, value);
+        }
+        default:
+            return undefined;
+    }
+}
+export function collectConstants(items) {
+    const constants = new Map();
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const item of items) {
+            if (item.kind !== 'equ' || constants.has(item.name))
+                continue;
+            const value = evaluateKnownConstant(item.expression, constants);
+            if (value === undefined)
+                continue;
+            constants.set(item.name, value);
+            changed = true;
+        }
+    }
+    return constants;
+}
+function evaluateUnaryConstant(expression, constants) {
+    const value = evaluateKnownConstant(expression.expression, constants);
+    if (value === undefined)
+        return undefined;
+    return applyUnaryOperator(expression.operator, value);
+}
+function evaluateBinaryConstant(expression, constants) {
+    const left = evaluateKnownConstant(expression.left, constants);
+    const right = evaluateKnownConstant(expression.right, constants);
+    if (left === undefined || right === undefined)
+        return undefined;
+    return applyBinaryOperator(expression.operator, left, right);
+}

package/dist/src/register-contracts/controlFlow.d.ts

@@ -0,0 +1,5 @@
+import type { InstructionEffect, RegisterContractsRoutine } from './types.js';
+export declare function labelIndex(routine: RegisterContractsRoutine): Map<string, number>;
+export declare function instructionSuccessors(routine: RegisterContractsRoutine, index: number, effect: InstructionEffect, labels: ReadonlyMap<string, number>, options?: {
+    boundaryFallthrough?: boolean;
+}): number[];

package/dist/src/register-contracts/controlFlow.js

@@ -0,0 +1,55 @@
+function unique(items) {
+    return [...new Set(items)];
+}
+export function labelIndex(routine) {
+    const out = new Map();
+    routine.instructions.forEach((item, index) => {
+        for (const label of item.labels)
+            out.set(label, index);
+    });
+    return out;
+}
+function localTargetIndex(labels, target) {
+    if (!target)
+        return undefined;
+    return labels.get(target);
+}
+function maybeIndex(index) {
+    return index === undefined ? [] : [index];
+}
+function nextInstructionIndex(routine, index) {
+    return index + 1 < routine.instructions.length ? index + 1 : undefined;
+}
+function shouldFallThroughBoundary(control, boundaryFallthrough) {
+    return Boolean(boundaryFallthrough && (control.kind === 'call' || control.kind === 'rst'));
+}
+function jumpSuccessors(control, labels, next) {
+    const target = localTargetIndex(labels, control.target);
+    if (!control.conditional)
+        return maybeIndex(target);
+    return unique([...maybeIndex(target), ...maybeIndex(next)]);
+}
+function returnSuccessors(control, next) {
+    return control.conditional ? maybeIndex(next) : [];
+}
+function controlSuccessors(control, labels, next) {
+    switch (control.kind) {
+        case 'fallthrough':
+            return maybeIndex(next);
+        case 'jump':
+            return jumpSuccessors(control, labels, next);
+        case 'return':
+            return returnSuccessors(control, next);
+        case 'call':
+        case 'rst':
+        case 'unknown':
+            return [];
+    }
+}
+export function instructionSuccessors(routine, index, effect, labels, options = {}) {
+    const next = nextInstructionIndex(routine, index);
+    if (shouldFallThroughBoundary(effect.control, options.boundaryFallthrough)) {
+        return maybeIndex(next);
+    }
+    return controlSuccessors(effect.control, labels, next);
+}

package/dist/src/register-contracts/fix.d.ts

@@ -0,0 +1,11 @@
+import type { RegisterContractsOutputCandidate, RegisterContractsRoutine, RegisterContractsUnit } from './types.js';
+export interface RegisterContractsExpectOutFix {
+    file: string;
+    line: number;
+    column: number;
+    routine: string;
+    carriers: RegisterContractsUnit[];
+}
+export declare function findExpectOutFixesForCandidates(routines: RegisterContractsRoutine[], candidates: RegisterContractsOutputCandidate[]): RegisterContractsExpectOutFix[];
+export declare function autoFixableCandidateKeys(routines: RegisterContractsRoutine[], candidates: RegisterContractsOutputCandidate[]): Set<string>;
+export declare function applyExpectOutFixesToSource(source: string, fixes: RegisterContractsExpectOutFix[], referenceSource?: string): string;

package/dist/src/{register-care → register-contracts}/fix.js

@@ -2,6 +2,15 @@ import { getZ80InstructionEffect } from '../z80/effects.js';
 import { instructionSuccessors, labelIndex } from './controlFlow.js';
 import { contractCarrierList } from './report.js';
 import { joinSourceLines, splitSourceLines } from './sourceText.js';
+const REGISTER_READ_UNITS = {
+    bc: ['B', 'C'],
+    de: ['D', 'E'],
+    hl: ['H', 'L'],
+    ix: ['IXH', 'IXL'],
+    iy: ['IYH', 'IYL'],
+    sp: ['SPH', 'SPL'],
+    af: ['A'],
+};
 function sameLocation(a, b) {
     return a.file === b.file && a.line === b.line && a.column === b.column;
 }
@@ -29,14 +38,7 @@ function operandReadsUnit(operand, unit) {
     }
 }
 function registerNameReadsUnit(registerName, unit) {
-    const register = registerName.toLowerCase();
-    return ((register === 'bc' && (unit === 'B' || unit === 'C')) ||
-        (register === 'de' && (unit === 'D' || unit === 'E')) ||
-        (register === 'hl' && (unit === 'H' || unit === 'L')) ||
-        (register === 'ix' && (unit === 'IXH' || unit === 'IXL')) ||
-        (register === 'iy' && (unit === 'IYH' || unit === 'IYL')) ||
-        (register === 'sp' && (unit === 'SPH' || unit === 'SPL')) ||
-        (register === 'af' && unit === 'A'));
+    return REGISTER_READ_UNITS[registerName.toLowerCase()]?.includes(unit) ?? false;
 }
 function instructionDataReadsUnit(instruction, unit) {
     switch (instruction.mnemonic) {
@@ -58,36 +60,18 @@ function instructionDataReadsUnit(instruction, unit) {
 function continuationReads(routine, callIndex, carriers) {
     const labels = labelIndex(routine);
     const confirmed = new Set();
-    const work = callIndex + 1 < routine.instructions.length
-        ? [{ index: callIndex + 1, pending: [...new Set(carriers)] }]
-        : [];
+    const work = initialContinuationWork(routine, callIndex, carriers);
     const seen = new Set();
     let steps = 0;
     while (work.length > 0 && steps < 512) {
         steps += 1;
         const state = work.pop();
-        const pending = state.pending.filter((unit) => !confirmed.has(unit));
-        if (pending.length === 0)
-            continue;
-        const key = `${state.index}:${pending.join(',')}`;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
         const item = routine.instructions[state.index];
-        if (!item)
+        const pending = unseenContinuationPending(state, confirmed, seen);
+        if (!item || pending.length === 0)
             continue;
         const effect = getZ80InstructionEffect(item.instruction);
-        const reads = new Set(effect.reads);
-        const writes = new Set(effect.writes);
-        const remaining = [];
-        for (const unit of pending) {
-            if (reads.has(unit) && instructionDataReadsUnit(item.instruction, unit)) {
-                confirmed.add(unit);
-                continue;
-            }
-            if (!writes.has(unit))
-                remaining.push(unit);
-        }
+        const remaining = remainingContinuationUnits(item, pending, confirmed);
         if (remaining.length === 0)
             continue;
         for (const next of instructionSuccessors(routine, state.index, effect, labels)) {
@@ -96,6 +80,39 @@ function continuationReads(routine, callIndex, carriers) {
     }
     return carriers.filter((unit) => confirmed.has(unit));
 }
+function initialContinuationWork(routine, callIndex, carriers) {
+    return callIndex + 1 < routine.instructions.length
+        ? [{ index: callIndex + 1, pending: [...new Set(carriers)] }]
+        : [];
+}
+function unseenContinuationPending(state, confirmed, seen) {
+    const pending = state.pending.filter((unit) => !confirmed.has(unit));
+    if (pending.length === 0)
+        return [];
+    const key = `${state.index}:${pending.join(',')}`;
+    if (seen.has(key))
+        return [];
+    seen.add(key);
+    return pending;
+}
+function remainingContinuationUnits(item, pending, confirmed) {
+    const effect = getZ80InstructionEffect(item.instruction);
+    const reads = new Set(effect.reads);
+    const writes = new Set(effect.writes);
+    const remaining = [];
+    for (const unit of pending) {
+        if (isConfirmedContinuationRead(item, unit, reads)) {
+            confirmed.add(unit);
+        }
+        else if (!writes.has(unit)) {
+            remaining.push(unit);
+        }
+    }
+    return remaining;
+}
+function isConfirmedContinuationRead(item, unit, reads) {
+    return reads.has(unit) && instructionDataReadsUnit(item.instruction, unit);
+}
 function findExpectOutFixes(routines, candidates) {
     const out = [];
     for (const routine of routines) {

package/dist/src/register-contracts/instruction-head.d.ts

@@ -0,0 +1,2 @@
+import type { RegisterContractsInstruction } from './types.js';
+export declare function instructionHead(item: RegisterContractsInstruction): string;

package/dist/src/register-contracts/instruction-head.js

@@ -0,0 +1,3 @@
+export function instructionHead(item) {
+    return item.instruction.mnemonic.toLowerCase();
+}

package/dist/src/register-contracts/instruction-operands.d.ts

@@ -0,0 +1,3 @@
+import type { Z80Instruction, Z80Operand } from '../z80/instruction.js';
+export declare function instructionOperandCount(instruction: Z80Instruction): number;
+export declare function instructionOperand(instruction: Z80Instruction, index: number): Z80Operand | undefined;

package/dist/src/register-contracts/instruction-operands.js

@@ -0,0 +1,101 @@
+const OPERAND_COUNTS = {
+    ret: 0,
+    'ret-cc': 1,
+    jp: 1,
+    'jp-cc': 1,
+    jr: 1,
+    'jr-cc': 1,
+    djnz: 1,
+    call: 1,
+    'call-cc': 1,
+    sub: 1,
+    and: 1,
+    or: 1,
+    xor: 1,
+    cp: 1,
+    ld: 2,
+    ex: 2,
+    add: targetedAluOperandCount,
+    adc: targetedAluOperandCount,
+    sbc: targetedAluOperandCount,
+};
+const OPERAND_SELECTORS = {
+    ld: ldOperand,
+    ex: exOperand,
+    add: aluOperand,
+    adc: aluOperand,
+    sbc: aluOperand,
+    sub: sourceOperand,
+    and: sourceOperand,
+    or: sourceOperand,
+    xor: sourceOperand,
+    cp: sourceOperand,
+};
+export function instructionOperandCount(instruction) {
+    const count = OPERAND_COUNTS[instruction.mnemonic];
+    if (count === undefined)
+        return 0;
+    return typeof count === 'number' ? count : count(instruction);
+}
+export function instructionOperand(instruction, index) {
+    return OPERAND_SELECTORS[instruction.mnemonic]?.(instruction, index);
+}
+function targetedAluOperandCount(instruction) {
+    return 'target' in instruction ? 2 : 1;
+}
+function positionalOperand(index, target, source) {
+    if (index === 0)
+        return target;
+    if (index === 1)
+        return source;
+    return undefined;
+}
+function ldOperand(instruction, index) {
+    return instruction.mnemonic === 'ld'
+        ? positionalOperand(index, instruction.target, instruction.source)
+        : undefined;
+}
+function exOperand(instruction, index) {
+    if (instruction.mnemonic !== 'ex')
+        return undefined;
+    if (index === 0)
+        return firstExOperand(instruction.form);
+    if (index === 1)
+        return secondExOperand(instruction.form);
+    return undefined;
+}
+function firstExOperand(form) {
+    if (form === 'de-hl')
+        return { kind: 'reg16', register: 'de' };
+    if (form === 'af-af')
+        return { kind: 'reg16', register: 'af' };
+    return undefined;
+}
+function secondExOperand(form) {
+    return form === 'de-hl' ? { kind: 'reg16', register: 'hl' } : undefined;
+}
+function aluOperand(instruction, index) {
+    if (instruction.mnemonic !== 'add' &&
+        instruction.mnemonic !== 'adc' &&
+        instruction.mnemonic !== 'sbc') {
+        return undefined;
+    }
+    if ('target' in instruction) {
+        return positionalOperand(index, instruction.target, instruction.source);
+    }
+    return index === 0 ? instruction.source : undefined;
+}
+function sourceOperand(instruction, index) {
+    if (index !== 0)
+        return undefined;
+    switch (instruction.mnemonic) {
+        case 'sub':
+        case 'and':
+        case 'or':
+        case 'xor':
+        case 'cp':
+            return instruction.source;
+        default:
+            return undefined;
+    }
+}

package/dist/src/register-contracts/instruction-predicates.d.ts

@@ -0,0 +1,6 @@
+import type { RegisterContractsInstruction } from './types.js';
+export declare function isUnconditionalReturnInstruction(item: RegisterContractsInstruction): boolean;
+export declare function isPureTokenTransferInstruction(item: RegisterContractsInstruction): boolean;
+export declare function isAccumulatorSelfOperand(item: RegisterContractsInstruction): boolean;
+export declare function isImmediateZeroOperand(item: RegisterContractsInstruction): boolean;
+export declare function isRegisterOperand(item: RegisterContractsInstruction | undefined, index: number, name: string): boolean;

package/dist/src/register-contracts/instruction-predicates.js

@@ -0,0 +1,44 @@
+import { instructionOperand, instructionOperandCount } from './instruction-operands.js';
+import { instructionHead } from './instruction-head.js';
+import { regName } from './operand-register-name.js';
+function immValue(item) {
+    const instruction = item.instruction;
+    if (instruction.mnemonic !== 'cp' || instruction.source.kind !== 'imm')
+        return undefined;
+    const expression = instruction.source.expression;
+    return expression.kind === 'number' ? expression.value : undefined;
+}
+export function isUnconditionalReturnInstruction(item) {
+    const head = instructionHead(item);
+    if (head === 'ret')
+        return item.instruction.mnemonic === 'ret';
+    return head === 'retn' || head === 'reti';
+}
+export function isPureTokenTransferInstruction(item) {
+    const head = instructionHead(item);
+    if (head === 'ex')
+        return true;
+    if (head !== 'ld' || instructionOperandCount(item.instruction) !== 2)
+        return false;
+    const dst = instructionOperand(item.instruction, 0);
+    const src = instructionOperand(item.instruction, 1);
+    if (regName(dst) === undefined)
+        return false;
+    return regName(src) !== undefined || src?.kind === 'imm';
+}
+export function isAccumulatorSelfOperand(item) {
+    const inst = item.instruction;
+    if (inst.mnemonic === 'or' || inst.mnemonic === 'and' || inst.mnemonic === 'xor') {
+        return inst.source.kind === 'reg8' && inst.source.register === 'a';
+    }
+    return false;
+}
+export function isImmediateZeroOperand(item) {
+    return immValue(item) === 0;
+}
+export function isRegisterOperand(item, index, name) {
+    if (item === undefined)
+        return false;
+    const operand = instructionOperand(item.instruction, index);
+    return regName(operand) === name.toUpperCase();
+}

package/dist/src/register-contracts/interfaceContracts.d.ts

@@ -0,0 +1,2 @@
+import type { RoutineContract } from './types.js';
+export declare function parseInterfaceContracts(text: string, file?: string): Map<string, RoutineContract>;

package/dist/src/register-contracts/interfaceContracts.js

@@ -0,0 +1,68 @@
+import { expandCarrierList } from './carriers.js';
+import { buildRoutineContracts } from './smartComments.js';
+const INTERFACE_TAG_RE = /^\s*(in|out|clobbers|preserves)(?:\s+(.+))?$/i;
+const INTERFACE_CONTRACT_BUILDERS = {
+    in: (carriers) => ({ kind: 'in', carriers }),
+    out: (carriers) => ({ kind: 'out', carriers }),
+    clobbers: (carriers) => ({ kind: 'clobbers', carriers }),
+    preserves: (carriers) => ({ kind: 'preserves', carriers }),
+};
+export function parseInterfaceContracts(text, file = '<register-contracts-interface>') {
+    const comments = [];
+    const lines = text.split(/\r?\n/u);
+    for (const [index, line] of lines.entries()) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (trimmed.startsWith(';')) {
+            throw new Error(`${file}:${index + 1}: .asmi files do not permit comments`);
+        }
+        const comment = parseInterfaceContractLine(line);
+        if (comment === undefined) {
+            throw new Error(`${file}:${index + 1}: invalid register contracts interface line \"${trimmed}\"`);
+        }
+        comments.push({ file, line: index + 1, comment });
+    }
+    const routines = buildRoutineContracts(comments);
+    const out = new Map();
+    for (const [name, contract] of routines) {
+        if (hasContractContent(contract))
+            out.set(name, contract);
+    }
+    return out;
+}
+function parseInterfaceContractLine(line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith(';'))
+        return undefined;
+    const boundary = parseInterfaceBoundary(trimmed);
+    if (boundary !== undefined)
+        return boundary;
+    const match = INTERFACE_TAG_RE.exec(trimmed);
+    if (!match)
+        return undefined;
+    const tag = match[1].toLowerCase();
+    const carriers = parseInterfaceCarrierList(match[2]?.trim());
+    return carriers === undefined ? undefined : INTERFACE_CONTRACT_BUILDERS[tag](carriers);
+}
+function parseInterfaceBoundary(trimmed) {
+    const extern = /^extern\s+(\S+)\s*$/i.exec(trimmed);
+    if (extern !== null)
+        return { kind: 'extern', name: extern[1] };
+    return /^end\s*$/i.test(trimmed) ? { kind: 'end' } : undefined;
+}
+function parseInterfaceCarrierList(rest) {
+    if (!rest)
+        return undefined;
+    const rawCarriers = rest.split(',').map((part) => part.trim());
+    if (rawCarriers.length === 0 || rawCarriers.some((part) => part.length === 0))
+        return undefined;
+    const carriers = expandCarrierList(rawCarriers);
+    return carriers && carriers.length > 0 ? carriers : undefined;
+}
+function hasContractContent(contract) {
+    return (contract.in.length > 0 ||
+        contract.out.length > 0 ||
+        contract.clobbers.length > 0 ||
+        contract.preserves.length > 0);
+}

package/dist/src/register-contracts/liveness.d.ts

@@ -0,0 +1,3 @@
+import type { LocatedSmartComment, RegisterContractsConflict, RegisterContractsOutputCandidate, RegisterContractsRoutine, RoutineSummary } from './types.js';
+export declare function findRegisterContractsConflicts(routine: RegisterContractsRoutine, summaries: Map<string, RoutineSummary>, hints: LocatedSmartComment[]): RegisterContractsConflict[];
+export declare function findCallerOutputCandidateObservations(routines: RegisterContractsRoutine[], summaries: Map<string, RoutineSummary>): RegisterContractsOutputCandidate[];