toy 0.8.0

data/tinynn/tinynn_backend_cuda.c

@@ -0,0 +1,99 @@
+/* tinynn_backend_cuda.c — CUDA backend init + BYO-pointer hook.
+ *
+ * Lives in its own .o so libtinynn_ggml_cuda.a contains only the
+ * symbols that bridge to ggml-cuda — no overlap with libtinynn_ggml.a.
+ * The common-side tnn_engine_get / tnn_session_attach_weight_mmap (in
+ * tinynn_ggml.c) call these through weak references, so CPU-only
+ * programs link cleanly without this archive and CUDA programs pull
+ * the needed symbols.
+ *
+ * Compiled only into libtinynn_ggml_cuda.a (rule in Makefile).
+ */
+#include "ggml.h"
+#include "ggml-backend.h"
+#include "ggml-cuda.h"
+#include <cuda_runtime.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+ggml_backend_t tnn_backend_cuda_init_internal(void)
+{
+    return ggml_backend_cuda_init(0);
+}
+
+/* GH#3 — multi-GPU mode 1. Strong override of the weak stub in
+ * tinynn_ggml.c. CPU-only builds keep the weak stub (returns NULL);
+ * CUDA programs link the archive and get device-parametric init.
+ *
+ * Device validation lives upstream in tnn_engine_get_on; we just
+ * pass through. Returns NULL if the device index isn't a valid
+ * CUDA device (ggml_backend_cuda_init will assert/abort on
+ * out-of-range, so callers should check device_count first). */
+ggml_backend_t tnn_backend_cuda_init_internal_on(int device)
+{
+    return ggml_backend_cuda_init(device);
+}
+
+/* GH#3 — bind ggml_backend_cuda_get_device_count for runtime
+ * enumeration. Weak stub in tinynn_ggml.c returns 0; this strong
+ * override returns the real GPU count when the CUDA archive is
+ * linked. */
+int tnn_cuda_get_device_count_internal(void)
+{
+    return ggml_backend_cuda_get_device_count();
+}
+
+/* Phase 2 BYO-pointer on CUDA: wraps an mmap'd region in a
+ * ggml_backend_cuda_buffer_from_ptr (vendored patch — see
+ * docs/cuda-byo-pointer-design.md). Strong override of the weak
+ * stub in tinynn_ggml.c. */
+ggml_backend_buffer_t tnn_cuda_buffer_from_ptr_internal(void *host_ptr,
+                                                         size_t size,
+                                                         int device)
+{
+    return ggml_backend_cuda_buffer_from_ptr(host_ptr, size, device);
+}
+
+/* Forcing-reference symbol. Pass `-Wl,-u,tnn_cuda_force_link` to the
+ * linker to force this object (and transitively libggml-cuda.a) to
+ * be pulled in from libtinynn_ggml_cuda.a. Without this, the weak
+ * tnn_backend_cuda_init_internal fallback in tinynn_ggml.c satisfies
+ * the symbol table and the strong overrides here never get linked —
+ * resulting in a "CUDA" binary that silently runs on CPU. */
+void tnn_cuda_force_link(void)
+{
+    /* Reference ggml_backend_cuda_init so the linker also pulls in
+     * libggml-cuda.a. */
+    volatile void *p = (void *)&ggml_backend_cuda_init;
+    (void)p;
+}
+
+/* Strong override of the weak tnn_pinned_alloc / tnn_pinned_free in
+ * tinynn_ggml.c. cudaHostAlloc allocates pinned (page-locked) host
+ * memory; cudaMemcpy from a pinned source bypasses the driver's
+ * internal staging copy and can DMA directly. For toy's per-step
+ * label-upload (heavy bench: t_labels = 155 MB at vocab=151936×T=256)
+ * this halves the wall-clock cost of the transfer. */
+void *tnn_pinned_alloc(size_t bytes)
+{
+    void *p = NULL;
+    cudaError_t err = cudaHostAlloc(&p, bytes, cudaHostAllocDefault);
+    if (err != cudaSuccess) {
+        fprintf(stderr, "[tnn-cuda] cudaHostAlloc(%zu) failed: %s — "
+                        "falling back to pageable\n",
+                        bytes, cudaGetErrorString(err));
+        return calloc(1, bytes);
+    }
+    return p;
+}
+
+void tnn_pinned_free(void *p)
+{
+    if (!p) return;
+    cudaError_t err = cudaFreeHost(p);
+    if (err != cudaSuccess) {
+        fprintf(stderr, "[tnn-cuda] cudaFreeHost failed: %s\n",
+                cudaGetErrorString(err));
+        free(p);  /* try pageable free as fallback */
+    }
+}

