kimdos 0.2.0__py3-none-any.whl

kimdos/__init__.py

@@ -0,0 +1 @@
+"""KIM-1 DOS test oracle: serial bus drive model and KIM-1 machine simulator."""

kimdos/bench.py

@@ -0,0 +1,97 @@
+"""Throughput and JiffyDOS timing margins of the 6502 library, simulated."""
+
+from tqdm import tqdm
+
+from .iec import JIFFY_AVR_EARLY, JIFFY_AVR_LATE, JIFFY_LPC, Drive
+from .sim import RETURN, Kim
+
+TIMINGS = {"lpc": JIFFY_LPC, "avr-early": JIFFY_AVR_EARLY, "avr-late": JIFFY_AVR_LATE}
+BUF = 0x4000
+NAME = 0x3F00
+SIZES = (1016, 2032)
+OPS = ("read", "write", "load")
+
+
+def _kim(image, files, **kw):
+    kim = Kim(image.binary, image.org, drives=Drive(files=files, **kw))
+    return kim, kim.drive
+
+
+def _call(kim, image, name, **kw):
+    r = kim.call(image[name], max_cycles=100_000_000, **kw)
+    assert r.reason == RETURN, name
+    return r
+
+
+def _setnam(kim, image, name):
+    kim.write(NAME, name)
+    _call(kim, image, "dos_setnam", a=len(name), x=NAME & 0xFF, y=NAME >> 8)
+
+
+def _range(kim, image, beg, end):
+    kim.write(image["dos_beg"], beg.to_bytes(2, "little") + end.to_bytes(2, "little"))
+
+
+def op_cycles(image, op, n, **kw):
+    """CPU cycles for one library operation moving n bytes: dos_read of an
+    open file, dos_write to one, or a whole dos_load (open, transfer, close)."""
+    data = bytes(i * 7 & 0xFF for i in range(n))
+    kim, drive = _kim(image, {b"F": b"\x00\x40" + data}, **kw)
+    if op == "load":
+        _setnam(kim, image, b"F")
+        c = _call(kim, image, "dos_load").cycles
+        assert kim.read(BUF, n) == data
+    else:
+        _setnam(kim, image, b"F" if op == "read" else b"G,S,W")
+        _call(kim, image, "dos_open", a=2)
+        if op == "write":
+            kim.write(BUF, data)
+        _range(kim, image, BUF, BUF + n + 2 if op == "read" else BUF + n)
+        c = _call(kim, image, "dos_" + op, a=2).cycles
+        _call(kim, image, "dos_close", a=2)
+        got = kim.read(BUF, n + 2)[2:] if op == "read" else drive.files[b"G"]
+        assert got == data, op
+    assert not drive.errors, drive.errors
+    return c
+
+
+def per_byte(image, op, **kw):
+    """Cycles per byte of op, fixed costs cancelled over two sizes."""
+    lo, hi = (op_cycles(image, op, n, **kw) for n in SIZES)
+    return (hi - lo) / (SIZES[1] - SIZES[0])
+
+
+def margin_ok(image, margin, **kw):
+    """Whether a load, a save and a status read stay margin us clear of
+    every device edge and sample point."""
+    data = bytes(range(256)) * 2
+    kim, drive = _kim(image, {b"F": b"\x00\x40" + data}, margin=margin, **kw)
+    _setnam(kim, image, b"F")
+    _call(kim, image, "dos_load")
+    _setnam(kim, image, b"G")
+    _range(kim, image, BUF, BUF + len(data))
+    _call(kim, image, "dos_save")
+    _call(kim, image, "dos_status")
+    return not drive.errors and drive.files.get(b"G", b"")[2:] == data
+
+
+def max_margin(image, step=0.25, **kw):
+    """Largest margin, in steps of step us, at which margin_ok holds."""
+    m = 0
+    while margin_ok(image, m + step, **kw):
+        m += step
+    return m
+
+
+def report(image, latencies=(0, 1, 2)):
+    """Throughput rows (op, standard, Jiffy) and margin rows (timing,
+    latency, margin), with progress bars."""
+    rows = []
+    for op in tqdm(OPS, desc="throughput"):
+        rows.append((op, per_byte(image, op, jiffy=None), per_byte(image, op)))
+    cases = [(t, lat) for t in TIMINGS for lat in latencies]
+    margins = [
+        (t, lat, max_margin(image, jiffy=TIMINGS[t], latency=lat))
+        for t, lat in tqdm(cases, desc="margins")
+    ]
+    return rows, margins

kimdos/board.py

@@ -0,0 +1,58 @@
+"""Drive the KIMDOS shell on a real board over its TTY line."""
+
+import re
+import sys
+import time
+
+from kimtape import Monitor, Port, Tape
+
+PROMPT = b"\r\n>"
+
+
+class Board:
+    """A KIM-1 running the KIMDOS shell, reached through the monitor."""
+
+    def __init__(self, dev, baud=1200, trace=False):
+        self.port = Port(dev, baud, trace=trace)
+        self.mon = Monitor(self.port, log=sys.stderr)
+
+    def install(self, ptp, org):
+        """Load a tape image with the monitor, verify it and start the shell."""
+        self.mon.sync()
+        tape = Tape("kimdos", ptp)
+        for _ in range(3):
+            self.mon.load(tape)
+            if self.mon.verify(tape):
+                break
+        else:
+            raise RuntimeError("image did not verify")
+        self.start(org)
+
+    def start(self, org):
+        """Run the shell at org and wait for its prompt."""
+        self.mon.sync()
+        self.port.take()
+        self.mon.go(org)
+        self.wait_prompt(10)
+
+    def wait_prompt(self, timeout):
+        """Collect output up to the next shell prompt."""
+        deadline = time.time() + timeout
+        while PROMPT not in self.port.rx and time.time() < deadline:
+            self.port.poll(0.1)
+        if PROMPT not in self.port.rx:
+            raise TimeoutError(Port.show(bytes(self.port.rx)))
+        out = bytes(self.port.rx)
+        self.port.take()
+        return out[: out.index(PROMPT)]
+
+    def command(self, line, timeout=60):
+        """Type a shell command and return its output without the echo."""
+        self.port.take()
+        self.port.write(line.encode() + b"\r")
+        out = self.wait_prompt(timeout).decode("ascii", "replace")
+        return re.sub(r"^.*?\r\n", "", out, count=1, flags=re.S).strip("\r\n")
+
+    def close(self):
+        """Release the serial line."""
+        self.port.close()

kimdos/build.py

@@ -0,0 +1,75 @@
+"""Build the 6502 image with cc65 and read back its symbols."""
+
+import fcntl
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+IMAGES = Path(__file__).resolve().parent / "images"
+
+
+@dataclass(frozen=True)
+class Image:
+    """A linked KIMDOS image: binary, tape, load address and symbol table."""
+
+    binary: bytes
+    ptp: Path
+    labels: dict
+    org: int
+
+    @classmethod
+    def load(cls, stem):
+        """Read the .bin, .ptp and .lbl files an ld65 build left at stem."""
+        stem = Path(stem)
+        labels = read_labels(stem.with_suffix(".lbl"))
+        return cls(
+            stem.with_suffix(".bin").read_bytes(),
+            stem.with_suffix(".ptp"),
+            labels,
+            labels["__RAM_START__"],
+        )
+
+    def __getitem__(self, name):
+        return self.labels[name]
+
+
+def read_labels(path):
+    """Parse an ld65 -Ln (VICE) label file into {name: address}."""
+    labels = {}
+    for line in Path(path).read_text(encoding="ascii").splitlines():
+        _, addr, name = line.split()
+        labels[name.lstrip(".")] = int(addr, 16)
+    return labels
+
+
+def _make(build_dir, *args):
+    build_dir.mkdir(parents=True, exist_ok=True)
+    with open(build_dir / ".lock", "w", encoding="ascii") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        subprocess.run(
+            ["make", "-s", "-C", str(ROOT), "BUILD=%s" % build_dir, *args],
+            check=True,
+            stdout=subprocess.DEVNULL,
+        )
+
+
+def build_c():
+    """Build the C library and its test program (llvm-mos in docker) under the
+    repository's build directory, which docker can mount; return kdtest.bin."""
+    build_dir = ROOT / "build"
+    _make(build_dir, "clib")
+    return (build_dir / "c" / "kdtest.bin").read_bytes()
+
+
+def build(org=0x2000, build_dir=None):
+    """Run make for an image at org and return it."""
+    build_dir = Path(build_dir or ROOT / "build")
+    _make(build_dir, "ORG=%04X" % org)
+    return Image.load(build_dir / ("kimdos-%04X" % org))
+
+
+def packaged(org=0x2000):
+    """The prebuilt shell image at org shipped in the wheel ($0400, $2000,
+    $C000; `make images` in a checkout)."""
+    return Image.load(IMAGES / ("kimdos-%04X" % org))

kimdos/c/Dockerfile

@@ -0,0 +1 @@
+FROM ghcr.io/anarkiwi/docker-mos-llvm-sdk:23.3.0

kimdos/c/include/kimdos.h

@@ -0,0 +1,86 @@
+/* KIMDOS: Commodore serial bus disk access for the KIM-1, llvm-mos C API. */
+#ifndef KIMDOS_H
+#define KIMDOS_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* assembly routines: they never call back into C */
+#define KD_ASM __attribute__((leaf))
+
+#define ST_WTO 0x01 /* a listener did not acknowledge a byte */
+#define ST_RTO 0x02 /* the talker sent nothing */
+#define ST_VER 0x10 /* verify mismatch */
+#define ST_EOI 0x40 /* the last byte read was the end of the data */
+#define ST_DNP 0x80 /* no device answered */
+
+extern uint8_t iec_st; /* status bits collected by the bus primitives */
+/* bit 0: offer JiffyDOS (default 1); 0 forces the standard protocol.
+ * bit 7: set by iec_listen/iec_talk when the device answered */
+extern uint8_t iec_jiffy;
+extern uint8_t kd_dev; /* device number, default 8 */
+
+/* bus primitives (asm, same semantics as asm/lib/iec.s) */
+KD_ASM void iec_listen(uint8_t dev);
+KD_ASM void iec_second(uint8_t sa);
+KD_ASM void iec_talk(uint8_t dev);
+KD_ASM void iec_tksa(uint8_t sa);
+KD_ASM void iec_ciout(uint8_t b);
+KD_ASM uint8_t iec_acptr(void);
+KD_ASM void iec_unlsn(void);
+KD_ASM void iec_untlk(void);
+/* after TALK and secondary 0x61 to a device in iec_jiffy bit 7: the rest of
+ * the file in JiffyDOS LOAD mode to addr up; returns one past the end */
+KD_ASM uint16_t iec_jload(uint16_t addr);
+
+/* DOS layer: functions returning uint8_t return 0 on success, else nonzero
+ * (iec_st bits or a DOS error code as documented) */
+uint8_t kd_open(uint8_t ch, const void *name, uint8_t len);
+void kd_close(uint8_t ch);
+uint8_t kd_chkin(uint8_t ch);  /* TALK ch */
+uint8_t kd_chkout(uint8_t ch); /* LISTEN ch */
+int16_t kd_getb(void); /* next byte, -1 once past the end (EOI seen or RTO) */
+/* TALK, read up to n bytes or to EOI, UNTALK; returns count; can be called
+ * again to continue */
+uint16_t kd_read(uint8_t ch, void *buf, uint16_t n);
+/* LISTEN, write, UNLISTEN; returns count */
+uint16_t kd_write(uint8_t ch, const void *buf, uint16_t n);
+/* command on channel 15 (binary safe) */
+uint8_t kd_cmd(const void *cmd, uint8_t len);
+/* reads channel 15 into buf (48 bytes, zero terminated, CR stripped); returns
+ * the numeric code, 0xFF if no device */
+uint8_t kd_status(char *buf);
+/* sd2iec "P" + chr(0x60|ch) + 4-byte little-endian offset, then kd_status;
+ * returns its code */
+uint8_t kd_seek(uint8_t ch, uint32_t offset);
+
+/* name raw PETSCII, zero terminated, quotes stripped; type e.g. "PRG" */
+typedef struct {
+  char name[17];
+  char type[4];
+  uint16_t blocks;
+} kd_dirent;
+/* opens "$"+pattern on channel 0 and skips the load address and header line;
+ * 0 ok */
+uint8_t kd_dir_open(const void *pattern, uint8_t len);
+/* 1 with the next file entry, 0 at the end (BLOCKS FREE line or end) */
+uint8_t kd_dir_next(kd_dirent *e);
+void kd_dir_close(void);
+/* addr NULL: to the file's own address; *end = one past last byte; 0 ok */
+uint8_t kd_load(const void *name, uint8_t len, uint8_t *addr, uint16_t *end);
+uint8_t kd_save(const void *name, uint8_t len, const uint8_t *beg,
+                const uint8_t *end);
+
+/* console via the KIM-1 monitor TTY */
+KD_ASM void kd_putc(uint8_t c); /* OUTCH */
+KD_ASM uint8_t kd_getc(void);   /* GETCH, 7-bit */
+KD_ASM void kd_puts(const char *s);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

kimdos/c/kim1/crt.s

@@ -0,0 +1,8 @@
+; KIM-1 llvm-mos start-up and exit: decimal mode off, exit to the monitor.
+
+        .section .init.050,"ax",@progbits
+        cld
+
+        .section .text._Exit,"ax",@progbits
+        .globl _Exit
+_Exit:  jmp 0x1C4F

kimdos/c/kim1/link.ld

@@ -0,0 +1,25 @@
+/* KIM-1 llvm-mos platform: a RAM image at $2000, the monitor's zero page
+ * ($EF-$FF) left alone, a 1K soft stack after the image. Programs may use
+ * __kim_end up to $FEFF as free RAM. */
+
+__rc0 = 0x00;
+INCLUDE imag-regs.ld
+ASSERT(__rc31 == 0x1f, "Inconsistent zero page map.")
+
+MEMORY {
+  zp : ORIGIN = __rc31 + 1, LENGTH = 0xEF - (__rc31 + 1)
+  ram (rw) : ORIGIN = 0x2000, LENGTH = 0xDF00
+}
+
+REGION_ALIAS("c_readonly", ram)
+REGION_ALIAS("c_writeable", ram)
+
+SECTIONS { INCLUDE c.ld }
+
+__stack = ALIGN(__heap_start + 0x400, 0x100);
+__kim_end = __stack;
+ASSERT(__kim_end <= 0xFF00, "Image and stack do not fit below $FF00.")
+
+INPUT(-lexit-custom -linit-stack -lzero-bss)
+
+OUTPUT_FORMAT { TRIM(ram) }

kimdos/c/src/con.s

@@ -0,0 +1,36 @@
+; Console over the KIM-1 monitor's TTY routines.  OUTCH and GETCH clobber
+; A, X, Y and the monitor's zero page ($EF-$FF), none of which the llvm-mos
+; calling convention asks a callee to preserve.
+
+OUTCH   = 0x1EA0
+GETCH   = 0x1E5A
+
+        .globl kd_putc, kd_getc, kd_puts
+
+        .section .text.kd_putc,"ax",@progbits
+kd_putc:
+        jmp OUTCH
+
+        .section .text.kd_getc,"ax",@progbits
+kd_getc:
+        jsr GETCH
+        and #0x7F
+        rts
+
+; String pointer in __rc2/__rc3, advanced past 256-byte pages as it goes.
+        .section .text.kd_puts,"ax",@progbits
+kd_puts:
+        ldy #0
+1:      lda (__rc2),y
+        beq 2f
+        sty savy
+        jsr OUTCH
+        ldy savy
+        iny
+        bne 1b
+        inc __rc3
+        bne 1b
+2:      rts
+
+        .section .bss.kd_puts,"aw",@nobits
+savy:   .zero 1

kimdos/c/src/dir.c

@@ -0,0 +1,43 @@
+#include "kdint.h"
+
+/* Next listing byte; 0 past the end, which also ends a line or the listing. */
+__attribute__((noinline)) static uint8_t next(void) {
+  int16_t c = kd_getb();
+  return c < 0 ? 0 : c;
+}
+
+uint8_t kd_dir_open(const void *pattern, uint8_t len) {
+  if (kd_openp(0, '$', pattern, len) & ST_DNP || kd_chkin(0) & ST_DNP)
+    return iec_st;
+  for (uint8_t n = 6; n; --n)
+    next();
+  while (next())
+    ;
+  iec_untlk();
+  return iec_st & ~ST_EOI;
+}
+
+uint8_t kd_dir_next(kd_dirent *e) {
+  uint8_t q = 0, n = 0, t = 0, c;
+  if (kd_chkin(0) & ST_DNP)
+    return 0;
+  if (next() | next()) {
+    c = next();
+    e->blocks = c | next() << 8;
+    while ((c = next())) {
+      if (c == '"')
+        ++q;
+      else if (q == 1) {
+        if (n < 16)
+          e->name[n++] = c;
+      } else if (q == 2 && c != ' ' && c != '*' && t < 3)
+        e->type[t++] = c;
+    }
+    e->name[n] = 0;
+    e->type[t] = 0;
+  }
+  iec_untlk();
+  return q > 1;
+}
+
+void kd_dir_close(void) { kd_close(0); }

kimdos/c/src/dos.c

@@ -0,0 +1,150 @@
+#include "kdint.h"
+
+#define ERRMAX 47
+
+uint8_t kd_dev = 8;
+
+static uint8_t listen_sa(uint8_t sa) {
+  iec_st = 0;
+  iec_listen(kd_dev);
+  if (!(iec_st & ST_DNP))
+    iec_second(sa);
+  return iec_st;
+}
+
+static void send(const uint8_t *p, uint8_t n) {
+  while (n--)
+    iec_ciout(*p++);
+}
+
+static const uint8_t *put(const uint8_t *p, const uint8_t *end) {
+  while (!iec_st && p < end)
+    iec_ciout(*p++);
+  iec_unlsn();
+  return p;
+}
+
+uint8_t kd_openp(uint8_t ch, uint8_t pre, const uint8_t *name, uint8_t len) {
+  if (listen_sa(0xF0 | ch) & ST_DNP)
+    return iec_st;
+  if (pre)
+    iec_ciout(pre);
+  send(name, len);
+  iec_unlsn();
+  return iec_st;
+}
+
+uint8_t kd_open(uint8_t ch, const void *name, uint8_t len) {
+  return kd_openp(ch, 0, name, len);
+}
+
+void kd_close(uint8_t ch) {
+  listen_sa(0xE0 | ch);
+  iec_unlsn();
+}
+
+uint8_t kd_chkout(uint8_t ch) { return listen_sa(0x60 | ch); }
+
+__attribute__((noinline)) uint8_t kd_chkin(uint8_t ch) {
+  iec_st = 0;
+  iec_talk(kd_dev);
+  iec_tksa(0x60 | ch);
+  return iec_st;
+}
+
+__attribute__((noinline)) int16_t kd_getb(void) {
+  if (iec_st & (ST_EOI | ST_RTO))
+    return -1;
+  uint8_t b = iec_acptr();
+  return iec_st & ST_RTO ? -1 : b;
+}
+
+uint16_t kd_read(uint8_t ch, void *buf, uint16_t n) {
+  uint8_t *p = buf;
+  uint16_t i = 0;
+  if (!(kd_chkin(ch) & ST_DNP)) {
+    for (int16_t c; i != n && (c = kd_getb()) >= 0;)
+      p[i++] = c;
+    iec_untlk();
+  }
+  return i;
+}
+
+uint16_t kd_write(uint8_t ch, const void *buf, uint16_t n) {
+  const uint8_t *p = buf;
+  if (kd_chkout(ch) & ST_DNP)
+    return 0;
+  return put(p, p + n) - p;
+}
+
+uint8_t kd_cmd(const void *cmd, uint8_t len) {
+  if (!(kd_chkout(15) & ST_DNP)) {
+    send(cmd, len);
+    iec_unlsn();
+  }
+  return iec_st;
+}
+
+uint8_t kd_status(char *buf) {
+  uint8_t i = 0;
+  int16_t c;
+  buf[0] = buf[1] = 0;
+  if (kd_chkin(15) & ST_DNP)
+    return 0xFF;
+  while ((c = kd_getb()) >= 0)
+    if (c != '\r' && i != ERRMAX)
+      buf[i++] = c;
+  buf[i] = 0;
+  iec_untlk();
+  return (buf[0] & 15) * 10 + (buf[1] & 15);
+}
+
+uint8_t kd_seek(uint8_t ch, uint32_t offset) {
+  uint8_t cmd[6] = {'P',         0x60 | ch,    offset,
+                    offset >> 8, offset >> 16, offset >> 24};
+  char st[ERRMAX + 1];
+  kd_cmd(cmd, sizeof cmd);
+  return kd_status(st);
+}
+
+uint8_t kd_load(const void *name, uint8_t len, uint8_t *addr, uint16_t *end) {
+  uint8_t st;
+  if (!(kd_open(0, name, len) & ST_DNP) && !(kd_chkin(0) & ST_DNP)) {
+    uint8_t lo = kd_getb();
+    uint16_t at = lo | (uint8_t)kd_getb() << 8;
+    if (!(iec_st & ST_RTO)) {
+      uint8_t *p = addr ? addr : (uint8_t *)at;
+      if (iec_jiffy & 0x80 && !iec_st && *(const uint8_t *)name != '$') {
+        iec_untlk();
+        iec_talk(kd_dev);
+        iec_tksa(0x61);
+        if (!iec_st)
+          p = (uint8_t *)iec_jload((uint16_t)p);
+      } else {
+        for (int16_t c; (c = kd_getb()) >= 0;)
+          *p++ = c;
+      }
+      if (end)
+        *end = (uint16_t)p;
+    }
+    iec_untlk();
+  }
+  st = iec_st;
+  kd_close(0);
+  iec_st = st;
+  return st & ~ST_EOI;
+}
+
+uint8_t kd_save(const void *name, uint8_t len, const uint8_t *beg,
+                const uint8_t *end) {
+  uint8_t st;
+  if (kd_open(1, name, len) & ST_DNP || kd_chkout(1) & ST_DNP)
+    return iec_st;
+  iec_ciout((uint16_t)beg);
+  iec_ciout((uint16_t)beg >> 8);
+  put(beg, end);
+  st = iec_st;
+  kd_close(1);
+  iec_st = st;
+  return st;
+}