zuspec-rt-core 0.1.0__py3-none-any.whl

zuspec/rt/core/__init__.py

@@ -0,0 +1,41 @@
+"""
+zuspec.rt.core -- shared runtime-core substrate for the ZBC execution stack.
+
+The package payload is the C substrate the native engine (``zuspec-rt-eng``) and
+the AOT output (``zuspec-be-sw``) both link against, plus the generated ABI
+header(s):
+
+* ``share/include`` -- the generated ABI header (``zbc_format.h``, see
+  :mod:`zuspec.be.bc.format.emit_c`) and the migrated substrate headers.
+* ``share/rt`` -- the migrated substrate C sources (scheduler, allocator, ...).
+
+Downstream builds discover the headers + sources through :func:`include_dir` and
+:func:`source_files`; :mod:`zuspec.rt.core.build` compiles them into a shared
+library (used by the pytest+ctypes substrate tests, per project convention).
+
+Migration is incremental (roadmap P2); ``zuspec-be-sw`` keeps its own copies as
+shims until the cutover, so it is unaffected while the substrate lands here.
+"""
+
+import os
+import glob
+
+from .__version__ import version as __version__
+
+#: Absolute path to the package's ``share`` tree (headers, runtime sources).
+SHARE_DIR = os.path.join(os.path.dirname(__file__), "share")
+
+
+def include_dir() -> str:
+    """Return the absolute path to the C include directory (headers)."""
+    return os.path.join(SHARE_DIR, "include")
+
+
+def rt_dir() -> str:
+    """Return the absolute path to the runtime C source directory."""
+    return os.path.join(SHARE_DIR, "rt")
+
+
+def source_files() -> list:
+    """Return the absolute paths of the substrate C sources (sorted, stable)."""
+    return sorted(glob.glob(os.path.join(rt_dir(), "*.c")))

zuspec/rt/core/__version__.py

@@ -0,0 +1,20 @@
+
+#****************************************************************************
+# Copyright 2019-2025 Matthew Ballance and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#****************************************************************************
+BASE="0.1.0"
+SUFFIX=""
+VERSION="%s%s" % (BASE, SUFFIX)
+version=VERSION

zuspec/rt/core/build.py

@@ -0,0 +1,84 @@
+"""
+zuspec.rt.core.build -- compile the substrate into a shared library.
+
+The runtime substrate is plain C with a stable ``zsp_`` ABI, so it is tested by
+compiling it to a ``.so`` and driving it from Python through ``ctypes`` (the
+project convention for native code -- no gtest). This module is that compile
+step, factored out so both the substrate tests and any downstream consumer can
+reuse it.
+
+``build_shared_lib`` compiles :func:`zuspec.rt.core.source_files` (plus any
+``extra_sources`` -- e.g. a test-support shim exposing struct accessors) against
+:func:`zuspec.rt.core.include_dir` and returns the path to the produced library.
+"""
+
+import os
+import subprocess
+import sysconfig
+from typing import Iterable, List, Optional
+
+from . import include_dir, source_files
+
+
+def default_cc() -> str:
+    """The C compiler to use (``$CC`` if set, else the platform default, else cc)."""
+    return os.environ.get("CC") or sysconfig.get_config_var("CC") or "cc"
+
+
+def _shared_flag() -> List[str]:
+    # macOS wants -dynamiclib; ELF platforms use -shared. Default to -shared.
+    if os.uname().sysname == "Darwin":
+        return ["-dynamiclib"]
+    return ["-shared"]
+
+
+def build_shared_lib(out_path: str,
+                     extra_sources: Optional[Iterable[str]] = None,
+                     extra_include_dirs: Optional[Iterable[str]] = None,
+                     extra_link_args: Optional[Iterable[str]] = None,
+                     cc: Optional[str] = None) -> str:
+    """Compile the substrate (+ ``extra_sources``) into ``out_path``.
+
+    ``extra_link_args`` are appended after the sources (e.g. ``-L``/``-l``/
+    ``-Wl,-rpath`` to link a downstream shared library such as libdv_solve).
+
+    Returns ``out_path`` on success; raises :class:`RuntimeError` with the
+    compiler output on failure.
+    """
+    cc = cc or default_cc()
+    srcs = list(source_files()) + list(extra_sources or [])
+    incs = [include_dir()] + list(extra_include_dirs or [])
+
+    # $CC may carry flags (e.g. "gcc -pthread"); split so they are honored.
+    cmd = cc.split() + _shared_flag() + ["-fPIC", "-O2", "-g"]
+    for inc in incs:
+        cmd += ["-I", inc]
+    cmd += srcs + ["-o", out_path]
+    cmd += list(extra_link_args or [])
+
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise RuntimeError(
+            "failed to build rt-core shared lib:\n"
+            "  cmd: %s\n%s%s" % (" ".join(cmd), proc.stdout, proc.stderr))
+    return out_path
+
+
+def compile_check(source: str, lang: str = "c",
+                  extra_flags: Optional[Iterable[str]] = None,
+                  compiler: Optional[str] = None) -> "tuple[bool, str]":
+    """Compile ``source`` (syntax-only) against the substrate include dir.
+
+    ``lang`` is ``"c"`` or ``"c++"``. Returns ``(ok, output)`` -- used by the
+    substrate hygiene tests to assert headers are self-contained and compile as
+    both C and C++.
+    """
+    if compiler is None:
+        compiler = default_cc() if lang == "c" else (
+            os.environ.get("CXX") or "c++")
+    cmd = compiler.split() + ["-fsyntax-only", "-x", lang,
+                              "-I", include_dir()]
+    cmd += list(extra_flags or [])
+    cmd += ["-"]
+    proc = subprocess.run(cmd, input=source, capture_output=True, text=True)
+    return proc.returncode == 0, (proc.stdout + proc.stderr)

