Give the machine a frame to wait for

V3. The screen interrupts at each frame on hardware vector 0x30, and WAIT finally has
something worth sleeping on.

THERE WAS NO CLOCK. Every program that wanted to happen at a certain speed counted
instructions and hoped, which is why Snake's pause silently halved the day a cycle stopped
being an instruction and became a memory access - the program was right and the thing it was
counting changed underneath it. A screen finishing sixty times a second is a real beat, and
it is counted in the MACHINE'S cycles rather than the host's, so the same program sees the
same number of frames in the same number of cycles however fast anything really ran. That is
what makes a frame something a test can count and a recorded result can hold.

Status bit 0 goes up when a frame has gone by and reading the status port puts it down, so a
program with no handler can watch for it instead. Control bit 0 asks to be interrupted, and
is OFF when the machine starts: an interrupt with nothing installed to catch it is a fault,
so a screen that began interrupting the moment it was switched on would take down every
program written before frames existed.

More than one frame can pass between two looks, and the flag and the line are each one
thing, so several still mean one of each. A missed frame is missed.

Programs/Examples/frames.asm prints a dot a frame for a second: 1,000,324 cycles, and 996,460
of them spent asleep. That split is the thing worth seeing - a program that polled instead
would print the same sixty dots, take the same second, and spend every cycle of it on the
bus. Its header explains why waiting is not spinning and why a machine with a beat can stop
guessing at one.

Six checks in Tests/video.sh, and two of them are about the clock rather than the output,
because the output cannot tell the difference. That the machine slept through nearly all of
ten frames, and that polling three frames actually took three frames - a status flag that
stayed up once set would print exactly the same character and look perfectly correct.

Breaking the frame interrupt on purpose left a machine asleep for ever and hung the whole
suite, which is a worse way to be told than a failing check. Tests/video.sh bounds its runs
at ten seconds now, the way Tests/run.sh always has.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW

Tests/video.sh

@@ -124,11 +124,21 @@ run() {
     cat > "$BUILD/$name.asm"
     "$ASM" "$BUILD/$name.asm" -o "$BUILD/$name.bin" >"$BUILD/$name.log" 2>&1 || {
         echo "could not assemble $name"; sed 's/^/    /' "$BUILD/$name.log"; return 1; }
+    # ---- Bounded, the way run.sh bounds things ----
+    #
+    # A program here can WAIT for something that never comes, and one did: breaking the frame
+    # interrupt on purpose left a machine asleep for ever and took the whole suite with it,
+    # which is a worse way to be told than a failing check. Ten seconds, and a test that hangs
+    # says so instead of hanging.
     if [ -n "${2:-}" ]; then
-        "$EMU" --fast --keyboard "$2" --screen "$BUILD/$name.ppm" "$BUILD/$name.bin" \
-            > "$BUILD/$name.out" 2>&1
+        timeout 10 "$EMU" --fast --keyboard "$2" --screen "$BUILD/$name.ppm" \
+            "$BUILD/$name.bin" > "$BUILD/$name.out" 2>&1
     else
-        "$EMU" --fast --screen "$BUILD/$name.ppm" "$BUILD/$name.bin" > "$BUILD/$name.out" 2>&1
+        timeout 10 "$EMU" --fast --screen "$BUILD/$name.ppm" "$BUILD/$name.bin" \
+            > "$BUILD/$name.out" 2>&1
+    fi
+    if [ $? -eq 124 ]; then
+        echo "  $name did not finish within ten seconds"
     fi
 }
 
@@ -525,6 +535,138 @@ coloured blinkagain 0 0 "216,216,216" \
     && result ok "and lit again after that" "which is what blinking is" \
     || result no "and lit again after that" "got $(pixel blinkagain 0 0)"
 
