gpu_test.c

Go to the documentation of this file.

/**
 * \file
 * \brief pico9918-core - the library-paced GPU
 *
 * Copyright (c) 2026 Troy Schrapel
 *
 * This code is licensed under the MIT license
 *
 * https://github.com/visrealm/pico9918-core
 *
 * pico9918_gpu_set_clock's contract, which nothing else covers: a rate makes the library
 * run an armed program from inside the arming write, and zero leaves the GPU to the host.
 *
 * The first half is what software detecting an F18A depends on. The probe arms a tiny
 * self-modifying program and reads its result back within a handful of host cycles, so a
 * host servicing the GPU once a scanline sees the chip only when a scanline boundary
 * happens to fall in between - a real flaky-detection bug in two emulators.
 *
 * The last section is the DMA engine, which is here because a program triggering one is
 * the only way to reach it: the ports it answers to are above the address space a host
 * can write.
 */
 
#include "impl/pico9918_priv.h"
#include "gpu/gpu.h"
#include "pico9918_debug.h"
 
#include <stdio.h>
 
#define PROGRAM_AT 0x2000u
#define RESULT_AT  0x2100u
#define MARKER     0xbeefu
 
static int failures;
 
static void fail(const char* what, unsigned wanted, unsigned got)
{
  ++failures;
  printf("  FAIL %s: want %04x got %04x\n", what, wanted, got);
}
 
static void regWrite(uint8_t reg, uint8_t value)
{
  pico9918_write_reg_value_impl(PICO9918_INST 0x80 | reg, value);
}
 
/* Two writes of 0x1c to R57, which is what an F18A answers to. */
static void unlock(void)
{
  regWrite(0x39, 0x1c);
  regWrite(0x39, 0x1c);
}
 
/*
 *   LI   R0, >BEEF     0200 BEEF
 *   MOV  R0, @>2100    C800 2100
 *   STST R3            02C3        so the status accessor has something to agree with
 *   IDLE               0340
 *
 * Written straight into VRAM rather than through the host bus, which masks to 16K.
 */
static void loadProgram(void)
{
  static const uint8_t program[] = {0x02, 0x00, 0xbe, 0xef, 0xc8, 0x00,
                                    0x21, 0x00, 0x02, 0xc3, 0x03, 0x40};
 
  for (unsigned i = 0; i < sizeof(program); ++i) tms9918->vram.bytes[PROGRAM_AT + i] = program[i];
 
  tms9918->vram.bytes[RESULT_AT]     = 0;
  tms9918->vram.bytes[RESULT_AT + 1] = 0;
}
 
static uint16_t result(void)
{
  return (uint16_t)((tms9918->vram.bytes[RESULT_AT] << 8) | tms9918->vram.bytes[RESULT_AT + 1]);
}
 
/* Arm at PROGRAM_AT. Writing R55 is what arms it, so R54 goes first. */
static void arm(void)
{
  regWrite(0x36, (uint8_t)(PROGRAM_AT >> 8));
  regWrite(0x37, (uint8_t)(PROGRAM_AT & 0xff));
}
 
/*
 *   LI   R1, >8008     0201 8008     the DMA trigger port
 *   LI   R2, >0100     0202 0100
 *   MOV  R2, *R1       C442          any write to >8008 starts the transfer
 *   IDLE               0340
 *
 * The registers below it are set by the case rather than by the program: what is under
 * test is the engine, not a program's ability to load eight bytes.
 */
static void loadDmaProgram(void)
{
  static const uint8_t program[] = {0x02, 0x01, 0x80, 0x08, 0x02, 0x02,
                                    0x01, 0x00, 0xc4, 0x42, 0x03, 0x40};
 
  for (unsigned i = 0; i < sizeof(program); ++i) tms9918->vram.bytes[PROGRAM_AT + i] = program[i];
}
 
#define NEW_WP 0x2800u
 
/*
 *   LWPI >2800        02E0 2800
 *   LI   R0, >BEEF    0200 BEEF     lands at >2800, which is R0 of the new workspace
 *   IDLE              0340
 */
static void loadWorkspaceProgram(void)
{
  static const uint8_t program[] = {0x02, 0xe0, 0x28, 0x00, 0x02, 0x00, 0xbe, 0xef, 0x03, 0x40};
 
  for (unsigned i = 0; i < sizeof(program); ++i) tms9918->vram.bytes[PROGRAM_AT + i] = program[i];
 
  tms9918->vram.bytes[NEW_WP]     = 0;
  tms9918->vram.bytes[NEW_WP + 1] = 0;
  tms9918->vram.map.wrksp[0]      = 0;
  tms9918->vram.bytes[PICO9918_GPU_WORKSPACE] = 0;
}
 
/*
 *   MOV  R0, @>2100    C800 2100     R0 is the caller's to set, not the program's
 *   IDLE               0340
 */