data/tinynn/tinynn_backend_metal.m

@@ -0,0 +1,75 @@
+/* tinynn_backend_metal.m — Metal backend init.
+ *
+ * Lives in its own .o so libtinynn_ggml_metal.a contains only the
+ * symbols that bridge to ggml-metal — no overlap with libtinynn_ggml.a.
+ * The common-side tnn_engine_get (in tinynn_ggml.c) calls
+ * tnn_backend_metal_init_internal through a weak reference, so CPU-only
+ * programs link cleanly without this archive and Metal programs pull
+ * the needed symbols.
+ *
+ * Compiled only into libtinynn_ggml_metal.a (rule in Makefile). The
+ * file is .m (Objective-C) because the Metal frameworks are an ObjC
+ * API; ggml-metal itself does the heavy lifting and the only thing
+ * we need at this layer is the C-callable init plus the cleanup
+ * trampoline.
+ *
+ * No BYO-pointer hook: ggml-metal doesn't expose a public
+ * buffer_from_ptr API. mmap'd weights through the BYO path would
+ * fall through to ggml_backend_cpu_buffer_from_ptr (the existing
+ * else branch in tnn_session_attach_weight_mmap) and the ggml-metal
+ * scheduler crashes when fed CPU-resident weight tensors as kernel
+ * inputs. lib/transformer_lm_metal.rb sidesteps this by taking the
+ * copy-load path (realize_for) for the Metal backend.
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+#include "ggml.h"
+#include "ggml-backend.h"
+#include "ggml-metal.h"
+
+ggml_backend_t tnn_backend_metal_init_internal(void)
+{
+    return ggml_backend_metal_init();
+}
+
+/* ggml-metal asserts on a non-empty residency set at process exit, via
+ * the destructor of a static std::vector<unique_ptr<ggml_metal_device>>
+ * registered with __cxa_atexit during ggml-metal init. The cached
+ * engine pattern keeps the backend alive for the program's lifetime;
+ * tearing it down via tnn_shutdown_engines does NOT drain the device's
+ * residency set (the dispatch queue keeping buffers alive runs on a
+ * separate thread with no public wait API).
+ *
+ * Rather than fight the lifecycle, expose `_exit` so single-shot
+ * inference programs can skip cxa_finalize entirely — the device
+ * vector's destructor never runs, the assert never fires, the OS
+ * reclaims everything cleanly. Long-running processes (servers)
+ * should think harder; none of our Metal callers fit that profile
+ * today.
+ *
+ * Callers: replace `exit(rc)` with `TinyNNMetal.tnn_force_exit(rc)`
+ * at end-of-main on Metal builds. */
+void tnn_force_exit(int status)
+{
+    /* _exit skips cxa_finalize, which means libc never flushes stdio
+     * buffers — Ruby/spinel-side puts that landed in the userspace
+     * FILE buffer would be lost. Flush every open stream first so the
+     * user sees the output they expect. */
+    fflush(NULL);
+    _exit(status);
+}
+
+/* Forcing-reference symbol. Pass `-Wl,-u,_tnn_metal_force_link` to the
+ * linker (note the leading underscore for the macOS ABI) so this
+ * object — and transitively libggml-metal.a — gets pulled in from
+ * libtinynn_ggml_metal.a. Without this, the weak
+ * tnn_backend_metal_init_internal fallback in tinynn_ggml.c satisfies
+ * the symbol table and the strong override here never gets linked,
+ * silently downgrading a "Metal" binary to CPU. */
+void tnn_metal_force_link(void)
+{
+    volatile void *p = (void *)&ggml_backend_metal_init;
+    (void)p;
+}

