TP3/shell/tests/rt_exec.py

#!/usr/bin/env python3
"""rt_exec.py -- call every 8086 runtime entry with a known argument, on qemu,
and check what it does.

The runtime (shell/Runtime.mod) is hand-assembled 8086, so "it built" says
nothing about it.  This says it *runs*.  It used to run it on Unicorn, and
Unicorn 2.1.4 mis-decodes 16-bit ModRM memory operands, so it failed 33 of 33
and every one of those failures was the emulator's.  A wrong oracle is worse
than none: it cannot tell "my codegen is broken" from "the machine is broken".

So the machine is now qemu-system-i386, driven through the same boot sector the
.COM fixtures use (tests/exec/bootcom.s), and the expectations are unchanged
except where they were demonstrably wrong -- see EXPECTATION FIXES below.

    .pas-free:  RtProbe (base = RT_BASE)  -> blob + entry offsets
                rt_exec.py                 -> 16-64 byte case record
                exec/rtdrv.s (assembled)   -> a whole .COM image
                bootcom.s + qemu           -> one framed record per case
                rt_exec.py                 -> parsed, compared

    tests/rt_exec.py --probe   # the standalone runtime dump (base 0)
    tests/rt_exec.py --list    # the case names
    tests/rt_exec.py --show    # print what came out, assert nothing

EXPECTATION FIXES -- two expectations were wrong, and both were wrong in the
direction that made the HARNESS the suspect:

  * rdchar stores ONE byte (Runtime.EmitRdChar: `StDiDl' = MOV [DI], DL), so
    dumping a two-byte word and comparing it against ord(c) could never pass.
    The check was broken, the entry was right.  The case now reports two bytes
    and expects the character followed by the 0xEE poison that is still there.

  * rdint at end of input does NOT store anything.  TP3's xrdint returns to
    rnerr without touching the variable, and Runtime.EmitRdInt says so in its
    own comment ("^Z before any digit reaches rnend ... returns WITHOUT
    touching the variable").  The old expectation said the variable became 0.
    It stays at the poison, and that is the faithful answer.

Everything else is the original expectation verbatim.  The two `rdln' halves of
the six rdint cases are merged into the same case as the value they follow: a
readln that printed anything would change the same compared string, so the
assertion is unchanged - one qemu boot per check instead of two.
"""

import math
import os
import re
import struct
import subprocess
import sys
import tempfile

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from run_com_exec import (GM2, QEMU, build_boot_sector, build_floppy,  # noqa: E402
                          run_qemu, visible_output)

HERE = os.path.dirname(os.path.abspath(__file__))
SHELL = os.path.dirname(HERE)

# --------------------------------------------------------------- the layout
# RT_BASE is restated from exec/rtdrv.s on purpose: the driver needs the blob at
# a known offset and Python needs to know where the driver thinks it is, so the
# two are written down and then CHECKED against each other (see build_image).
# A restated constant that is never compared is a constant waiting to lie.
RT_BASE = 0x0190
HDR = 0x1100
DLEN = 32
DATA = 0x1110
STORE = 0x1140
WSTR = 0x1150
WSTR_EMPTY = 0x1158
CASE = 0x1160
CASE_SZ = 64
RDSTR_DST = 0x11B0
SST_HELLO = 0x11C0
SST_LONG = 0x11D0
SST_EMPTY = 0x11E0
SST_DST = 0x11F0
SST_CAT = 0x1200
SST_CAT0 = 0x1210
SST_WORLD = 0x1220
AXOUT = 0x11A6          # the driver stores the last call's AX here
FMTDEST = 0x1430        # a 64-byte string for the real_fmt cases
ASCSRC = 0x1470          # the ASCIIZ strings for real_val
REALDST = 0x0FA8

# A .COM is loaded at CS:0100, and every address in the image is an image
# offset.  The load bias is therefore the difference between the two, and
# putting it in one place here stops it being applied -- or forgotten -- in each
# field.  exec/rtdrv.s has its own .set of it, for the same reason it has its
# own .set of the record offsets: two independent statements that are then
# checked against each other by the fact that any disagreement stops the cases
# from passing.
LOAD_BIAS = 0x0100

# The 8086 has a fixed 16-byte-case-record area in rtdrv.s, and the harness
# asserts this window is still zeros.  If the driver outgrows its space it
# starts eating the runtime it is testing, which would be silent; this makes it
# loud.
DRIVER_TOP = 0x0180

# The four framing bytes exec/rtdrv.s wraps each case's report in.
SOH, STX, ETX, EOT = 0x01, 0x02, 0x03, 0x04

# Entry selector order, as Runtime.def declares it.  The names are used only to
# be looked up in RtProbe's output, so renaming an entry in Runtime.mod makes
# the lookup fail loudly instead of silently testing offset 0.
ENTS = ["initmem", "progend", "stackchk", "wrint", "wrchar", "wrbool",
        "wrreal", "wrln", "rdint", "rdchar", "rdbool", "rdln", "halt",
        "wrtinl", "rdbyte", "wrstr", "rdstr", "strstore", "cmpstr", "strcat",
        "wrintw", "real_from_int", "real_add", "real_sub", "real_mul",
        "real_div", "real_cmp", "real_int", "real_fmt", "real_val",
        "real_write"]

# A call slot's flags, as rtdrv.s reads them.
F_STACK = 1     # the argument goes on the stack, popped by the caller
F_AX = 2        # ...or in AX instead (initmem's convention)
F_INL = 4       # wrtinl: the argument is at the return address, not on the stack
F_STACK2 = 8    # two stack words: +6 pushed first (lands at [BP+6]), +2 second
                # (at [BP+4]) -- strstore's dest/src order
F_CX = 16       # CX := the word at +8, the maximum length rdstr and strstore
                # both read from the register
F_STACK3 = 32   # three stack words: +8 first, then +6, then +2, so +2 is
                # [BP+4], +6 is [BP+6] and +8 is [BP+8]

