romdevtools 0.70.0 → 0.71.0

package/src/platforms/n64/lib/c/n64.c

@@ -1,117 +1,218 @@
-/* n64.c — N64 helpers + software 3D pipeline (see n64.h). Framebuffer backend. */
+/* n64.c — N64 helpers with a GPU (RDP/GBI) drawing backend.
+ *
+ * WHY THIS IS NOT A SOFTWARE RASTERIZER: the shipping N64 core renders through
+ * glide64 (a GL HLE plugin) — it presents the game's RDP/GBI **display lists** on
+ * the real GPU, NOT a raw CPU-written framebuffer. A software rasterizer that pokes
+ * pixels into RDRAM shows BLACK on glide64 (and would be <1fps even if it didn't).
+ * So this lib builds a GBI display list each frame and kicks the RSP/RDP; glide64
+ * HLEs it onto the GPU.
+ *
+ * HOW glide64 ACCEPTS OUR LIST (no Nintendo microcode shipped):
+ *  - The RSP-HLE treats an OSTask with type==1 (M_GFXTASK) as a graphics task and
+ *    hands the display list to glide64.
+ *  - glide64 picks its command table by CRC-summing 3072 bytes of the task's
+ *    "ucode" region and matching a known-ucode CRC. The bytes are NEVER executed
+ *    (HLE), only summed — so we embed a 3072-byte blob that SUMS to a real F3DEX2
+ *    CRC (0x5d3099f1). glide64 then interprets our list as standard F3DEX2.
+ *  - We emit standard F3DEX2 GBI: set color image / scissor / fill rectangles for
+ *    clear+rects, and shaded vertex triangles for tri2d/tri3d. Solid colors only.
+ */
 #include "n64.h"
 
-/* Two 320x240x16bpp framebuffers in RDRAM (double-buffered), cached kseg0. */
-#define FB0 0xA0100000u  /* uncached kseg1 — writes go straight to RDRAM */
-#define FB1 0xA0120000u
-static volatile unsigned short *fb;   /* the back buffer we draw into */
-static unsigned int front;
-
-/* VI registers (0xA4400000). */
-#define VI(n) (*(volatile unsigned int*)(0xA4400000u + (n)*4))
-#define VI_STATUS 0
-#define VI_ORIGIN 1
-#define VI_WIDTH  2
-#define VI_V_CURRENT 4
-#define VI_H_START 9
-#define VI_V_START 10
-#define VI_X_SCALE 12
-#define VI_Y_SCALE 13
+/* ── RCP register blocks ── */
+#define SP(n)  (*(volatile unsigned int*)(0xA4040000u + (n)*4))  /* RSP */
+#define DP(n)  (*(volatile unsigned int*)(0xA4100000u + (n)*4))  /* RDP cmd */
+#define VI(n)  (*(volatile unsigned int*)(0xA4400000u + (n)*4))  /* video */
+
+#define SP_MEM_ADDR  0   /* SP DMEM/IMEM address */
+#define SP_DRAM_ADDR 1
+#define SP_RD_LEN    2
+#define SP_WR_LEN    3
+#define SP_STATUS    4
+
+#define FB_ADDR 0x00200000u     /* 320x240x16bpp color image in RDRAM */
+#define DL_ADDR 0x00280000u     /* the GBI display list buffer (room for many spans) */
+#define UC_ADDR 0x00290000u     /* the fake "ucode" blob (CRC bait) */
+
+/* uncached pointers (kseg1) into those RDRAM regions */
+#define U16P(a) ((volatile unsigned short*)(0xA0000000u | (a)))
+#define U32P(a) ((volatile unsigned int*)  (0xA0000000u | (a)))
+
+static volatile unsigned int *dl;   /* write cursor into the display list */
+static unsigned int dl_count;       /* words written */
+
+/* ── GBI / F3DEX2 command opcodes (the ones the fill-rect path uses) ── */
+#define G_ENDDL          0xDF
+#define G_SETOTHERMODE_H 0xE3
+#define G_RDPPIPESYNC    0xE7
+#define G_RDPFULLSYNC    0xE9
+#define G_SETSCISSOR     0xED
+#define G_FILLRECT       0xF6
+#define G_SETFILLCOLOR   0xF7
+#define G_SETCIMG        0xFF
+
+static inline void dl_w(unsigned int w0, unsigned int w1)
+{ dl[dl_count++] = w0; dl[dl_count++] = w1; }
 
 void n64_init(void)
 {
-    /* NTSC 320x240 16bpp — register indices per the N64 VI map:
-       0=STATUS 1=ORIGIN 2=WIDTH 3=V_INTR 4=CURRENT 5=BURST 6=V_SYNC 7=H_SYNC
-       8=LEAP 9=H_START 10=V_START 11=V_BURST 12=X_SCALE 13=Y_SCALE. */
-    VI(0)  = 0x0000320E;   /* STATUS: 16bpp(type=2) + AA + dither + pixel_advance */
-    VI(2)  = 320;          /* WIDTH */
-    VI(3)  = 2;            /* V_INTR */
-    VI(4)  = 0;            /* CURRENT */
-    VI(5)  = 0x03E52239;   /* BURST (NTSC) */
-    VI(6)  = 0x0000020D;   /* V_SYNC = 525 */
-    VI(7)  = 0x00000C15;   /* H_SYNC */
-    VI(8)  = 0x0C150C15;   /* LEAP */
-    VI(9)  = 0x006C02EC;   /* H_START: 108..748 */
-    VI(10) = 0x002501FF;   /* V_START: 37..511 */
-    VI(11) = 0x000E0204;   /* V_BURST */
-    VI(12) = 0x00000200;   /* X_SCALE (320) */
-    VI(13) = 0x00000400;   /* Y_SCALE (240) */
-    front = FB0;
-    fb = (volatile unsigned short *)FB1;
-    VI(1) = FB0 & 0x1FFFFFFF;   /* ORIGIN */
+    int i;
+    /* NTSC 320x240 16bpp VI setup, scanning out FB_ADDR — glide64 reads our color
+       image from the SetColorImage GBI cmd, but the VI must still be programmed so
+       there is a valid display target. */
+    VI(0)  = 0x0000320E; VI(2) = 320; VI(3) = 2; VI(5) = 0x03E52239;
+    VI(6)  = 0x0000020D; VI(7) = 0x00000C15; VI(8) = 0x0C150C15;
+    VI(9)  = 0x006C02EC; VI(10)= 0x002501FF; VI(11)= 0x000E0204;
+    VI(12) = 0x00000200; VI(13)= 0x00000400;
+    VI(1)  = FB_ADDR;
+
+    /* Build the CRC-bait "ucode": 3072 bytes that SUM (as u32 words) to the F3DEX2
+       CRC glide64 expects (UCODE_ZELDA_OOT = 0x5d3099f1). All words 0 except one. */
+    { volatile unsigned int *uc = U32P(UC_ADDR);
+      for (i = 0; i < 3072/4; i++) uc[i] = 0;
+      uc[0] = 0x5d3099f1u; }
 }
 
-static inline void putpx(int x, int y, unsigned short c)
+/* Begin a fresh display list for this frame: sync + set the color image + scissor +
+   fill cycle, and a default combine that passes the fill/shade through. */
+static void dl_begin(void)
 {
-    if ((unsigned)x < SCREEN_W && (unsigned)y < SCREEN_H) fb[y * SCREEN_W + x] = c;
+    dl = U32P(DL_ADDR);
+    dl_count = 0;
+    dl_w((G_RDPPIPESYNC << 24), 0);
+    /* SetColorImage: fmt=0(RGBA) size=2(16b) width-1=319, addr=FB */
+    dl_w((G_SETCIMG << 24) | (0 << 21) | (2 << 19) | 319, FB_ADDR);
+    /* SetScissor: (0,0)-(320,240) in 10.2 fixed (<<2) */
+    dl_w((G_SETSCISSOR << 24) | (0 << 12) | 0, (320 << 14) | (240 << 2));
+    /* SetOtherMode_H: cycle type = FILL (3<<20 within the H word). F3DEX2 form:
+       shift=0x14(20) len=2 → set the 2 cycle-type bits to 3 (G_CYC_FILL). */
+    dl_w((G_SETOTHERMODE_H << 24) | ((32 - 20 - 2) << 8) | (2 - 1), 3u << 20);
+}
+
+/* End the list with sync + ENDDL, then ship it to the RSP/RDP as a GFX OSTask. */
+static void dl_end_and_run(void)
+{
+    dl_w((G_RDPFULLSYNC << 24), 0);
+    dl_w((G_ENDDL << 24), 0);
+
+    /* Write the OSTask into SP DMEM at 0xFC0 (SP DMEM is at 0xA4000000). */
+    volatile unsigned int *task = (volatile unsigned int *)0xA4000FC0u;
+    task[0] = 1;          /* 0xFC0 TASK_TYPE = M_GFXTASK (glide64 path) */
+    task[1] = 0;          /* 0xFC4 flags */
+    task[2] = 0;          /* 0xFC8 ucode_boot */
+    task[3] = 0;          /* 0xFCC ucode_boot_size */
+    task[4] = UC_ADDR;    /* 0xFD0 ucode (CRC-summed by glide64) */
+    task[5] = 0xC00;      /* 0xFD4 ucode_size (>= 3072 so the full CRC region reads) */
+    task[6] = UC_ADDR;    /* 0xFD8 ucode_data */
+    task[7] = 0x800;      /* 0xFDC ucode_data_size */
+    task[8] = 0;          /* 0xFE0 dram_stack */
+    task[9] = 0x400;      /* 0xFE4 dram_stack_size */
+    task[10] = 0;         /* 0xFE8 output_buff */
+    task[11] = 0;         /* 0xFEC output_buff_size */
+    task[12] = DL_ADDR;   /* 0xFF0 data_ptr → our GBI display list */
+    task[13] = dl_count * 4; /* 0xFF4 data_size (bytes) */
+    task[14] = 0;         /* 0xFF8 yield_data_ptr */
+    task[15] = 0;         /* 0xFFC yield_data_size */
+
+    /* Kick the RSP. The SP status-write handler runs the task only when BOTH HALT
+       and BROKE are clear after the write: bit0 (0x1) clears HALT, bit2 (0x4) clears
+       BROKE. Setting interrupt-on-break (0x100) makes the task signal completion.
+       The RSP-HLE then reads the OSTask at DMEM 0xFC0, sees type==1, and forwards
+       our display list to glide64. (SP_PC at 0xA4080000 is irrelevant under HLE —
+       the ucode never executes; only the OSTask fields + the CRC matter.) */
+    SP(SP_STATUS) = 0x00105;   /* clear HALT (0x1) + clear BROKE (0x4) + intr-on-break (0x100) */
 }
 
 void n64_clear(unsigned short col)
 {
-    int i; for (i = 0; i < SCREEN_W * SCREEN_H; i++) fb[i] = col;
+    dl_begin();
+    /* SetFillColor: 16bpp color packed twice into 32 bits. */
+    unsigned int c32 = ((unsigned int)col << 16) | col;
+    dl_w((G_SETFILLCOLOR << 24), c32);
+    /* FillRectangle covering the whole screen (coords in 10.2 fixed, inclusive). */
+    dl_w((G_FILLRECT << 24) | (((320 - 1) << 2) << 12) | ((240 - 1) << 2),
+         (0 << 12) | 0);
 }
 
 void n64_rect(int x, int y, int w, int h, unsigned short col)
 {
-    int r, c;
-    for (r = 0; r < h; r++) for (c = 0; c < w; c++) putpx(x + c, y + r, col);
+    int x1 = x + w - 1, y1 = y + h - 1;
+    if (x < 0) x = 0; if (y < 0) y = 0;
+    if (x1 > 319) x1 = 319; if (y1 > 239) y1 = 239;
+    if (x1 < x || y1 < y) return;
+    unsigned int c32 = ((unsigned int)col << 16) | col;
+    dl_w((G_SETFILLCOLOR << 24), c32);
+    dl_w((G_FILLRECT << 24) | ((x1 << 2) << 12) | (y1 << 2),
+         ((x << 2) << 12) | (y << 2));
 }
 
-/* edge function for the rasterizer */
-static inline int edge(int ax, int ay, int bx, int by, int cx, int cy)
-{ return (bx - ax) * (cy - ay) - (by - ay) * (cx - ax); }
-
-void n64_tri2d(int x0,int y0,int x1,int y1,int x2,int y2,unsigned short col)
+/* Triangle: a flat-shaded, screen-space triangle. The verts are already projected
+   to 2D pixels by the 3D pipeline. Rather than drive glide64's full F3DEX2 vertex/
+   matrix/combine pipeline (heavy state), we scan-convert the triangle into a span of
+   GPU FILL RECTANGLES — one per scanline. These are the SAME hardware-accelerated
+   fill-rects that clear/rect use (rasterized by glide64 on the GPU, NOT CPU pixels),
+   so it stays fast + renders correctly under the fill-cycle render state. The
+   examples draw a handful of large flat quads, so the per-scanline rect count is low. */
+static void emit_tri(int x0,int y0,int x1,int y1,int x2,int y2,unsigned short col)
 {
-    int minx = x0, maxx = x0, miny = y0, maxy = y0, px, py, w0, w1, w2, area;
-    if (x1 < minx) minx = x1; if (x1 > maxx) maxx = x1;
-    if (x2 < minx) minx = x2; if (x2 > maxx) maxx = x2;
-    if (y1 < miny) miny = y1; if (y1 > maxy) maxy = y1;
-    if (y2 < miny) miny = y2; if (y2 > maxy) maxy = y2;
-    if (minx < 0) minx = 0; if (miny < 0) miny = 0;
-    if (maxx >= SCREEN_W) maxx = SCREEN_W - 1; if (maxy >= SCREEN_H) maxy = SCREEN_H - 1;
-    area = edge(x0, y0, x1, y1, x2, y2);
-    if (area == 0) return;
-    for (py = miny; py <= maxy; py++) {
-        for (px = minx; px <= maxx; px++) {
-            w0 = edge(x1, y1, x2, y2, px, py);
-            w1 = edge(x2, y2, x0, y0, px, py);
-            w2 = edge(x0, y0, x1, y1, px, py);
-            if (area > 0) { if (w0 >= 0 && w1 >= 0 && w2 >= 0) fb[py * SCREEN_W + px] = col; }
-            else          { if (w0 <= 0 && w1 <= 0 && w2 <= 0) fb[py * SCREEN_W + px] = col; }
+    /* sort vertices by y (y0 <= y1 <= y2) */
+    int t;
+    if (y0 > y1) { t=x0;x0=x1;x1=t; t=y0;y0=y1;y1=t; }
+    if (y1 > y2) { t=x1;x1=x2;x2=t; t=y1;y1=y2;y2=t; }
+    if (y0 > y1) { t=x0;x0=x1;x1=t; t=y0;y0=y1;y1=t; }
+    if (y2 == y0) return;                 /* degenerate */
+
+    int y;
+    for (y = y0; y <= y2; y++) {
+        if (y < 0 || y > 239) continue;
+        /* x along the long edge 0→2 */
+        int xa = x0 + (x2 - x0) * (y - y0) / (y2 - y0);
+        int xb;
+        if (y < y1) {
+            if (y1 == y0) continue;
+            xb = x0 + (x1 - x0) * (y - y0) / (y1 - y0);
+        } else {
+            if (y2 == y1) continue;
+            xb = x1 + (x2 - x1) * (y - y1) / (y2 - y1);
         }
+        if (xa > xb) { t = xa; xa = xb; xb = t; }
+        if (xa < 0) xa = 0; if (xb > 319) xb = 319;
+        if (xb < xa) continue;
+        /* one GPU fill-rect for this 1px-tall span */
+        unsigned int c32 = ((unsigned int)col << 16) | col;
+        dl_w((G_SETFILLCOLOR << 24), c32);
+        dl_w((G_FILLRECT << 24) | ((xb << 2) << 12) | (y << 2),
+             ((xa << 2) << 12) | (y << 2));
     }
 }
 
+void n64_tri2d(int x0,int y0,int x1,int y1,int x2,int y2,unsigned short col)
+{ emit_tri(x0,y0,x1,y1,x2,y2,col); }
+
 void n64_flip(void)
 {
-    /* swap buffers + point VI at the freshly drawn one, then wait for a frame. */
-    unsigned int newfront = (unsigned int)(unsigned long)fb;
-    VI(1) = newfront & 0x1FFFFFFF;
-    fb = (volatile unsigned short *)(front);
-    front = newfront;
-    { volatile int i; for (i = 0; i < 200000; i++) { } }
+    dl_end_and_run();
+    /* wait for the frame to scan out + the RDP to drain. */
+    { volatile int i; for (i = 0; i < 100000; i++) { } }
 }
 
-/* ── input: read controller port 0 via the SI/PIF. The PIF command 0x01 polls
-   the pad; the 16-bit button word is at PIF RAM. We use the simple JoyBus poll. ── */
+/* ── input: read controller port 0 via the SI/PIF JoyBus poll. ── */
 static unsigned int read_pad(void)
 {
-    volatile unsigned int *pif = (volatile unsigned int *)0xBFC007C0; /* PIF RAM */
+    volatile unsigned int *pif = (volatile unsigned int *)0xBFC007C0;
     volatile unsigned int *si  = (volatile unsigned int *)0xA4800000;
     unsigned int buttons;
-    /* command block: read controller 0 (1 byte cmd 0x01, 1 byte send, ...) */
     pif[0] = 0xFF010401; pif[1] = 0xFFFFFFFF; pif[2] = 0xFFFFFFFF;
     pif[3] = 0xFE000000; pif[4] = 0; pif[5] = 0; pif[6] = 0; pif[7] = 1;
-    si[1] = 0x1FC007C0;          /* SI_PIF_ADDR_RD64B: kick the PIF read */
+    si[1] = 0x1FC007C0;
     { volatile int t; for (t = 0; t < 5000; t++) { } }
-    buttons = pif[1] >> 16;      /* the button half-word */
-    return (~0u) & buttons;      /* JoyBus buttons are active-high already */
+    buttons = pif[1] >> 16;
+    return (~0u) & buttons;
 }
 unsigned int n64_pad(void) { return read_pad(); }
 int n64_pressed(unsigned int mask) { return (n64_pad() & mask) ? 1 : 0; }
 
-/* ── trig (shared with PS1 lib: 256-step binary angle) ── */
+/* ── trig (256-step binary angle) ── */
 static const short SINTAB[64] = {
 0,804,1608,2410,3212,4011,4808,5602,6393,7179,7962,8739,9512,10278,11039,11793,
 12539,13279,14010,14732,15446,16151,16846,17530,18204,18868,19519,20159,20787,21403,
@@ -127,7 +228,7 @@ static fix sin_lut(int idx) {
 fix n64_sin(fix a) { return sin_lut((F2I(a)) & 255); }
 fix n64_cos(fix a) { return sin_lut((F2I(a) + 64) & 255); }
 
-/* ── camera + model (identical to the PS1 lib) ── */
+/* ── camera + model + projection (math unchanged; output drives emit_tri) ── */
 static fix cam_x, cam_y, cam_z, cam_cy, cam_sy, cam_cp, cam_sp;
 static fix mdl_x, mdl_y, mdl_z, mdl_cy, mdl_sy;
 void n64_camera(fix ex, fix ey, fix ez, fix yaw, fix pitch)
@@ -162,7 +263,7 @@ void n64_tri3d(Vec3 a, Vec3 b, Vec3 c, unsigned short col)
     int x0,y0,x1,y1,x2,y2;
     if (!project(ca,&x0,&y0)||!project(cb,&x1,&y1)||!project(cc,&x2,&y2)) return;
     if ((x1-x0)*(y2-y0)-(x2-x0)*(y1-y0) <= 0) return; /* back-face cull */
-    n64_tri2d(x0,y0,x1,y1,x2,y2,col);
+    emit_tri(x0,y0,x1,y1,x2,y2,col);
 }
 void n64_quad3d(Vec3 a, Vec3 b, Vec3 c, Vec3 d, unsigned short col)
 { n64_tri3d(a,b,c,col); n64_tri3d(a,c,d,col); }
@@ -171,7 +272,7 @@ void n64_tri3d_nc(Vec3 a, Vec3 b, Vec3 c, unsigned short col)
     Vec3 ca=to_cam(a), cb=to_cam(b), cc=to_cam(c);
     int x0,y0,x1,y1,x2,y2;
     if (!project(ca,&x0,&y0)||!project(cb,&x1,&y1)||!project(cc,&x2,&y2)) return;
-    n64_tri2d(x0,y0,x1,y1,x2,y2,col);
+    emit_tri(x0,y0,x1,y1,x2,y2,col);
 }
 void n64_quad3d_nc(Vec3 a, Vec3 b, Vec3 c, Vec3 d, unsigned short col)
 { n64_tri3d_nc(a,b,c,col); n64_tri3d_nc(a,c,d,col); }
@@ -181,7 +282,7 @@ static unsigned int rng = 0x12345678u;
 void n64_srand(unsigned int s) { rng = s ? s : 1; }
 unsigned int n64_rand(void) { unsigned int x=rng; x^=x<<13; x^=x>>17; x^=x<<5; return rng=x; }
 
-/* ── HUD number (3x5 cells scaled) ── */
+/* ── HUD number (3x5 cells via filled rects) ── */
 static const unsigned char DIG[10][5] = {
  {0x7,0x5,0x5,0x5,0x7},{0x2,0x6,0x2,0x2,0x7},{0x7,0x1,0x7,0x4,0x7},{0x7,0x1,0x3,0x1,0x7},
  {0x5,0x5,0x7,0x1,0x1},{0x7,0x4,0x7,0x1,0x7},{0x7,0x4,0x7,0x5,0x7},{0x7,0x1,0x1,0x1,0x1},

package/src/platforms/ps1/MENTAL_MODEL.md

@@ -0,0 +1,85 @@
+# PlayStation (PS1) — mental model
+
+The PS1 is a **3D machine**: a 33.87 MHz MIPS R3000A CPU + the GPU (2D/3D
+rasterizer, drawing into 1 MB VRAM) + the GTE (Geometry Transformation Engine,
+a CPU coprocessor for 3D math) + the SPU (24-voice ADPCM sound). romdev runs it on
+**beetle_psx_hw** (Mednafen PSX) built to WASM, presenting through the
+**native-gles / WebGL2 hardware GPU**.
+
+## The one thing to know about rendering
+
+PS1 homebrew draws by issuing **GPU primitives** (GP0 command packets) — not by
+writing a raw CPU framebuffer. The core is `beetle_psx_hw`, the **hardware** renderer
+(`hwRender: true`): it rasterizes the GPU command stream on the real GPU via
+GLES3/WebGL2 (through romdev's native-gles bridge), exactly like a console. So the
+bundled `psx.c` helper lib is a small **software-3D front end** (16.16 fixed-point
+transform + project + cull + painter sort) whose **back end emits GP0 flat-poly
+primitives** to the GPU — the GPU does the actual rasterization. (This differs from
+N64, which software-rasterizes into RDRAM; PS1 hands triangles to the GPU.)
+
+GP0 gotcha that cost real time: **`GP0 0x60` is a variable-size rectangle**, encoded
+as 3 words (color, top-left corner, size) — NOT a 4-vertex polygon. Feeding it
+polygon vertices stretches rects to the screen edge. Use the right command for the
+primitive (triangles = `0x20`/`0x24`/`0x28`/`0x2C` family; rects = `0x60`). Read the
+GP0 encoding carefully.
+
+## CPU / memory map (R3000A, MIPS I, 32-bit, little-endian)
+
+| Region | Address (KUSEG/KSEG) | Notes |
+|--------|----------------------|-------|
+| Main RAM | `0x8001_0000`+ (kseg0) / `0x0001_0000`+ | 2 MB. Programs load at `0x8001_0000`. |
+| Scratchpad | `0x1F80_0000` | 1 KB fast on-chip RAM |
+| Hardware I/O | `0x1F80_1000`+ | GPU (`…1810`), SPU (`…1C00`), SIO (`…1040`), DMA, timers |
+| BIOS | `0xBFC0_0000` | HLE'd by default — you don't ship a BIOS |
+
+Addresses are **little-endian**. `memory({op:'read', region:'system_ram'})` reads
+main RAM.
+
+## Booting — PS-EXE (no BIOS, no disc)
+
+PS1 boots from a **2048-byte PS-EXE header** (magic `PS-X EXE`, with `pc0` / `t_addr`
+/ `t_size` at fixed offsets). The HLE BIOS loads `t_size` bytes to `t_addr` and jumps
+to `pc0`. romdev's `build`/`cart` wrap a valid PS-EXE around your code (`wrapPsExe`) —
+no CD image, no real BIOS needed. (We never build discs; HLE + PS-EXE is enough for
+homebrew.)
+
+## Input
+
+Homebrew reads the pad from **hardware** — the SIO handshake at `0x1F80_1040`
+(transfer `0x01`, `0x42`, read the button halfword). The host's `setInput`/`run`
+holdInputs drive the emulated pad; the game polls SIO. The helper lib has a
+`pad_read()`.
+
+## Sound
+
+The SPU (24 ADPCM voices) at `0x1F80_1C00`. Samples are SPU-ADPCM in SPU RAM, keyed on
+via the voice registers. The helper lib has a minimal tone path.
+
+## MCP debug & inspection tooling — current state
+
+- **`memory({op:'read', region:'system_ram'})`** — main RAM. ✅
+- **`disasm` / `decompile`** — MIPS via rizin/Ghidra. ✅ (R3000A `jal` targets are
+  absolute VAs — the analysis buffer is base-aligned so call-following works; see
+  TROUBLESHOOTING if a fixed-VA image misbehaves.)
+- **`frame({op:'verify'})` / screenshot** — render-health + capture. ✅
+- **`cart` extract/wrap** — PS-EXE. ✅
+- **`cpu({op:'read'})`** — live R3000A register file (`romdev_mips_regs_get`: r0..r31,
+  LO, HI, PC). ✅
+- **`audioDebug({op:'inspect', chip:'spu'})`** — the SPU register block at `0x1F80_1C00`
+  (`romdev_spu_get`, the 1 KB window). ✅
+- **`breakpoint` / `watch`** — not yet (those need interpreter-step + memory-path hooks
+  patched into beetle; cpuState/audioDebug are plain reads and ARE wired).
+- **`renderingContext`** is **N/A** (false) — 3D GPU machine, no 2D tile VDP to decode.
+
+## Build pipeline
+
+`build({platform:'ps1'})` cross-compiles with the from-scratch **mips-elf-gcc → WASM**
+toolchain (little-endian libs; a small `softint.c` supplies 64-bit divide helpers on
+the LE side), then `wrapPsExe` produces the bootable PS-EXE. `#include` the bundled
+`psx.h` for the software-3D front end + GP0 emit + SIO/SPU helpers.
+
+## What's NOT bundled / hardware limits
+
+- No CD-ROM/XA/streaming or MDEC video.
+- `breakpoint`/`watch` not yet (need interpreter-step hooks; cpuState/audioDebug ARE wired).
+- `renderingContext` is N/A (3D GPU, no tile VDP).

package/src/platforms/ps1/TROUBLESHOOTING.md

@@ -0,0 +1,55 @@
+# PlayStation (PS1) — troubleshooting
+
+Read `platform({op:'doc', platform:'ps1', name:'mental_model'})` first — PS1 renders
+by issuing **GPU primitives (GP0)** on the hardware renderer, not by writing a CPU
+framebuffer.
+
+## "ROM builds + boots but the screen is BLACK"
+
+1. **You're trying to write a raw framebuffer.** PS1's renderer is the hardware GPU
+   (`beetle_psx_hw`, `hwRender:true`) — it rasterizes the **GP0 command stream**, not
+   a CPU-written framebuffer. Draw with GPU primitives (the bundled `psx.c` emits
+   them); a CPU memset of "VRAM" won't show.
+2. **You never set the display area / drawing environment.** GP1 sets the display
+   mode + display start; GP0 `0xE1..0xE6` set the drawing area/offset. Without a valid
+   draw env + display env the GPU has nowhere to put pixels. The helper lib's
+   `gpu_init` does this — call it before drawing.
+3. **Nothing was actually submitted to GP0.** Confirm with `frame({op:'verify'})`
+   (nearlyBlank) + check you're writing the GP0 port (`0x1F80_1810`) / running a DMA
+   to it, not just touching VRAM.
+
+## "Rectangles stretch to the edge of the screen / primitives are garbage"
+
+`GP0 0x60` (and the rect family) is a **variable-size rectangle**: 3 words = color,
+top-left corner, size. If you feed it 4 polygon vertices it reads corner+size+garbage
+and stretches. Use the **triangle** family (`0x20`/`0x24`/`0x28`/`0x2C`) for polys and
+the **rect** family (`0x60`/`0x64`/`0x68`/`0x6C`) for rects. Match the command to the
+primitive and word count.
+
+## "Geometry is wrong / inside-out / clipped"
+
+Software-3D front-end math (the helper lib transforms before emitting GP0): check
+16.16 fixed-point throughout, back-face winding matches your vertex order, perspective
+divide before the GP0 vertex coords, and coords fit the 11-bit signed GPU range.
+
+## "disasm/decompile of a multi-function program returns junk (fcn.00000000)"
+
+Known rizin trap: for **absolute-addressed `jal`** (PS1 `jal 0x80010518`), rizin
+ignores `-B` on a raw `malloc://` buffer and addresses flat from 0, so cross-function
+discovery dangles outside the image. romdev fixes this by left-padding `.text` so the
+flat offset == the VA's low 20 bits, seeding analysis there, and rebasing the high bits
+back — so reported addresses are real VAs. If you see a lone `fcn.00000000`, you're on
+a path that bypassed the rebase; build a **multi-function** program to exercise it (a
+single-instruction smoke test hides this).
+
+## "breakpoint / watch return N/A"
+
+`cpu({op:'read'})` and `audioDebug({op:'inspect', chip:'spu'})` ARE wired on PS1 (the
+core exports `romdev_mips_regs_get` + `romdev_spu_get`). `breakpoint`/`watch` are not
+yet — those need interpreter-step + memory-path hooks patched into beetle (cpuState/
+audioDebug are plain reads). Use `cpu`/`audioDebug` + `memory` + `disasm`/`decompile`
+meanwhile.
+
+## "renderingContext returns N/A"
+
+Correct — PS1 is a 3D GPU machine with no 2D tile/sprite VDP for that op. Not a bug.

package/src/platforms/ps1/UPSTREAM_SOURCES.md

@@ -0,0 +1,54 @@
+# PlayStation (PS1) — source you can read
+
+Trust hierarchy (try in order before filing a feedback round):
+
+1. **Bundled examples** (`examples/ps1/{shmup,platformer,puzzle,racing,sports}/main.c` +
+   `sprite_move/`) — verified building + rendering on the GPU. Start here.
+2. **Bundled helper lib source** (`src/platforms/ps1/lib/c/psx.c` + `psx.h`) — the GPU
+   front end. Read this when a primitive renders wrong: it shows how the software-3D
+   transform feeds **GP0 GPU primitives** (the real console path — the GPU rasterizes the
+   command stream; this is NOT a software framebuffer). The GP0 `0x60` rect-vs-poly gotcha
+   is in here + TROUBLESHOOTING.
+3. **The core source** (NOT bundled — fetch on demand):
+
+   | What | Upstream |
+   |---|---|
+   | beetle-psx (Mednafen PSX, libretro, HW renderer) | https://github.com/libretro/beetle-psx-libretro |
+   | R3000A CPU / SPU / GPU internals | (in the beetle tree: `mednafen/psx/cpu.c`, `spu.c`, `gpu.cpp`) |
+
+   The cpuState/audioDebug exports we patch in (`romdev_mips_regs_get`,
+   `romdev_spu_get`) live in `scripts/patches/romdev-snippets/beetle-psx-regsnap.c` +
+   `beetle-psx-spu.c`.
+
+4. **The toolchain** — a from-scratch `mips-elf-gcc` cross-compiler (little-endian) built
+   to WASM (`scripts/build-mips-toolchain.sh` — one toolchain emits both N64 BE + PS1 LE):
+
+   | Component | Upstream |
+   |---|---|
+   | binutils | https://ftp.gnu.org/gnu/binutils/ |
+   | gcc | https://ftp.gnu.org/gnu/gcc/ |
+   | newlib | https://sourceware.org/pub/newlib/ |
+
+5. **Reverse engineering** — Rizin + Ghidra MIPS (R3000A):
+
+   | What | Upstream |
+   |---|---|
+   | Rizin | https://github.com/rizinorg/rizin |
+   | rz-ghidra | https://github.com/rizinorg/rz-ghidra |
+
+## PS1 hardware docs
+
+- **psx-spx** (Nocash, the canonical reference): https://psx-spx.consoledev.net/
+- **PSn00bSDK** (a real open PS1 SDK — read its GPU/GTE/SPU code for the standard GP0/GP1
+  encodings + SPU register layout): https://github.com/Lameguy64/PSn00bSDK
+
+## When to use what
+
+- "Why is my screen BLACK?" → MENTAL_MODEL + TROUBLESHOOTING (you must issue GP0
+  primitives + set the draw/display environment — a CPU memset won't show).
+- "My rectangles stretch to the edge" → the GP0 `0x60` variable-size-rect gotcha
+  (TROUBLESHOOTING).
+- "How does the helper emit a triangle?" → `psx.c` + psx-spx GPU section.
+- "audioDebug SPU volumes look off" → the SPU volume/sweep registers read processed
+  values; the decode reads the raw mirror (see `psx.c` / beetle `spu.c`).
+- "disasm returns a single `fcn.00000000`" → TROUBLESHOOTING (the absolute-`jal` rebase).

package/src/platforms/snes/TROUBLESHOOTING.md

@@ -261,6 +261,16 @@ synthesizes a fallback `issues[]` entry with a hint. The idioms to avoid:
   block where the layout expects it. Use
   `examples({op:'snippets', platform:"snes", mode:"get", snippetName:"lorom_header.asm"})`
   for the canonical layout (and `lorom_multibank.asm` for multi-bank).
+- **`readfile1`/`filesize`/`canreadfile` across MANY distinct files.** Converting
+  assets at assemble time (the commercial-disassembly idiom — e.g. an `incpal`
+  macro reading every `.pal` palette to emit 15-bit color) reads many *distinct*
+  files via the readfile API. asar-WASM can **abort with no diagnostic** above a
+  threshold of distinct files read that way (one file read 200× is fine — it's
+  the *count of distinct files*). `incbin` does NOT have this problem. The build
+  log carries an `[asar advisory]`/abort-hint when it sees a source over the
+  threshold. **Fix: pre-convert the assets to `.bin` blobs offline and `incbin`
+  them** — the output is byte-identical. (Put the converted blobs in a subdir;
+  `output:'project'` stages subdirectory assets recursively.)
 
 (This is the asar/asm path. The default PVSnesLib **C** path goes through
 tcc-65816 + wla-65816 and has its own C89 trap, above.)