Interpreter Performance Plan

Where the programme stands

Done on development

Route A's verdict and gate G3

• Route A: on the PC3 it removed about 10% of the anchor's overhead, against the 37-38% MicroPython removes. Peter judged further Route A steps not worth their risk and moved to G3.
• G3 passed (25 September, 3140045). A wordcode VM run as a CSUB was 8.8-22x faster than the interpreter with symbols, on both boards. The census, the stream size and the overhead conditions all passed. The one open item is whether the full VM fits in the RP2040 VGA's flash. Kit: Bas/bench/g3; results: Bas/bench/results/g3.
• Route B: go (Peter, 25 September). Design: docs/Interpreter_RouteB_Design.html (9650f69). Five decisions await Peter's review, and P1 does not start before them.

Open on development

• The RP2040 WebMite does not link. Its .heap runs 1,660 B past RAM with symbols, even after the symbol helpers moved to flash on that build (317da5b). The options put to Peter:
  1. Move cmd_loop and cmd_print to flash on WEB RP2040 only (recommended).
  2. Shrink the C heap from 10 KB to 8 KB.
  3. Shrink the BASIC heap from 88 KB to 84 KB.
• The funtbl replacement (18 KB of BSS on the RP2350, to be given to the heap) is proposed, not started.
• OPTION SYMBOLS is a development A/B switch, to be removed at the end unless Peter keeps it.
• The manual and help still describe OPTION TRACECACHE and OPTION CACHE.
• A side issue from S1c: after a PID handler has run inside a loop, statements are about 3% slower (in findvar).

Purpose and ground rules

MMBasic spends most of its time interpreting, not computing. The work it repeats on every execution is fixed for the whole RUN. This plan measures that work first. It then moves the answers into the stored program, written once when the program is saved, and never into heap tables that grow with the program.

The short version

• Overhead is most of the run time. Peter's mmb2csub pairs show that the same routine as native code runs about 4x faster, even when the heavy lifting is already in optimised firmware such as the graphics commands. On solar_eclipse.bas about 80% of the run time is interpreter overhead: 1 − 2.5/13 = 80.8% from Peter's figures, or 1 − 2.7/13 = 79% from the 252 MHz pair in docs/mmb2csub.md:670.
• The overhead is repeated work. Each statement is scanned to its end. Arguments are split again, names are hashed again and NEXT or LOOP is found again. A SUB's parameter list is re-read on every call, and the firmware polls for events that almost never happened.
• The trace cache shows what not to do. It kept its answers in one fixed heap slab, which has to be made bigger as the code grows (Elite needed 256 slots). It keyed them on buffer addresses and invalidated them through one global counter. It rarely pays, and it can make programs slower.
• Phase 0 measures before anything is built. It uses the anchor benchmark and its CSUB twin as the floor, a matrix of runs that needs no build, and OPTION PROFILING, extended one argument at a time as the hypotheses need it.
• Route A makes the text cheaper. It adds an attention word in place of per-statement polling, call descriptors, symbol ids for names with storage bound lazily at run time, and block-partner tables. The ids, descriptors and partner tables are kept in the stored image. RAM grows only with the number of unique names.
• Route B comes only if the numbers justify it. It is a compiled statement stream, written when the program is saved into a slot beside the text that LIST, EDIT and SAVE use. For testing, the slot is a RAM slot on the PC3 and a flash slot on the RP2040.
• The yardstick is the fraction of the anchor's measured overhead removed. MicroPython, doing the same double-precision arithmetic, removes about 37% of it (8.8 s against 12.5 s, with the CSUB at 2.5 s). That is the bar Route A should reach.

Why first principles, and not more tuning

Tuning hot functions has been tried several times and has not moved the overhead:

• A word-level heap bitmap scan was 17% slower on knivd.
• Moving the double-precision routines to RAM only shuffled code placement.
• Dispatch tables in RAM gained 0.4%.
• One TinyUSB debug flag moved knivd by about 4% (11,840 against 12,330) through code placement alone. Any claimed gain must beat that noise.