# The byte patterns check_bp_contract looks for, and the rule they express:
# "an entry that borrows BP opens with PUSH BP; MOV BP,SP and pops it again
# before it returns" -- so an entry containing 8B EC anywhere must start with
# 55 8B EC and must contain a 5D.  See that function: the first half of that
# rule is exact and the second is a screen, and the difference matters.
PUSH_BP_MOV_BP_SP = b"\x55\x8b\xec"   # PUSH BP ; MOV BP,SP
MOV_BP_SP = b"\x8b\xec"                # MOV BP,SP
POP_BP = b"\x5d"                       # POP BP


# --------------------------------------------------------------- RtProbe
def ensure_rtprobe():
    """Build tests/RtProbe.mod, return its path.

    Timestamp-checked, for the reason run_com_exec.ensure_comtest documents:
    a probe older than the runtime it reports on is worse than no probe, and
    the failure it produces -- a blob with the wrong addresses in it -- is
    silent at the byte level and catastrophic at the behaviour level.
    """
    exe = os.path.join(HERE, "rtprobe")
    newer = ["Runtime.mod", "Runtime.def", "Runtime.o", "Posix.c",
             os.path.join("tests", "RtProbe.mod")]
    if os.path.exists(exe):
        t = os.path.getmtime(exe)
        if all(os.path.exists(os.path.join(SHELL, f))
               and os.path.getmtime(os.path.join(SHELL, f)) <= t
               for f in newer):
            return exe
    r = subprocess.run([GM2, "-fiso", "-o", exe, "tests/RtProbe.mod",
                        "Runtime.o", "Posix.o"],
                       capture_output=True, cwd=SHELL)
    if r.returncode != 0:
        sys.exit("building RtProbe failed:\n" + r.stderr.decode(errors="replace"))
    return exe


def load_runtime(base):
    """Run RtProbe at `base`.

    Return (blob, {name: image-absolute offset}, code_end).  `code_end` is the
    blob-relative offset where the code stops and the data area starts, and it
    is what bounds the last entry's bytes: without it the last entry's "does
    it contain MOV SP,BP" question would be answered partly by the data area,
    and a string or an entry-table word that happens to contain the pattern
    would turn a missing epilogue into a pass.
    """
    out = subprocess.run([ensure_rtprobe()], input=b"%d\n" % base,
                         capture_output=True, check=True).stdout.decode(
                             errors="replace")
    # RtProbe ends its lines CR LF, as a program of this vintage would.  Every
    # pattern below is `$'-anchored, and Python's `$' in MULTILINE stops before
    # "\n" only -- so without this the first regex fails and the report blames
    # the probe for it.
    out = out.replace("\r\n", "\n")
    m = re.search(r"^base=(\d+)$", out, re.M)
    if m is None or int(m.group(1)) != base:
        sys.exit("RtProbe did not confirm base=%d:\n%s" % (base, out[:400]))
    size = int(re.search(r"^(\d+) bytes", out, re.M).group(1))
    cm = re.search(r"^code ends at (\d+)$", out, re.M)
    if cm is None:
        sys.exit("RtProbe did not say where the code ends:\n%s" % out[:400])
    code_end = int(cm.group(1))
    if not 0 < code_end <= size:
        sys.exit("RtProbe says the code ends at %d, which is not inside a "
                 "%d byte blob" % (code_end, size))
    entries = {nm: int(v) for v, nm in
               re.findall(r"entry \d+ = (\d+)\s+\((\w+)\)", out)}
    missing = [e for e in ENTS if e not in entries]
    if missing:
        sys.exit("RtProbe did not report entries: %s" % ", ".join(missing))
    blob = bytearray()
    for line in out.splitlines():
        h = re.match(r"^[0-9A-F]{8}  ((?:[0-9A-F]{2} )+)$", line)
        if h:
            blob += bytes.fromhex(h.group(1).replace(" ", ""))
    if len(blob) != size:
        sys.exit("parsed %d bytes of runtime, RtProbe says %d"
                 % (len(blob), size))
    for nm, off in entries.items():
        if not base <= off < base + code_end:
            sys.exit("entry %s is at %d, outside the code area %d..%d -- the "
                     "entry table and the blob disagree"
                     % (nm, off, base, base + code_end))
    return bytes(blob), entries, code_end


def probe():
    """The standalone dump run_all.sh's `runtime probe' step wants: base 0."""
    raw = subprocess.run([ensure_rtprobe()], input=b"0\n", capture_output=True,
                         check=True).stdout
    sys.stdout.buffer.write(raw)
    return 0


