diagnose_neoram.py

#!/usr/bin/env python3
"""
NeoRAM System Diagnostic Tool

This script checks for common issues in the NeoRAM project and helps identify
problems with the setup, configuration, and code.
"""

import argparse
import glob
import json
import os
import subprocess
import sys


# ANSI colors for terminal output
class Colors:
    HEADER = '\033[95m'
    BLUE = '\033[94m'
    GREEN = '\033[92m'
    YELLOW = '\033[93m'
    RED = '\033[91m'
    END = '\033[0m'
    BOLD = '\033[1m'
    UNDERLINE = '\033[4m'

def print_header(text):
    """Print a formatted header"""
    print(f"\n{Colors.HEADER}{Colors.BOLD}=== {text} ==={Colors.END}")

def print_success(text):
    """Print success message"""
    print(f"{Colors.GREEN}✓ {text}{Colors.END}")

def print_warning(text):
    """Print warning message"""
    print(f"{Colors.YELLOW}⚠ {text}{Colors.END}")

def print_error(text):
    """Print error message"""
    print(f"{Colors.RED}✗ {text}{Colors.END}")

def print_info(text):
    """Print info message"""
    print(f"{Colors.BLUE}ℹ {text}{Colors.END}")

def run_command(cmd, capture_output=True):
    """Run a shell command and return result"""
    try:
        if capture_output:
            result = subprocess.run(cmd, capture_output=True, check=False, text=True)
            return result
        else:
            subprocess.run(cmd, check=False)
            return None
    except Exception as e:
        print_error(f"Failed to execute command {cmd}: {e}")
        return None

def check_directories():
    """Check if all required directories exist."""
    print_header("Checking Directory Structure")
    required_dirs = ["rtl", "tb", "sim", "scripts", "docs", "fusesoc_libraries"]
    missing_dirs = []

    for d in required_dirs:
        if not os.path.isdir(d):
            missing_dirs.append(d)
            print_error(f"Required directory '{d}' not found")
        else:
            print_success(f"Found directory '{d}'")

    if missing_dirs:
        print_warning(f"{len(missing_dirs)} directories missing. Creating them...")
        for d in missing_dirs:
            os.makedirs(d, exist_ok=True)
            print_info(f"Created directory '{d}'")

    return len(missing_dirs) == 0

def check_files():
    """Check if all required files exist."""
    print_header("Checking Required Files")

    # SystemVerilog files
    sv_files = {
        "rtl/neoram_wrapper.sv": "NeoRAM wrapper module",
        "rtl/neoram_controller.sv": "NeoRAM controller module",
        "rtl/ecc_encoder.sv": "ECC encoder module",
        "rtl/ecc_decoder.sv": "ECC decoder module",
        "rtl/power_manager.sv": "Power manager module",
        "rtl/multi_port_arbiter.sv": "Multi-port arbiter module"
    }

    # Python files
    py_files = {
        "tb/neoram_model.py": "NeoRAM model for testbench",
        "tb/neoram_system_tb.py": "NeoRAM system testbench",
        "tb/test_neoram_system.py": "Test cases for NeoRAM system",
        "scripts/generate_neoram_config.py": "Configuration generator script"
    }

    # Other files
    other_files = {
        "sim/Makefile": "Simulation Makefile",
        "requirements.txt": "Python dependencies",
        "neoram_config.json": "NeoRAM configuration"
    }

    file_categories = [
        ("SystemVerilog Files", sv_files),
        ("Python Files", py_files),
        ("Other Files", other_files)
    ]

    all_present = True

    for category_name, files in file_categories:
        print_info(f"\nChecking {category_name}:")
        for file_path, description in files.items():
            if os.path.isfile(file_path):
                print_success(f"Found {file_path} ({description})")
            else:
                print_error(f"Missing {file_path} ({description})")
                all_present = False

    return all_present

def check_submodules():
    """Check if submodules are initialized and updated."""
    print_header("Checking Git Submodules")

    if not os.path.isfile(".gitmodules"):
        print_warning("No .gitmodules file found. Skipping submodule check.")
        return True

    # Check Sky130 SRAM macros
    sram_path = "fusesoc_libraries/sky130_sram_macros"
    if not os.path.isdir(sram_path):
        print_error(f"Sky130 SRAM macros not found at {sram_path}")
        print_info("Run 'git submodule init && git submodule update' to fetch submodules")
        return False

    # Check if the SRAM macro Verilog file exists
    sram_vfile = f"{sram_path}/sky130_sram_1kbyte_1rw1r_32x256_8/sky130_sram_1kbyte_1rw1r_32x256_8.v"
    if not os.path.isfile(sram_vfile):
        print_error(f"SRAM Verilog model not found at {sram_vfile}")
        return False

    print_success(f"Found Sky130 SRAM macros at {sram_path}")
    return True