static void loadEchoProgram(void)
{
  static const uint8_t program[] = {0xc8, 0x00, 0x21, 0x00, 0x03, 0x40};
 
  for (unsigned i = 0; i < sizeof(program); ++i) tms9918->vram.bytes[PROGRAM_AT + i] = program[i];
 
  tms9918->vram.bytes[RESULT_AT]                  = 0;
  tms9918->vram.bytes[RESULT_AT + 1]              = 0;
  tms9918->vram.bytes[PICO9918_GPU_WORKSPACE]     = 0;
  tms9918->vram.bytes[PICO9918_GPU_WORKSPACE + 1] = 0;
}
 
/*
 *   STST R3            02C3          nothing above it, so R3 is what the caller wrote
 *   IDLE               0340
 */
static void loadStatusProgram(void)
{
  static const uint8_t program[] = {0x02, 0xc3, 0x03, 0x40};
 
  for (unsigned i = 0; i < sizeof(program); ++i) tms9918->vram.bytes[PROGRAM_AT + i] = program[i];
}
 
#define DMA_SRC 0x1000u
#define DMA_DST 0x1800u
 
/* One transfer, from a source that is 0x40 counting up. Returns with the destination
   wherever the engine left it. */
static void dma(uint32_t src, uint32_t dst, uint8_t width, uint8_t height, uint8_t stride,
                uint8_t params)
{
  for (unsigned i = 0; i < 0x400; ++i)
  {
    tms9918->vram.bytes[DMA_SRC + i] = (uint8_t)(0x40 + i);
    tms9918->vram.bytes[DMA_DST + i] = 0;
  }
 
  tms9918->vram.bytes[0x8000] = (uint8_t)(src >> 8);
  tms9918->vram.bytes[0x8001] = (uint8_t)src;
  tms9918->vram.bytes[0x8002] = (uint8_t)(dst >> 8);
  tms9918->vram.bytes[0x8003] = (uint8_t)dst;
  tms9918->vram.bytes[0x8004] = width;
  tms9918->vram.bytes[0x8005] = height;
  tms9918->vram.bytes[0x8006] = stride;
  tms9918->vram.bytes[0x8007] = params;
 
  loadDmaProgram();
  arm();
}
 
static void expect(const char* what, uint32_t at, uint8_t wanted)
{
  if (tms9918->vram.bytes[at] != wanted) fail(what, wanted, tms9918->vram.bytes[at]);
}
 
static uint16_t stepPc[8];
static unsigned stepCalls;
static uint16_t stepStopAt;
static unsigned stepWrongArgs;
 
static bool stepWatch(pico9918_t* vdp, uint16_t pc, void* userdata)
{
  if (vdp != tms9918 || userdata != &stepStopAt) ++stepWrongArgs;
  if (stepCalls < 8) stepPc[stepCalls] = pc;
  ++stepCalls;
 
  return pc != stepStopAt;
}
 
#if PICO9918_BUILD_STEP_CALLBACK
static uint16_t armedPc[8];
static unsigned armedCalls;
static uint16_t armedStopAt;
static unsigned armedWrongArgs;
 
static bool armedWatch(pico9918_t* vdp, uint16_t pc, void* userdata)
{
  if (vdp != tms9918 || userdata != &armedStopAt) ++armedWrongArgs;
  if (armedCalls < 8) armedPc[armedCalls] = pc;
  ++armedCalls;
 
  return pc != armedStopAt;
}
#endif
 