data/tinynn/tinynn_events.c

@@ -0,0 +1,122 @@
+/* See tinynn_events.h. */
+
+#include "tinynn_events.h"
+
+#include <stdio.h>
+#include <string.h>
+#include <time.h>
+#include <unistd.h>
+#include <sys/utsname.h>
+
+static struct {
+    FILE   *out;
+    double  epoch_sec;   /* CLOCK_MONOTONIC at open time */
+} g_evt = { NULL, 0.0 };
+
+static double monotonic_seconds(void) {
+    struct timespec ts;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    return (double)ts.tv_sec + (double)ts.tv_nsec / 1.0e9;
+}
+
+static int events_open_mode(const char *path, const char *mode) {
+    if (g_evt.out) return -1;
+    if (!path)     return -2;
+    g_evt.out = fopen(path, mode);
+    if (!g_evt.out) return -3;
+    /* Line-buffered so consumers tailing the file see new events
+     * promptly — no waiting on a 4 KB stdio block boundary. */
+    setvbuf(g_evt.out, NULL, _IOLBF, 0);
+    g_evt.epoch_sec = monotonic_seconds();
+    return 0;
+}
+
+int tnn_events_open(const char *path) {
+    return events_open_mode(path, "a");
+}
+
+int tnn_events_open_trunc(const char *path) {
+    return events_open_mode(path, "w");
+}
+
+void tnn_events_emit(const char *json_obj) {
+    if (!g_evt.out || !json_obj) return;
+    fputs(json_obj, g_evt.out);
+    fputc('\n', g_evt.out);
+}
+
+void tnn_events_close(void) {
+    if (!g_evt.out) return;
+    fflush(g_evt.out);
+    fclose(g_evt.out);
+    g_evt.out = NULL;
+    g_evt.epoch_sec = 0.0;
+}
+
+int tnn_events_active(void) {
+    return g_evt.out != NULL;
+}
+
+double tnn_events_now_seconds(void) {
+    if (!g_evt.out) return 0.0;
+    return monotonic_seconds() - g_evt.epoch_sec;
+}
+
+/* Provenance helpers for run_start / run_end fields the v1 schema
+ * documents (tao#run-start-provenance). All return pointers to
+ * static thread-unsafe buffers (callers must copy before reusing). */
+
+/* ISO-8601 UTC, second precision: "2026-05-25T17:42:13Z". */
+const char *tnn_events_iso8601_now(void) {
+    static char buf[32];
+    time_t now = time(NULL);
+    struct tm tm_buf;
+    gmtime_r(&now, &tm_buf);
+    strftime(buf, sizeof(buf), "%Y-%m-%dT%H:%M:%SZ", &tm_buf);
+    return buf;
+}
+
+const char *tnn_provenance_host_name(void) {
+    static char buf[256] = {0};
+    if (buf[0] == '\0') {
+        if (gethostname(buf, sizeof(buf) - 1) != 0) {
+            strncpy(buf, "unknown", sizeof(buf) - 1);
+        }
+    }
+    return buf;
+}
+
+const char *tnn_provenance_host_os(void) {
+    static char buf[64] = {0};
+    if (buf[0] == '\0') {
+        struct utsname u;
+        if (uname(&u) == 0) {
+            /* Lowercase ("Linux" -> "linux") to match the schema's
+             * `"os": "linux"` example. */
+            size_t i = 0;
+            while (u.sysname[i] != '\0' && i < sizeof(buf) - 1) {
+                char c = u.sysname[i];
+                if (c >= 'A' && c <= 'Z') c = c + ('a' - 'A');
+                buf[i] = c;
+                i++;
+            }
+            buf[i] = '\0';
+        } else {
+            strncpy(buf, "unknown", sizeof(buf) - 1);
+        }
+    }
+    return buf;
+}
+
+const char *tnn_provenance_host_arch(void) {
+    static char buf[64] = {0};
+    if (buf[0] == '\0') {
+        struct utsname u;
+        if (uname(&u) == 0) {
+            strncpy(buf, u.machine, sizeof(buf) - 1);
+        } else {
+            strncpy(buf, "unknown", sizeof(buf) - 1);
+        }
+    }
+    return buf;
+}