def check_config():
    """Check if the configuration file exists and is valid."""
    print_header("Checking Configuration")

    config_path = "neoram_config.json"
    if not os.path.isfile(config_path):
        print_warning(f"{config_path} not found")
        print_info("Will be generated during setup")
        return True

    try:
        with open(config_path) as f:
            config = json.load(f)

        required_keys = ["NUM_PORTS", "ADDR_WIDTH", "DATA_WIDTH", "SRAM_DEPTH"]
        missing_keys = [key for key in required_keys if key not in config]

        if missing_keys:
            print_error(f"Configuration file is missing keys: {', '.join(missing_keys)}")
            return False

        print_success("Configuration file contains all required keys")
        print_info("Configuration values:")
        for k, v in config.items():
            print(f"  - {k}: {v}")

        return True
    except json.JSONDecodeError:
        print_error(f"{config_path} is not valid JSON")
        return False

def check_dependencies():
    """Check if required tools and packages are installed."""
    print_header("Checking Dependencies")

    # Check Python version
    python_version = sys.version_info
    if python_version.major < 3 or (python_version.major == 3 and python_version.minor < 6):
        print_error(f"Python version {python_version.major}.{python_version.minor} is too old")
        print_info("Python 3.6 or newer is required")
    else:
        print_success(f"Python version {python_version.major}.{python_version.minor}.{python_version.micro}")

    # Check Python packages
    required_packages = ["cocotb", "pytest", "cocotb-bus", "cocotb-test"]
    missing_packages = []

    for package in required_packages:
        try:
            __import__(package.replace("-", "_"))
            print_success(f"Found Python package: {package}")
        except ImportError:
            missing_packages.append(package)
            print_error(f"Missing Python package: {package}")

    if missing_packages:
        packages_str = " ".join(missing_packages)
        print_info(f"Install missing packages with: pip install {packages_str}")

    # Check for Verilog simulator
    simulator_found = False
    for simulator in ["iverilog", "verilator"]:
        result = run_command(["which", simulator])
        if result and result.returncode == 0:
            print_success(f"Found Verilog simulator: {simulator}")
            simulator_found = True
            break

    if not simulator_found:
        print_error("No Verilog simulator found")
        print_info("Install Icarus Verilog:")
        print_info("  - macOS: brew install icarus-verilog")
        print_info("  - Linux: sudo apt-get install iverilog")

    # Check for waveform viewer based on platform
    if sys.platform == "darwin":  # macOS
        result = run_command(["which", "surfer"])
        if result and result.returncode == 0:
            print_success("Found waveform viewer: surfer")
        else:
            print_warning("Surfer waveform viewer not found")
            print_info("Install with: brew install surfer")
    else:
        result = run_command(["which", "gtkwave"])
        if result and result.returncode == 0:
            print_success("Found waveform viewer: gtkwave")
        else:
            print_warning("GTKWave not found")
            print_info("Install GTKWave for viewing waveforms")

    return True

def check_sv_syntax():
    """Check SystemVerilog files for potential syntax issues."""
    print_header("Checking SystemVerilog Files")

    sv_files = glob.glob("rtl/*.sv")
    if not sv_files:
        print_warning("No SystemVerilog files found in rtl/ directory")
        return False

    # Check each file for basic syntax
    issues_found = False
    for sv_file in sv_files:
        with open(sv_file) as f:
            content = f.read()

        # Check for common issues
        issues = []

        # Check module declarations
        module_name = os.path.basename(sv_file).replace(".sv", "")
        if f"module {module_name}" not in content:
            issues.append(f"Module name '{module_name}' doesn't match filename")

        # Check for incomplete process blocks
        if content.count("begin") != content.count("end"):
            issues.append("Unbalanced begin/end blocks")

        # Check for incomplete conditional statements
        if content.count("if") != content.count("end") - content.count("begin"):
            issues.append("Potentially incomplete if statements")

        # Check for missing semicolons after end
        if "end;" not in content and "end " in content:
            issues.append("Missing semicolons after 'end' statements")

        # Check port declarations
        if "input" in content and "output" not in content:
            issues.append("Module has inputs but no outputs")

        if issues:
            print_error(f"Potential issues in {sv_file}:")
            for issue in issues:
                print(f"  - {issue}")
            issues_found = True
        else:
            print_success(f"No obvious issues found in {sv_file}")

    return not issues_found