int main(void)
{
  pico9918_init();
  pico9918_gpu_init(PICO9918_INST_ONLY);
 
  /* 1. no rate is the default, and leaves the GPU to whoever else drives it. The
        program is armed, so a host's own step_n would still run it - but the arming
        write must not. */
  unlock();
  loadProgram();
  arm();
  if (result() != 0) fail("no-rate-ran", 0, result());
 
  /* and armed is where pico9918_gpu_pc says it is, before a single instruction runs */
  if (pico9918_gpu_pc(PICO9918_INST_ONLY) != PROGRAM_AT)
    fail("armed-pc", PROGRAM_AT, pico9918_gpu_pc(PICO9918_INST_ONLY));
 
  /* and a disassembler can reach the program: the guest's own view stops at 0x3fff, so
     PROGRAM_AT is in range for both, but only the GPU's reaches past it. */
  if (pico9918_gpu_mem_value(PICO9918_INST PROGRAM_AT) != 0x02)
    fail("gpu-mem-program", 0x02, pico9918_gpu_mem_value(PICO9918_INST PROGRAM_AT));
 
  tms9918->vram.bytes[0x4100] = 0x5a;
  if (pico9918_gpu_mem_value(PICO9918_INST 0x4100) != 0x5a)
    fail("gpu-mem-gram", 0x5a, pico9918_gpu_mem_value(PICO9918_INST 0x4100));
  if (pico9918_vram_value(PICO9918_INST 0x4100) == 0x5a) fail("vram-value-reached-gram", 0, 0x5a);
 
  /* and it stops where the map does rather than walking into the instance */
  if (pico9918_gpu_mem_value(PICO9918_INST pico9918_gpu_mem_size()) != 0)
    fail("gpu-mem-past-end", 0, pico9918_gpu_mem_value(PICO9918_INST pico9918_gpu_mem_size()));
 
  /* 2. and it is only armed, not lost: the host-driven path still works. */
  pico9918_gpu_step_n(PICO9918_INST 1000);
  if (result() != MARKER) fail("host-driven", MARKER, result());
 
  /* the program left >BEEF in R0, which is the last word of the map, and R1 is above it
     in the workspace overflow - so reading either through the 16-bit map cannot work */
  if (pico9918_gpu_reg_value(PICO9918_INST 0) != MARKER)
    fail("gpu-r0", MARKER, pico9918_gpu_reg_value(PICO9918_INST 0));
 
  tms9918->vram.map.wrksp[0] = 0x12;
  tms9918->vram.map.wrksp[1] = 0x34;
  if (pico9918_gpu_reg_value(PICO9918_INST 1) != 0x1234)
    fail("gpu-r1", 0x1234, pico9918_gpu_reg_value(PICO9918_INST 1));
 
  /* the accessor publishes what STST stored, bit for bit - a non-zero check cannot see
     the two disagreeing by the eight places the low-byte storage sits at */
  if (pico9918_gpu_status(PICO9918_INST_ONLY) != pico9918_gpu_reg_value(PICO9918_INST 3))
    fail("gpu-status-stst", pico9918_gpu_reg_value(PICO9918_INST 3),
         pico9918_gpu_status(PICO9918_INST_ONLY));
 
  /* and it is what >BEEF earns from a cleared status: logical greater than alone, since
     arming zeroed it, MOV keeps only C/OV/P across, and >BEEF is negative and non-zero */
  if (pico9918_gpu_status(PICO9918_INST_ONLY) != PICO9918_GPU_ST_LGT)
    fail("gpu-status-flags", PICO9918_GPU_ST_LGT, pico9918_gpu_status(PICO9918_INST_ONLY));
 
  /* and it moved: a run leaves the point it reached, not the address it was armed at */
  if (pico9918_gpu_pc(PICO9918_INST_ONLY) == PROGRAM_AT)
    fail("pc-did-not-move", 0, pico9918_gpu_pc(PICO9918_INST_ONLY));
 
  /* 3. a rate runs it from inside the arming write, which is the whole point */
  pico9918_gpu_set_clock(PICO9918_INST PICO9918_GPU_IPS_PRO);
  loadProgram();
  arm();
  if (result() != MARKER) fail("armed-not-run", MARKER, result());
 
  /* 4. the other arming route: R56 bit 0. It resumes from gpuAddress rather than
        restarting, so R55 sets the address with no rate on - arming without running -
        and the R56 write is what starts it. */
  pico9918_gpu_set_clock(PICO9918_INST 0);
  loadProgram();
  arm();
  if (result() != 0) fail("r56-early-run", 0, result());
 
  pico9918_gpu_set_clock(PICO9918_INST PICO9918_GPU_IPS_PRO);
  regWrite(0x38, 1);
  if (result() != MARKER) fail("r56-not-run", MARKER, result());
 
  /* 5. a locked device has no GPU to arm - a reset re-locks it. The registers that
        would arm one are above the eight it admits, so the write is ignored outright,
        and the rate is still set so this is the lock doing it. */
  pico9918_reset(PICO9918_INST_ONLY);
 
  /* the reset parks an odd address, which is what the header calls "nothing armed" */
  if ((pico9918_gpu_pc(PICO9918_INST_ONLY) & 1) == 0)
    fail("reset-pc-even", 1, pico9918_gpu_pc(PICO9918_INST_ONLY));
 
  pico9918_gpu_init(PICO9918_INST_ONLY);
  pico9918_gpu_set_clock(PICO9918_INST PICO9918_GPU_IPS_PRO);
  loadProgram();
  arm();
  if (result() != 0) fail("locked-ran", 0, result());
 
  /* and the locked arm did not move it: the registers that would are above the eight */
  if ((pico9918_gpu_pc(PICO9918_INST_ONLY) & 1) == 0)
    fail("locked-armed-pc", 1, pico9918_gpu_pc(PICO9918_INST_ONLY));
 
  /* 6. and unlocking again brings it back, so nothing above latched */
  unlock();
  loadProgram();
  arm();
  if (result() != MARKER) fail("relocked", MARKER, result());
 
  /* 7. back to zero, back to the host */
  pico9918_gpu_set_clock(PICO9918_INST 0);
  loadProgram();
  arm();
  if (result() != 0) fail("cleared-rate-ran", 0, result());
 
  /* 8. a workspace the program moved has to survive the slice that stopped after it.
        Both legs run the same three instructions; the stepped one stops between every
        pair, which is the only place the workspace can be dropped. */
  for (int stepped = 0; stepped < 2; ++stepped)
  {
    const char* leg = stepped ? "wp-stepped" : "wp-one-slice";
 
    loadWorkspaceProgram();
    arm();
 
    if (pico9918_gpu_wp(PICO9918_INST_ONLY) != PICO9918_GPU_WORKSPACE)
      fail("wp-armed", PICO9918_GPU_WORKSPACE, pico9918_gpu_wp(PICO9918_INST_ONLY));
 
    if (stepped)
      while (pico9918_gpu_step_n(PICO9918_INST 1)) { }
    else
      pico9918_gpu_step_n(PICO9918_INST 1000);
 
    if (pico9918_gpu_wp(PICO9918_INST_ONLY) != NEW_WP)
      fail(leg, NEW_WP, pico9918_gpu_wp(PICO9918_INST_ONLY));
 
    expect(stepped ? "wp-stepped-r0-hi" : "wp-one-slice-r0-hi", NEW_WP, MARKER >> 8);
    expect(stepped ? "wp-stepped-r0-lo" : "wp-one-slice-r0-lo", NEW_WP + 1, MARKER & 0xff);
    expect(stepped ? "wp-stepped-not-start" : "wp-one-slice-not-start", PICO9918_GPU_WORKSPACE, 0);
 
    if (pico9918_gpu_reg_value(PICO9918_INST 0) != MARKER)
      fail(stepped ? "wp-stepped-reg" : "wp-one-slice-reg", MARKER,
           pico9918_gpu_reg_value(PICO9918_INST 0));
  }
 
  loadProgram();
  arm();
  if (pico9918_gpu_wp(PICO9918_INST_ONLY) != PICO9918_GPU_WORKSPACE)
    fail("wp-new-program", PICO9918_GPU_WORKSPACE, pico9918_gpu_wp(PICO9918_INST_ONLY));
 
  /* 9. the writers, which are what make a GPU pane editable. Each is checked through the
        reader it mirrors and then through a program, because a value that is stored and
        read back and then dropped on the way into the slice looks exactly like success. */
  loadWorkspaceProgram();
  arm();
  while (pico9918_gpu_step_n(PICO9918_INST 1)) { }
 
  pico9918_debug_gpu_set_reg_value(PICO9918_INST 3, 0x1234);
  if (pico9918_gpu_reg_value(PICO9918_INST 3) != 0x1234)
    fail("set-reg", 0x1234, pico9918_gpu_reg_value(PICO9918_INST 3));
  expect("set-reg-hi", NEW_WP + 6, 0x12);
  expect("set-reg-lo", NEW_WP + 7, 0x34);
 
  pico9918_debug_gpu_set_reg_value(PICO9918_INST 0x13, 0x5678);
  if (pico9918_gpu_reg_value(PICO9918_INST 3) != 0x5678)
    fail("set-reg-masked", 0x5678, pico9918_gpu_reg_value(PICO9918_INST 3));
 
  if (!pico9918_debug_gpu_set_wp(PICO9918_INST PICO9918_GPU_WORKSPACE)) fail("set-wp-kept", 1, 0);
 
  pico9918_debug_gpu_set_reg_value(PICO9918_INST 15, MARKER);
  if (pico9918_gpu_reg_value(PICO9918_INST 15) != MARKER)
    fail("set-reg-overflow", MARKER, pico9918_gpu_reg_value(PICO9918_INST 15));
  expect("set-reg-overflow-hi", PICO9918_GPU_WORKSPACE + 30, MARKER >> 8);
 
  pico9918_debug_gpu_set_status(PICO9918_INST PICO9918_GPU_ST_EQ | PICO9918_GPU_ST_C);
  if (pico9918_gpu_status(PICO9918_INST_ONLY) != (PICO9918_GPU_ST_EQ | PICO9918_GPU_ST_C))
    fail("set-status", PICO9918_GPU_ST_EQ | PICO9918_GPU_ST_C, pico9918_gpu_status(PICO9918_INST_ONLY));
 
  pico9918_debug_gpu_set_status(PICO9918_INST PICO9918_GPU_ST_OV | 0x00ff);
  if (pico9918_gpu_status(PICO9918_INST_ONLY) != PICO9918_GPU_ST_OV)
    fail("set-status-low-dropped", PICO9918_GPU_ST_OV, pico9918_gpu_status(PICO9918_INST_ONLY));
 
  loadStatusProgram();
  arm();
  pico9918_debug_gpu_set_status(PICO9918_INST PICO9918_GPU_ST_LGT | PICO9918_GPU_ST_P);
  while (pico9918_gpu_step_n(PICO9918_INST 1)) { }
  if (pico9918_gpu_reg_value(PICO9918_INST 3) != (PICO9918_GPU_ST_LGT | PICO9918_GPU_ST_P))
    fail("set-status-ran", PICO9918_GPU_ST_LGT | PICO9918_GPU_ST_P,
         pico9918_gpu_reg_value(PICO9918_INST 3));
 
  loadEchoProgram();
  arm();
  if (!pico9918_debug_gpu_set_wp(PICO9918_INST NEW_WP)) fail("set-wp-armed", 1, 0);
  if (pico9918_gpu_wp(PICO9918_INST_ONLY) != NEW_WP)
    fail("set-wp-readback", NEW_WP, pico9918_gpu_wp(PICO9918_INST_ONLY));
 
  pico9918_debug_gpu_set_reg_value(PICO9918_INST 0, MARKER);
  while (pico9918_gpu_step_n(PICO9918_INST 1)) { }
  if (result() != MARKER) fail("set-wp-ran", MARKER, result());
  expect("set-wp-not-start", PICO9918_GPU_WORKSPACE, 0);
 
  arm();
  if (pico9918_gpu_wp(PICO9918_INST_ONLY) != PICO9918_GPU_WORKSPACE)
    fail("set-wp-rearmed", PICO9918_GPU_WORKSPACE, pico9918_gpu_wp(PICO9918_INST_ONLY));
 
  /* 10. the step callback. Four instructions with known addresses, so the count, the
         order and the address a break stops on are all one program. */
  stepCalls     = 0;
  stepWrongArgs = 0;
  stepStopAt    = 0xffff;
  loadProgram();
  arm();
 
  if (pico9918_debug_gpu_step_n(PICO9918_INST 0, stepWatch, &stepStopAt))
    fail("step-cb-still-running", 0, 1);
  if (stepWrongArgs) fail("step-cb-args", 0, stepWrongArgs);
  if (stepCalls != 4) fail("step-cb-count", 4, stepCalls);
  if (stepPc[0] != PROGRAM_AT) fail("step-cb-pc0", PROGRAM_AT, stepPc[0]);
  if (stepPc[1] != PROGRAM_AT + 4) fail("step-cb-pc1", PROGRAM_AT + 4, stepPc[1]);
  if (stepPc[2] != PROGRAM_AT + 8) fail("step-cb-pc2", PROGRAM_AT + 8, stepPc[2]);
  if (stepPc[3] != PROGRAM_AT + 10) fail("step-cb-pc3", PROGRAM_AT + 10, stepPc[3]);
  if (result() != MARKER) fail("step-cb-ran", MARKER, result());
 
  /* stopping on the MOV: the PC left behind is the address broken on rather than the one
     after it, and the store that instruction would have made has not happened */
  stepCalls  = 0;
  stepStopAt = PROGRAM_AT + 4;
  loadProgram();
  arm();
 
  if (!pico9918_debug_gpu_step_n(PICO9918_INST 0, stepWatch, &stepStopAt))
    fail("step-cb-break-stopped", 1, 0);
  if (stepCalls != 2) fail("step-cb-break-count", 2, stepCalls);
  if (pico9918_gpu_pc(PICO9918_INST_ONLY) != PROGRAM_AT + 4)
    fail("step-cb-break-pc", PROGRAM_AT + 4, pico9918_gpu_pc(PICO9918_INST_ONLY));
  if (result() != 0) fail("step-cb-break-early", 0, result());
 
  /* and the resume starts at the instruction that did not run, not the one after it */
  stepCalls  = 0;
  stepStopAt = 0xffff;
 
  if (pico9918_debug_gpu_step_n(PICO9918_INST 0, stepWatch, &stepStopAt))
    fail("step-cb-resume-running", 0, 1);
  if (stepCalls != 3) fail("step-cb-resume-count", 3, stepCalls);
  if (result() != MARKER) fail("step-cb-resume-ran", MARKER, result());
 
  /* the callback is the call's, not the instance's: neither the plain entry nor a null
     one may reach the last callback a debugger happened to pass */
  stepCalls = 0;
  loadProgram();
  arm();
  pico9918_gpu_step_n(PICO9918_INST 0);
  if (stepCalls) fail("step-cb-persisted", 0, stepCalls);
  if (result() != MARKER) fail("step-cb-plain-ran", MARKER, result());
 
  loadProgram();
  arm();
  if (pico9918_debug_gpu_step_n(PICO9918_INST 0, NULL, NULL)) fail("step-cb-null-running", 0, 1);
  if (stepCalls) fail("step-cb-null-called", 0, stepCalls);
  if (result() != MARKER) fail("step-cb-null-ran", MARKER, result());
 
#if PICO9918_BUILD_STEP_CALLBACK
  /* 10b. the same watch armed on the instance, which is what a host that leaves the
          pacing to the library has instead of a call of its own to pass one to. */
  armedCalls     = 0;
  armedStopAt    = 0xffff;
  armedWrongArgs = 0;
  void* armedData = NULL;
  pico9918_debug_set_step_callback(PICO9918_INST armedWatch, &armedStopAt);
  if (pico9918_debug_step_callback(PICO9918_INST &armedData) != armedWatch)
    fail("armed-cb-readback", 1, 0);
  if (armedData != &armedStopAt) fail("armed-cb-readback-data", 1, 0);
 
  loadProgram();
  arm();
  pico9918_gpu_step_n(PICO9918_INST 0);
  if (armedWrongArgs) fail("armed-cb-args", 0, armedWrongArgs);
  if (armedCalls != 4) fail("armed-cb-count", 4, armedCalls);
  if (result() != MARKER) fail("armed-cb-ran", MARKER, result());
 
  /* breaking from it stops the slice the same way, with the PC on the instruction that
     did not run and its store not made */
  armedCalls  = 0;
  armedStopAt = PROGRAM_AT + 4;
  loadProgram();
  arm();
  if (!pico9918_gpu_step_n(PICO9918_INST 0)) fail("armed-cb-break-stopped", 1, 0);
  if (armedCalls != 2) fail("armed-cb-break-count", 2, armedCalls);
  if (pico9918_gpu_pc(PICO9918_INST_ONLY) != PROGRAM_AT + 4)
    fail("armed-cb-break-pc", PROGRAM_AT + 4, pico9918_gpu_pc(PICO9918_INST_ONLY));
  if (result() != 0) fail("armed-cb-break-early", 0, result());
 
  /* RESUMING RE-OFFERS THE ADDRESS THAT BROKE. The slice stopped on that instruction
     rather than after it, so a host that does not skip its own breakpoint once never
     gets past the first one - which is the contract EMULATOR-INTEGRATION.md states. */
  armedCalls = 0;
  if (!pico9918_gpu_step_n(PICO9918_INST 0)) fail("armed-cb-rebreak-stopped", 1, 0);
  if (armedCalls != 1) fail("armed-cb-rebreak-count", 1, armedCalls);
  if (armedPc[0] != PROGRAM_AT + 4) fail("armed-cb-rebreak-pc", PROGRAM_AT + 4, armedPc[0]);
  if (result() != 0) fail("armed-cb-rebreak-early", 0, result());
 
  /* and moving it on is all the host owes: the same resume then finishes the program */
  armedCalls  = 0;
  armedStopAt = 0xffff;
  if (pico9918_gpu_step_n(PICO9918_INST 0)) fail("armed-cb-rebreak-resume-running", 0, 1);
  if (armedCalls != 3) fail("armed-cb-rebreak-resume-count", 3, armedCalls);
  if (result() != MARKER) fail("armed-cb-rebreak-resume-ran", MARKER, result());
 
  /* and the case the per-call callback cannot reach at all: the run the library starts
     from inside the arming write */
  armedCalls  = 0;
  armedStopAt = 0xffff;
  pico9918_gpu_set_clock(PICO9918_INST PICO9918_GPU_IPS_PRO);
  loadProgram();
  arm();
  if (armedCalls != 4) fail("armed-cb-clocked-count", 4, armedCalls);
  if (result() != MARKER) fail("armed-cb-clocked-ran", MARKER, result());
  pico9918_gpu_set_clock(PICO9918_INST 0);
 
  /* a reset is the guest's to make and the callback is the host's, so it survives one */
  pico9918_reset(PICO9918_INST_ONLY);
  if (pico9918_debug_step_callback(PICO9918_INST NULL) != armedWatch) fail("armed-cb-reset", 1, 0);
 
  /* a call that brings its own wins, so one pane's stepping is not the other's */
  unlock();
  armedCalls = 0;
  stepCalls  = 0;
  stepStopAt = 0xffff;
  loadProgram();
  arm();
  if (pico9918_debug_gpu_step_n(PICO9918_INST 0, stepWatch, &stepStopAt))
    fail("armed-cb-override-running", 0, 1);
  if (stepCalls != 4) fail("armed-cb-override-count", 4, stepCalls);
  if (armedCalls) fail("armed-cb-override-leaked", 0, armedCalls);
 
  pico9918_debug_set_step_callback(PICO9918_INST NULL, NULL);
  if (pico9918_debug_step_callback(PICO9918_INST NULL)) fail("armed-cb-disarm", 0, 1);
 
  armedCalls = 0;
  loadProgram();
  arm();
  pico9918_gpu_step_n(PICO9918_INST 0);
  if (armedCalls) fail("armed-cb-disarmed-called", 0, armedCalls);
  if (result() != MARKER) fail("armed-cb-disarmed-ran", MARKER, result());
#endif
 
  /* 11. the DMA engine's geometry. The source is 0x40 counting up, so where a byte landed
        says which one it was and therefore which row and column the engine thought it
        was on. Zero width and height mean 256; stride is a different animal entirely. */
  unlock();
  pico9918_gpu_set_clock(PICO9918_INST PICO9918_GPU_IPS_PRO);
 
  dma(DMA_SRC, DMA_DST, 4, 3, 4, 0x00);
  expect("dma-run-first", DMA_DST, 0x40);
  expect("dma-run-last", DMA_DST + 11, 0x4b);
  expect("dma-run-past", DMA_DST + 12, 0x00);
 
  dma(DMA_SRC, DMA_DST, 4, 3, 16, 0x00);
  expect("dma-stride-row0", DMA_DST, 0x40);
  expect("dma-stride-gap", DMA_DST + 4, 0x00);
  expect("dma-stride-row1", DMA_DST + 16, 0x50);
  expect("dma-stride-row2", DMA_DST + 32, 0x60);
 
  /* stride zero is a pitch of zero, not of 256: every row lands on the one before it */
  dma(DMA_SRC, DMA_DST, 4, 3, 0, 0x00);
  expect("dma-stride0-row0", DMA_DST, 0x40);
  expect("dma-stride0-end", DMA_DST + 4, 0x00);
  expect("dma-stride0-not256", DMA_DST + 256, 0x00);
 
  /* and a stride the eight-bit difference overflows walks backwards: 200 with a width of
     8 is a pitch of -56, not +200 */
  dma(0x1100, 0x1900, 8, 2, 200, 0x00);
  expect("dma-back-row0", 0x1900, 0x40);
  expect("dma-back-row1", 0x18c8, 0x08);
  expect("dma-back-not-forward", 0x19c8, 0x00);
 
  /* either side of where it overflows, which for a width of 8 is a stride of 135 */
  dma(0x1100, 0x1900, 8, 2, 134, 0x00);
  expect("dma-edge-fwd-row1", 0x1986, 0xc6);
  expect("dma-edge-fwd-gap", 0x1985, 0x00);
 
  dma(0x1100, 0x1900, 8, 2, 135, 0x00);
  expect("dma-edge-back-row1", 0x1887, 0xc7);
  expect("dma-edge-back-not-forward", 0x1987, 0x00);
 
  /* a width of zero is 256, and with stride zero the difference wraps to a pitch of 256 */
  dma(DMA_SRC, DMA_DST, 0, 1, 0, 0x00);
  expect("dma-width256-first", DMA_DST, 0x40);
  expect("dma-width256-last", DMA_DST + 255, 0x3f);
  expect("dma-width256-past", DMA_DST + 256, 0x00);
 
  /* and a height of zero is 256 rows of it */
  dma(DMA_SRC, DMA_DST, 1, 0, 1, 0x00);
  expect("dma-height256-first", DMA_DST, 0x40);
  expect("dma-height256-last", DMA_DST + 255, 0x3f);
  expect("dma-height256-past", DMA_DST + 256, 0x00);
 
  /* the top of each register: 255 wide by one, then one wide by 255 */
  dma(DMA_SRC, DMA_DST, 255, 1, 255, 0x00);
  expect("dma-width255-first", DMA_DST, 0x40);
  expect("dma-width255-last", DMA_DST + 254, 0x3e);
  expect("dma-width255-past", DMA_DST + 255, 0x00);
 
  dma(DMA_SRC, DMA_DST, 1, 255, 1, 0x00);
  expect("dma-height255-first", DMA_DST, 0x40);
  expect("dma-height255-last", DMA_DST + 254, 0x3e);
  expect("dma-height255-past", DMA_DST + 255, 0x00);
 
  /* a stride under the width steps back into the row just written */
  dma(DMA_SRC, DMA_DST, 8, 2, 4, 0x00);
  expect("dma-narrow-kept", DMA_DST + 3, 0x43);
  expect("dma-narrow-rewritten", DMA_DST + 4, 0x44);
  expect("dma-narrow-last", DMA_DST + 11, 0x4b);
  expect("dma-narrow-past", DMA_DST + 12, 0x00);
 
  /* only two bits of the parameter byte are decoded, so the other six say nothing */
  dma(DMA_SRC, DMA_DST, 4, 3, 4, 0xfc);
  expect("dma-params-spare-first", DMA_DST, 0x40);
  expect("dma-params-spare-last", DMA_DST + 11, 0x4b);
  expect("dma-params-spare-past", DMA_DST + 12, 0x00);
 
  /* both parameter bits at once: a fill that decrements */
  dma(0x1100, 0x1900, 4, 2, 4, 0x03);
  expect("dma-fill-dec-first", 0x1900, 0x40);
  expect("dma-fill-dec-row0", 0x18fd, 0x40);
  expect("dma-fill-dec-row1", 0x18f9, 0x40);
  expect("dma-fill-dec-past", 0x18f8, 0x00);
 
  /* LOAD-BEARING: overlapping forwards, so each byte read has already been written. A
     block copy would answer 40..47 here, which is what makes this the guard on the fast
     path being taken only where source and destination are disjoint. */
  dma(DMA_SRC, DMA_SRC + 2, 8, 1, 8, 0x00);
  expect("dma-overlap-0", DMA_SRC + 2, 0x40);
  expect("dma-overlap-2", DMA_SRC + 4, 0x40);
  expect("dma-overlap-7", DMA_SRC + 9, 0x41);
 
  /* sixteen bits of address, either end */
  dma(DMA_SRC, 0xfffe, 4, 1, 4, 0x00);
  expect("dma-dst-wrap-before", 0xffff, 0x41);
  expect("dma-dst-wrap-after", 0x0000, 0x42);
  expect("dma-dst-wrap-last", 0x0001, 0x43);
 
  tms9918->vram.bytes[0xfffe] = 0x11;
  tms9918->vram.bytes[0xffff] = 0x22;
  tms9918->vram.bytes[0x0000] = 0x33;
  tms9918->vram.bytes[0x0001] = 0x44;
  dma(0xfffe, DMA_DST, 4, 1, 4, 0x00);
  expect("dma-src-wrap-before", DMA_DST + 1, 0x22);
  expect("dma-src-wrap-after", DMA_DST + 2, 0x33);
  expect("dma-src-wrap-last", DMA_DST + 3, 0x44);
 
  /* a fill reads its byte once and strides like a copy */
  dma(DMA_SRC, DMA_DST, 4, 3, 16, 0x01);
  expect("dma-fill-row0", DMA_DST + 3, 0x40);
  expect("dma-fill-gap", DMA_DST + 4, 0x00);
  expect("dma-fill-row2", DMA_DST + 32, 0x40);
 
  /* decrementing runs both ends backwards, so a row ends below the address it started at */
  dma(0x1100, 0x1900, 4, 2, 4, 0x02);
  expect("dma-dec-row0-first", 0x1900, 0x40);
  expect("dma-dec-row0-last", 0x18fd, 0x3d);
  expect("dma-dec-row1-first", 0x18fc, 0x3c);
  expect("dma-dec-row1-last", 0x18f9, 0x39);
  expect("dma-dec-past", 0x1901, 0x00);
 
  /* decrementing with a stride of zero cancels the row's own backwards run exactly */
  dma(0x1100, 0x1900, 4, 3, 0, 0x02);
  expect("dma-dec-stride0-first", 0x1900, 0x40);
  expect("dma-dec-stride0-last", 0x18fd, 0x3d);
  expect("dma-dec-stride0-end", 0x18fc, 0x00);
  expect("dma-dec-stride0-past", 0x1901, 0x00);
 
  /* TRAP: the difference is (width - 1) - stride here, so an ordinary stride always makes
     the pitch negative and only one that underflows walks the rows FORWARDS while each row
     is still written backwards. 200 with a width of 8 gives (7 - 200) & 0xff = 63, so +56 -
     the mirror of dma-back-row1 above, which is the same numbers incrementing. */
  dma(0x1100, 0x1900, 8, 2, 200, 0x02);
  expect("dma-dec-fwd-row0-first", 0x1900, 0x40);
  expect("dma-dec-fwd-row0-last", 0x18f9, 0x39);
  expect("dma-dec-fwd-row1-first", 0x1938, 0x78);
  expect("dma-dec-fwd-row1-last", 0x1931, 0x71);
  expect("dma-dec-fwd-gap", 0x1901, 0x00);
  expect("dma-dec-fwd-not-back", 0x18c8, 0x00);
 
  /* and its own edge, which is NOT where incrementing turns over: two's complement holds
     one more negative than positive, so dec flips at 136 where inc flipped at 135 */
  dma(0x1100, 0x1900, 8, 2, 135, 0x02);
  expect("dma-dec-edge-back-row1", 0x1879, 0xb9);
  expect("dma-dec-edge-back-not-forward", 0x1979, 0x00);
 
  dma(0x1100, 0x1900, 8, 2, 136, 0x02);
  expect("dma-dec-edge-fwd-row1", 0x1978, 0xb8);
  expect("dma-dec-edge-fwd-not-back", 0x1878, 0x00);
 
  printf("%s: library-paced GPU, %d failure(s)\n", failures ? "FAIL" : "PASS", failures);
  return failures != 0;
}