genesispy 0.6.0__tar.gz

genesispy-0.6.0/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org/>

genesispy-0.6.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: genesispy
+Version: 0.6.0
+Summary: Genesis Chip Generator, Python port of Genesis2
+Author: stfns-s
+License-Expression: Unlicense
+Project-URL: Homepage, https://github.com/stfns-s/genesispy
+Project-URL: Repository, https://github.com/stfns-s/genesispy
+Keywords: RTL generator,verilog,ASIC,FPGA
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: xml
+Requires-Dist: lxml>=4.9; extra == "xml"
+Provides-Extra: color
+Requires-Dist: colorama>=0.4; extra == "color"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: fixedpoint>=1.0; extra == "dev"
+Requires-Dist: lxml>=4.9; extra == "dev"
+Requires-Dist: colorama>=0.4; extra == "dev"
+Provides-Extra: import-j2
+Requires-Dist: jinja2>=3.1; extra == "import-j2"
+Dynamic: license-file
+
+# genesispy
+
+Python port of the Genesis2 Chip Generator (see
+<https://github.com/StanfordVLSI/Genesis2>). Replaces the Perl runtime
+with a pure-Python implementation while keeping the template hierarchy
+(now `.vpy` / `.svpy`). Configuration is JSON; legacy Genesis2 `.xml`
+configs convert via the bundled `genesispy-xml2json` helper.
+
+## Install
+
+### From PyPI
+
+```sh
+pip install genesispy
+```
+
+Installs the `genesispy`, `gvpy`, `genesispy-vp2vpy`, `genesispy-xml2json`,
+`genesispy-json2xml` and `genesispy-jinja2j2` commands. There are no
+mandatory dependencies; three optional extras:
+
+```sh
+pip install 'genesispy[xml]'        # lxml: pretty-printed genesispy-json2xml
+pip install 'genesispy[color]'      # colorama: coloured diagnostics
+pip install 'genesispy[import-j2]'  # jinja2: required by genesispy-jinja2j2
+```
+
+### From a checkout, without pip (recommended for developers -- `bin/` launchers)
+
+The repo ships shell launchers in `bin/` (`bin/genesispy`, `bin/gvpy`)
+that set `PYTHONPATH` to the sibling `src/` and exec
+`python3 -m genesispy.cli`. No build step, no pip -- just run from a
+checkout:
+
+```sh
+./bin/genesispy --input top.vpy --top top --json-cfg config.json
+```
+
+To "install" to a destination, copy `bin/` and `src/` together (the
+launchers resolve `src/` as `../src` relative to their own directory):
+
+```sh
+DEST=/path/to/install-dir
+mkdir -p "$DEST"
+cp -a bin src "$DEST/"
+export PATH="$DEST/bin:$PATH"
+```
+
+### From a checkout, with pip
+
+```sh
+pip install -e .
+# or
+pip install --target /path/to/install-dir .
+```
+
+## Tests
+
+Against the in-tree source, no install required:
+
+```sh
+PYTHONPATH=src pytest tests/
+```
+
+Against an installed copy (`pip install -e .` or `pip install genesispy`):
+
+```sh
+pytest tests/
+```
+
+## Documentation
+
+Each entry links to the rendered copy on GitHub; the `local` link resolves in a
+source checkout.
+
+- [doc/user-guide.md](https://github.com/stfns-s/genesispy/blob/main/doc/user-guide.md)
+  ([local](./doc/user-guide.md)) -- `.vpy` syntax, walkthrough, CLI reference
+  for `genesispy` and `gvpy`, migrating from Genesis2.
+- [doc/code-structure.md](https://github.com/stfns-s/genesispy/blob/main/doc/code-structure.md)
+  ([local](./doc/code-structure.md)) -- pipeline, dedup, control flags.
+- [doc/interfaces.md](https://github.com/stfns-s/genesispy/blob/main/doc/interfaces.md)
+  ([local](./doc/interfaces.md)) -- module-boundary interfaces.
+- [doc/genesis2-incompatibilities.md](https://github.com/stfns-s/genesispy/blob/main/doc/genesis2-incompatibilities.md)
+  ([local](./doc/genesis2-incompatibilities.md)) -- non-obvious behavior
+  differences from Perl Genesis2.

genesispy-0.6.0/README.md

@@ -0,0 +1,84 @@
+# genesispy
+
+Python port of the Genesis2 Chip Generator (see
+<https://github.com/StanfordVLSI/Genesis2>). Replaces the Perl runtime
+with a pure-Python implementation while keeping the template hierarchy
+(now `.vpy` / `.svpy`). Configuration is JSON; legacy Genesis2 `.xml`
+configs convert via the bundled `genesispy-xml2json` helper.
+
+## Install
+
+### From PyPI
+
+```sh
+pip install genesispy
+```
+
+Installs the `genesispy`, `gvpy`, `genesispy-vp2vpy`, `genesispy-xml2json`,
+`genesispy-json2xml` and `genesispy-jinja2j2` commands. There are no
+mandatory dependencies; three optional extras:
+
+```sh
+pip install 'genesispy[xml]'        # lxml: pretty-printed genesispy-json2xml
+pip install 'genesispy[color]'      # colorama: coloured diagnostics
+pip install 'genesispy[import-j2]'  # jinja2: required by genesispy-jinja2j2
+```
+
+### From a checkout, without pip (recommended for developers -- `bin/` launchers)
+
+The repo ships shell launchers in `bin/` (`bin/genesispy`, `bin/gvpy`)
+that set `PYTHONPATH` to the sibling `src/` and exec
+`python3 -m genesispy.cli`. No build step, no pip -- just run from a
+checkout:
+
+```sh
+./bin/genesispy --input top.vpy --top top --json-cfg config.json
+```
+
+To "install" to a destination, copy `bin/` and `src/` together (the
+launchers resolve `src/` as `../src` relative to their own directory):
+
+```sh
+DEST=/path/to/install-dir
+mkdir -p "$DEST"
+cp -a bin src "$DEST/"
+export PATH="$DEST/bin:$PATH"
+```
+
+### From a checkout, with pip
+
+```sh
+pip install -e .
+# or
+pip install --target /path/to/install-dir .
+```
+
+## Tests
+
+Against the in-tree source, no install required:
+
+```sh
+PYTHONPATH=src pytest tests/
+```
+
+Against an installed copy (`pip install -e .` or `pip install genesispy`):
+
+```sh
+pytest tests/
+```
+
+## Documentation
+
+Each entry links to the rendered copy on GitHub; the `local` link resolves in a
+source checkout.
+
+- [doc/user-guide.md](https://github.com/stfns-s/genesispy/blob/main/doc/user-guide.md)
+  ([local](./doc/user-guide.md)) -- `.vpy` syntax, walkthrough, CLI reference
+  for `genesispy` and `gvpy`, migrating from Genesis2.
+- [doc/code-structure.md](https://github.com/stfns-s/genesispy/blob/main/doc/code-structure.md)
+  ([local](./doc/code-structure.md)) -- pipeline, dedup, control flags.
+- [doc/interfaces.md](https://github.com/stfns-s/genesispy/blob/main/doc/interfaces.md)
+  ([local](./doc/interfaces.md)) -- module-boundary interfaces.
+- [doc/genesis2-incompatibilities.md](https://github.com/stfns-s/genesispy/blob/main/doc/genesis2-incompatibilities.md)
+  ([local](./doc/genesis2-incompatibilities.md)) -- non-obvious behavior
+  differences from Perl Genesis2.

genesispy-0.6.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+# >=77 for PEP 639 (license = "<SPDX>" / license-files).
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "genesispy"
+version = "0.6.0"
+description = "Genesis Chip Generator, Python port of Genesis2"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Unlicense"
+license-files = ["LICENSE"]
+authors = [{ name = "stfns-s" }]
+keywords = ["RTL generator", "verilog", "ASIC", "FPGA"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: POSIX :: Linux",
+]
+# No hard runtime requirements. Both accelerators below are guarded imports
+# with stdlib fallbacks (tools/xml_json.py:23, reporting.py:21), so the
+# package is fully functional without either.
+dependencies = []
+
+[project.optional-dependencies]
+# Pretty-printed genesispy-json2xml output; without it the stdlib
+# xml.etree.ElementTree writer is used.
+xml = ["lxml>=4.9"]
+# Coloured error/warning output; without it messages are uncoloured.
+color = ["colorama>=0.4"]
+dev = [
+    "pytest>=7",
+    "fixedpoint>=1.0",
+    "lxml>=4.9",
+    "colorama>=0.4",
+]
+import-j2 = [
+    "jinja2>=3.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/stfns-s/genesispy"
+Repository = "https://github.com/stfns-s/genesispy"
+
+[project.scripts]
+genesispy = "genesispy.cli:main"
+gvpy = "genesispy.gvpy_cli:main"
+genesispy-jinja2j2 = "genesispy.tools.jinja2j2:main"
+genesispy-xml2json = "genesispy.tools.xml_json:main_xml2json"
+genesispy-json2xml = "genesispy.tools.xml_json:main_json2xml"
+genesispy-vp2vpy = "genesispy.tools.vp2vpy:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+# vp2vpy locates its Perl helper as a sibling of vp2vpy.py
+# (tools/vp2vpy.py:35), so it must ship inside the package.
+[tool.setuptools.package-data]
+"genesispy.tools" = ["*.pl"]
+
+[tool.pytest.ini_options]
+# demos/ carries the dsp-gpy submodule, which has a pytest suite of its own.
+norecursedirs = ["demos", "build", "dist", ".git"]

genesispy-0.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

genesispy-0.6.0/src/genesispy/__init__.py

@@ -0,0 +1,3 @@
+"""genesispy — Python port of the Genesis2 Chip Generator."""
+
+__version__ = "0.6.0"

genesispy-0.6.0/src/genesispy/_scalars.py

@@ -0,0 +1,50 @@
+"""Shared scalar coercion used by config_handler and json_io.
+
+Single source of truth for parsing string-shaped scalars (from XML, JSON,
+or CLI ``-parameter NAME=VALUE``) into native Python ``int``/``float``/
+``bool``. Lives in its own leaf module so neither caller introduces an
+import-time dependency on the other.
+
+Behaviour: stricter than Python's ``float()`` — strings without a decimal
+point or exponent character are not parsed as floats. This means
+``"inf"``, ``"nan"``, ``"infinity"`` round-trip as strings rather than
+silently becoming ``float('inf')`` / ``float('nan')``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def coerce_scalar(s: Any) -> Any:
+    """Coerce a string scalar to int/float/bool when unambiguous.
+
+    Non-strings pass through. Empty / whitespace-only strings are kept
+    as the original string. Recognised:
+      * ``"true"`` / ``"false"`` (case-insensitive) -> ``bool``.
+      * Optional sign + digits -> ``int``.
+      * Strings containing ``.``, ``e``, or ``E`` that ``float()``
+        accepts -> ``float``.
+    Anything else returns the input unchanged.
+    """
+    if not isinstance(s, str):
+        return s
+    stripped = s.strip()
+    if stripped == "":
+        return s
+    low = stripped.lower()
+    if low == "true":
+        return True
+    if low == "false":
+        return False
+    if stripped.lstrip("+-").isdigit():
+        try:
+            return int(stripped)
+        except ValueError:
+            pass
+    if any(c in stripped for c in ".eE"):
+        try:
+            return float(stripped)
+        except ValueError:
+            pass
+    return s

genesispy-0.6.0/src/genesispy/cache.py

@@ -0,0 +1,208 @@
+"""Process-wide singletons backing the elaboration engine.
+
+These dictionaries replace the Perl ``shared-ref`` globals used in
+``UniqueModule.pm`` (see e.g. lines 176-181, 248-251 of that file).  They
+are intentionally module-level so that every ``UniqueModule`` instance
+agrees on the dedup state.  Tests reset them via :func:`clear_all`.
+
+The two journaled caches (MODULE_CACHE, OUTFILE_CONTENT_CACHE) record
+writes inside an active :func:`journaled` block so :meth:`UniqueModule.unique_inst`
+can roll back the discarded child's registrations on a post-elaboration
+dedup hit without paying O(N) to copy/restore the entire cache.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Dict, Iterator, List, Tuple
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .unique_module import UniqueModule
+
+
+_MISSING = object()
+
+
+class _JournaledDict(dict):
+    """``dict`` subclass that records first-touch writes for active journals.
+
+    Each entry on :attr:`_journals` is a ``dict[key -> pre_value]`` capturing
+    what the key was *before* the first write inside that journal scope; the
+    sentinel :data:`_MISSING` means the key was absent. Rollback walks the
+    journal and restores or deletes accordingly.
+
+    Only ``__setitem__`` and ``__delitem__`` are journaled; ``.clear()`` is
+    used only by :func:`clear_all` between tests and bypasses journaling on
+    purpose. No call site uses ``.update()`` / ``.pop()`` / ``.popitem()``
+    while a journal is active (verified at port time); add overrides if that
+    changes.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._journals: List[Dict[Any, Any]] = []
+
+    def _record(self, key: Any) -> None:
+        if not self._journals:
+            return
+        prev = super().get(key, _MISSING)
+        for j in self._journals:
+            if key not in j:
+                j[key] = prev
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        self._record(key)
+        super().__setitem__(key, value)
+
+    def __delitem__(self, key: Any) -> None:
+        self._record(key)
+        super().__delitem__(key)
+
+
+# MODULE_CACHE keys live in two disjoint namespaces, partitioned by the
+# `::` separator:
+#   * dedup signatures used by unique_inst / unique_inst_param to collapse
+#     equivalent elaborations:
+#       "<base>::<sha256>[::sub::<sha256>]"        (pre-elaboration param key)
+#       "<base>::post::<sha256>[::sub::<sha256>]"  (post-elaboration full-param key)
+#       "<base>::param::<sha256>[::sub::<sha256>]" (parametric form)
+#     The optional `::sub::` tail (unique_module._subtree_tag) folds the
+#     scoped-subtree override signature into the key, separating instances
+#     whose descendants carry different scoped CLI overrides.
+#   * registered instance identifiers (`<base>_unqN`, plus user-supplied
+#     synonyms) — these must NOT contain `::`; cache.register asserts this
+#     so a future synonym name can never collide with a dedup signature.
+MODULE_CACHE: _JournaledDict = _JournaledDict()
+
+# Base-class-name -> next derivative counter.  Drives unique-name suffixes
+# such as ``Foo_unq2`` (unique_inst, plus unique_inst_param on override
+# paths).  Namespaced keys like ``<base>::ununq_tmp`` number the temp
+# generations of ununique_inst's re-elaborate-and-compare path.
+MODULE_NAME_NUM_DERIVS: Dict[str, int] = {}
+
+# Filename -> emitted Verilog text.  Flushed on demand (e.g. by Manager).
+OUTFILE_CONTENT_CACHE: _JournaledDict = _JournaledDict()
+
+# Base-name -> {"instance": UniqueModule, "params": dict[str, Any],
+# "subtree_sig": tuple}.  Tracks `ununique_inst` calls; a second call with
+# the same base name aliases the previous instance (identical resolved
+# params and subtree signature), raises (different params), or
+# re-elaborates and compares generated bodies (different subtree
+# signatures).  Mirrors Perl UnUniquifiedModules + does_generate_same +
+# compare_generated_files (UniqueModule.pm:1610-1700, :3130); global
+# scope (not per-parent) because the on-disk filename is global.
+UNUNIQUE_REGISTRY: Dict[str, Dict[str, Any]] = {}
+
+
+# Filename -> 'synth' | 'verif' | 'synth_and_verif'.  Built by Manager
+# before flush from a path-based DFS over the elaborated instance tree
+# (mirrors Perl Manager.pm:1330-1395 / UniqueModule.pm:_get_prod_list_insts).
+# Empty when synth_top is None -> output_writer treats unmapped files as
+# 'verif' (matches Perl SynthTop=undef default).
+OUTFILE_TAGS: Dict[str, str] = {}
+
+# Output filenames in DFS first-seen walk order, populated by Manager
+# _populate_outfile_tags alongside OUTFILE_TAGS.  output_writer uses this
+# to emit product lists in a single consistent order (matching Perl
+# Manager.pm:1330-1395).  Keys not present here (test-only raw entries)
+# fall back to alphabetical after all ordered entries.
+OUTFILE_ORDER: List[str] = []
+
+# Resolved paths of include()'d template files, appended by
+# user_config._include.  Consumed together with Manager.parsed_source_files
+# by output_writer.write_file_lists as the .depend prerequisite list.
+# Append order; deduped at read time.
+INCLUDED_FILES: List[str] = []
+
+
+def clear_all() -> None:
+    """Reset every singleton.  Intended for tests."""
+    MODULE_CACHE.clear()
+    MODULE_NAME_NUM_DERIVS.clear()
+    OUTFILE_CONTENT_CACHE.clear()
+    OUTFILE_TAGS.clear()
+    OUTFILE_ORDER.clear()
+    UNUNIQUE_REGISTRY.clear()
+    INCLUDED_FILES.clear()
+    # Recycled tmpdir paths could otherwise inherit a stale .vpy mapping.
+    from .template import runtime as _rt
+    _rt.clear_line_maps()
+
+
+def next_derivation(base_name: str) -> int:
+    """Return the next derivative index for ``base_name`` (1-based).
+
+    The first call returns ``1``; subsequent calls increment.  This
+    matches the Perl ``ModuleNameNumDerivs`` semantics.
+
+    Best-effort contiguous: gaps may appear when post-elaboration dedup
+    in ``unique_inst`` reclaims a slot, and the rollback only fires if
+    no nested ``next_derivation`` call bumped the counter past it.
+    """
+    n = MODULE_NAME_NUM_DERIVS.get(base_name, 0) + 1
+    MODULE_NAME_NUM_DERIVS[base_name] = n
+    return n
+
+
+def register(unique_name: str, instance: "UniqueModule") -> None:
+    """Register ``instance`` under ``unique_name`` in the module cache.
+
+    Re-registering the same instance is a silent no-op. Re-registering a
+    *different* instance under an existing name emits a one-line warning
+    on stderr — typically a synonym collision or a misuse of
+    `synonym_class`. The new entry still wins (preserves prior behaviour
+    for tests that intentionally rebind), but the warning surfaces what
+    used to be a silent overwrite.
+    """
+    if "::" in unique_name:
+        # Reserved for dedup-signature keys; see module docstring.
+        raise ValueError(
+            f"cache.register: '::' is reserved in unique-name keys; "
+            f"got {unique_name!r}"
+        )
+    existing = MODULE_CACHE.get(unique_name)
+    if existing is not None and existing is not instance:
+        from . import reporting
+
+        reporting.warning(
+            f"cache.register: {unique_name!r} already bound to a different "
+            f"UniqueModule instance; overwriting."
+        )
+    MODULE_CACHE[unique_name] = instance
+
+
+@contextmanager
+def journaled() -> Iterator[Tuple[Dict[Any, Any], Dict[Any, Any]]]:
+    """Context manager: capture writes to MODULE_CACHE and OUTFILE_CONTENT_CACHE.
+
+    Yields a ``(mc_journal, oc_journal)`` pair of dicts that map each
+    touched key to its pre-block value (or :data:`_MISSING` if absent at
+    block entry). Pass these to :func:`rollback_journal` to undo only the
+    writes recorded inside the block, leaving unrelated entries untouched.
+    Journals nest: each scope tracks its own first-touch set.
+    """
+    mc_j: Dict[Any, Any] = {}
+    oc_j: Dict[Any, Any] = {}
+    MODULE_CACHE._journals.append(mc_j)
+    OUTFILE_CONTENT_CACHE._journals.append(oc_j)
+    try:
+        yield mc_j, oc_j
+    finally:
+        OUTFILE_CONTENT_CACHE._journals.pop()
+        MODULE_CACHE._journals.pop()
+
+
+def rollback_journal(
+    mc_j: Dict[Any, Any], oc_j: Dict[Any, Any]
+) -> None:
+    """Undo writes recorded by a :func:`journaled` block on both caches."""
+    for key, prev in mc_j.items():
+        if prev is _MISSING:
+            dict.pop(MODULE_CACHE, key, None)
+        else:
+            dict.__setitem__(MODULE_CACHE, key, prev)
+    for key, prev in oc_j.items():
+        if prev is _MISSING:
+            dict.pop(OUTFILE_CONTENT_CACHE, key, None)
+        else:
+            dict.__setitem__(OUTFILE_CONTENT_CACHE, key, prev)