added hash

Author: Zaneham

CHANGELOG.txt

@@ -1,6 +1,66 @@
 CHANGELOG
 =========
 
+2026-05-14  Synthesis fingerprint (--hash)
+  - New --hash flag prints a 64-bit deterministic digest of
+    the synthesised netlist to stdout, formatted as
+    "hash: %016x", so that two runs of takahe on the same
+    input source produce byte-identical digests and any
+    divergence between runs surfaces as an immediate hash
+    mismatch rather than as silent non-determinism that only
+    becomes visible when somebody tries to reproduce a build
+    months later.
+  - The underlying algorithm is FNV-1a 64-bit, chosen because
+    it fits in twelve lines, has zero external dependencies,
+    and is more than sufficient for the question being asked,
+    which is "did these two synthesis runs produce the same
+    netlist" rather than "can an adversary forge a collision";
+    a future bump to SHA-256 is a drop-in replacement should
+    a stronger fingerprint ever become necessary.
+  - The canonical byte stream consumed by the hash covers
+    every net's width, radix, port role, and driver index,
+    followed by every cell's type, width, output net, input
+    arity, input net indices, and parameter value, walked in
+    array order with index 0 reserved as the pool sentinel as
+    is the convention everywhere else in the codebase.
+  - Net names and cell names are deliberately excluded from
+    the canonical form because a wire renamed from q to q_r
+    is the same hardware and the fingerprint should agree;
+    generation counters and other runtime bookkeeping are
+    likewise excluded for the same reason.
+  - Slots vacated by deletion passes (cells whose type has
+    been overwritten with the RT_CELL_COUNT sentinel) are
+    folded into the hash as a single zero byte so that
+    deletions remain distinct from rewrites and so that
+    reordering passes never accidentally collide.
+  - The canonical form carries a version byte (HS_VER, set to
+    1 in this release) which must be bumped any time the set
+    of fields included in the hash or the order in which they
+    are emitted changes, on the principle that saved digests
+    become meaningfully invalid the moment the form changes
+    and the version byte ensures the divergence shows up at
+    the very first byte rather than as a confusing mid-stream
+    collision much later.
+  - Smoke verification on tests/smoke.sv produces the digest
+    5e2f63ed79b19097 reproducibly across consecutive runs,
+    tests/bigger.sv produces 8c4d1dacdbf02ee0 reproducibly
+    both before and after optimisation since op_opt finds no
+    work on that particular design, and designs/voyager_fds.sv
+    correctly diverges from 40a6def1e6c5fc0e pre-optimisation
+    to fadd81c343371411 after the optimiser applies its 24
+    transformations, confirming that the hash both holds
+    steady when the netlist holds steady and changes when the
+    netlist changes.
+  - Implementation lives in src/emit/tk_hash.c at roughly 125
+    lines, uses the hs_ file prefix consistent with the rest
+    of the emit directory, exposes mp_hash as the public
+    entry point in include/takahe.h alongside mp_blif and
+    mp_yosys, and compiles cleanly under the full project
+    warning gauntlet of -Wall -Wextra -Werror -pedantic plus
+    twelve additional diagnostics.
+  - All 76 existing tests continue to pass with no regression
+    introduced by the new flag or its supporting code.
+
 2026-03-28  ABEL-HDL frontend (third language)
   - Lexer and parser for ABEL-HDL (Data I/O / Synario, 1995)
   - Definition file: 37 keywords, 36 operators (abel_tok.def)

Makefile

@@ -60,7 +60,8 @@ SRCS = src/main.c \
        src/map/tk_fpga.c \
        src/emit/tk_blif.c \
        src/emit/tk_yosys.c \
-       src/emit/tk_vlog.c
+       src/emit/tk_vlog.c \
+       src/emit/tk_hash.c
 
 OBJS = $(SRCS:.c=.o)
 TARGET = takahe

README.md

@@ -166,6 +166,7 @@ takahe [flags] <source.sv|.vhd>
   --parse         dump AST + RTL
   --opt           optimise (cprop + pattern match + DCE)
   --equiv         equivalence check (pre-opt vs post-opt)
+  --hash          print 64-bit fingerprint of synthesised netlist
   --blif <f>      emit BLIF netlist
   --yosys <f>     emit Yosys JSON netlist
   --lib <f>       Liberty .lib cell library

include/takahe.h

@@ -599,6 +599,7 @@ int          op_dce  (rt_mod_t *M);
 /* Technology mapping / export */
 int          mp_blif (const rt_mod_t *M, FILE *fp);
 int          mp_yosys(const rt_mod_t *M, FILE *fp);
