c64-kb 0.17.0

package/docs/recipes/oscar64/lfsr-random-seed2.md

@@ -0,0 +1,338 @@
+---
+recipe: lfsr-random-seed2
+toolchain: oscar64
+output_format: PRG
+region: pal
+techniques: [lfsr_random]
+file_formats: [PRG]
+uses_registers: [D40E, D40F, D412, D418, D41B, DC04, DC05, DC0E, D011, D020, D021]
+uses_kernal: []
+---
+
+<!-- doc-type: recipe -->
+
+# Oscar64 LFSR random numbers with a fixed seed
+
+## Synopsis
+
+The listing of `lfsr-random.md` with one line added at the top,
+`#define FIXED_SEED 0xBEEF`, so the generators start from `$BEEF`
+instead of the two $D41B reads. It exists because a headless VICE run
+seeds the main recipe identically every time, so that page alone cannot
+show that the picture depends on the seed. This one does: same code,
+different seed, different first bytes, different mosaic. The SID is still
+set up and the $D41B change count is still measured; only the seed is
+replaced. The technique is `lfsr_random` in `techniques/maths.md`.
+
+## Source
+
+```c
+#define FIXED_SEED 0xBEEF
+// lfsr-random.c
+// Two Galois LFSRs, an 8-bit one (taps $B8, period 255) and a 16-bit one
+// (taps $B400, period 65535), seeded from SID voice 3 noise at $D41B.
+// The screen shows the seed, the first eight output bytes, a mosaic
+// painted by the 16-bit generator, then a self-check: both periods are
+// walked on the 6510 and folded into a checksum that must match the value
+// computed in Python and compiled in below. CIA1 timer A times each step.
+// Define FIXED_SEED to ignore $D41B and use a constant seed instead; the
+// companion page recipes/oscar64/lfsr-random-seed2.md does exactly that.
+#include <c64/vic.h>
+#include <c64/sid.h>
+#include <c64/cia.h>
+
+#define SCREEN ((char *)0x0400)
+#define COLOUR ((char *)0xd800)
+
+#define EXPECT_CS8  0x5F8B   // Python fold over the 255 states from state 1
+#define EXPECT_CS16 0x6D9B   // Python fold over the 65535 states from state 1
+
+static const char hex_glyph[16] = {
+    '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 1, 2, 3, 4, 5, 6 };
+
+// Generator state. Globals so the inline assembler can name them.
+volatile char     s8;
+volatile unsigned s16;
+unsigned hist[256];
+
+// 8-bit Galois LFSR, one step, right shift, taps $B8 (x^8+x^6+x^5+x^4+1).
+__noinline void step8(void)
+{
+    __asm volatile {
+        lda s8
+        lsr
+        bcc l1
+        eor #$b8
+    l1:
+        sta s8
+    }
+}
+
+// 16-bit Galois LFSR, one step, right shift, taps $B400 (x^16+x^14+x^13+x^11+1).
+__noinline void step16(void)
+{
+    __asm volatile {
+        lsr s16 + 1
+        ror s16
+        bcc l1
+        lda s16 + 1
+        eor #$b4
+        sta s16 + 1
+    l1:
+    }
+}
+
+__noinline void nothing(void)
+{
+}
+
+static void put_str(char row, char col, const char *s)
+{
+    char *p = SCREEN + 40 * row + col;
+    while (*s)
+    {
+        char c = *s++;
+        *p++ = (c >= 'a' && c <= 'z') ? c - 'a' + 1 : c;
+    }
+}
+
+static void put_hex8(char row, char col, char v)
+{
+    char *p = SCREEN + 40 * row + col;
+    p[0] = hex_glyph[v >> 4];
+    p[1] = hex_glyph[v & 15];
+}
+
+static void put_hex16(char row, char col, unsigned v)
+{
+    put_hex8(row, col, v >> 8);
+    put_hex8(row, col + 2, v & 0xff);
+}
+
+static void put_dec(char row, char col, unsigned v, char width)
+{
+    char *p = SCREEN + 40 * row + col + width;
+    do
+    {
+        *--p = '0' + v % 10;
+        v /= 10;
+    } while (--width);
+}
+
+static unsigned fold(unsigned cs, unsigned v)
+{
+    return (cs ^ v) * 5 + 1;
+}
+
+// CIA1 timer A: force-load $FFFF, count phi2 while fn runs 256 times, read.
+static unsigned time_loop(void (*fn)(void))
+{
+    cia1.cra = 0x00;
+    cia1.ta = 0xffff;
+    cia1.cra = 0x11;
+    char i = 0;
+    do
+    {
+        fn();
+    } while (++i);
+    cia1.cra = 0x00;
+    return 0xffff - cia1.ta;
+}
+
+int main(void)
+{
+    for (unsigned i = 0; i < 1000; i++)
+    {
+        SCREEN[i] = 0x20;
+        COLOUR[i] = VCOL_WHITE;
+    }
+    vic.color_back = VCOL_BLACK;
+    vic.color_border = VCOL_BLACK;
+
+    // Voice 3 as a noise source: top frequency, noise gated, output muted
+    // by bit 7 of $D418 so the volume nibble a music player owns is
+    // left alone (a real game ORs the bit into its own $D418 shadow).
+    sid.voices[2].freq = 0xffff;
+    sid.voices[2].ctrl = SID_CTRL_NOISE | SID_CTRL_GATE;
+    sid.fmodevol = SID_FMODE_3_OFF | 15;
+
+    // Does $D41B move between reads? Count changes over 255 read pairs.
+    char prev = sid.random, changes = 0;
+    for (char i = 0; i < 255; i++)
+    {
+        char r = sid.random;
+        if (r != prev)
+            changes++;
+        prev = r;
+    }
+
+    // Seed: two reads a little apart make the 16-bit seed. The timer
+    // is read too, as the second source a game would mix in.
+    unsigned seed = sid.random;
+    for (char i = 0; i < 100; i++)
+        nothing();
+    seed = (seed << 8) | sid.random;
+    unsigned timer = cia1.ta;
+#ifdef FIXED_SEED
+    // Fetched through a runtime index so the seed is never a compile-time
+    // constant. With a bare constant here (or a volatile initialised to
+    // one) Oscar64 folded the volatile compare in the period loop below
+    // into an unconditional jump and dropped the rest of main.
+    static unsigned fixed_seed[2] = { FIXED_SEED, FIXED_SEED };
+    seed = fixed_seed[changes & 1];
+#endif
+    if (seed == 0)              // all-zero state never leaves zero
+        seed = 0xACE1;
+    char seed8 = (char)seed;
+    if (seed8 == 0)
+        seed8 = 0x01;
+
+    put_str(0, 0, "seed      cia1 ta       d41b chg");
+    put_hex16(0, 5, seed);
+    put_hex16(0, 18, timer);
+    put_dec(0, 33, changes, 3);
+
+    // The first eight bytes and the mosaic come from the same run.
+    s16 = seed;
+    put_str(1, 0, "first");
+    for (char i = 0; i < 8; i++)
+    {
+        step16();
+        put_hex8(1, 6 + 3 * i, (char)s16);
+    }
+    s16 = seed;
+    for (unsigned i = 240; i < 1000; i++)
+    {
+        step16();
+        SCREEN[i] = 0xa0;
+        COLOUR[i] = (char)s16 & 15;
+    }
+
+    // Period of the 8-bit generator from seed8, then its checksum from 1.
+    unsigned p8 = 0;
+    s8 = seed8;
+    do
+    {
+        step8();
+        p8++;
+    } while (s8 != seed8);
+    unsigned cs8 = 0;
+    s8 = 1;
+    do
+    {
+        step8();
+        cs8 = fold(cs8, s8);
+    } while (s8 != 1);
+    put_str(2, 0, "p8     cs      exp       p16");
+    put_dec(2, 3, p8, 3);
+    put_hex16(2, 10, cs8);
+    put_hex16(2, 19, EXPECT_CS8);
+
+    // Period of the 16-bit generator from the seed, with a byte histogram
+    // of its low byte, then its checksum from state 1.
+    for (unsigned i = 0; i < 256; i++)
+        hist[i] = 0;
+    unsigned p16 = 0;
+    s16 = seed;
+    do
+    {
+        step16();
+        p16++;
+        hist[(char)s16]++;
+    } while (s16 != seed);
+    unsigned cs16 = 0;
+    s16 = 1;
+    do
+    {
+        step16();
+        cs16 = fold(cs16, s16);
+    } while (s16 != 1);
+    unsigned hmin = 0xffff, hmax = 0;
+    for (unsigned i = 0; i < 256; i++)
+    {
+        if (hist[i] < hmin) hmin = hist[i];
+        if (hist[i] > hmax) hmax = hist[i];
+    }
+    put_dec(2, 29, p16, 5);
+    put_str(3, 0, "cs16      exp      hist min     max");
+    put_hex16(3, 5, cs16);
+    put_hex16(3, 14, EXPECT_CS16);
+    put_dec(3, 28, hmin, 3);
+    put_dec(3, 36, hmax, 3);
+
+    bool ok = p8 == 255 && cs8 == EXPECT_CS8 && p16 == 65535 &&
+              cs16 == EXPECT_CS16 && hmin == 255 && hmax == 256 &&
+              hist[0] == 255;
+
+    // Cycle cost: 256 calls each, DEN off so no badline stalls the count.
+    __asm { sei }
+    vic.ctrl1 = 0x0b;
+    vic_waitFrame();
+    unsigned t0 = time_loop(nothing);
+    unsigned t8 = time_loop(step8);
+    unsigned t16 = time_loop(step16);
+    vic.ctrl1 = 0x1b;
+    put_str(4, 0, "cyc x256 empty       l8       l16");
+    put_dec(4, 15, t0, 5);
+    put_dec(4, 24, t8, 5);
+    put_dec(4, 34, t16, 5);
+
+    put_str(5, 0, ok ? "pass" : "fail");
+    put_str(5, 6, "hist0");
+    put_dec(5, 12, hist[0], 3);
+    vic.color_border = ok ? VCOL_GREEN : VCOL_RED;
+    for (;;)
+        ;
+    return 0;
+}
+```
+
+## Build
+
+```
+oscar64 -tm=c64 -O2 -o=lfsr-random-seed2.prg lfsr-random-seed2.c
+GSETTINGS_SCHEMA_DIR=/opt/homebrew/share/glib-2.0/schemas timeout 120 x64sc -default -warp +sound +autostart-delay-random -autostartprgmode 1 -limitcycles 20000000 -exitscreenshot lfsr-random-seed2.png -autostart lfsr-random-seed2.prg
+```
+
+## Expected output
+
+Black screen, green border. Decoded from
+`screenshots/lfsr-random-seed2.png` (PAL) with the character ROM:
+
+```
+SEED BEEF CIA1 TA 24F3  D41B CHG 255
+FIRST 77 BB DD 6E 37 9B CD E6
+P8 255 CS 5F8B EXP 5F8B  P16 65535
+CS16 6D9B EXP 6D9B HIST MIN 255 MAX 256
+CYC X256 EMPTY 09476 L8 12933 L16 14441
+PASS  HIST0 255
+```
+
+The first bytes are what the Python model gives from `$BEEF`
+(`77 BB DD 6E 37 9B CD E6`), and the first mosaic cell is yellow, colour
+7, the low nibble of `$xx77`. Against the main recipe's PAL picture the
+mosaic agrees in 51 of 760 cells; two unrelated 16-colour patterns agree
+in 47.5 by chance. Rows 2 to 5 are identical to the main recipe: the
+period, checksum, histogram and cycle figures do not depend on the seed,
+which is the point of folding the checksum from state 1.
+
+What this picture proves: the mosaic and the first bytes are a function
+of the seed, and the self-check passes from a second seed. What it does
+not prove: that $D41B delivers a different seed on real hardware from
+one power-on to the next. That is rung 4 on both pages. The `CIA1 TA`
+value differs from the main recipe's `251C` because the two builds run a
+different number of cycles before the read, not because the timer is
+random here.
+
+## Why this works
+
+Everything on the main page applies. The one difference worth its own
+paragraph is how the constant gets in. `seed = FIXED_SEED;` produced a
+932-byte PRG whose 8-bit period loop was an unconditional jump: Oscar64
+(build 2026-05-19) treated the `volatile` compare against a
+compile-time constant as always true and removed the rest of `main`, so
+the screen stopped after the FIRST row with a black border. A `volatile`
+holding the constant, local or file-scope, was folded the same way. The
+two-entry array indexed by `changes & 1` (a value the compiler cannot
+know) gives a listing that compiles to the same code as the $D41B path,
+1,949 bytes against 1,935, and passes.