PySHDL 0.1.0__py3-none-any.whl

PySHDL/__init__.py

@@ -0,0 +1,21 @@
+"""shdl library."""
+
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, version
+
+from .circuit import Circuit
+from .shdlc import Component, Instance, Port, SHDLParser, generate_c_code
+
+__all__ = [
+    "Circuit",
+    "Component",
+    "Instance",
+    "Port",
+    "SHDLParser",
+    "generate_c_code",
+    "__version__",
+]
+try:
+    __version__ = version("shdl")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

PySHDL/circuit.py

@@ -0,0 +1,180 @@
+"""
+SHDL Driver - Simple Python interface for SHDL circuits
+========================================================
+
+A minimal module for compiling and driving SHDL circuits from Python.
+Provides a clean, Pythonic API for circuit simulation.
+
+Usage:
+    from shdl_driver import SHDLCircuit
+    
+    # Load and compile a circuit
+    circuit = SHDLCircuit("adder16.shdl")
+    
+    # Set inputs
+    circuit.poke("A", 42)
+    circuit.poke("B", 17)
+    circuit.poke("Cin", 1)
+    
+    # Read outputs
+    result = circuit.peek("Sum")
+    print(f"42 + 17 + 1 = {result}")
+    
+    # Advance simulation time
+    circuit.step(1)
+"""
+
+import ctypes
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Dict, Optional, Union
+
+
+class Circuit:
+    """
+    Interface for driving SHDL circuits from Python.
+    
+    Compiles SHDL to C, builds a shared library, and provides
+    Python wrappers for the circuit API.
+    """
+    
+    def __init__(self, shdl_file: Union[str, Path], search_paths: Optional[list] = None):
+        """
+        Load and compile a SHDL circuit.
+        
+        Args:
+            shdl_file: Path to the .shdl file
+            search_paths: Optional list of directories to search for imports
+        """
+        self.shdl_file = Path(shdl_file)
+        if not self.shdl_file.exists():
+            raise FileNotFoundError(f"SHDL file not found: {shdl_file}")
+        
+        # Default search path includes SHDL_components if it exists
+        if search_paths is None:
+            search_paths = []
+            component_dir = self.shdl_file.parent / "SHDL_components"
+            if component_dir.exists():
+                search_paths.append(str(component_dir))
+        
+        self.search_paths = search_paths
+        self._lib = None
+        self._compile_and_load()
+    
+    def _compile_and_load(self):
+        """Compile SHDL to C and load the shared library."""
+        # Generate C code
+        c_file = self.shdl_file.with_suffix('.c')
+        self._compile_shdl_to_c(c_file)
+        
+        # Build shared library
+        so_file = self._build_shared_library(c_file)
+        
+        # Load library
+        self._lib = ctypes.CDLL(str(so_file))
+        
+        # Set up function signatures
+        self._lib.reset.argtypes = []
+        self._lib.reset.restype = None
+        
+        self._lib.poke.argtypes = [ctypes.c_char_p, ctypes.c_uint64]
+        self._lib.poke.restype = None
+        
+        self._lib.peek.argtypes = [ctypes.c_char_p]
+        self._lib.peek.restype = ctypes.c_uint64
+        
+        self._lib.step.argtypes = [ctypes.c_int]
+        self._lib.step.restype = None
+        
+        # Initialize circuit
+        self.reset()
+    
+    def _compile_shdl_to_c(self, output_file: Path):
+        """Compile SHDL file to C using shdlc compiler."""
+        # Look for shdlc in the same directory as the SHDL file
+        from .shdlc import generate_c_code, SHDLParser
+        shdl_parser = SHDLParser(self.search_paths)
+        component = shdl_parser.parse_file(self.shdl_file)
+        component = shdl_parser.flatten_all_levels(component)
+        c_code = generate_c_code(component)
+        with open(output_file, 'w') as f:
+            f.write(c_code)
+            
+    def _build_shared_library(self, c_file: Path) -> Path:
+        """Build a shared library from C code."""
+        so_file = c_file.with_suffix('.so')
+        
+        cmd = [
+            "gcc",
+            "-shared",
+            "-fPIC",
+            "-O2",
+            "-o", str(so_file),
+            "-xc", str(c_file)
+        ]
+        
+        try:
+            subprocess.run(cmd, check=True, capture_output=True, text=True)
+        except subprocess.CalledProcessError as e:
+            raise RuntimeError(
+                f"Failed to build shared library:\n{e.stderr}"
+            )
+        
+        return so_file
+    
+    def reset(self):
+        """Reset all circuit state to zero."""
+        self._lib.reset()
+    
+    def poke(self, signal: str, value: int):
+        """
+        Set an input signal to a specific value.
+        
+        Args:
+            signal: Name of the input signal
+            value: Integer value to set
+        """
+        self._lib.poke(signal.encode('utf-8'), value)
+    
+    def peek(self, signal: str) -> int:
+        """
+        Read the current value of a signal.
+        
+        Args:
+            signal: Name of the signal (input or output)
+            
+        Returns:
+            Current value as an integer
+        """
+        return self._lib.peek(signal.encode('utf-8'))
+    
+    def step(self, cycles: int = 1):
+        """
+        Advance simulation by the specified number of cycles.
+        
+        Args:
+            cycles: Number of clock cycles to advance (default: 1)
+        """
+        self._lib.step(cycles)
+
+    
+    def test(self, inputs: Dict[str, int], steps: int) -> Dict[str, int]:
+        """
+        Convenience method: set inputs and return all outputs.
+        
+        Args:
+            inputs: Dictionary mapping signal names to values
+            
+        Returns:
+            Dictionary with the same keys containing output values
+        """
+        # Set all inputs
+        for signal, value in inputs.items():
+            self.poke(signal, value)
+        
+        self.step(steps)
+        
+        # Read back the same signals
+        return {signal: self.peek(signal) for signal in inputs.keys()}