Integer and float benchmarks run at almost the same speed, so the arithmetic is not the cost. The question is not "which function is slow". It is "what does the interpreter work out again on every execution that it could have worked out once".

Ground rules

• Scope. This is the development branch, and everything may change: the stored program format, the tokeniser, LIST/EDIT/SAVE, the library and RAM-slot image formats, and interrupt-check timing. The trace cache is out of scope: Peter will probably remove it, and the plan ignores it.
• The hard constraints are RAM and flash, and nothing else.
  • Firmware flash per variant:
    • VGAUSBRP2350's margin is not known until that variant is built again. It outgrew its 1040 KB offset, and commit 564fcff (2026-09-21) moved it one 16 KB step to 1056 KB (configuration.h:146).
    • RP2040 VGA has 13,340 B: buildRP2040L/PicoMite.bin is 822,244 B against the 816 KB offset.
    • Flash moves in 16 KB steps.
  • RAM-resident code on the RP2040 costs whole 4 KB pages.
  • struct option_s is exactly 896 bytes.
  • The function token table is 7-bit and nearly full: HDMIWEB is at 127.
• Program capacity. In Peter's words, "going very fast but only supporting small programs isn't a step forward".
  • The largest programs today are about 100 KB on the RP2040 VGA, 144 KB on the PC3's HDMIWEB build and 300 KB on PICORP2350 (configuration.h:109,200,326). MAX_PROG_SIZE equals the heap, except that every RP2040 PicoMite build (PICO, PICOUSB and PICOMIN) fixes it at 120 KB (:393-397). That is the whole heap on PICO, but less than the heap on PICOUSB (124 KB) and PICOMIN (128 KB) (:356, 361).
  • Every proposal is priced in bytes of RAM and bytes of program flash per KB of user program.
  • Heap used by a side table is heap taken from the user's variables. The RP2040 has no PSRAM.
• Method.
  • Measure before building.
  • One mechanism per build and per commit.
  • Every step runs on the board against golden outputs.
  • No benchmark may get slower beyond the placement floor.
  • A per-statement cache keyed on an address, or a heap table that grows with the code, is rejected on sight (§3.5).
• Hardware.
  • PC3 on COM16: RP2350B with PSRAM and HDMI, running HDMIWEB with WiFi live.
  • RP2040 VGA on COM7: a LOWRAM build with no trace cache and no label hashing. findvar, DefinedSubFun and the FOR, IF, NEXT, DO and INC handlers run from flash.
• Etiquette.
  • Never drive a board Peter is using. He types RUN.
  • Never build while he builds.
  • Serial lines go at least 20 ms apart.
  • Every result is logged with MM.DEVICE$, MM.VER, the git hash, the CPU speed and OPTION LIST.

How the interpreter spends its time today

This section follows one statement through the firmware. Every step was read in the code. The cycle cost of each step has not been measured on either board; Phase 0 exists to measure it.

What the program looks like in memory

The program runs directly from its tokenised image in flash, read through the 16 KB XIP cache. On the PC3 the RAM library and the RAM slots sit in PSRAM behind the same cache (PSRAMbase 0x11000000, configuration.h:524).

• Only keywords are tokens. Names, numbers, spaces and trailing comments stay as ASCII.
• Each line starts with T_NEWLINE and a skip byte (MMBasic.h:98-107, written at MMBasic.c:1698-1720).
• Statements end in a 0, and the program ends with 00 00.

The same image is the source for LIST, EDIT and SAVE, which is why it stays text.

One statement, step by step