zuspec/rt/core/share/include/zbc_format.h

@@ -0,0 +1,199 @@
+/*
+ * zbc_format.h -- the .zbc container format, C view.
+ *
+ * GENERATED from zuspec.be.bc.format.spec -- DO NOT EDIT BY HAND.
+ * Regenerate with:  python -m zuspec.be.bc.format.emit_c
+ * (A regen no-diff test guards this file against drift.)
+ */
+
+#ifndef ZUSPEC_ZBC_FORMAT_H
+#define ZUSPEC_ZBC_FORMAT_H
+
+#include <stdint.h>
+
+#if defined(__cplusplus)
+#  define ZBC_STATIC_ASSERT(cond, msg) static_assert(cond, msg)
+#else
+#  define ZBC_STATIC_ASSERT(cond, msg) _Static_assert(cond, msg)
+#endif
+
+/* File identity */
+#define ZBC_MAGIC0 0x5a
+#define ZBC_MAGIC1 0x42
+#define ZBC_MAGIC2 0x43
+#define ZBC_MAGIC3 0x1a
+#define ZBC_VERSION_MAJOR 1
+#define ZBC_VERSION_MINOR 0
+
+/* zbc_sec_kind: Section kinds. Readers skip unknown kinds (forward-compat). */
+#define ZBC_SEC_CODE   0x0001  /* opcode stream */
+#define ZBC_SEC_CORO   0x0002  /* coroutine/func descriptors */
+#define ZBC_SEC_TYPE   0x0003  /* type/field metadata */
+#define ZBC_SEC_CONST  0x0004  /* >64-bit literal constant pool */
+#define ZBC_SEC_SOLVE  0x0005  /* SolveProblem blobs (P4) */
+#define ZBC_SEC_STRB   0x0006  /* string blob */
+#define ZBC_SEC_STRO   0x0007  /* string offsets */
+#define ZBC_SEC_FILE   0x0008  /* file table */
+#define ZBC_SEC_PROV   0x0009  /* provenance records */
+#define ZBC_SEC_CMNT   0x000a  /* comment records */
+#define ZBC_SEC_LINE   0x000b  /* pc->src_ref line table */
+#define ZBC_SEC_BLOCK  0x000c  /* FSM block table (zbc_block[]) */
+#define ZBC_SEC_OPLIST 0x000d  /* u32 operand lists (PAR/SELECT branch ids) */
+#define ZBC_SEC_SELECT 0x000e  /* weighted-SELECT descriptors (zbc_select[]) */
+#define ZBC_SEC_SPROB  0x000f  /* relocatable dv-solve SolveProblem blobs */
+
+/* zbc_hdr_flags: Header flag bits. */
+#define ZBC_HDR_HAS_PROV        0x0001  /* provenance sections present */
+#define ZBC_HDR_PROFILE_RUNTIME 0x0002  /* runtime profile (provenance stripped) */
+#define ZBC_HDR_COMP_INIT       0x0004  /* a coroutine constructs the component tree before the entry (P1.5) */
+
+/* zbc_secf_flags: Per-section flag bits. */
+#define ZBC_SECF_COMPRESSED 0x0001  /* payload is compressed */
+
+/* zbc_prov_flags: Provenance granularity + attribute bits. */
+#define ZBC_PROV_G_INSN  0x0001  /* granularity: instruction */
+#define ZBC_PROV_G_BLOCK 0x0002  /* granularity: block */
+#define ZBC_PROV_G_CORO  0x0004  /* granularity: coroutine */
+#define ZBC_PROV_G_DECL  0x0008  /* granularity: declaration */
+#define ZBC_PROV_F_SYNTH 0x0100  /* compiler-synthesized; no real source */
+
+/* zbc_sel_flags: SELECT descriptor flag bits. */
+#define ZBC_SEL_ALLOW_NONE 0x0001  /* no eligible branch -> run nothing (not an error) */
+
+/* zbc_solve_flags: SOLVE descriptor flag bits. */
+#define ZBC_SOLVE_SEED_FIXED 0x0001  /* use seed_value; else draw from the frame stream */
+
+/* zbc_cmt_kind: Comment kinds. */
+#define ZBC_CMT_LEADING  0x0001
+#define ZBC_CMT_TRAILING 0x0002
+#define ZBC_CMT_INLINE   0x0003
+#define ZBC_CMT_DOC      0x0004
+
+/* zbc_header: File header at offset 0. Magic is byte-order-fixed and checked first. */
+typedef struct {
+    uint8_t    magic[4];  /* 'Z','B','C',0x1A */
+    uint16_t   version_major;  /* incompatible bump -> engine REJECTS */
+    uint16_t   version_minor;  /* additive bump -> tolerated */
+    uint32_t   flags;  /* ZBC_HDR_* */
+    uint32_t   header_size;  /* sizeof(zbc_header); readers skip grown tail */
+    uint32_t   abi_id;  /* value-ABI version (D§11); must match engine */
+    uint32_t   section_count;
+    uint32_t   section_dir_off;
+    uint32_t   entry_coro;  /* index of root/entry coroutine descriptor */
+    uint64_t   file_size;  /* integrity: equals actual length */
+    uint64_t   content_hash;  /* hash of bytes after this field (0=none) */
+} zbc_header;
+
+/* zbc_section: Section directory entry; fixed size so it is itself trivially indexable. */
+typedef struct {
+    uint32_t   kind;  /* ZBC_SEC_* */
+    uint32_t   flags;  /* ZBC_SECF_* */
+    uint64_t   offset;  /* from file start, 8-byte aligned */
+    uint64_t   size;  /* byte length */
+    uint32_t   count;  /* element count for record arrays (0=N/A) */
+    uint32_t   elem_size;  /* per-element stride (0=N/A); forward-compat lever */
+} zbc_section;
+
+/* zbc_prov: Provenance record (32 bytes). prov[0] is the reserved all-zero 'none' entry. */
+typedef struct {
+    uint32_t   name;  /* StrId (0=none) */
+    uint32_t   node_id;  /* stable IR node id (0=none) */
+    uint32_t   line;  /* 1-based start line (0=unknown) */
+    uint32_t   cmt_first;  /* CMNT index of first attached comment */
+    uint16_t   file;  /* FileId */
+    uint16_t   node_kind;  /* origin-node-kind enum */
+    uint16_t   col;  /* start column (0=unknown) */
+    uint16_t   col_end;  /* end column (0=unknown) */
+    uint16_t   line_end;  /* end line (0=same as line) */
+    uint16_t   flags;  /* ZBC_PROV_* */
+    uint16_t   cmt_count;  /* comments in this record's run */
+    uint16_t   _rsvd;
+} zbc_prov;
+
+/* zbc_comment: Comment record (8 bytes). A prov entry owns run [cmt_first, cmt_first+cmt_count). */
+typedef struct {
+    uint32_t   text;  /* StrId */
+    uint8_t    kind;  /* ZBC_CMT_* */
+    uint8_t    _pad;
+    uint16_t   line;  /* source line of the comment (0=unknown) */
+} zbc_comment;
+
+/* zbc_file: File-table entry (8 bytes). FileId = u16 index into files[]. */
+typedef struct {
+    uint32_t   path;  /* StrId */
+    uint32_t   _rsvd;
+} zbc_file;
+
+/* zbc_lineent: pc->src_ref line table entry (8 bytes). Binary-searched by pc. */
+typedef struct {
+    uint32_t   pc_start;  /* sorted ascending */
+    uint32_t   src_ref;  /* prov index; src_at(pc)=largest pc_start<=pc */
+} zbc_lineent;
+
+/* zbc_instr: One fixed-width instruction (32 bytes). CODE section is zbc_instr[]. */
+typedef struct {
+    uint16_t   op;  /* ZBC opcode (see model.Op) */
+    uint8_t    nargs;  /* count of valid args (0..4) */
+    uint8_t    flags;  /* per-op flags (e.g. CONST from pool) */
+    uint32_t   src_ref;  /* provenance index (0=none) */
+    uint64_t   imm;  /* immediate / const bits (two's complement) */
+    uint32_t   arg0;
+    uint32_t   arg1;
+    uint32_t   arg2;
+    uint32_t   arg3;
+} zbc_instr;
+
+/* zbc_coro: Coroutine/func descriptor (32 bytes). CORO section is zbc_coro[]. */
+typedef struct {
+    uint32_t   name;  /* StrId (0=none/runtime profile) */
+    uint32_t   code_start;  /* first instr index into CODE */
+    uint32_t   code_count;  /* instr count */
+    uint32_t   n_blocks;  /* FSM block count */
+    uint32_t   block_start;  /* first entry into BLOCK table */
+    uint32_t   frame_type;  /* TYPE id of frame struct (0=none) */
+    uint32_t   src_ref;  /* provenance index (0=none) */
+    uint32_t   _rsvd;
+} zbc_coro;
+
+/* zbc_block: FSM block (16 bytes). BLOCK section is zbc_block[]; a coro owns a run. */
+typedef struct {
+    uint32_t   idx;  /* FSM block index */
+    uint32_t   pc_start;  /* first instr index (relative to coro) */
+    uint32_t   pc_end;  /* one past last instr index */
+    uint16_t   suspend_op;  /* orchestration op ending the block (0=terminal) */
+    uint16_t   _rsvd;
+} zbc_block;
+
+/* zbc_select: Weighted-SELECT descriptor (16 bytes). SELECT section is zbc_select[]; arg0 of a SELECT instr indexes it. The OPLIST pool holds, contiguously from oplist_off, three u32 runs of length n_branches: branch coro ids, positive weights, then guard registers (0xFFFFFFFF = unguarded). */
+typedef struct {
+    uint32_t   oplist_off;  /* start index into OPLIST u32 pool */
+    uint32_t   n_branches;  /* branch count */
+    uint32_t   flags;  /* ZBC_SEL_* (bit0 = allow_none) */
+    uint32_t   _rsvd;
+} zbc_select;
+
+/* zbc_solve: SOLVE descriptor (32 bytes). SOLVE section is zbc_solve[]; arg0 of a SOLVE instr indexes it. The OPLIST pool holds, from oplist_off, n_writeback interleaved (field_slot, var_id) u32 pairs -- the value ABI write-back keyed by object slot. When prob_len > 0, the (prob_off, prob_len) slice of the SPROB pool is a relocatable dv-solve SolveProblem blob: the engine compiles + solves it with the drawn seed and writes dvs_solver_get_value(var_id) back to each field_slot. When prob_len == 0 the minimal M1 randomizer applies: slot = seed + var_id (FixedSolveBackend, base 0). Seed is seed_value if SEED_FIXED else the frame's next draw. */
+typedef struct {
+    uint64_t   seed_value;  /* fixed-seed value (when flags & SEED_FIXED) */
+    uint32_t   oplist_off;  /* start of (field_slot, var_id) pairs in OPLIST */
+    uint32_t   n_writeback;  /* writeback pair count */
+    uint32_t   flags;  /* ZBC_SOLVE_* (bit0 = fixed seed) */
+    uint32_t   prob_off;  /* byte offset of the problem blob in the SPROB pool */
+    uint32_t   prob_len;  /* problem blob length in bytes (0 = minimal randomizer) */
+    uint32_t   _rsvd;
+} zbc_solve;
+
+/* Layout guards: sizes must match the spec (natural alignment). */
+ZBC_STATIC_ASSERT(sizeof(zbc_header) == 48, "zbc_header size mismatch");
+ZBC_STATIC_ASSERT(sizeof(zbc_section) == 32, "zbc_section size mismatch");
+ZBC_STATIC_ASSERT(sizeof(zbc_prov) == 32, "zbc_prov size mismatch");
+ZBC_STATIC_ASSERT(sizeof(zbc_comment) == 8, "zbc_comment size mismatch");
+ZBC_STATIC_ASSERT(sizeof(zbc_file) == 8, "zbc_file size mismatch");
+ZBC_STATIC_ASSERT(sizeof(zbc_lineent) == 8, "zbc_lineent size mismatch");
+ZBC_STATIC_ASSERT(sizeof(zbc_instr) == 32, "zbc_instr size mismatch");
+ZBC_STATIC_ASSERT(sizeof(zbc_coro) == 32, "zbc_coro size mismatch");
+ZBC_STATIC_ASSERT(sizeof(zbc_block) == 16, "zbc_block size mismatch");
+ZBC_STATIC_ASSERT(sizeof(zbc_select) == 16, "zbc_select size mismatch");
+ZBC_STATIC_ASSERT(sizeof(zbc_solve) == 32, "zbc_solve size mismatch");
+
+#endif /* ZUSPEC_ZBC_FORMAT_H */

