v4 effect.c: stack effects derived from code (ADR step 3, task 2)
Walks a word's code, opcode by opcode with the engine's own counts, and gives what it takes and leaves on both stacks, or why it has none. Called and in-line words; recursion, computed jumps, paths that meet at different depths and loops that leave a count have none. Test first: 23 checks failed against a stub. SWAP', UM/MOD, C@, C! and ROUNDTRIP agree with their stack comments. On the nucleus: 214 of 315 headers fixed. v4 test, test-32 and ASan+UBSan pass. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
This commit is contained in:
@@ -0,0 +1,72 @@
|
||||
/* SPDX-License-Identifier: LicenseRef-Starship-1.0
|
||||
* Copyright (c) 2023-2026 Robert A. James
|
||||
*/
|
||||
/* effect.h -- derive a word's stack effect from its compiled code.
|
||||
*
|
||||
* docs/v4.0.0/plans/2026-11-19-f18-artifact-build.md section 2, task 2; ABI.md section 9, choice 2,
|
||||
* "Derived by the tool", and 2c. A build-machine analysis, not part of the engine: the host tool
|
||||
* (mkf18a) records each exported word's effect in its artifact, and the proofs check it.
|
||||
*
|
||||
* THE WALK. From the word's entry, every path is followed instruction word by instruction word,
|
||||
* slot by slot, counting what each opcode takes from and leaves on the data stack and the return
|
||||
* stack, as the engine's own table has it (v4/src/exec.c, D-16):
|
||||
* - a literal (`@p`) and the fetches push one; the stores, `drop`, `a!`, `b!` pop one;
|
||||
* - `+ and xor` take two and leave one; `+*` looks at two; `2* 2/ inv` and `if -if` look at one;
|
||||
* - `dup` and `over` push one, after looking at one and two;
|
||||
* - `push` moves one to the return stack, `pop` one back;
|
||||
* - `jump` goes on at its target; `if`, `-if` and `next` go on at both their target and the next
|
||||
* word, `next` and `unext` counting the return stack's top down;
|
||||
* - `call` applies the effect of the word it calls, derived first, and goes on.
|
||||
* Where two paths meet at the same instruction word with different depths, the word has no fixed
|
||||
* effect. So a loop that leaves a count of values has none, while a loop that leaves the stacks as
|
||||
* it found them has one, whatever its count.
|
||||
*
|
||||
* HOW A WORD ENDS.
|
||||
* - Called (V4_EFFECT_CALLED): it returns with `;` when the return stack is back where it was on
|
||||
* entry, its caller's return address on top. Every return must leave the same depths. A `;`
|
||||
* with something of the word's own on the return stack goes to a computed address (EXECUTE, a
|
||||
* DEFERred word): no fixed effect. So does touching the caller's return address (`pop` or `ex`
|
||||
* with nothing of the word's own pushed, or `ex` at all). A called word's return-stack effect is
|
||||
* therefore always 0 -> 0.
|
||||
* - In line (V4_EFFECT_INLINE, a header's flag 8): the compiler copies the body to the first `;`,
|
||||
* and that `;` ends it wherever the return stack is. The body may take from the return stack
|
||||
* and leave on it: `push` is 1 -> 0 on the data stack and 0 -> 1 on the return stack.
|
||||
* A word with no way to return has no fixed effect.
|
||||
*
|
||||
* WHAT IS GIVEN. `taken` is the deepest the word reaches below its entry; `left` is what it leaves
|
||||
* counted from there. `dup` takes 1 and leaves 2.
|
||||
*/
|
||||
#ifndef V4_EFFECT_H
|
||||
#define V4_EFFECT_H
|
||||
|
||||
#include "v4/node.h"
|
||||
|
||||
#define V4_EFFECT_CALLED 0
|
||||
#define V4_EFFECT_INLINE 1
|
||||
|
||||
typedef struct {
|
||||
int fixed; /* 1: the effect below is the word's; 0: it has none */
|
||||
unsigned d_taken, d_left; /* the data stack */
|
||||
unsigned r_taken, r_left; /* the return stack */
|
||||
v4_cell at; /* when not fixed: the instruction word where that was found */
|
||||
const char *why; /* when not fixed: why */
|
||||
} v4_effect;
|
||||
|
||||
/* The effect of code outside the range analysed (the ROM's words, another train's): 1 and *out, or
|
||||
* 0 if it is not known. */
|
||||
typedef int (*v4_effect_extern)(void *ctx, v4_cell addr, v4_effect *out);
|
||||
|
||||
typedef struct v4_effects v4_effects;
|
||||
|
||||
/* Analyse the code in [lo, hi) of node `n`. `ext` may be NULL: a call outside the range then has
|
||||
* no fixed effect. NULL if there is no memory for it. */
|
||||
v4_effects *v4_effects_new(const v4_node *n, v4_cell lo, v4_cell hi, v4_effect_extern ext, void *ext_ctx);
|
||||
|
||||
/* The effect of the word whose entry is `addr`, reached as `how` (V4_EFFECT_CALLED or
|
||||
* V4_EFFECT_INLINE). A called word's effect is kept, so a word called from many places is walked
|
||||
* once. */
|
||||
v4_effect v4_effect_of(v4_effects *e, v4_cell addr, int how);
|
||||
|
||||
void v4_effects_free(v4_effects *e);
|
||||
|
||||
#endif /* V4_EFFECT_H */
|
||||
Reference in New Issue
Block a user