1. Line header (MMBasic.c:1834-1859), once per line: set CurrentLinePtr, write the TraceBuff ring, test TraceOn, and step over the line number and label.
2. Pre-scan (1879-1881): skipelement(nextstmt) walks every byte to the terminating 0, including any trailing comment. ExecuteProgram uses the skip byte only to jump over comment-only lines (1863-1875).
3. Dispatch (1890-1917): commandtbl_decode, then commandtbl[].fptr(). The table is const, so it is in flash. A user SUB name goes through FindSubFun and then DefinedSubFun. setjmp runs only while ON ERROR SKIP, IGNORE or RESTART is in effect, that is while OptionErrorSkip is not 0 (1925-1938; Commands.c:8546-8575).
4. The command reads its own text again.
   • getargs/makeargs copy it into a 384 B stack buffer, calling strchr on each top-level byte (MMBasic.c:5551). A bracketed argument or function call is found with getclosebracket and copied in one memcpy (5600-5607).
   • LET scans for = with a tokenfunction table lookup on each byte (an inline macro, MMBasic.h:227-230; Commands.c:1787-1788), then skipvar, then findvar on the left side (Commands.c:1818).
5. Expressions. evaluate calls getvalue for the first operand, then doexpr while an operator follows (MMBasic.c:2889-2891). doexpr calls getvalue for each next operand and recurses on precedence (3066, 3146).
   • Literals are parsed again on every evaluation (MMBasic.c:3336-3398).
   • Operators receive their operands through globals and are reached by an indirect call (3135).
6. Every name. findvar upper-cases and FNV-hashes each character, then takes % maxglobalvars at run time (4689-4701). Inside a SUB it probes the local table before the global one.
7. Every name(. FindSubFun runs first (3277-3279), so every array read asks "is this a function?".
   • On the RP2040 that starts by counting subfun[] one entry at a time (2027-2028).
   • Array indices then go through a getargs copy, a bracket re-scan and skipvar.
8. Every built-in function that takes arguments (T_FUN, 3245-3253; Memory.c:1852-1860): getclosebracket, then a zeroed 256 B temp page, then a memcpy of the argument text. The page is freed at the end of the statement. Functions with no arguments, such as TIMER and PI, skip the copy (3254-3256).
9. Tail (MMBasic.c:1940-1952):
   • ClearTempMemory if anything was allocated.
   • The core1 stack canary, which is not compiled on WEB builds (1944).
   • Unless NOCHECK is set, CheckAbort() and then check_interrupt():
     • CheckAbort calls ProcessWeb(1) on every statement on WEB builds (PicoMite.c:2682-2687), and HDMIWEB is one (CMakeLists.txt:798-806). ProcessWeb reads time_us_64, walks the PCBs, and polls cyw43 every 100 calls or every 1 ms (net/WiFi.c:295-345).
     • routinechecks calls time_us_64() and returns if less than 100 µs have passed (PicoMite.c:893-901).
     • check_interrupt calls ProcessTouch on every statement while GUI controls exist. Otherwise it returns unless InterruptUsed is set. Once any interrupt has been set, checkdetailinterrupts runs on every statement until END (MM_Misc.c:10558-10586). That is a 350-line function in flash (10209-10557) that tests every interrupt source in turn.

Control flow and calls

• FOR entry (Commands.c:5121-5235):
  • getargs, which trims argbuf in place (5130-5133).
  • Removal of any stale entry for the same loop from the FOR stack.
  • A forward scan to the matching NEXT. For each NEXT it meets, it runs mystrncasecmp at every byte offset of that NEXT's argument list (5198-5235).

  NEXT itself is a pointer compare (5278-5284). An inner loop therefore re-scans its body once per outer iteration.

• DO scans forward to LOOP on entry (5378-5394). SELECT walks the arms on every dispatch (4729-4912).
• GOTO and GOSUB. findline is a linear walk on both chips (MMBasic.c:3547). findlabel is hashed on the RP2350 (3742) and linear on the RP2040 (3802).
• SUB and FUNCTION calls (DefinedSubFun, 2232-2709):
  • makeargs runs over the caller's argument list and over the definition's parameter list (2392, 2398).
  • For each parameter: the BYVAL/BYREF test twice, skipvar, CheckIfTypeSpecified (2527), and findvar(V_LOCAL).
  • The RP2350 clears 600 B per call (2370-2371). The RP2040 allocates and zeroes 75 × 29 + 512 = 2,687 B per call (2376-2385).
  • A FUNCTION re-enters ExecuteProgram (2679), which copies the jmp_buf on entry and again on exit.
  • On return, ClearVars walks the whole hash list (6356+).

Where the code runs

• RP2350. ExecuteProgram, the evaluator, findvar, the operators and the hottest handlers are RAM-resident. checkdetailinterrupts and most fun_ routines run from flash; fun_sin is at 0x1000cbfc in the HDMIUSB map (buildRP2350L).
• RP2040 VGA (LOWRAM). These also run from flash:
  • findvar and DefinedSubFun (MMBasic.c:4643, 2227);
  • cmd_for, cmd_if, cmd_else, cmd_next, cmd_do and cmd_inc (Commands.c:5097, 3659, 3947, 5256, 5327, 909).
• Flash clock.
  • The RP2350 runs the flash at CLKDIV 2 up to 288 MHz and CLKDIV 4 above (PicoMite.c:3758-3761); the RP2040 VGA is always at CLKDIV 4 (CMakeLists.txt:588-591, PicoMite.c:3825-3827).
  • Not pursued. Peter's judgement is that flash timing is not very relevant, because its effect is confounded by the QMI cache, and placement effects are already known to be about 4%. The plan runs no flash-clock experiments.

The repeated work, in one table

What has been learned already

3.1 The overhead, measured against CSUB twins of the same routine

Split the interpreted time as T = W + O: the work itself plus the interpreter's overhead. mmb2csub converts about 132 of the 166 routines in its corpus (mmb2c's tests/, plus se.bas, julia.bas and knivd.bas). The same routine therefore exists interpreted and native, and T_native is a measured floor for W.