def check_bp_contract(blob, entries, base, code_end):
    """Every entry must hand BP back.

    The driver keeps its cursor into the case record in BP, because an entry is
    allowed to destroy every register except BP and SP.  Two entries did not
    honour that: wrchar and wrbool borrowed BP to reach their argument -- [SP]
    is unencodable in 16-bit mode -- and returned without saving it.  One
    multi-call case caught it, and only because it made four calls in a row; a
    new entry that borrowed BP the same way would be caught by nothing.

    So the rule is checked here, over the built blob, before any case runs.

    The rule is the runtime's own convention, in two halves, and the halves are
    NOT equally strong -- which is worth writing down rather than discovering:

      * "an entry that borrows BP must START with 55 8B EC" is EXACT.  The
        prologue is the first thing the entry does, so a positional test
        cannot be fooled by anything.

      * "...and must contain a 5D somewhere" is a SCREEN, not a proof.  5D is
        POP BP, but it is also a perfectly ordinary displacement byte, and
        this code does not disassemble.  Requiring the POP to be contiguous
        with something else does not rescue it either: wrbool legitimately
        closes its frame with POP BP after the INT 21h, and a rule that
        insisted on 89 EC 5D would have failed a correct entry -- a false
        alarm, which is worse here than a miss because it teaches a reader to
        distrust the check.  So the honest position is: a push with no pop is
        CAUGHT unless some displacement in the entry happens to be 5Dh, and
        the argument displacements in this runtime are 2 and 4, so nothing can
        collide today.  tests/nonvacuity.sh removes the POP as well as the
        PUSH and requires each to turn this red, so the screen is at least
        witnessed rather than assumed.

    Counting 55s and 5Ds to check frame BALANCE would be worse than either:
    55 occurs as an immediate and 5D as a displacement, so the answer would
    come out wrong without the check ever looking wrong.  For the same reason
    each entry's bytes stop at the next entry, or at `code_end` for the last
    one: running on into the data area would let a string satisfy either test.

    The counts it returns are the point as much as the verdict.  A scan that
    matches nothing is indistinguishable from a scan that passes, and that has
    happened here before -- so zero borrowers is a failure, not a pass.

    Entries are counted by OFFSET, not by name: `progend' and `halt' are one
    entry with two names, and counting them twice would make the total here
    disagree with the number of things that can actually be wrong.
    """
    offs = sorted(set(entries.values()))
    scanned = borrowed = 0
    bad = []
    for i, a in enumerate(offs):
        lo = a - base
        hi = (offs[i + 1] - base) if i + 1 < len(offs) else code_end
        code = bytes(blob[lo:hi])
        scanned += 1
        if MOV_BP_SP not in code:
            continue
        borrowed += 1
        # The two halves are reported separately, because they are separate
        # faults with separate fixes and "it does not hand BP back" does not
        # say which of them happened.
        if not code.startswith(PUSH_BP_MOV_BP_SP):
            why = "borrows BP but does not open with 55 8B EC, so the "\
                  "caller's BP is destroyed"
        elif POP_BP not in code:
            why = "pushes BP but never pops it, so the caller gets a "\
                  "cursor two bytes off"
        else:
            continue
        names = sorted(n for n, v in entries.items() if v == a)
        bad.append("%s -- %s (image 0x%04X: %s)"
                   % (",".join(names), why, a, code[:12].hex(" ")))
    if bad:
        sys.exit("these entries do not hand BP back, so a caller that keeps a "
                 "cursor in BP -- which this driver does, and which is the whole "
                 "reason BP is the one register an entry may keep -- loses it:\n"
                 "  %s" % "\n  ".join(bad))
    if borrowed == 0:
        sys.exit("no entry borrows BP, so this check examined %d entries and "
                 "matched nothing: it is not looking at what it claims to "
                 "look at" % scanned)
    return scanned, borrowed


# ------------------------------------------------------------------ the case
def case_bytes(c, entries):
    """One CASE_SZ byte case record, exactly as exec/rtdrv.s reads it.

    The record is a second, independent statement of the same layout rtdrv.s
    carries in its .set block.  The cases only pass if the two agree on every
    offset, which is the whole reason for writing it twice: a driver that
    silently read the wrong field would still boot, still run, and still print.
    """
    if len(c["in"]) > 8:
        sys.exit("case %s supplies %d input bytes; the record holds 8"
                 % (c["name"], len(c["in"])))
    b = bytearray(CASE_SZ)
    struct.pack_into("<H", b, 0, c["dump"])             # OFF_DUMPLEN
    struct.pack_into("<H", b, 2, c["dumpadr"])          # OFF_DUMPADR
    b[4] = len(c["in"])                                 # OFF_INLEN
    b[5:5 + len(c["in"])] = c["in"]                     # OFF_INBUF
    struct.pack_into("<H", b, 13, c["index"])           # OFF_CASE (word)
    calls = c["calls"]
    if len(calls) > 4:
        sys.exit("case %s has %d calls; the record holds 4"
                 % (c["name"], len(calls)))
    b[15] = len(calls)                                  # OFF_NCALLS (byte)
    for i, (ent, arg, mode, arg2, cx) in enumerate(calls):
        o = 16 + 12 * i                                 # SLOT0, SLOT_SZ = 12
        struct.pack_into("<H", b, o, entries[ent])
        struct.pack_into("<H", b, o + 2, arg & 0xFFFF)
        b[o + 4] = mode
        struct.pack_into("<H", b, o + 6, arg2 & 0xFFFF)
        struct.pack_into("<H", b, o + 8, cx & 0xFFFF)
    return bytes(b)


def build_image(blob, rec):
    """Assemble exec/rtdrv.s into a complete .COM, and check it is the one
    we think it is.

    The three assertions are the point of this function.  An image that is
    subtly not the image we intended would still boot, still run, and still
    print something -- the failure would look like a runtime bug.
    """
    if RT_BASE + len(blob) > HDR:
        sys.exit("the runtime is %d bytes: at RT_BASE=%04X it runs into the "
                 "test scaffolding at %04X.  Move the .org's in rtdrv.s."
                 % (len(blob), RT_BASE, HDR))
    with tempfile.TemporaryDirectory() as td:
        open(os.path.join(td, "rtblob.bin"), "wb").write(blob)
        open(os.path.join(td, "rtcase.bin"), "wb").write(rec)
        src = os.path.join(HERE, "exec", "rtdrv.s")
        obj, raw = os.path.join(td, "r.o"), os.path.join(td, "r.bin")
        r = subprocess.run(["as", "--32", "-I", td, "-o", obj, src],
                           capture_output=True)
        if r.returncode != 0:
            sys.exit("as failed on rtdrv.s:\n"
                     + r.stderr.decode(errors="replace"))
        r = subprocess.run(["objcopy", "-O", "binary", obj, raw],
                           capture_output=True)
        if r.returncode != 0:
            sys.exit("objcopy failed:\n" + r.stderr.decode(errors="replace"))
        img = open(raw, "rb").read()

    # E9 00 00: a near jump to offset 3 from offset 0, so the displacement is
    # 3 - (0 + 3) = 0.  The driver is the first thing after the jump, which is
    # what makes the rel16 zero and therefore useless as a check on the target
    # -- the check that matters is the one below, that the blob landed where the
    # driver thinks it did.
    if img[0:3] != b"\xe9\x00\x00":
        sys.exit("rtdrv.s does not open with a 3-byte near JMP over itself: %s"
                 % img[0:3].hex())
    if img[RT_BASE:RT_BASE + len(blob)] != blob:
        sys.exit("the blob is not at RT_BASE=%04X in the assembled image -- "
                 "rtdrv.s and rt_exec.py disagree about the layout"
                 % RT_BASE)
    gap = img[DRIVER_TOP:RT_BASE]
    if gap != b"\x00" * len(gap):
        sys.exit("the driver has outgrown its space: rtdrv.s no longer fits "
                 "under %04X, so it is overwriting the runtime" % DRIVER_TOP)
    return img