def check_python_syntax():
    """Check Python files for syntax errors."""
    print_header("Checking Python Files")

    py_files = glob.glob("tb/*.py") + glob.glob("scripts/*.py")
    if not py_files:
        print_warning("No Python files found in tb/ or scripts/ directories")
        return False

    all_ok = True
    for py_file in py_files:
        result = run_command(["python3", "-m", "py_compile", py_file])
        if result and result.returncode == 0:
            print_success(f"Python syntax check passed: {py_file}")
        else:
            print_error(f"Python syntax check failed: {py_file}")
            if result and result.stderr:
                print(f"  Error: {result.stderr.strip()}")
            all_ok = False

    return all_ok

def check_makefile():
    """Check if Makefile is set up correctly."""
    print_header("Checking Makefile")

    makefile_path = "sim/Makefile"
    if not os.path.isfile(makefile_path):
        print_error(f"Makefile not found at {makefile_path}")
        return False

    with open(makefile_path) as f:
        makefile_content = f.read()

    # Check for required elements
    required_elements = [
        ("TOPLEVEL", "Top-level module definition"),
        ("MODULE", "Python test module definition"),
        ("VERILOG_SOURCES", "Verilog source files"),
        ("include", "Cocotb Makefile inclusion")
    ]

    for element, description in required_elements:
        if element not in makefile_content:
            print_error(f"Missing {description} in Makefile")
            return False

    # Check for OS detection for waveform viewer
    if "uname" not in makefile_content and ("surfer" in makefile_content or "gtkwave" in makefile_content):
        print_warning("Makefile doesn't detect OS for waveform viewer selection")

    print_success("Makefile appears to be set up correctly")
    return True

def check_common_issues():
    """Check for common issues in the NeoRAM project"""
    print_header("Checking for Common Issues")

    # List of common issues to check (updated for v1.3.0)
    issues = [
        {
            "name": "Ready signal undefined states",
            "files": ["rtl/multi_port_arbiter.sv"],
            "pattern": "ready = grant",
            "description": "Ready signal might have undefined 'x' states without proper initialization"
        },
        {
            "name": "Data width inconsistencies",
            "files": ["rtl/neoram_controller.sv"],
            "pattern": "DATA_WIDTH = 39",
            "description": "Controller should use 32-bit data width for consistency"
        },
        {
            "name": "Genvar naming conflicts",
            "files": ["rtl/neoram_wrapper.sv"],
            "pattern": "genvar i;.*genvar i;",
            "description": "Multiple genvar declarations with same name"
        },
        {
            "name": "ECC bypass mode issues",
            "files": ["rtl/neoram_controller.sv"],
            "pattern": "sram_din_reg",
            "description": "ECC logic might interfere with bypass mode operation"
        }
    ]

    issues_found = False
    for issue in issues:
        for file_pattern in issue["files"]:
            for file_path in glob.glob(file_pattern):
                if os.path.isfile(file_path):
                    with open(file_path) as f:
                        content = f.read()

                    if issue["pattern"] in content:
                        print_error(f"{issue['name']} in {file_path}")
                        print(f"  Description: {issue['description']}")
                        issues_found = True

    if not issues_found:
        print_success("No common issues found")

    return not issues_found