What this implies:

• Even where the firmware does the drawing, three quarters of the time goes between the firmware calls, getting arguments out of text and into C.
• Code built from SUBs with locals is almost pure overhead.
• Nothing that speeds up the arithmetic can matter.

This gives the yardstick used everywhere below. It is measured per board, within one build and one condition:

Removing 10% of the overhead counts the same on a 4x routine as on a 35x one. The floor needs two caveats:

• It is slightly optimistic. A CSUB skips bounds checks, per-statement Ctrl-C and interrupts, and error line numbers (docs/mmb2csub.md Appendix A).
• It is pessimistic on the RP2350. The blobs are M0+ code, helpers are reached through the CallTable, and a 37 KB blob runs from XIP flash.

The sefunc CSUB barely scales with the clock: 2.7 s at 252 MHz and 2.48 s at 378 MHz (docs/mmb2csub.md:668-672). Between those two clocks the flash clock fell from 126 to 94.5 MHz while the CPU rose 1.5x. The interpreted remainder, flash fetch or the CallTable's double routines could each explain that. The plan does not chase it (flash timing is confounded by the QMI cache); it takes the floor as measured, on the same build as the interpreted time.

3.2 What MicroPython's lead teaches

On the same chips, MicroPython written to mimic BASIC is up to about 30% faster than MMBasic (Peter's figure). Peter's MicroPython is his own PC3 port (\\wsl.localhost\Ubuntu\home\peter\src\micropython\ports\rp2, board PICO_COMPUTER_3). It uses double-precision floats and arbitrary-precision (MPZ) integers, so it does the same arithmetic as MMBasic (mpconfigboard.h:24-26; DEVELOPMENT_NOTES.md §1). On the anchor, the line-faithful port tests/solar_eclipse.py takes about 8.8 s against MMBasic's 12.5 s at 378 MHz on the same chip, with digit-identical output. That removes (12.5 − 8.8)/(12.5 − 2.5) ≈ 37% of the overhead.

Implication. A suffix-typed BASIC that adopts these resolution ideas without the dynamic object model has a higher ceiling than 1.3x. An Amdahl projection from the 300% overhead: cutting the overhead by 5x would give about 2.5x on graphics-heavy code and 4-5x on compute kernels. This is unverified.

A consistency check, also unverified. An assignment costs about 1,900-2,270 cycles in MMBasic (6 µs at 315 or 378 MHz), against a few hundred for MicroPython's x=x+1. That predicts far more than 1.3x on scalar code. The arithmetic is the same, so precision does not explain the gap. Two things could:

• If the 30% came from mixed programs, time spent in C (builtins, graphics) dilutes the difference.
• MicroPython's own costs: a heap allocation for every float result, dictionary lookups for module-level names, and a slow software sin on an anchor with about 450 SIN( calls in its text.

Either way, MicroPython carries costs MMBasic does not have and still wins. That points at MMBasic's operand handling, not at its arithmetic.

The E pairs in Phase 0 settle it.

3.3 What is already resolved once

• The line skip byte (MMBasic.h:98-107; MMBasic.c:1698-1720). ExecuteProgram uses it only to jump over comment-only lines (1863-1875). Every executed statement is still scanned byte by byte (1881).
• FOR and DO iterations. forptr and nextptr sit on the FOR stack, and loopptr on the DO stack (Commands.c:5391, 5492-5496), so NEXT and LOOP jump straight back. What remains is the forward scan each time a FOR (Commands.c:5198-5235) or DO (5378-5394) is entered, which for an inner loop is once per outer iteration.
• Multi-line IF/ELSEIF/ELSE/ENDIF uses a sorted jump table built at PrepareProgram (Commands.c:3250-3565). It lives in the heap.
• Labels and SUB names on the RP2350 are hashed into funtbl (MMBasic.c:3654). The RP2040 does not have this.
• Still unresolved: the SELECT CASE walk on every dispatch, line-number targets, and labels on the RP2040.

So block partners are mostly done already. The remaining gaps are the entry scans and SELECT.

3.4 Binary literals: tried, no gain

Peter stored numeric literals in binary behind a pretend function token, and there was no noticeable improvement. That fits the model. Converting a literal is a small part of a statement whose evaluator still walks the text around it, hashes the names and copies the arguments.

The lesson is general: removing one piece of text parsing buys little while the evaluator still re-walks the text. The gain arrives only when the walk itself stops. Symbols (S5-S6) start that, and a compiled stream (Route B) finishes it.

3.5 The trace cache, and why a per-statement cache fails to pay

OPTION TRACECACHE ON [size[,flags]] is off by default and exists only on CACHE builds (CMakeLists.txt:297-309): HDMIWEB has it, the RP2040 VGA does not. It compiles the right-hand sides of LET, IF, INC, DO and SELECT, and caches jump targets. Entries are keyed on the statement's source address, through a golden-ratio hash with up to 8 probes (MMtrace.c:407-452). A cached statement replays a small typed stack machine.

It fails for six reasons.

1. The lookup costs about what it saves, and the frame stays.
   • Every hit pays a multiply-hash, up to 8 probes, and a replay with a stack check and a type tag on every op.
   • It skips findvar and the evaluator for one statement. It does not skip the pre-scan, the dispatch or the tail. IF's getargs runs before the cache is even checked (Commands.c:3694 against 3722).
   • The dispatch-level hook TraceCacheTryExec is a stub (MMtrace.c:3376-3381).
   • Even in the best case, a fully cached DO loop is still 2.9x slower than the FOR loop.
2. The binding lifetime is wrong.
   • One global 16-bit counter, g_local_frame_gen (MMtrace.h:50-59), changes on every frame entry and exit.
   • After any call, every cached statement that uses a local re-resolves it with a linear scan (MMtrace.c:822-878).
   • For SUBs with locals called once a tick this costs more than findvar. That is why the Exile kernel got slower.
3. The identity is wrong.
   • The key is a buffer address. The stack argbuf, which runs a single-line THEN a ELSE b (Commands.c:3787), and tknbuf, which runs EXECUTE and the prompt, present one key for different code.
   • physics.bas:450 and :452 are both If cy Then X = a Else X = 0. That is the probable cause of the CollTiles result. This comes from reading the code; it has not been reproduced.
4. The coverage is wrong. It covers expression right-hand sides, including simple 1-D and 2-D array element reads and writes (MMtrace.c:15-18, 1482-1553). Real programs spend their time on calls, array traffic and command arguments ("calls and array traffic, not tight arithmetic", design review :372). It does not cover calls to user SUBs and FUNCTIONs, or command arguments.
5. It is a second semantics.
   • Eight divergences are known from reading the code:
     • ^ is right-associative;
     • INT^INT goes through pow();
     • >> is an arithmetic shift;
     • NOT 0.4 gives 1;
     • NaN compares differently;
     • float-to-integer conversion truncates instead of rounding in the side paths: the DO fast-path limit, an INC float step on an integer, and SELECT CASE constants (MMtrace.c:3497, 3847, 4135). LET and IF round, as the interpreter does;
     • RND advances twice when a statement bails out;
     • computed GOTO targets are frozen.
   • The DO fast path (Commands.c:5415-5450) is gated only by #ifdef CACHE. On COM16's HDMIWEB build it is live today, with no option set.
6. Its size must grow with the code, and it never shrinks.
   • The slab is allocated once, at the size the user sets (default 64 entries; MMtrace.c:79-83, 373-377). What grows with the code is the number of slots needed to stop missing. Each slot is 216 B (MMtrace.c:115, 314-329), so Elite's 256 slots take about 55 KB of heap.
   • It compiles on the first visit and never evicts. One bail-out marks a statement BAD for the rest of the run.
   • Every CACHE build pays about 10 KB of RAM-resident code plus 9 KB of flash whether the option is used or not. The HDMIUSB map (buildRP2350L) shows 10,038 B of .time_critical and 9,138 B of .text, 19.2 KB in all.
   • Part of the invalidation its header documents (MMtrace.c:74-77) is not wired up. NEW, RUN and EDIT drop the whole cache (Memory.c:2010; misc/Editor.c:629), and the file-manager relaunch frees it (misc/Editor.c:4440), but DIM, ERASE, OPTION BASE and OPTION EXPLICIT do not invalidate it.

Rules every new step must pass

How symbol ids differ from the trace cache

A symbol id identifies a name as it appears in the program text. It does not identify a variable, and it does not identify a statement address.

• Ids are assigned when the program is tokenised, because every name in the program is known at that point.
• Storage is still bound at run time, and lazily. On first use an id has no binding, so findvar runs exactly as today and its result is recorded against the id. Implicit creation, conditional DIM and LOCAL, OPTION EXPLICIT and recursion all behave as they do now.
• A binding changes only when storage changes: a local created or destroyed, ERASE, CLEAR, RUN or CHAIN.
• Copies cannot alias. A fragment copied into argbuf carries its own ids.
• Names that never appear in the program text keep today's by-name path. These are EXECUTE strings, CALL by string and the prompt.

The trace cache bound results to a statement address and invalidated them globally on every frame change. Ids bind to a name and change only on the events listed above.

The review method

Measure on both boards, lead with one real program, compare every interpreted number with its native twin, and state in advance which result would kill each hypothesis.

4.1 The anchor benchmark: solar_eclipse.bas

Bas/solar_eclipse.bas is byte-identical to Testfiles/solar_eclipse.BAS. It is 3,213 lines and 70 KB, of which about 44 KB is non-comment text, in 33 routines. It times itself: Timer =0 is at line 224, and "Time taken" is printed at line 242. The key routine is Sub sefunc(x, fx) at line 248. With its callees it covers 15 of the 20 profiled routines and 99.8% of the calls (docs/mmb2csub.md §9).

Reference inputs (Peter), typed in this order at the five prompts: 12,1,2000 · 39,40,36 · -104,57,12 · 1644 · 30. They give the 25 December 2000 eclipse. Golden output: JD 2451904.14541560, .19690359 and .25420764, the same to the last digit in MMBasic, in the CSUB version and in Peter's MicroPython port (boards/PICO_COMPUTER_3/tests/README.md in that tree). Every run uses these inputs and is checked against these digits.

What each ratio means:

• Overhead fraction. 1 − 2.5/12.5 = 0.80 at 378 MHz; the 252 MHz pair (mmb2csub.md:670) gives 1 − 2.7/13 = 0.79. Against today's 14.6 s on HDMIWEB it is 0.83, once the CSUB has been re-measured on the same build. This is a lower bound, because the CSUB run still includes the interpreted remainder. The overhead is about 22 ms per sefunc call (10.5 s over 474 calls).
• MicroPython's share. On the same chip and clock it removes (12.5 − 8.8)/(12.5 − 2.5) ≈ 37% of the overhead; with Peter's rounder 13 s and 9 s it is 38%. It does the same double-precision arithmetic as MMBasic, keeps every float result as a heap-allocated box, and reads flash at 63 MHz against MMBasic's 94.5 MHz, and it still wins. About 37% is the bar for Route A. On COM16's HDMIWEB build that means about 10 s.
• Why gates are in removed fraction. A 1.3x gain on the PC3 (14.6 → 11.2 s) removes only (14.6 − 11.2)/(14.6 − 2.5) ≈ 28%, which is below MicroPython. So every gate below is written as removed fraction, not as "x times faster".
• Only compare within one build and one condition. The spread between builds (12.5 s against 14.6 s at 378 MHz) is larger than several of the candidate steps. The likely causes are the per-statement ProcessWeb on WEB builds, HDMI scan-out contention and code placement. COM16 can take any RP2350 build, and all of them auto-configure as a Pico Computer 3 (Peter), so 0b measures the spread directly.

What the anchor exercises (from reading the source):

• Types come from OPTION DEFAULT. The file sets Option default float (line 10) and Option base 1 (line 12). Most numeric variables carry no suffix and take FLOAT from OPTION DEFAULT. But loop counters in six routines are % integers, line 26 declares i and j AS INTEGER, and a few names carry $. Typed operations must take their type from OPTION DEFAULT, DIM and LOCAL, not only from suffixes.
• Call counts. sefunc is called 474 times. findleap, utc2tdb and jdfunc are called about 1,455 times each (mmb2csub.md §9).
• LOCAL arrays. The file has 92 LOCAL statements. sefunc alone creates 7 LOCAL arrays on every call (lines 262-274), each allocated and freed on the heap. Arrays are passed BYREF.
• CONSTs. The file's "globals" are mostly CONSTs read inside SUBs, for example dtr with 101 uses and pidiv2 with 167. Every read probes the local table first.
• Built-in functions. The text has about 450 SIN( and 25 COS(, and each call goes through the T_FUN temp-page path.
• Loops and branches. There are 23 FOR loops, 10 of them over 3 elements, and every entry scans the body to NEXT. There are 71 IF lines and 4 DO loops.
• What it lacks. No SELECT, GOTO/GOSUB, interrupts or graphics, and almost no string work (only the result printout).
• XIP pressure. moon() (lines 974-1531) is about 20 KB of non-comment text, more than the 16 KB XIP cache. Its text streams from flash on every call and evicts flash-resident handlers such as fun_sin.
• Inputs come before the timer. All five inputs are read before Timer =0 (getdate at 199, observer at 205, ndays at 223; the input routines are at 1884-1959). Feeding them over serial does not touch the timed region.
• Secondary benchmarks cover what it lacks:
  • a fixed-work knivd, for strings and trig (today's never reaches END, Bas/knivd.bas:9-16);
  • ExilePhysicsBench and the PoP scenario, for calls, arrays and graphics (PC3);
  • an Elite frame (PC3);
  • julia (both boards);
  • one graphics macro on COM7.

Log with every anchor run:

• the variant, MM.VER and git hash;
• the CPU speed, read with MM.INFO(CPUSPEED);
• whether WiFi is connected;
• the display resolution. On the PC3's HDMI builds it fixes the CPU clock (MM_Misc.c:6723-6768). The heap shrinks with the mode only on the full HDMI builds (PicoMite.c:3847-3877), not on HDMIWEB;
• where the program runs from (flash or a RAM library);
• OPTION LIST;
• a hash of the printed eclipse circumstances. The interpreted and CSUB answers agree to the last digit (mmb2csub.md §9).

4.2 Phase 0: harness, profiler, goldens

About 1-2 weeks (a guess). No behaviour change.

Moved out of Phase 0: the VM-as-CSUB prototype. It only informs the Route B decision, and it is confounded (M0+ code on the M33, big blobs running from XIP, doubles through the CallTable). It now sits at G3.

4.3 Phase 1: characterisation

About 1 week (a guess). Both boards.

The output is one table per workload per chip:

• the overhead fraction O against the CSUB floor;
• the bucket shares from the extended PROFILING histograms and counters (shares from profiled runs, times from unprofiled ones): tail, pre-scan, name lookup, evaluator core, argument copies and temp pages, call machinery, block and jump scans, and work;
• the MicroPython/MMBasic ratios for E0-E9;
• the name-lookup ceiling.

Each of H1-H10 is marked confirmed or killed by the thresholds below.

4.4 Hypotheses, and the experiment that confirms or kills each

Candidate architectures compared

Five strategies were written independently and then judged. None is adopted as written. The recommended programme takes the measurement discipline from one, the identity layer from another, a binding mechanism from a third, the yardstick from a fourth, and the design rules for a later compiler from the fifth.

The judge's scorecard

On every axis 10 is best. For compatibility risk, 10 means lowest risk; for effort, 10 means least effort. These are judgements of each strategy as written.

Bytecode's capacity score of 4 is for compiling into the heap. Moved to a stream written at save time into a separate slot, as Route B does, it costs nothing from the program area or the heap beyond names and call depth.

Program capacity: what each costs per KB of user program

"Heap" here means heap at run time, which comes out of the user's variables. Today both boards are limited by the source text that LOAD holds in the heap: GetTempMemory(EDIT_BUFFER_SIZE - 2048) (misc/FileIO.c:4345; configuration.h:561). That is about 93 KB on the VGA and about 137 KB on the PC3 at 640 pixels wide, less at the wider HDMI modes. A smaller image becomes a bigger program only once LOAD tokenises while it streams the file.

The emulator is measure.py in the session scratchpad: an approximate re-implementation of tokenise(), good to about ±2-3%. It was re-run for this document on Bas/elite/elite.bas, Bas/sandglass_tools/player.min.bas, Bas/solar_eclipse.bas and Bas/exile/*.bas.

The recommended programme

Measure; characterise; then make the text cheaper one mechanism at a time, with every static answer stored in the image. Build a compiled stream only if Route A leaves a large, measured overhead and a prototype shows the stream can remove it.

Route A: cheaper text, one step, one build, one commit each

Every step runs the goldens, the micro and macro sets, the never-slower set and a capacity check, on both boards. The capacity check has two parts: the image size from "Saved nnn bytes", and MM.INFO(HEAP) free at RUN for the largest corpus programs.

S6 in detail.

• The RAM binding table holds, per symbol, the global slot, the local slot and the local level. It is set when a variable is created and restored by ClearVars and ERASE.
• Reset events: CLEAR, RUN, NEW, ClearVars(0), CHAIN/RestoreContext, and LIBRARY LOAD ,RAM.
• An unbound symbol takes findvar and then binds. This keeps implicit creation, conditional LOCAL, re-DIM and recursion exact.
• Types come from the suffix, OPTION DEFAULT, DIM and LOCAL.
• Library and program symbols are merged.
• EXECUTE, CALL by string and the prompt use by-name lookup.
• A shadow build also runs findvar on every hit and counts disagreements.

Not in the plan unless the measurements ask for it. Four hand micro-optimisations are left out: a static argument pool, zeroing sized by argument count, an early exit from ClearVars, and a register-local skipelement. Each is likely below the ~4% placement floor on the anchor. One is allowed only when the histogram shows its bucket at 2x the floor or more. Caching the subfun count (S2) is different: it is algorithmic, O(N) to O(1).

Who does what, and on which hardware

Effort, all guesses: Phase 0 1-2 weeks; Phase 1 about a week; S1-S4 a few days each including board runs; S5-S7 several weeks together; Route B 3-5 months part-time, the bytecode strategy's own estimate.

Risks and compatibility checklist

Decisions needed from Peter