PySHDL/cli.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""
+SHDL Compiler - Command-line interface
+Usage: shdlc [options] <input.shdl>
+"""
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from .shdlc import SHDLParser, generate_c_code
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description='SHDL Compiler - Compile SHDL hardware description files to C',
+        usage='%(prog)s [options] <input.shdl>'
+    )
+    
+    parser.add_argument(
+        'input',
+        help='Input SHDL file'
+    )
+    
+    parser.add_argument(
+        '-o', '--output',
+        help='Output C file (default: <input>.c)',
+        default=None
+    )
+    
+    parser.add_argument(
+        '-I', '--include',
+        action='append',
+        dest='include_paths',
+        help='Add directory to component search path',
+        default=[]
+    )
+    
+    parser.add_argument(
+        '-c', '--compile-only',
+        action='store_true',
+        help='Generate C code only, do not compile to binary'
+    )
+    
+    parser.add_argument(
+        '-O', '--optimize',
+        choices=['0', '1', '2', '3'],
+        default='3',
+        help='GCC optimization level (default: 3)'
+    )
+    
+    parser.add_argument(
+        '--no-flatten',
+        action='store_true',
+        help='Do not flatten component hierarchy'
+    )
+    
+    parser.add_argument(
+        '-v', '--verbose',
+        action='store_true',
+        help='Verbose output'
+    )
+    
+    args = parser.parse_args()
+    
+    # Validate input file
+    input_path = Path(args.input)
+    if not input_path.exists():
+        print(f"shdlc: error: {args.input}: No such file", file=sys.stderr)
+        return 1
+    
+    if not input_path.suffix == '.shdl':
+        print(f"shdlc: warning: {args.input}: File does not have .shdl extension", file=sys.stderr)
+    
+    # Determine output file
+    if args.output:
+        output_c = Path(args.output)
+        if not output_c.suffix == '.c' and not args.compile_only:
+            # Binary output
+            output_bin = output_c
+            output_c = input_path.with_suffix('.c')
+        else:
+            output_bin = output_c.with_suffix('')
+    else:
+        output_c = input_path.with_suffix('.c')
+        output_bin = input_path.with_suffix('')
+    
+    # Setup search paths
+    search_paths = [input_path.parent]
+    
+    # Add SHDL_components if it exists
+    default_lib = input_path.parent / "SHDL_components"
+    if default_lib.exists():
+        search_paths.append(default_lib)
+    
+    # Add user-specified include paths
+    for inc_path in args.include_paths:
+        search_paths.append(Path(inc_path))
+    
+    if args.verbose:
+        print(f"Input: {input_path}")
+        print(f"Output C: {output_c}")
+        if not args.compile_only:
+            print(f"Output binary: {output_bin}")
+        print(f"Search paths: {[str(p) for p in search_paths]}")
+    
+    try:
+        # Parse SHDL file
+        if args.verbose:
+            print("Parsing SHDL file...")
+        
+        shdl_parser = SHDLParser(search_paths)
+        component = shdl_parser.parse_file(input_path)
+        
+        if args.verbose:
+            print(f"  Component: {component.name}")
+            print(f"  Instances: {len(component.instances)}")
+            print(f"  Connections: {len(component.connections)}")
+        
+        # Flatten component hierarchy
+        if not args.no_flatten:
+            if args.verbose:
+                print("Flattening component hierarchy...")
+            
+            component = shdl_parser.flatten_all_levels(component)
+            
+            if args.verbose:
+                print(f"  Instances after flattening: {len(component.instances)}")
+                print(f"  Connections after flattening: {len(component.connections)}")
+                print(f"  Gate types: {set(i.component_type for i in component.instances)}")
+        
+        # Generate C code
+        if args.verbose:
+            print("Generating C code...")
+        
+        c_code = generate_c_code(component)
+
+        with open(output_c, 'w', encoding='utf-8') as file_handle:
+            file_handle.write(c_code)
+        
+        if args.verbose:
+            print(f"  Generated {output_c} ({len(c_code)} bytes)")
+        
+        # Compile to binary
+        if not args.compile_only:
+            if args.verbose:
+                print("Compiling C code to binary...")
+            
+            # gcc -shared -fPIC -O3 your_design.c -o your_design.so
+            gcc_cmd = [
+                'gcc',
+                '-shared',
+                '-fPIC',
+                f'-O{args.optimize}',
+                str(output_c),
+                '-o', str(output_bin)+".so"
+            ]
+            
+            if args.verbose:
+                print(f"  Command: {' '.join(gcc_cmd)}")
+            
+            result = subprocess.run(gcc_cmd, capture_output=True, text=True)
+            
+            if result.returncode != 0:
+                print(f"shdlc: error: gcc compilation failed", file=sys.stderr)
+                if result.stderr:
+                    print(result.stderr, file=sys.stderr)
+                return 1
+            
+            if args.verbose:
+                print(f"  Generated binary: {output_bin}")
+        
+        if not args.verbose:
+            # Mimic gcc's quiet success
+            pass
+        else:
+            print("Done!")
+        
+        return 0
+        
+    except Exception as e:
+        print(f"shdlc: error: {e}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())