zuspec/rt/core/share/include/zsp_alloc.h

@@ -0,0 +1,28 @@
+#ifndef INCLUDED_ZSP_ALLOC_H
+#define INCLUDED_ZSP_ALLOC_H
+
+#include <sys/types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif 
+
+struct zsp_alloc_s;
+
+typedef void *(*zsp_alloc_func)(struct zsp_alloc_s *, size_t);
+typedef void (*zsp_free_func)(struct zsp_alloc_s *, void *);
+
+typedef struct zsp_alloc_s {
+    zsp_alloc_func  alloc;
+    zsp_free_func   free;
+} zsp_alloc_t;
+
+void zsp_alloc_malloc_init(zsp_alloc_t *alloc);
+
+zsp_alloc_t *zsp_alloc_malloc_create();
+
+#ifdef __cplusplus
+}
+#endif 
+
+#endif /* INCLUDED_ZSP_ALLOC_H */

zuspec/rt/core/share/include/zsp_indexed_pool.h

@@ -0,0 +1,25 @@
+#ifndef INCLUDED_ZSP_INDEXED_POOL_H
+#define INCLUDED_ZSP_INDEXED_POOL_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct zsp_indexed_pool_s {
+    uint32_t  size;
+    uint32_t *used_mask;  /* one bit per slot */
+    uint32_t  seed;       /* for random selection */
+} zsp_indexed_pool_t;
+
+void zsp_indexed_pool_init(zsp_indexed_pool_t *p, uint32_t size);
+int  zsp_indexed_pool_acquire(zsp_indexed_pool_t *p, int idx);
+int  zsp_indexed_pool_acquire_random(zsp_indexed_pool_t *p);
+void zsp_indexed_pool_release(zsp_indexed_pool_t *p, int idx);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* INCLUDED_ZSP_INDEXED_POOL_H */