def parse_record(raw, want_index):
    """Split the serial output into (case index, printed, dumped) or raise.

    Nothing here is lenient.  A driver that printed nothing, a truncated
    record, or a record for the wrong case are all failures with a reason, not
    a comparison against an empty string that happens to pass.
    """
    if not raw or raw[0] != SOH:
        raise AssertionError("no record header: the driver printed %r" % raw[:64])
    if len(raw) < 7 or raw[5] != STX:
        raise AssertionError("malformed record header %r" % raw[:16])
    idx = int(raw[1:5], 16)
    if idx != want_index:
        raise AssertionError("record is for case %04X, expected %04X"
                             % (idx, want_index))
    if raw[-1] != EOT:
        raise AssertionError("record was never closed (EOT): the last call did "
                             "not return, or the machine halted early")
    end = raw.index(ETX, 6)
    if end < 0:
        raise AssertionError("record has no ETX: the calls printed nothing and "
                             "the driver never got past them")
    printed, dump = raw[6:end], raw[end + 1:-1]
    if len(dump) % 2 or not re.fullmatch(b"[0-9A-F]*", dump):
        raise AssertionError("the memory report %r is not hex" % dump)
    return idx, printed, bytes.fromhex(dump.decode())


# ----------------------------------------------------------------- the cases
def build_cases():
    """Every check, in the order the names are printed.

    Each case is a list of calls plus two expectations: the bytes the entry(s)
    printed, and the bytes that must be at `dumpadr' afterwards.  `dump=0' means
    the case asserts nothing about memory, which is itself an assertion: the
    report is empty, so a case cannot quietly acquire a memory check it did not
    ask for.

    The addresses handed to an entry as its argument are MEMORY addresses, not
    image offsets -- that is the whole of LoadBias, and it is the difference
    between a read entry storing where the harness looks and storing one page
    lower where nothing checks it.  V below is "the memory address of STORE",
    which is what every read case wants.
    """
    cs = []
    V = STORE + LOAD_BIAS

    def add(name, calls, out=b"", stdin=b"", dump=0, dumpbytes=b"",
            dumpadr=STORE, note=""):
        cs.append({"name": name, "calls": calls, "out": out, "in": stdin,
                   "dump": dump, "dumpbytes": dumpbytes, "dumpadr": dumpadr,
                   "note": note, "index": len(cs)})

    def s(ent, arg):
        return (ent, arg, F_STACK, 0, 0)

    def x(ent, arg):
        return (ent, arg, F_AX, 0, 0)

    def n(ent):
        return (ent, 0, 0, 0, 0)

    def i(ent):
        return (ent, 0, F_INL, 0, 0)

    def s2(ent, arg, arg2):
        """Two stack words: arg2 is pushed first (it lands at [BP+6]), arg
        second (at [BP+4]).  real_from_int(src, dst) takes its source first."""
        return (ent, arg, F_STACK | F_STACK2, arg2, 0)

    def s3(ent, a, b, c):
        """Three stack words: c is pushed first (landing at [BP+8]), then b
        ([BP+6]), then a ([BP+4])."""
        return (ent, a, F_STACK | F_STACK3, b, c)

    def s2cx(ent, arg, arg2, cx):
        """Two stack words AND CX: arg2 is pushed first (it lands at [BP+6]),
        arg second (at [BP+4]), and CX carries the maximum length.  strstore is
        the only entry that wants all three."""
        return (ent, arg, F_STACK | F_STACK2 | F_CX, arg2, cx)

    def scx(ent, arg, cx):
        """One stack word and CX, for rdstr: dest at [BP+4], limit in CX."""
        return (ent, arg, F_STACK | F_CX, 0, cx)

    # initmem is handed the header in AX -- and the header's MEMORY address, not
    # its image offset.  Given the image offset it reads the two words it wants
    # out of blank space, finds both zero, and clears nothing at all: a silent
    # no-op, which is the reason this case poisons the data area to AAH first.
    add("initmem zeroes globals",
        [x("initmem", HDR + LOAD_BIAS)], dump=DLEN, dumpadr=DATA,
        dumpbytes=b"\x00" * DLEN,
        note="the data area is poisoned to AA first, so a zero is a result")

    for v, why in [(0, "the one value where a signed/unsigned slip is invisible"),
                   (1, ""), (-1, ""), (7, ""), (10, ""), (42, ""),
                   (100, ""), (12345, ""), (-32768, "the sign bit"), (32767, "")]:
        add("wrint(%d)" % v, [s("wrint", v & 0xFFFF)],
            out=str(v).encode(), note=why)

    # --- the 6-byte MBF real: integer -> real ---------------------------
    # The source word is passed in the case record's input bytes (CASE+5),
    # and the destination at STORE; both are memory addresses, as always.
    def mbf(v):
        """TP3's measured 6-byte Real for an integer (CALC-PORT.md)."""
        if v == 0:
            return bytes(6)
        neg = v < 0
        a = abs(v)
        k = a.bit_length() - 1
        e = 129 + k
        n = (a - (1 << k)) << (39 - k)
        b = bytearray([e]) + bytearray((n >> (8 * i)) & 0xFF
                                       for i in range(5))
        if neg:
            b[5] |= 0x80
        return bytes(b)

    def mbf_float(x):
        """The measured 6-byte MBF nearest to a fractional value."""
        if x == 0:
            return bytes(6)
        neg = x < 0
        a = abs(x)
        k = math.floor(math.log2(a))
        e = 129 + k
        n = int(round((a / (2.0 ** k) - 1.0) * (1 << 39)))
        if n >= (1 << 39):
            n = 0
            e += 1
        b = bytearray([e]) + bytearray((n >> (8 * i)) & 0xFF for i in range(5))
        if neg:
            b[5] |= 0x80
        return bytes(b)

    SRC = CASE + 5 + LOAD_BIAS
    for v in (0, 1, 2, 3, 5, 7, 42, 1000, 32767, -1, -2, -42, -32768):
        add("real_from_int(%d)" % v,
            [s2("real_from_int", STORE + LOAD_BIAS, SRC)],
            stdin=struct.pack("<h", v),
            dump=6, dumpbytes=mbf(v), dumpadr=STORE,
            note="the measured exponent bias is 129")

    # --- MBF addition and subtraction -----------------------------------
    # The driver preloads 12-byte blocks (a then b); real_add/real_sub take
    # the block's address, read both operands, and overwrite a with the result.
    BLOCKS = [(1, 2), (3, 5), (5, 3), (1, 1), (1000, 1), (-3, 2),
              (42, 1000), (32767, 1), (0, 5), (-3, -2),
              (6, 2), (10, 2), (15, 3), (1000, 2), (-6, 2), (6, -2),
              (-6, -2), (0, 5), (5, 2), (42, 6)]
    for bi, (a, b) in enumerate(BLOCKS):
        blk = 0x1230 + 16 * bi
        add("real_add(%d,%d)" % (a, b),
            [s("real_add", blk + LOAD_BIAS)],
            dump=6, dumpbytes=mbf(a + b), dumpadr=blk,
            note="the measured MBF bytes, the reference's readd")
        add("real_sub(%d,%d)" % (a, b),
            [s("real_sub", blk + LOAD_BIAS)],
            dump=6, dumpbytes=mbf(a - b), dumpadr=blk,
            note="the measured MBF bytes, the reference's resub")
        add("real_mul(%d,%d)" % (a, b),
            [s("real_mul", blk + LOAD_BIAS)],
            dump=6, dumpbytes=mbf(a * b), dumpadr=blk,
            note="the measured MBF bytes, the reference's remult")
        if b != 0 and a % b == 0:
            q = mbf(a // b)
        elif a == 5 and b == 2:
            q = bytes.fromhex("820000000020")   # 2.5
        else:
            q = None
        if q is not None:
            add("real_div(%d,%d)" % (a, b),
                [s("real_div", blk + LOAD_BIAS)],
                dump=6, dumpbytes=q, dumpadr=blk,
                note="the measured MBF bytes, the reference's rediv")

    # --- recmp: AX := -1/0/+1 for a<b, a=b, a>b ------------------------
    # The driver stores every call's AX at AXOUT, so these cases can read the
    # result.  The operand block is the same one the arithmetic cases use.
    seen = set()
    for bi, (a, b) in enumerate(BLOCKS):
        if (a, b) in seen:
            continue
        seen.add((a, b))
        blk = 0x1230 + 16 * bi
        want = (a > b) - (a < b)
        add("real_cmp(%d,%d)" % (a, b),
            [s("real_cmp", blk + LOAD_BIAS)],
            dump=2, dumpbytes=struct.pack("<H", want & 0xFFFF), dumpadr=AXOUT,
            note="the reference's recmp, returned as AX = -1/0/+1")

    # Fractional blocks, compared through the exponent/mantissa path.
    FRAC = [(3.7, 3.7), (3.9, 3.7), (-3.7, -3.9), (0.5, 0.25),
            (-0.5, 0.5), (12345.75, 12345.5), (2.5, 0.0), (-2.5, 0.0),
            (0.99, 0.0), (1.9, 0.0)]
    for fi, (a, b) in enumerate(FRAC):
        blk = 0x1370 + 16 * fi
        want = (a > b) - (a < b)
        add("real_cmp(%g,%g)" % (a, b),
            [s("real_cmp", blk + LOAD_BIAS)],
            dump=2, dumpbytes=struct.pack("<H", want & 0xFFFF), dumpadr=AXOUT,
            note="fractional magnitudes: the mantissa decides")
    add("real_cmp(2^40,0)",
        [s("real_cmp", 0x1410 + LOAD_BIAS)],
        dump=2, dumpbytes=struct.pack("<h", 1), dumpadr=AXOUT,
        note="the exponent alone decides")

    # --- reint: Int(real), in place --------------------------------------
    # a is the real; the block's b is unused.  The expected bytes are the
    # measured MBF of trunc(a), because reint returns a REAL, not an integer
    # (TPSRC's xint pushes the six-byte result back).
    for bi, (a, b) in enumerate(BLOCKS):
        if a in (0, 1, -3, 32767):
            blk = 0x1230 + 16 * bi
            add("real_int(%d)" % a,
                [s("real_int", blk + LOAD_BIAS)],
                dump=6, dumpbytes=mbf(math.trunc(a)), dumpadr=blk,
                note="the integer part as a real, the reference's reint")
    for fi, (a, b) in enumerate(FRAC):
        blk = 0x1370 + 16 * fi
        add("real_int(%g)" % a,
            [s("real_int", blk + LOAD_BIAS)],
            dump=6, dumpbytes=mbf(math.trunc(a)), dumpadr=blk,
            note="the fraction is masked away; the sign and exponent stay")
    add("real_int(2^40)",
        [s("real_int", 0x1410 + LOAD_BIAS)],
        dump=6, dumpbytes=bytes.fromhex("A90000000000"), dumpadr=0x1410,
        note="exponent >= 0A8h is already integral and returns unchanged")

    # --- fmtreal: real_fmt writes a length-prefixed, left-padded field -----
    # CX = (decimals << 8) | width, [BP+4] = real, [BP+6] = destination.
    def fmt(name, blk, width, dec, text):
        add(name,
            [s2cx("real_fmt", blk + LOAD_BIAS, FMTDEST + LOAD_BIAS,
                  (dec << 8) | width)],
            dump=1 + len(text), dumpbytes=bytes([len(text)]) + text,
            dumpadr=FMTDEST,
            note="the reference's fmtreal; dest[0] is the field length")
    add("real_fmt(from int 1)",
        [s2("real_from_int", STORE + LOAD_BIAS, SRC),
         s2cx("real_fmt", STORE + LOAD_BIAS, FMTDEST + LOAD_BIAS, 0)],
        stdin=struct.pack("<h", 1), dump=2, dumpbytes=bytes([1]) + b"1",
        dumpadr=FMTDEST, note="a known-good 1.0 from real_from_int")
    fmt("real_fmt(1:0:0)", 0x1230, 0, 0, b"1")
    fmt("real_fmt(0:0:0)", 0x12B0, 0, 0, b"0")
    fmt("real_fmt(3.7:0:2)", 0x1370, 0, 2, b"3.70")
    fmt("real_fmt(12345.75:12:2)", 0x13C0, 12, 2, b"    12345.75")
    fmt("real_fmt(0.5:6:3)", 0x13A0, 6, 3, b" 0.500")
    fmt("real_fmt(-3.7:0:1)", 0x1390, 0, 1, b"-3.7")
    fmt("real_fmt(0:5:2)", 0x12B0, 5, 2, b" 0.00")
    fmt("real_fmt(2.5:0:0)", 0x13D0, 0, 0, b"3")
    fmt("real_fmt(3.7:10:25)", 0x1370, 10, 25, b"3.7000E+00")

    # --- ascreal: real_val parses an ASCIIZ string ------------------------
    # A dump of AXOUT shows the returned offset, or FFFFh on a hard error.
    ASC_STRINGS = [b"3.5\0", b"-2.25\0", b"1E3\0", b"0.5\0",
                   b"12345.75\0", b"3.5x\0", b"1E\0", b"1E40\0",
                   b"\0", b".5\0", b"1.2.3\0", b"35\0", b"5E-1\0", b"5.\0", b"5.0\0", b"12345\0", b"1234575\0", b"1234.5\0", b"1000\0", b"123\0", b"1234\0", b"12340\0", b"12341\0", b"12341E0\0", b"12345E0\0"]
    WANT_OFF = [3, 5, 3, 3, 8, 3, 0xFFFF, 0xFFFF, 0, 2, 0xFFFF, 2, 4, 2, 3, 5, 7, 6, 4, 3, 4, 5, 5, 7, 7]
    off = 0
    for txt, want in zip(ASC_STRINGS, WANT_OFF):
        add("real_val(%r) offset" % txt[:-1],
            [s2("real_val", ASCSRC + off + LOAD_BIAS, STORE + LOAD_BIAS)],
            dump=2, dumpbytes=struct.pack("<H", want & 0xFFFF), dumpadr=AXOUT,
            note="AX = the first unparsed character, FFFFh on error")
        off += len(txt)
    # The parsed VALUE.  On a hard error nothing is stored, and STORE is
    # poisoned with EEEE (its first two bytes are all the driver writes), so
    # those cases also prove the destination was left alone.
    VAL = [3.5, -2.25, 1000.0, 0.5, 12345.75, 3.5, None, None, 0.0, 0.5,
           None, 35.0, 0.5, 5.0, 5.0, 12345.0, 1234575.0, 1234.5,
           1000.0, 123.0, 1234.0, 12340.0, 12341.0, 12341.0, 12345.0]
    off = 0
    for txt, v in zip(ASC_STRINGS, VAL):
        wantv = (b"\xEE\xEE" + bytes(4)) if v is None else mbf_float(v)
        add("real_val(%r) value" % txt[:-1],
            [s2("real_val", ASCSRC + off + LOAD_BIAS, STORE + LOAD_BIAS)],
            dump=6, dumpbytes=wantv, dumpadr=STORE,
            note="the packed MBF, or the untouched EEEE poison on error")
        off += len(txt)

    for bi, (a, b) in [(0, (12340, 5)), (1, (12340, 1))]:
        blk = 0x1500 + 16 * bi
        add("real_add(%d,%d)" % (a, b), [s("real_add", blk + LOAD_BIAS)],
            dump=6, dumpbytes=mbf(a + b), dumpadr=blk,
            note="a large value plus a small digit: the add core's alignment")

    for bi, a in [(2, 12341), (3, 12345), (4, 12340)]:
        blk = 0x1500 + 16 * bi
        add("real_mul(%d,1)" % a, [s("real_mul", blk + LOAD_BIAS)],
            dump=6, dumpbytes=mbf(a), dumpadr=blk,
            note="multiplying by 1.0 must be exact")

    # --- real_write: [BP+4]=decimals, [BP+6]=width, [BP+8]=real ----------
    def wr(name, blk, width, dec, text):
        add(name, [s3("real_write", dec, width, blk + LOAD_BIAS)], out=text,
            note="fmtreal's field, padded and printed by the entry itself")
    wr("real_write(3.7:0:2)", 0x1370, 0, 2, b"3.70")
    wr("real_write(3.7:10:2)", 0x1370, 10, 2, b"      3.70")
    wr("real_write(12345.75:12:2)", 0x13C0, 12, 2, b"    12345.75")
    wr("real_write(0.5:0:3)", 0x13A0, 0, 3, b"0.500")
    wr("real_write(-3.7:0:1)", 0x1390, 0, 1, b"-3.7")
    wr("real_write(2.5:0:0)", 0x13D0, 0, 0, b"3")
    wr("real_write(42:0:0)", 0x1290, 0, 0, b"42")
    wr("real_write(3.7:18:FFFF)", 0x1370, 18, 0xFFFF,
       b"  3.7000000000E+00")

    add("wrchar('A')", [s("wrchar", ord("A"))], out=b"A")
    add("wrchar('!')", [s("wrchar", ord("!"))], out=b"!")

    add("wrbool(0)", [s("wrbool", 0)], out=b"FALSE")
    add("wrbool(1)", [s("wrbool", 1)], out=b"TRUE")
    add("wrbool(2)", [s("wrbool", 2)], out=b"TRUE",
        note="any non-zero is true, as TP3's xwrb does")

    add("wrln", [n("wrln")], out=b"\r\n")

    add("stackchk returns", [n("stackchk")], out=b"",
        note="no output: the assertion is that control came back at all")

    add("writeln(42) writeln TRUE in one program",
        [s("wrint", 42), s("wrchar", ord(" ")), s("wrbool", 1), n("wrln")],
        out=b"42 TRUE\r\n",
        note="four calls back to back, so no register leaks between them")

    # rdint: the value, and then the rdln that must eat the rest of the line.
    for text, want in [(b"  42abc", 42), (b"-17 x", -17), (b"+5", 5),
                       (b"0", 0), (b"  007", 7), (b"1234", 1234)]:
        add("rdint(%r) then rdln" % text,
            [s("rdint", V), n("rdln")], out=b"", stdin=text, dump=2,
            dumpbytes=struct.pack("<H", want & 0xFFFF),
            note="the delimiter must be left for rdln, which prints nothing")

    for c in "Q7":
        add("rdchar(%r)" % c, [s("rdchar", V)], out=b"", stdin=c.encode(),
            dump=2, dumpbytes=bytes([ord(c), 0xEE]),
            note="rdchar stores ONE byte, so the poison is still in byte 2")

    # rdbyte: the same reader as rdint, entered through its own frame, and the
    # whole point is the WIDTH of the store.  A poison byte sits just past the
    # variable, so the word store rdint used would show up here as byte 2
    # turning into the high byte of the value instead of staying EE.  -1 is
    # the case where the two disagree most visibly: the value is FFFF, so a
    # word store writes FF twice.
    for text, want in [(b"200", 200), (b"-1", 0xFF), (b"7", 7), (b"0", 0)]:
        add("rdbyte(%r) then rdln" % text,
            [s("rdbyte", V), n("rdln")], out=b"", stdin=text, dump=2,
            dumpbytes=bytes([want & 0xFF, 0xEE]),
            note="rdbyte stores ONE byte, so the poison is still in byte 2")

    for c, want in [("T", 1), ("y", 1), ("1", 1), ("F", 0), ("n", 0), ("0", 0)]:
        add("rdbool(%r)" % c, [s("rdbool", V)], out=b"", stdin=c.encode(),
            dump=2, dumpbytes=struct.pack("<H", want & 0xFFFF))

    add("rdint at end of input leaves the variable alone",
        [s("rdint", V), n("rdln")], out=b"", stdin=b"", dump=2,
        dumpbytes=b"\xee\xee",
        note="TP3's xrdint returns to rnerr without storing; the poison stays")

    add("rdbyte at end of input leaves the variable alone",
        [s("rdbyte", V), n("rdln")], out=b"", stdin=b"", dump=2,
        dumpbytes=b"\xee\xee",
        note="rdscan returns CX=2 on the ^Z path, so rdbyte stores nothing")

    add("wrtinl reads its length and characters from the return address",
        [i("wrtinl")], out=b"hello",
        note="the one entry whose argument is not a stack word")

    # wrstr is the other way round from wrtinl: its argument IS a stack word,
    # but a word that has to be a POINTER, so the string's bytes live in memory
    # instead of after the call.  WSTR (seeded in rtdrv.s, restated here) is a
    # length byte and five characters - the same bytes wrtinl reads from the
    # code stream - so the two cases must print the same word.  The argument
    # carries LOAD_BIAS because a runtime entry dereferences a MEMORY address,
    # not an image offset.
    add("wrstr prints the length byte's worth of characters",
        [s("wrstr", WSTR + LOAD_BIAS)], out=b"hello",
        note="the entry dereferences the stack word; the bytes are in memory")

    add("wrstr prints nothing for an empty string",
        [s("wrstr", WSTR_EMPTY + LOAD_BIAS)], out=b"",
        note="a length byte of 0 must print no characters at all")

    # --- rdstr: the entry behind readln(s)/read(s).  Its argument is a stack
    # word (the destination address), it walks it with SI, and CX is the limit.
    # The destination is pre-filled with 0xEE in rtdrv.s, so every byte past the
    # stored length is a checked claim that the entry did not write it.
    add("rdstr reads a line into a string",
        [scx("rdstr", RDSTR_DST + LOAD_BIAS, 10)], out=b"", stdin=b"hello\n",
        dump=11, dumpbytes=bytes([5]) + b"hello" + b"\xee" * 5,
        dumpadr=RDSTR_DST,
        note="length byte then the characters; nothing past the length is written")

    add("rdstr truncates a line longer than CX",
        [scx("rdstr", RDSTR_DST + LOAD_BIAS, 3)], out=b"", stdin=b"abcdef\n",
        dump=5, dumpbytes=bytes([3]) + b"abc" + b"\xee",
        dumpadr=RDSTR_DST,
        note="CX is the limit; the rest of the line is left unread, not stored")

    add("rdstr stores length 0 for an empty line",
        [scx("rdstr", RDSTR_DST + LOAD_BIAS, 10)], out=b"", stdin=b"\n",
        dump=3, dumpbytes=bytes([0]) + b"\xee\xee", dumpadr=RDSTR_DST,
        note="the terminator is the first character, so only dest[0] is written")

    add("rdstr at end of input stores length 0",
        [scx("rdstr", RDSTR_DST + LOAD_BIAS, 10)], out=b"", stdin=b"",
        dump=3, dumpbytes=bytes([0]) + b"\xee\xee", dumpadr=RDSTR_DST,
        note="getch returns ^Z at end of input, a terminator like CR and LF")

    # --- strstore: `s := t' for two string variables.  dest at [BP+4], source
    # at [BP+6], maximum in CX.  The count is min(source length, CX), the source
    # is never written, and the destination tail past the new length is left
    # exactly as it was.
    add("strstore copies a whole string",
        [s2cx("strstore", SST_DST + LOAD_BIAS, SST_HELLO + LOAD_BIAS, 20)],
        out=b"", dump=8, dumpbytes=bytes([5]) + b"hello" + b"\xee" * 2,
        dumpadr=SST_DST,
        note="dest length and characters; the tail past them is still EE")

    add("strstore truncates to the destination maximum",
        [s2cx("strstore", SST_DST + LOAD_BIAS, SST_LONG + LOAD_BIAS, 4)],
        out=b"", dump=8, dumpbytes=bytes([4]) + b"abcd" + b"\xee" * 3,
        dumpadr=SST_DST,
        note="count := min(source length, CX); the source itself is not shortened")

    add("strstore copies an empty string",
        [s2cx("strstore", SST_DST + LOAD_BIAS, SST_EMPTY + LOAD_BIAS, 10)],
        out=b"", dump=4, dumpbytes=bytes([0]) + b"\xee" * 3, dumpadr=SST_DST,
        note="CX 0 must copy nothing -- LOOP would otherwise run 65536 times")

    add("strstore leaves the source alone",
        [s2cx("strstore", SST_DST + LOAD_BIAS, SST_LONG + LOAD_BIAS, 4)],
        out=b"", dump=9, dumpbytes=bytes([8]) + b"abcdefgh", dumpadr=SST_LONG,
        note="TP3 shortens a stack copy of the source; this entry writes none")

    # --- cmpstr: string compare, AX := -1 / 0 / +1 for left <, =, > right.
    # left is at [BP+6] and right at [BP+4] (the same order s2cx gives which
    # string goes where), so this compares 'hello' against 'abcdefgh'.
    #
    # The sign is NOT checked here, and cannot be: a case record dumps MEMORY,
    # and the driver does not capture AX after a call.  What this case can say
    # is that the entry runs to RET without touching an operand - it is
    # read-only - and check_bp_contract separately proves it hands BP back.  The
    # SIGN is pinned by t48_strcmp and t49_strcmp_lit, which run whole compiled
    # programs on qemu and print all six relations as booleans; a program is a
    # better observer of a return value than a record with no field for one.
    add("cmpstr compares 'hello' with 'abcdefgh' and writes neither",
        [s2cx("cmpstr", SST_LONG + LOAD_BIAS, SST_HELLO + LOAD_BIAS, 20)],
        out=b"", dump=6, dumpbytes=bytes([5]) + b"hello", dumpadr=SST_HELLO,
        note="the dump is the LEFT operand ([BP+6]); it must come back unchanged")

    # --- strcat: s := s + t.  The same argument shape as strstore -- source
    # pushed first, destination at [BP+4], maximum in CX -- but the DESTINATION
    # is READ as well as written: dest[0] is the existing length, dest[0]+src[0]
    # is the new one, and the characters are copied to dest[1]+dest[0].  That is
    # why the destination is seeded: strstore may ignore its destination, but
    # 0xEE here would read as a length of 238 and raise the overflow error.
    #
    # The overflow EXIT cannot be a case: a record dumps memory after the calls
    # return, and the error path leaves through INT 21h AH=4C, so the record is
    # never closed.  t55_strcat_overflow runs a whole compiled program and
    # checks the exit code instead - see run_com_exec.py and the .exit file.
    add("strcat appends the source to the destination",
        [s2cx("strcat", SST_CAT + LOAD_BIAS, SST_WORLD + LOAD_BIAS, 20)],
        out=b"", dump=11, dumpbytes=bytes([10]) + b"helloworld",
        dumpadr=SST_CAT,
        note="'hello' + 'world': the new length is the SUM of the two")

    add("strcat appends to an empty destination",
        [s2cx("strcat", SST_CAT0 + LOAD_BIAS, SST_WORLD + LOAD_BIAS, 20)],
        out=b"", dump=6, dumpbytes=bytes([5]) + b"world", dumpadr=SST_CAT0,
        note="a zero destination length is the ordinary case, not a special one")

    add("strcat of an empty source leaves the destination alone",
        [s2cx("strcat", SST_CAT + LOAD_BIAS, SST_EMPTY + LOAD_BIAS, 20)],
        out=b"", dump=8, dumpbytes=bytes([5]) + b"hello" + b"\xee" * 2,
        dumpadr=SST_CAT,
        note="a zero SOURCE length takes JCXZ; a LOOP would run 65536 times")

    add("strcat at the destination maximum does not overflow",
        [s2cx("strcat", SST_CAT + LOAD_BIAS, SST_WORLD + LOAD_BIAS, 10)],
        out=b"", dump=11, dumpbytes=bytes([10]) + b"helloworld",
        dumpadr=SST_CAT,
        note="sum == CX is allowed; only sum > CX is the error")

    return cs


def run_case(c, blob, entries, boot):
    rec = case_bytes(c, entries)
    img = build_image(blob, rec)
    with tempfile.TemporaryDirectory() as td:
        floppy = os.path.join(td, "f.img")
        open(floppy, "wb").write(build_floppy(boot, img, c["in"]))
        return run_qemu(floppy)


def main(argv):
    if "--probe" in argv:
        return probe()
    cases = build_cases()
    if "--list" in argv:
        for c in cases:
            print(c["name"])
        return 0
    show = "--show" in argv
    only = [a for a in argv if not a.startswith("-")]

    blob, entries, code_end = load_runtime(RT_BASE)
    boot = build_boot_sector()

    # Before any machine is started: the contract the driver depends on.
    nscan, nborrow = check_bp_contract(blob, entries, RT_BASE, code_end)
    print("  %-52s PASS   (%d entries scanned, %d borrow BP and hand it "
          "back)" % ("every entry preserves BP", nscan, nborrow))
    npass = 1
    nfail = 0
    for c in cases:
        if only and not any(o in c["name"] for o in only):
            continue
        # A marker byte inside an expectation would make the framing
        # ambiguous, so it is refused rather than mis-parsed.
        for b in (SOH, STX, ETX, EOT):
            if bytes([b]) in c["out"]:
                sys.exit("case %s: its expected output contains the framing "
                         "byte %02X, which would be indistinguishable from the "
                         "driver's own markers" % (c["name"], b))
        raw, rc, note = run_case(c, blob, entries, boot)
        if show:
            print(c["name"], "->", repr(visible_output(raw)))
            continue
        try:
            _, printed, dumped = parse_record(raw, c["index"])
        except AssertionError as e:
            print("  %-52s FAIL  %s" % (c["name"], e))
            nfail += 1
            continue
        if printed != c["out"]:
            print("  %-52s FAIL  printed %s, want %s"
                  % (c["name"], visible_output(printed),
                     visible_output(c["out"])))
            nfail += 1
            continue
        if dumped != c["dumpbytes"]:
            print("  %-52s FAIL  +%04X = %s, want %s"
                  % (c["name"], c["dumpadr"], dumped.hex() or "-",
                     c["dumpbytes"].hex() or "-"))
            nfail += 1
            continue
        print("  %-52s PASS%s" % (c["name"],
                                  ("   (" + c["note"] + ")") if c["note"] else ""))
        npass += 1
    if show:
        return 0
    print("\nruntime entries: %d passed, %d failed (of %d)"
          % (npass, nfail, npass + nfail))
    return 1 if nfail else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))