Add authentic deck loading and cap deck concatenation

Author: danielinux

Makefile

@@ -37,6 +37,7 @@ tests/tests: $(TESTS) libge.a
 tools:
 	$(MAKE) -C assembler gasm
 	$(MAKE) -C disassembler gdis
+	$(MAKE) -C tools capcat
 
 .PHONY: check
 .PHONY: native-reset
@@ -97,6 +98,7 @@ clean:
 	rm -f $(TESTS) $(TESTS:%.o=%.d)
 	$(MAKE) -C assembler clean
 	$(MAKE) -C disassembler clean
+	$(MAKE) -C tools clean
 	# NB: do NOT recurse into console/wasm clean here — the wasm build's own
 	# libge.a step calls `make -C ../.. clean`, so recursing would delete the
 	# console/wasm/main.o it just built and break `make wasm`. Clean the wasm

cardreader.c

@@ -99,6 +99,7 @@ struct cardreader_ctx {
      * to two packed nibbles here.) `half` tracks which nibble is pending. */
     int pack;
     int half;   /* 0 = high nibble pending, 1 = low nibble pending */
+    int post_loader_pack;
 
     /* the ge_peri node we allocated (kept for potential future use) */
     struct ge_peri peri;
@@ -215,6 +216,7 @@ static int cr_advance(struct cardreader_ctx *ctx)
 static int cardreader_on_clock(struct ge *ge, void *opaque)
 {
     struct cardreader_ctx *ctx = (struct cardreader_ctx *)opaque;
+    int pack_now;
 
     /* TU03N card-feed strobe (CE09), read as a one-cycle pulse: the CPU raises
      * it at end-of-card (state ea). We latch and clear it here at TO00 so it
@@ -320,6 +322,8 @@ static int cardreader_on_clock(struct ge *ge, void *opaque)
          * loader card in the registered mode and the program cards in TC_BINARY
          * ("by-pass"). */
         enum transcode_mode m;
+        pack_now = ctx->pack || (ctx->post_loader_pack &&
+                                 ctx->card_idx != ctx->loader_card);
         if (ctx->pack)
             m = ctx->mode;
         else if (ctx->card_idx == ctx->loader_card)
@@ -331,6 +335,13 @@ static int cardreader_on_clock(struct ge *ge, void *opaque)
              * must NOT override the loader card — it applies to the PROGRAM
              * cards the loader's Set-by-Pass selects. */
             m = ctx->mode;
+        else if (ctx->post_loader_pack)
+            /* The recovered loader program reads the following program cards in
+             * by-pass / column-binary form. The current signal-level model does
+             * not yet expose a distinct "non-packed by-pass" transfer state, so
+             * we feed each decoded COLBIN byte as a hi/lo nibble pair through
+             * the existing channel-1 packer. */
+            m = TC_COLBIN;
         else if (ge->integrated_reader.active_valid)
             m = ge->integrated_reader.active_mode;
         else
@@ -355,7 +366,7 @@ static int cardreader_on_clock(struct ge *ge, void *opaque)
          * In legacy mode one full value is presented per column. */
         uint8_t present;
         int     is_last;
-        if (ctx->pack) {
+        if (pack_now) {
             present = (ctx->half == 0) ? (uint8_t)((byte >> 4) & 0x0f)
                                        : (uint8_t)(byte & 0x0f);
             is_last = (ctx->half == 1) && is_last_col;
@@ -377,7 +388,7 @@ static int cardreader_on_clock(struct ge *ge, void *opaque)
          * mode / framing visible at the pins. */
         ge->integrated_reader.pom01 = (m == TC_BINARY || m == TC_COLBIN);
         ge->integrated_reader.picon = (ctx->col_idx == 0);
-        ge->integrated_reader.bi20  = (ctx->pack && ctx->half == 1);
+        ge->integrated_reader.bi20  = (pack_now && ctx->half == 1);
 
         reader_setup_to_send(ge, present, is_last ? 1 : 0);
         ctx->end_of_card_presented = is_last;
@@ -387,14 +398,20 @@ static int cardreader_on_clock(struct ge *ge, void *opaque)
          * the next call (do not move the pointer); only after the low nibble do
          * we advance to the next column / card. For a multi-card deck cr_advance
          * moves to (card+1, col 0), ready for the next PER read. */
-        if (ctx->pack && ctx->half == 0) {
+        if (pack_now && ctx->half == 0) {
             ctx->half = 1;
         } else {
             ctx->half = 0;
             if (is_last_col) {
-                /* Card boundary: defer the cross-to-next-card feed until the
-                 * CPU's TU03N end-of-card strobe (state ea). */
-                ctx->feed_pending = 1;
+                /* Only the bootstrap loader card uses the explicit TU03 feed
+                 * pulse (state ea). Once that loader has switched the reader to
+                 * by-pass and is pulling binary program cards into its buffer,
+                 * the next card becomes visible at the transfer boundary rather
+                 * than waiting for the bootstrap-only TU03 path. */
+                if (ctx->card_idx == ctx->loader_card && !ctx->pack)
+                    ctx->feed_pending = 1;
+                else
+                    cr_advance(ctx);
             } else {
                 cr_advance(ctx);
             }
@@ -475,6 +492,7 @@ static int cr_register(struct ge *ge, const char *cap_path,
         auto_loader = cr_find_hollerith_loader_card(deck);
     if (auto_loader >= 0)
         ctx->mode = TC_HEX;
+    ctx->post_loader_pack = !ctx->pack && ctx->mode == TC_HEX;
 
     /* Find the first non-empty card at or after first_card */
     ctx->card_idx = auto_loader >= 0 ? auto_loader : (first_card < 0 ? 0 : first_card);

docs/peripherals.md

@@ -174,6 +174,80 @@ the overlapped typewriter/printer transfer to finish before halting.
 `present` is set only by `printer_register`, so bootstrap/reader tests (which do
 not register a printer) leave it 0 and are completely unaffected.
 
+### Example: load a small printer program
+
+`assembler/examples/print.s` is the shortest end-to-end channel-2 output demo.
+It issues a `PER 0x80, order`, waits for `__io_status` at `0x0031` to become
+`0x01`, then halts.
+
+Build it:
+
+```sh
+make -C software/gemu tools ge
+./software/gemu/assembler/gasm \
+  -o /tmp/print.bin \
+  ./software/gemu/assembler/examples/print.s
+```
+
+Run it from the CLI:
+
+```sh
+./software/gemu/ge /tmp/print.bin
+```
+
+You should see:
+
+```text
+PRN> HELLO
+exit: halted=1 ...
+```
+
+Run it in wasm:
+
+```sh
+make -C software/gemu wasm
+```
+
+Then open the wasm console, choose `/tmp/print.bin` in the simulator gadget,
+press `Stage`, then on the panel press `CLEAR`, `LOAD`, `START`. The printer
+paper view should show `HELLO`, then the CPU halts.
+
+### Example: load the authentic printer deck
+
+The real punched deck in the dump set is
+`software/DUMP1/printermechanicaltest.cap`. This is a full card deck, not a
+direct binary image.
+
+CLI, authentic reader/bootstrap path:
+
+```sh
+./software/gemu/ge --deck ./software/DUMP1/printermechanicaltest.cap
+```
+
+That path uses the real reader flow (`LOAD1`, `LOAD`, bootstrap card, then deck
+cards through the integrated reader).
+
+CLI, fast scatter-decoded path:
+
+```sh
+./software/gemu/ge ./software/DUMP1/printermechanicaltest.cap
+```
+
+That uses the default positional `.cap` image path: the deck is scatter-decoded
+to memory first, then execution starts at the lowest loaded address.
+
+Wasm:
+
+1. Choose `software/DUMP1/printermechanicaltest.cap` in the simulator gadget.
+2. Press `Stage`.
+3. On the panel press `CLEAR`.
+4. Press `LOAD`.
+5. Press `START`.
+
+In the browser, `.cap` currently follows the staged scatter-image path rather
+than the authentic multi-card reader chain, so use the `--deck` CLI form above
+when you specifically want to exercise the real bootstrap/read path.
+
 ### Two-way chat (wasm + interactive CLI)
 
 * **Output** — `printer_output()` / `printer_output_len()` expose the captured

docs/punchcards.md

@@ -355,6 +355,28 @@ as a gemu-loadable **unified binary** (`gdis --image -o deck.bin deck.cap`; see
 `docs/binformat.md`), bridging a Hollerith `.cap` deck to the binary load path
 (`./ge deck.bin`).
 
+When a base deck needs extra payload cards appended, use `tools/capcat`:
+
+```sh
+make -C software/gemu tools
+
+# append one or more unified GE12 images
+software/gemu/tools/capcat -o combined.cap \
+    software/DUMP1/funktionalcpu.cap \
+    overlay.bin
+
+# raw flat overlay at an explicit address
+software/gemu/tools/capcat -o combined.cap \
+    software/DUMP1/funktionalcpu.cap \
+    0x2E00:segment2.raw
+```
+
+`capcat` copies the base deck's parsed hex-token cards, auto-detects its dominant
+8-byte program-card prefix, and emits appended self-addressed COLBIN cards
+(`LL`, load address, payload). The result is a real `.cap` medium that can be
+scatter-loaded (`./ge combined.cap`) or run through the authentic reader path
+(`./ge --deck combined.cap`).
+
 ---
 
 *Findings derived from the project's own reader firmware and the `gemu`

main.c

@@ -90,7 +90,8 @@ static void print_usage(const char *argv0)
         "                       e.g. --poke 0x0E00=0x80 to set a diagnostic option\n"
         "  --deck <path>        Path to a .cap card deck; loaded via the reader (connector 2)\n"
         "  --trace <spec>       Enable log types from spec string\n"
-        "  --max-cycles <N>     Maximum CPU cycles before forced exit (default: 100000)\n"
+        "  --max-cycles <N>     Maximum CPU cycles before forced exit (default: 100000,\n"
+        "                       or 500000 for --deck unless overridden)\n"
         "  --console            Enable the console socket /tmp/gemu.console (no UI attached)\n"
         "  --tui                Implies --console and starts the ncurses console client\n"
         "  --interactive, -i    Run until killed; SIGUSR1/SIGUSR2 toggle SWITCH 1/2 at\n"
@@ -107,6 +108,7 @@ int main(int argc, char *argv[])
     struct ge ge;
     int ret = 0;
     long max_cycles = 100000;
+    int max_cycles_set = 0;
     long cycles = 0;
     int use_console = 0;
     int use_tui = 0;
@@ -150,6 +152,7 @@ int main(int argc, char *argv[])
                 return 1;
             }
             max_cycles = atol(argv[++i]);
+            max_cycles_set = 1;
             if (max_cycles <= 0) {
                 fprintf(stderr, "error: --max-cycles must be a positive integer\n");
                 return 1;
@@ -220,6 +223,13 @@ int main(int argc, char *argv[])
         return 1;
     }
 
+    /* The cycle-faithful card-reader bootstrap is substantially slower than a
+     * direct binary or scatter-loaded image. Give `--deck` a roomier default so
+     * a real deck does not time out during the load unless the user explicitly
+     * requested a tighter budget. */
+    if (deck_path && !max_cycles_set)
+        max_cycles = 500000;
+
     ge_init(&ge);
 
     if (use_console) {

reader.c

@@ -52,7 +52,8 @@ void reader_send_tu00(struct ge *ge)
         case 0x01: r->mode_n002 = 1; r->active_mode = TC_NORMAL; break; /* read normal ii */
         case 0x24: r->mode_mi01 = 1; r->active_mode = TC_NORMAL; break; /* read mixed i   */
         case 0x04: r->mode_mi02 = 1; r->active_mode = TC_NORMAL; break; /* read mixed ii  */
-        case 0x20: r->mode_debi = 1; r->active_mode = TC_BINARY; break; /* read binary    */
+        case 0x20: r->mode_debi = 1; r->active_mode = TC_COLBIN; break; /* read by-pass / column-binary */
+        case 0xa0: r->mode_debi = 1; r->active_mode = TC_COLBIN; break; /* channel code card: with by-pass */
         default:   latch = 0; break;                                    /* 0x40 etc.: keep mode */
         }
         if (latch) { r->cocon = 1; r->active_valid = 1; }

tests/cap.c

@@ -1,7 +1,40 @@
 #include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
 
 #include "utest.h"
 #include "../cap.h"
+#include "../binimage.h"
+#include "../transcode.h"
+
+static uint16_t test_colbin_encode_byte(uint8_t b)
+{
+    uint16_t col = 0;
+
+    if (b & 0x80) col |= (uint16_t)(1u << 0);
+    if (b & 0x40) col |= (uint16_t)(1u << 1);
+    if (b & 0x20) col |= (uint16_t)(1u << 2);
+    if (b & 0x10) col |= (uint16_t)(1u << 3);
+    if (b & 0x08) col |= (uint16_t)(1u << 6);
+    if (b & 0x04) col |= (uint16_t)(1u << 7);
+    if (b & 0x02) col |= (uint16_t)(1u << 8);
+    if (b & 0x01) col |= (uint16_t)(1u << 9);
+
+    return col;
+}
+
+static int write_single_card_cap(const char *path, const uint16_t cols[80])
+{
+    FILE *f = fopen(path, "w");
+    if (!f)
+        return -1;
+    fprintf(f, "Synthetic cap for capcat test\n");
+    fprintf(f, "Card n. 1\n");
+    for (int i = 0; i < 80; i++)
+        fprintf(f, "%04X%c", cols[i] & 0x1FFFu, (i == 79) ? '\n' : ' ');
+    fclose(f);
+    return 0;
+}
 
 UTEST(cap, parse_funktional)
 {
@@ -29,3 +62,54 @@ UTEST(cap, missing_file)
     struct cap_deck *d = cap_load("DUMP1/does-not-exist.cap");
     ASSERT_TRUE(d == NULL);
 }
+
+UTEST(cap, capcat_appends_overlay_cards)
+{
+    static const char base_path[] = "/tmp/gemu_capcat_base.cap";
+    static const char overlay_path[] = "/tmp/gemu_capcat_overlay.bin";
+    static const char out_path[] = "/tmp/gemu_capcat_out.cap";
+    static const char tool_path[] = "tools/capcat";
+    static const uint8_t prefix[8] = { 0x00, 0x04, 0x40, 0x00, 0x20, 0x40, 0x40, 0x42 };
+    uint16_t cols[80] = {0};
+    uint8_t image[65536];
+    unsigned lo = 0, hi = 0;
+    char cmd[512];
+    FILE *probe;
+
+    probe = fopen(tool_path, "r");
+    if (!probe) {
+        printf("  [SKIP] %s not built\n", tool_path);
+        return;
+    }
+    fclose(probe);
+
+    for (int i = 0; i < 8; i++)
+        cols[i] = test_colbin_encode_byte(prefix[i]);
+    cols[8] = test_colbin_encode_byte(0x01);  /* 2 payload bytes */
+    cols[9] = test_colbin_encode_byte(0x01);
+    cols[10] = test_colbin_encode_byte(0x00);
+    cols[11] = test_colbin_encode_byte(0xAA);
+    cols[12] = test_colbin_encode_byte(0x55);
+    ASSERT_EQ(write_single_card_cap(base_path, cols), 0);
+
+    {
+        uint8_t ov[3] = { 0x11, 0x22, 0x33 };
+        FILE *f = fopen(overlay_path, "wb");
+        ASSERT_TRUE(f != NULL);
+        ASSERT_EQ(binimage_write(f, 0x0200, 0x0200, ov, (uint16_t)sizeof(ov)), BINIMAGE_OK);
+        fclose(f);
+    }
+
+    snprintf(cmd, sizeof(cmd), "%s -o %s %s %s >/tmp/gemu_capcat_cmd.log 2>&1",
+             tool_path, out_path, base_path, overlay_path);
+    ASSERT_EQ(system(cmd), 0);
+
+    memset(image, 0, sizeof(image));
+    ASSERT_GT(cap_load_scattered(out_path, TC_COLBIN, image, &lo, &hi), 0);
+    ASSERT_EQ(lo, 0x0100u);
+    ASSERT_EQ(image[0x0100], 0xAA);
+    ASSERT_EQ(image[0x0101], 0x55);
+    ASSERT_EQ(image[0x0200], 0x11);
+    ASSERT_EQ(image[0x0201], 0x22);
+    ASSERT_EQ(image[0x0202], 0x33);
+}