def fix_files(args):
    """Apply fixes to common issues"""
    print_header("Applying Fixes")

    # Only apply fixes if the user specifically requested them
    if not args.fix:
        print_info("Use --fix to apply automatic fixes to common issues")
        return

    # List of fixes to apply
    fixes = [
        {
            "file": "sim/Makefile",
            "search": "gtkwave",
            "replace": "ifeq ($(shell uname), Darwin)\n\t@surfer $(VCD_FILE) &\nelse\n\t@gtkwave $(VCD_FILE) &\nendif",
            "description": "Update Makefile to use Surfer on macOS"
        },
        {
            "file": "rtl/neoram_controller.sv",
            "search": ".sram_din(write_data)",
            "replace": ".sram_din(encoded_data)",
            "description": "Fix controller signal width mismatch"
        },
        {
            "file": "tb/neoram_system_tb.py",
            "search": "self.neoram_model = NeoRAMModel(depth=self.config['depth'], width=self.config['width'])",
            "replace": "depth = config.get('SRAM_DEPTH', 256)\nwidth = config.get('DATA_WIDTH', 32)\nself.neoram_model = NeoRAMModel(depth=depth, width=width)",
            "description": "Fix configuration key access in testbench"
        }
    ]

    fixes_applied = 0
    for fix in fixes:
        file_path = fix["file"]
        if not os.path.isfile(file_path):
            print_warning(f"Cannot apply fix: {file_path} not found")
            continue

        with open(file_path) as f:
            content = f.read()

        if fix["search"] in content:
            new_content = content.replace(fix["search"], fix["replace"])
            with open(file_path, "w") as f:
                f.write(new_content)
            print_success(f"Applied fix to {file_path}: {fix['description']}")
            fixes_applied += 1
        else:
            print_info(f"No need to apply fix to {file_path}: pattern not found")

    print_info(f"Applied {fixes_applied} fixes")

def create_missing_files(args):
    """Create missing essential files if requested"""
    if not args.create_missing:
        return

    print_header("Creating Missing Files")

    # Define templates for essential files (updated for v1.3.0)
    templates = {
        "requirements.txt": """# requirements.txt for NeoRAM project

# Simulation and verification
cocotb>=1.6.0
cocotb-bus>=0.1.1
cocotb-test>=0.2.0

# Testing
pytest>=6.0.0
pytest-cov>=2.10.0
""",
        "neoram_config.json": """{
  "NUM_PORTS": 2,
  "ADDR_WIDTH": 8,
  "DATA_WIDTH": 32,
  "SRAM_DEPTH": 256,
  "ECC_ENABLED": true,
  "POWER_MANAGEMENT_ENABLED": true,
  "ROUND_ROBIN_ARBITRATION": true,
  "READY_SIGNAL_INIT": true
}
"""
    }

    # Check and create each file if missing
    created_count = 0
    for file_path, content in templates.items():
        if not os.path.isfile(file_path):
            # Ensure directory exists
            os.makedirs(os.path.dirname(file_path), exist_ok=True)

            # Create the file
            with open(file_path, "w") as f:
                f.write(content)

            print_success(f"Created missing file: {file_path}")
            created_count += 1

    if created_count == 0:
        print_info("No essential files needed to be created")
    else:
        print_info(f"Created {created_count} missing files")

def main():
    """Main function to run diagnostics and fixes"""
    parser = argparse.ArgumentParser(description="NeoRAM System Diagnostic Tool")
    parser.add_argument("--fix", action="store_true", help="Apply fixes to common issues")
    parser.add_argument("--create-missing", action="store_true", help="Create missing essential files")
    parser.add_argument("--verbose", action="store_true", help="Show detailed output")
    args = parser.parse_args()

    print_header("NeoRAM System Diagnostic Tool")

    checks = [
        ("Directory Structure", check_directories),
        ("Required Files", check_files),
        ("Git Submodules", check_submodules),
        ("Configuration", check_config),
        ("Dependencies", check_dependencies),
        ("SystemVerilog Syntax", check_sv_syntax),
        ("Python Syntax", check_python_syntax),
        ("Makefile", check_makefile),
        ("Common Issues", check_common_issues)
    ]

    results = {}
    for name, check_func in checks:
        print_info(f"\nRunning check: {name}")
        result = check_func()
        results[name] = result

    # Create missing files if requested
    create_missing_files(args)

    # Apply fixes if requested
    fix_files(args)

    # Summary
    print_header("Summary")
    success_count = sum(1 for result in results.values() if result)
    total_count = len(results)

    for name, result in results.items():
        status = f"{Colors.GREEN}PASS{Colors.END}" if result else f"{Colors.RED}FAIL{Colors.END}"
        print(f"{status} - {name}")

    if success_count == total_count:
        print_success(f"\nAll {total_count} checks passed!")
        print_info("\nYour NeoRAM project appears to be set up correctly.")
        print_info("To run the simulation:")
        print("  1. cd sim")
        print("  2. make clean")
        print("  3. make sim")
    else:
        print_warning(f"\n{success_count} of {total_count} checks passed.")
        print_info("Please fix the issues identified above before running the simulation.")
        print_info("You can run this script with --fix to apply automatic fixes to some issues.")
        print_info("You can run this script with --create-missing to create essential missing files.")

    return 0 if success_count == total_count else 1

if __name__ == "__main__":
    sys.exit(main())