PySHDL 0.3.0__tar.gz → 0.3.1__tar.gz

{pyshdl-0.3.0 → pyshdl-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PySHDL
-Version: 0.3.0
+Version: 0.3.1
 Summary: SHDL (Simple Hardware Description Language) is a minimal HDL designed for creating digital circuits and easily simulating them. It compiles directly to C for maximum performance and portability. PySHDL is the Python interface for SHDL.
 Project-URL: Homepage, https://github.com/rafa-rrayes/SHDL
 Project-URL: Repository, https://github.com/rafa-rrayes/SHDL

{pyshdl-0.3.0 → pyshdl-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "PySHDL"
-version = "0.3.0"
+version = "0.3.1"
 description = "SHDL (Simple Hardware Description Language) is a minimal HDL designed for creating digital circuits and easily simulating them. It compiles directly to C for maximum performance and portability. PySHDL is the Python interface for SHDL."
 readme = "README.md"
 authors = [

{pyshdl-0.3.0 → pyshdl-0.3.1}/src/SHDL/bus_compiler/analyzer.py

@@ -114,12 +114,18 @@ class BusAnalyzer:
                 grouped_gates.add(gate.name)
                 gate_group_map[gate.name] = name
 
+        # Build position map: gate_name -> (group_name, position_in_group)
+        gate_position_map: dict[str, tuple[str, int]] = {}
+        for group in bus_groups:
+            for pos, gate in enumerate(group.gates):
+                gate_position_map[gate.name] = (group.name, pos)
+
         # Singletons
         singletons = [g for g in all_gates if g.name not in grouped_gates]
 
         # Step 4: Classify sources for each bus group
         for group in bus_groups:
-            self._classify_sources(group, gate_group_map)
+            self._classify_sources(group, gate_group_map, gate_position_map)
 
         # Step 5: SCC detection
         scc_map = self._detect_feedback(bus_groups)
@@ -215,7 +221,8 @@ class BusAnalyzer:
 
         return positions
 
-    def _classify_sources(self, group: BusGroup, gate_group_map: dict[str, str]):
+    def _classify_sources(self, group: BusGroup, gate_group_map: dict[str, str],
+                          gate_position_map: dict[str, tuple[str, int]]):
         """Classify each input port source for a bus group."""
         input_port_names = ["A", "B"] if group.primitive != "NOT" else ["A"]
 
@@ -228,12 +235,14 @@ class BusAnalyzer:
             if not wires or wires[0] is None:
                 continue
 
-            source = self._classify_wire_list(wires, group.bit_indices, gate_group_map)
+            source = self._classify_wire_list(wires, group.bit_indices, gate_group_map,
+                                              gate_position_map)
             group.input_sources[port_name] = source
 
     def _classify_wire_list(
         self, wires: list[WireRef], bit_indices: list[int],
-        gate_group_map: dict[str, str]
+        gate_group_map: dict[str, str],
+        gate_position_map: dict[str, tuple[str, int]]
     ) -> BusSource:
         """Classify a list of wires (one per gate in the group)."""
         if not wires or wires[0] is None:
@@ -275,7 +284,17 @@ class BusAnalyzer:
 
             if len(src_groups) == 1 and None not in src_groups:
                 group_name = src_groups.pop()
-                return BusSource(kind="bus_group", ref=group_name)
+                # Verify sequential alignment: source positions must be 0,1,2,...
+                positions = []
+                misaligned = False
+                for w in wires:
+                    info = gate_position_map.get(w.name)
+                    if info is None or info[0] != group_name:
+                        misaligned = True
+                        break
+                    positions.append(info[1])
+                if not misaligned and positions == list(range(len(positions))):
+                    return BusSource(kind="bus_group", ref=group_name)
 
         # Fallback: mixed
         return BusSource(kind="mixed", per_bit=list(wires))

pyshdl-0.3.1/src/SHDL/bus_compiler/compiler.py

@@ -0,0 +1,137 @@
+"""
+Bus Compiler Orchestration.
+
+Pipeline: Flattened Component -> ConnectionGraph -> BusAnalyzer -> BusCodeGenerator -> clang
+"""
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from ..compiler.compiler import CompileResult
+from .graph import ConnectionGraph
+from .analyzer import BusAnalyzer
+from .codegen import BusCodeGenerator
+from .debug_codegen import BusDebugCodeGenerator
+from .debug_info_gen import BusDebugInfoBuilder
+
+
+class BusCompiler:
+    """Compiles a flattened Component to C using bus-width operations."""
+
+    def compile(self, component) -> str:
+        """Generate C code from a flattened Component (expanded AST)."""
+        graph = ConnectionGraph.from_component(component)
+        analysis = BusAnalyzer(graph).analyze()
+        return BusCodeGenerator(analysis).generate()
+
+    def compile_debug(self, component) -> str:
+        """Generate C code with debug API from a flattened Component."""
+        graph = ConnectionGraph.from_component(component)
+        analysis = BusAnalyzer(graph).analyze()
+        return BusDebugCodeGenerator(analysis).generate()
+
+    def _analyze(self, component):
+        """Run the analysis pipeline, returning the AnalysisResult."""
+        graph = ConnectionGraph.from_component(component)
+        return BusAnalyzer(graph).analyze()
+
+    def compile_to_library(
+        self,
+        component,
+        output_path: str,
+        cc: str = "clang",
+        cflags: Optional[list[str]] = None,
+    ) -> CompileResult:
+        """Compile a flattened Component to a shared library."""
+        c_code = self.compile(component)
+
+        with tempfile.NamedTemporaryFile(
+            mode='w', suffix='.c', delete=False
+        ) as f:
+            f.write(c_code)
+            c_path = f.name
+
+        try:
+            default_flags = ["-O3", "-shared", "-fPIC"]
+            all_flags = default_flags + (cflags or [])
+            cmd = [cc] + all_flags + ["-o", output_path, c_path]
+
+            proc = subprocess.run(cmd, capture_output=True, text=True)
+
+            if proc.returncode != 0:
+                return CompileResult(
+                    success=False,
+                    c_code=c_code,
+                    errors=[f"C compilation failed: {proc.stderr}"],
+                )
+
+            return CompileResult(
+                success=True,
+                c_code=c_code,
+                library_path=output_path,
+            )
+        finally:
+            os.unlink(c_path)
+
+    def compile_to_library_debug(
+        self,
+        component,
+        output_path: str,
+        component_name: str = "",
+        source_path: str = "",
+        cc: str = "clang",
+        cflags: Optional[list[str]] = None,
+        generate_shdb: bool = True,
+    ) -> CompileResult:
+        """Compile a flattened Component to a shared library with debug support.
+
+        Produces:
+        - A shared library with peek_gate, peek_gate_previous, get_cycle
+        - A .shdb file with gate names, ports, hierarchy info
+        """
+        analysis = self._analyze(component)
+        c_code = BusDebugCodeGenerator(analysis).generate()
+
+        with tempfile.NamedTemporaryFile(
+            mode='w', suffix='.c', delete=False
+        ) as f:
+            f.write(c_code)
+            c_path = f.name
+
+        debug_info_path = None
+
+        try:
+            # Generate .shdb if requested
+            if generate_shdb:
+                lib_path = Path(output_path)
+                shdb_path = lib_path.with_suffix('.shdb')
+                builder = BusDebugInfoBuilder(analysis, source_file=source_path)
+                builder.set_component_name(component_name)
+                builder.save(str(shdb_path))
+                debug_info_path = str(shdb_path)
+
+            # Compile with -g for C debug symbols, -O1 for debug builds
+            default_flags = ["-g", "-O1", "-shared", "-fPIC"]
+            all_flags = default_flags + (cflags or [])
+            cmd = [cc] + all_flags + ["-o", output_path, c_path]
+
+            proc = subprocess.run(cmd, capture_output=True, text=True)
+
+            if proc.returncode != 0:
+                return CompileResult(
+                    success=False,
+                    c_code=c_code,
+                    errors=[f"C compilation failed: {proc.stderr}"],
+                )
+
+            return CompileResult(
+                success=True,
+                c_code=c_code,
+                library_path=output_path,
+                debug_info_path=debug_info_path,
+            )
+        finally:
+            os.unlink(c_path)

pyshdl-0.3.1/src/SHDL/bus_compiler/debug_codegen.py

@@ -0,0 +1,313 @@
+"""
+Debug-Aware Bus Code Generator.
+
+Extends BusCodeGenerator with debug features:
+- Gate name table mapping gate names to group/singleton + bit position
+- peek_gate() / peek_gate_previous() for inspecting internal gates
+- Cycle counter and get_cycle()
+- Previous state tracking for breakpoint change detection
+
+Key difference from parent: all bus group and singleton gate results are stored
+in static file-scope variables (not locals in tick), so peek_gate can read them.
+"""
+
+from ..compiler.ast import PrimitiveType
+from .codegen import BusCodeGenerator, _select_c_type, _width_mask
+from .analyzer import AnalysisResult, BusGroup
+
+
+class BusDebugCodeGenerator(BusCodeGenerator):
+    """Bus code generator with debug API additions.
+
+    Overrides _emit_group_eval and _emit_unit to assign to static globals
+    instead of declaring locals, so gate values persist after tick() returns.
+    """
+
+    def __init__(self, analysis: AnalysisResult):
+        super().__init__(analysis)
+        self._group_list: list[BusGroup] = []
+        self._group_idx: dict[str, int] = {}
+
+    def generate(self) -> str:
+        self._emit_header()
+        self._emit_state_struct()
+        self._emit_gate_globals()
+        self._emit_dut_context_debug()
+        self._emit_gate_table()
+        # Parent's tick — our overrides make it assign to statics
+        self._emit_tick_function()
+        self._emit_api_functions_debug()
+        self._emit_debug_api()
+        return self.output.getvalue()
+
+    # ── Gate globals (static file-scope vars) ──
+
+    def _emit_gate_globals(self):
+        """Emit static variables for all groups and singletons."""
+        self._group_list = list(self.analysis.bus_groups)
+        self._group_idx = {g.name: i for i, g in enumerate(self._group_list)}
+
+        self._w("/* Bus group values (persist between tick calls for debug) */")
+        for group in self._group_list:
+            c_type = _select_c_type(group.width)
+            self._w(f"static {c_type} {group.name};")
+            self._w(f"static {c_type} dbg_prev_{group.name};")
+
+        if self.analysis.singleton_gates:
+            self._w()
+            self._w("/* Singleton gate values */")
+            for gate in self.analysis.singleton_gates:
+                self._w(f"static uint8_t s_{gate.name};")
+                self._w(f"static uint8_t dbg_prev_s_{gate.name};")
+
+        self._w()
+
+    # ── DUT context (debug version with previous + cycle) ──
+
+    def _emit_dut_context_debug(self):
+        self._w("typedef struct {")
+        self._indent()
+        self._w("State current;")
+        self._w("State previous;")
+        for name, width in self.analysis.input_ports.items():
+            self._w(f"{_select_c_type(width)} input_{name};")
+        for name, width in self.analysis.output_ports.items():
+            self._w(f"{_select_c_type(width)} output_{name};")
+        self._w("int outputs_valid;")
+        self._w("uint64_t cycle_count;")
+        self._dedent()
+        self._w("} DutContext;")
+        self._w()
+        self._w("static DutContext dut = {0};")
+        self._w()
+
+    # ── Gate table ──
+
+    def _emit_gate_table(self):
+        """Emit gate lookup table: name -> (is_group, index, bit_pos)."""
+        self._w("typedef struct {")
+        self._indent()
+        self._w("const char *name;")
+        self._w("uint8_t is_group;")
+        self._w("uint16_t idx;")
+        self._w("uint8_t bit_pos;")
+        self._dedent()
+        self._w("} GateEntry;")
+        self._w()
+
+        entries: list[tuple[str, int, int, int]] = []
+
+        for group in self._group_list:
+            gidx = self._group_idx[group.name]
+            for pos, gate in enumerate(group.gates):
+                entries.append((gate.name, 1, gidx, pos))
+
+        for i, gate in enumerate(self.analysis.singleton_gates):
+            entries.append((gate.name, 0, i, 0))
+
+        self._w("static const GateEntry GATE_TABLE[] = {")
+        self._indent()
+        for name, is_grp, idx, bit in entries:
+            self._w(f'{{"{name}", {is_grp}, {idx}, {bit}}},')
+        if not entries:
+            self._w('{NULL, 0, 0, 0},')
+        self._dedent()
+        self._w("};")
+        self._w(f"static const size_t NUM_GATES = {len(entries)};")
+        self._w()
+
+    # ── Override group/unit emit to assign to statics ──
+
+    def _emit_group_eval(self, group: BusGroup, is_feedback: bool):
+        """Assign to static global instead of declaring a local."""
+        var = group.name
+        self._group_vars[group.name] = var
+
+        ptype = PrimitiveType.from_string(group.primitive)
+        mask = _width_mask(group.width)
+
+        a_expr = self._source_to_expr(group.input_sources.get("A"), group, is_feedback)
+        b_expr = self._source_to_expr(group.input_sources.get("B"), group, is_feedback)
+
+        if ptype == PrimitiveType.NOT:
+            self._w(f"{var} = (~({a_expr})) & {mask};")
+        elif ptype == PrimitiveType.AND:
+            self._w(f"{var} = ({a_expr}) & ({b_expr});")
+        elif ptype == PrimitiveType.OR:
+            self._w(f"{var} = ({a_expr}) | ({b_expr});")
+        elif ptype == PrimitiveType.XOR:
+            self._w(f"{var} = ({a_expr}) ^ ({b_expr});")
+
+    def _emit_unit(self, unit):
+        """Assign to static global instead of declaring a local."""
+        if isinstance(unit, BusGroup):
+            self._emit_group_eval(unit, is_feedback=False)
+        else:
+            var = f"s_{unit.name}"
+            self._singleton_vars[unit.name] = var
+            expr = self._build_singleton_expr(unit)
+            self._w(f"{var} = {expr};")
+
+    # ── API functions (debug versions) ──
+
+    def _emit_api_functions_debug(self):
+        self._emit_reset_debug()
+        self._emit_poke()   # parent's
+        self._emit_peek()   # parent's
+        self._emit_step_debug()
+
+    def _emit_reset_debug(self):
+        self._w("void reset(void) {")
+        self._indent()
+        self._w("memset(&dut, 0, sizeof(dut));")
+        # Zero all static gate variables
+        for group in self._group_list:
+            self._w(f"{group.name} = 0;")
+            self._w(f"dbg_prev_{group.name} = 0;")
+        for gate in self.analysis.singleton_gates:
+            self._w(f"s_{gate.name} = 0;")
+            self._w(f"dbg_prev_s_{gate.name} = 0;")
+        self._dedent()
+        self._w("}")
+        self._w()
+
+    def _emit_step_debug(self):
+        self._w("void step(int cycles) {")
+        self._indent()
+        self._w("for (int i = 0; i < cycles; ++i) {")
+        self._indent()
+
+        # Save previous state for breakpoint detection
+        self._w("dut.previous = dut.current;")
+        for group in self._group_list:
+            self._w(f"dbg_prev_{group.name} = {group.name};")
+        for gate in self.analysis.singleton_gates:
+            self._w(f"dbg_prev_s_{gate.name} = s_{gate.name};")
+
+        self._w("tick();")
+        self._w("dut.cycle_count++;")
+        self._dedent()
+        self._w("}")
+        self._w("dut.outputs_valid = 1;")
+        self._dedent()
+        self._w("}")
+        self._w()
+
+    # ── Debug API functions ──
+
+    def _emit_debug_api(self):
+        self._emit_get_cycle()
+        self._emit_peek_gate()
+        self._emit_peek_gate_previous()
+        self._emit_get_num_gates()
+
+    def _emit_get_cycle(self):
+        self._w("uint64_t get_cycle(void) {")
+        self._indent()
+        self._w("return dut.cycle_count;")
+        self._dedent()
+        self._w("}")
+        self._w()
+
+    def _emit_peek_gate(self):
+        self._w("uint64_t peek_gate(const char *gate_name) {")
+        self._indent()
+
+        # Ensure circuit is evaluated
+        self._w("if (!dut.outputs_valid) {")
+        self._indent()
+        self._w("tick();")
+        self._w("dut.outputs_valid = 1;")
+        self._dedent()
+        self._w("}")
+        self._w()
+
+        self._w("for (size_t i = 0; i < NUM_GATES; i++) {")
+        self._indent()
+        self._w("if (strcmp(GATE_TABLE[i].name, gate_name) == 0) {")
+        self._indent()
+
+        self._w("if (GATE_TABLE[i].is_group) {")
+        self._indent()
+        self._w("uint64_t val;")
+        self._emit_group_switch("val", is_prev=False)
+        self._w("return (val >> GATE_TABLE[i].bit_pos) & 1ull;")
+        self._dedent()
+
+        self._w("} else {")
+        self._indent()
+        self._emit_singleton_switch(is_prev=False)
+        self._dedent()
+        self._w("}")
+
+        self._dedent()
+        self._w("}")
+        self._dedent()
+        self._w("}")
+        self._w()
+        self._w("return 0ull;")
+        self._dedent()
+        self._w("}")
+        self._w()
+
+    def _emit_peek_gate_previous(self):
+        self._w("uint64_t peek_gate_previous(const char *gate_name) {")
+        self._indent()
+
+        self._w("for (size_t i = 0; i < NUM_GATES; i++) {")
+        self._indent()
+        self._w("if (strcmp(GATE_TABLE[i].name, gate_name) == 0) {")
+        self._indent()
+
+        self._w("if (GATE_TABLE[i].is_group) {")
+        self._indent()
+        self._w("uint64_t val;")
+        self._emit_group_switch("val", is_prev=True)
+        self._w("return (val >> GATE_TABLE[i].bit_pos) & 1ull;")
+        self._dedent()
+
+        self._w("} else {")
+        self._indent()
+        self._emit_singleton_switch(is_prev=True)
+        self._dedent()
+        self._w("}")
+
+        self._dedent()
+        self._w("}")
+        self._dedent()
+        self._w("}")
+        self._w()
+        self._w("return 0ull;")
+        self._dedent()
+        self._w("}")
+        self._w()
+
+    def _emit_get_num_gates(self):
+        self._w("size_t get_num_gates(void) {")
+        self._indent()
+        self._w("return NUM_GATES;")
+        self._dedent()
+        self._w("}")
+        self._w()
+
+    # ── Helpers for peek_gate switch statements ──
+
+    def _emit_group_switch(self, target_var: str, is_prev: bool):
+        prefix = "dbg_prev_" if is_prev else ""
+        self._w("switch (GATE_TABLE[i].idx) {")
+        self._indent()
+        for idx, group in enumerate(self._group_list):
+            self._w(f"case {idx}: {target_var} = {prefix}{group.name}; break;")
+        self._w(f"default: {target_var} = 0; break;")
+        self._dedent()
+        self._w("}")
+
+    def _emit_singleton_switch(self, is_prev: bool):
+        prefix = "dbg_prev_s_" if is_prev else "s_"
+        self._w("switch (GATE_TABLE[i].idx) {")
+        self._indent()
+        for idx, gate in enumerate(self.analysis.singleton_gates):
+            self._w(f"case {idx}: return (uint64_t){prefix}{gate.name};")
+        self._w("default: return 0ull;")
+        self._dedent()
+        self._w("}")

pyshdl-0.3.1/src/SHDL/bus_compiler/debug_info_gen.py

@@ -0,0 +1,96 @@
+"""
+Debug Info Generator for Bus Compiler.
+
+Generates .shdb debug info files from bus compiler AnalysisResult,
+matching the format expected by the debugger (DebugInfo).
+"""
+
+from pathlib import Path
+import json
+
+from .analyzer import AnalysisResult
+
+
+class BusDebugInfoBuilder:
+    """Builds .shdb debug info from bus compiler analysis."""
+
+    def __init__(self, analysis: AnalysisResult, source_file: str = ""):
+        self.analysis = analysis
+        self.source_file = source_file
+        self.component_name = ""
+
+    def set_component_name(self, name: str) -> "BusDebugInfoBuilder":
+        self.component_name = name
+        return self
+
+    def build(self) -> dict:
+        """Build the debug info dictionary."""
+        gates = {}
+
+        # Gates from bus groups
+        for group in self.analysis.bus_groups:
+            for pos, gate in enumerate(group.gates):
+                gates[gate.name] = {
+                    "type": gate.primitive,
+                    "lane": pos,
+                    "chunk": 0,  # Bus compiler doesn't use chunk/lane packing
+                    "hierarchy_path": self._infer_hierarchy(gate.name),
+                    "original_name": self._extract_original(gate.name),
+                    "parent_instance": self._extract_parent(gate.name),
+                }
+
+        # Singleton gates
+        for gate in self.analysis.singleton_gates:
+            gates[gate.name] = {
+                "type": gate.primitive,
+                "lane": 0,
+                "chunk": 0,
+                "hierarchy_path": self._infer_hierarchy(gate.name),
+                "original_name": self._extract_original(gate.name),
+                "parent_instance": self._extract_parent(gate.name),
+            }
+
+        return {
+            "version": "1.0",
+            "component": self.component_name,
+            "source_file": self.source_file,
+            "ports": {
+                "inputs": [
+                    {"name": name, "width": width, "source_line": 0, "source_column": 0}
+                    for name, width in self.analysis.input_ports.items()
+                ],
+                "outputs": [
+                    {"name": name, "width": width, "source_line": 0, "source_column": 0}
+                    for name, width in self.analysis.output_ports.items()
+                ],
+            },
+            "hierarchy": {},
+            "gates": gates,
+            "connections": [],
+            "constants": {},
+            "source_map": {},
+        }
+
+    def save(self, path: str) -> None:
+        """Save to a .shdb file."""
+        data = self.build()
+        with open(path, "w") as f:
+            json.dump(data, f, indent=2)
+
+    def _infer_hierarchy(self, gate_name: str) -> str:
+        if "_" in gate_name:
+            parts = gate_name.split("_")
+            return f"{self.component_name}/" + "/".join(parts)
+        return f"{self.component_name}/{gate_name}"
+
+    def _extract_original(self, gate_name: str) -> str:
+        if "_" in gate_name:
+            return gate_name.split("_")[-1]
+        return gate_name
+
+    def _extract_parent(self, gate_name: str) -> str:
+        if "_" in gate_name:
+            parts = gate_name.split("_")
+            if len(parts) > 1:
+                return "_".join(parts[:-1])
+        return ""