+# ---- The frame, which is the only beat this machine has ----
+#
+# There is no clock. Every program that wanted to happen at a certain speed has until now
+# counted instructions and hoped, which is why Snake's pause silently halved when a cycle
+# stopped being an instruction. A screen finishing sixty times a second is a real one, and it
+# arrives on the MACHINE'S clock, so the same program sees the same number of frames in the
+# same number of cycles however fast the host really went.
+
+FRAMER='#Program
+start:
+  SETD.0 Frames
+  RSTA
+  STA.0
+  INIA 0x01
+  OUTA 0x35
+  SIF
+loop:
+  WAIT
+  SETD.0 Frames
+  LDA.0
+  INIB 0d10
+  CCF
+  SUB
+  BRQ done
+  BRI loop
+done:
+  SETD.0 Frames
+  LDA.0
+  INIB 0d48
+  CCF
+  ADD
+  MVQA
+  OUTA 0x00
+  HALT
+frame:
+  SETD.0 Frames
+  LDA.0
+  INCA
+  STA.0
+  RETI
+#Data
+Frames:
+  0x00
+#Vectors
+  Boot         start
+  Device 0x30  frame'
+
+echo "$FRAMER" | run frames || exit 1
+[ "$(said frames)" = "58" ] \
+    && result ok "the screen interrupts once a frame" "ten of them, counted" \
+    || result no "the screen interrupts once a frame" "got $(said frames)"
+
+# ---- And the machine was ASLEEP for them ----
+#
+# Which is the whole point of having a frame to wait for, and the one thing the picture
+# cannot show. Ten frames is 166,670 cycles and the program does a few hundred cycles of work
+# in them; a machine spinning on the status port instead would show the same characters, take
+# the same time, and spend every cycle of it on the bus.
+IDLE="$(grep -oE '[0-9]+ of them waiting' "$BUILD/frames.out" | grep -oE '^[0-9]+')"
+TOTAL="$(grep -oE 'after [0-9]+' "$BUILD/frames.out" | grep -oE '[0-9]+')"
+[ -n "$IDLE" ] && [ "$IDLE" -gt $(( TOTAL - TOTAL / 50 )) ] \
+    && result ok "and slept through nearly all of it" "$IDLE of $TOTAL cycles idle" \
+    || result no "and slept through nearly all of it" "$IDLE of $TOTAL cycles idle"
+
+# Nothing is asked for, so nothing arrives - and that matters more than it sounds. An
+# interrupt with no handler installed is a fault, so a screen that interrupted whether or not
+# it was asked would take down every program written before frames existed.
+UNARMED='#Program
+start:
+  SIF
+  INIA 0d100
+spin:
+  DECA
+  BNA spin
+  INIA 0d65
+  OUTA 0x00
+  HALT
+#Vectors
+  Boot start'
+echo "$UNARMED" | run unarmed || exit 1
+[ "$(said unarmed)" = "65" ] \
+    && result ok "and none arrives unless asked for" "no handler, no fault" \
+    || result no "and none arrives unless asked for" "got $(said unarmed)"
+
+# A program with no handler can watch for the frame instead, the way one can poll the console
+# rather than being interrupted by it.
+POLLER='#Program
+start:
+  SETD.0 Seen
+  RSTA
+  STA.0
+poll:
+  INA 0x30
+  INIB 0x01
+  AND
+  BRQ poll
+  SETD.0 Seen
+  LDA.0
+  INCA
+  STA.0
+  INIB 0d3
+  CCF
+  SUB
+  BNQ poll
+  SETD.0 Seen
+  LDA.0
+  INIB 0d48
+  CCF
+  ADD
+  MVQA
+  OUTA 0x00
+  HALT
+#Data
+Seen:
+  0x00
+#Vectors
+  Boot start'
+echo "$POLLER" | run poller || exit 1
+[ "$(said poller)" = "51" ] \
+    && result ok "or watch for it without one" "three frames, polled" \
+    || result no "or watch for it without one" "got $(said poller)"
+
+# ---- And looking is what answers it ----
+#
+# Three frames polled have to have TAKEN three frames. A flag that stayed up once it was
+# first set would let this loop through all three without a frame going by, print exactly the
+# same character, and look perfectly correct - so the count is not the check, the clock is.
+TOTAL="$(grep -oE 'after [0-9]+' "$BUILD/poller.out" | grep -oE '[0-9]+')"
+[ "$TOTAL" -gt 33334 ] \
+    && result ok "and the flag comes down when looked at" "$TOTAL cycles, so three frames passed" \
+    || result no "and the flag comes down when looked at" "$TOTAL cycles, too few to be three frames"
+
 # And what scrolled off the top is still in the map, which is scrollback nothing had to keep.
 { printf '#Program\nstart:\n'
   say "A"