+uint64_t     mp_hash (const rt_mod_t *M);
 
 /* ---- Exact Timing Arithmetic ----
  * Femtoseconds and attofarads. Integer. No floats.

src/emit/tk_hash.c

@@ -0,0 +1,125 @@
+/* Copyright (c) 2026 Zane Hambly
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/*
+ * tk_hash.c -- Synthesis fingerprint for Takahe RTL
+ *
+ * Hash a netlist deterministically. Two runs on the same
+ * input produce the same digest. When they don't, something
+ * has crept in that you didn't intend: a drifted pass
+ * iteration order, an uninitialised byte, a clock cycle
+ * the gremlins won at darts.
+ *
+ * FNV-1a, 64 bits. Not a cryptographic hash. It won't
+ * survive an adversary but it will catch the day your
+ * pipeline turned non-deterministic, which is the one
+ * thing anyone actually wants to know about a synthesis
+ * tool. IBM used CRCs to detect tape errors for forty
+ * years before anyone needed SHA-anything. The principle
+ * holds.
+ *
+ * Canonical form: bump HS_VER any time you change what
+ * goes into the hash or in what order. Saved digests
+ * become meaningfully invalid the moment the form changes,
+ * like postage stamps after a regime change.
+ */
+
+#include "takahe.h"
+
+#define HS_VER     1u
+#define HS_OFFSET  0xcbf29ce484222325ULL
+#define HS_PRIME   0x100000001b3ULL
+
+/* ---- FNV-1a primitives ----
+ * Twelve lines, no dependencies, faster than fetching
+ * SHA-256 off the internet. A measurable engineering
+ * virtue. */
+
+static uint64_t
+hs_byte(uint64_t h, uint8_t b)
+{
+    h ^= (uint64_t)b;
+    h *= HS_PRIME;
+    return h;
+}
+
+static uint64_t
+hs_u32(uint64_t h, uint32_t v)
+{
+    h = hs_byte(h, (uint8_t)( v        & 0xffu));
+    h = hs_byte(h, (uint8_t)((v >>  8) & 0xffu));
+    h = hs_byte(h, (uint8_t)((v >> 16) & 0xffu));
+    h = hs_byte(h, (uint8_t)((v >> 24) & 0xffu));
+    return h;
+}
+
+static uint64_t
+hs_u64(uint64_t h, uint64_t v)
+{
+    h = hs_u32(h, (uint32_t)( v        & 0xffffffffULL));
+    h = hs_u32(h, (uint32_t)( v >> 32));
+    return h;
+}
+
+/* ---- Public: hash a module ----
+ * Walks nets then cells in array order. The walk order
+ * is part of the canonical form: anyone changing pool
+ * allocation strategy must bump HS_VER. Cell and net
+ * indices are deterministic per run on the same input,
+ * which is all a fingerprint needs to be useful.
+ *
+ * Names are NOT hashed. A wire renamed from q to q_r is
+ * the same hardware. The hash agrees. */
+
+uint64_t
+mp_hash(const rt_mod_t *M)
+{
+    uint64_t h = HS_OFFSET;
+    uint32_t i;
+    uint8_t  j;
+
+    if (!M) return 0;
+
+    /* Magic + version. Later versions diverge from byte one,
+     * so a v1 digest will never collide with a v2 digest by
+     * accident. Belt, braces, and a length of fencing wire. */
+    h = hs_byte(h, (uint8_t)'T');
+    h = hs_byte(h, (uint8_t)'K');
+    h = hs_byte(h, (uint8_t)'H');
+    h = hs_byte(h, (uint8_t)'1');
+    h = hs_u32(h, HS_VER);
+
+    /* Nets. Index 0 is the sentinel; every pool reserves it
+     * for "nobody's home". Skip it deliberately. */
+    h = hs_u32(h, M->n_net);
+    for (i = 1; i < M->n_net; i++) {
+        const rt_net_t *n = &M->nets[i];
+        h = hs_u32 (h, n->width);
+        h = hs_byte(h, n->radix);
+        h = hs_byte(h, n->is_port);
+        h = hs_u32 (h, n->driver);
+    }
+
+    /* Cells. RT_CELL_COUNT marks a slot vacated by some
+     * pass — record the gap as a single zero byte so a
+     * deletion doesn't collide with an unrelated rewrite. */
+    h = hs_u32(h, M->n_cell);
+    for (i = 1; i < M->n_cell; i++) {
+        const rt_cell_t *c = &M->cells[i];
+        if (c->type == RT_CELL_COUNT) {
+            h = hs_byte(h, 0);
+            continue;
+        }
+        h = hs_byte(h, (uint8_t)c->type);
+        h = hs_u32 (h, c->width);
+        h = hs_u32 (h, c->out);
+        h = hs_byte(h, c->n_in);
+        for (j = 0; j < c->n_in; j++)
+            h = hs_u32(h, c->ins[j]);
+        h = hs_u64(h, (uint64_t)c->param);
+    }
+
+    return h;
+}

src/main.c

@@ -32,6 +32,7 @@ usage(const char *prog)
     printf("  --parse     dump AST + RTL IR\n");
     printf("  --opt       optimise (constant propagation + DCE)\n");
     printf("  --equiv     equivalence check (pre-opt vs post-opt)\n");
+    printf("  --hash      print 64-bit fingerprint of synthesised netlist\n");
     printf("  --tmr       radiation hardening (triplicate DFFs + voters)\n");
     printf("  --tmr-full  radiation hardening (triplicate everything)\n");
     printf("  --fpga <f>  emit nextpnr JSON for iCE40 FPGA\n");
@@ -66,6 +67,7 @@ main(int argc, char **argv)
     int mode_vhdl = 0;
     int mode_abel = 0;
     int mode_equiv = 0;
+    int mode_hash = 0;
     const char *fpga_path = NULL;
     int mode_tmr = 0;
     int tmr_full = 0;
@@ -126,6 +128,9 @@ main(int argc, char **argv)
             mode_equiv = 1;
             mode_opt = 1;
             mode_parse = 1;
+        } else if (strcmp(argv[i], "--hash") == 0) {
+            mode_hash = 1;
+            mode_parse = 1;
         } else if (strcmp(argv[i], "--vhdl") == 0) {
             mode_vhdl = 1;
             def_path = "defs/vhdl_tok.def";
@@ -503,6 +508,10 @@ main(int argc, char **argv)
                                             fpga_path);
                                     }
                                 }
+                                if (mode_hash) {
+                                    printf("hash: %016" PRIx64 "\n",
+                                           mp_hash(rtl));
+                                }
                                 if (map_path) {
                                     if (!lib_path) {
                                         fprintf(stderr,