data/tinynn/tinynn_events.h

@@ -0,0 +1,83 @@
+/* JSON Lines event-stream emitter.
+ *
+ * Sibling to tinynn_trace.h (Chrome Trace format for per-op timing).
+ * This primitive emits the run-level event stream documented in
+ * docs/events-schema.md — one JSON object per line, append-only,
+ * versioned `"schema": "toy/v1"`. The file is the contract between
+ * Toy and downstream consumers (live TUIs, post-run analyzers,
+ * W&B/MLflow adapters, the Tao project).
+ *
+ * Design choices:
+ *
+ * - Caller builds each event's JSON object (typically in Ruby via
+ *   string concatenation). We append a newline and a single fprintf.
+ *   Buffered fwrite under the hood; one fflush at close.
+ *
+ * - The OFF path (no file open) is a single load + compare in
+ *   tnn_events_emit and tnn_events_active — same shape as the trace
+ *   primitive. Cheap enough to leave instrumented in production.
+ *
+ * - tnn_events_now_seconds() returns time since open as a double,
+ *   matching the schema's `"t"` field. CLOCK_MONOTONIC under the
+ *   hood; immune to wall-clock skew.
+ *
+ * - One file per process. Multiple opens fail (returns -1). This
+ *   matches the one-run-one-file convention from the schema.
+ *
+ * - We do NOT validate the JSON we're handed. Callers are expected
+ *   to emit well-formed objects per the schema. A bad object turns
+ *   into a torn line that consumers will skip.
+ */
+
+#ifndef TINYNN_EVENTS_H
+#define TINYNN_EVENTS_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Open the JSONL file for append-only writes. Path may be relative
+ * or absolute. Parent directories must already exist (we don't
+ * mkdir — keep the primitive simple). Returns 0 on success, negative
+ * on failure (-1 already open, -2 null path, -3 fopen failed). */
+int     tnn_events_open(const char *path);
+
+/* Same as tnn_events_open but TRUNCATES an existing file ("w" vs
+ * "a"). The fresh-bundle opener for re-runnable run dirs
+ * (Toy::RunBundle, toy#73): re-running with the same run_id replaces
+ * the bundle instead of doubling it. Same return codes as open. */
+int     tnn_events_open_trunc(const char *path);
+
+/* Append a single JSON event followed by `\n`. The string MUST be a
+ * complete, well-formed JSON object — we do not validate. When the
+ * file isn't open, this is a single load + branch (no-op). */
+void    tnn_events_emit(const char *json_obj);
+
+/* Flush and close. Idempotent — closing an unopened stream is a
+ * no-op. After close, subsequent emits are no-ops until a new
+ * open. */
+void    tnn_events_close(void);
+
+/* Cheap predicate — callers can guard expensive JSON-building code
+ * (string concats, .to_s on floats, etc.) so the OFF path is
+ * truly zero-cost. */
+int     tnn_events_active(void);
+
+/* Seconds-since-open as a double (schema's `"t"` field). When the
+ * file isn't open, returns 0.0. Uses CLOCK_MONOTONIC; safe under
+ * clock skew. */
+double  tnn_events_now_seconds(void);
+
+/* Provenance helpers for the run_start / run_end fields the v1 schema
+ * documents (tao#run-start-provenance). All return pointers to static
+ * thread-unsafe buffers; copy or emit immediately. */
+const char *tnn_events_iso8601_now(void);   /* "2026-05-25T17:42:13Z" */
+const char *tnn_provenance_host_name(void); /* gethostname() */
+const char *tnn_provenance_host_os(void);   /* uname.sysname lowercased */
+const char *tnn_provenance_host_arch(void); /* uname.machine */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif