oscura 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

oscura/analyzers/digital/vintage.py

@@ -0,0 +1,377 @@
+"""High-level vintage logic analysis API.
+
+This module provides a unified interface for complete vintage logic system analysis,
+orchestrating all analysis steps and returning consolidated results.
+
+Example:
+    >>> from oscura.analyzers.digital.vintage import analyze_vintage_logic
+    >>> result = analyze_vintage_logic(
+    ...     traces={"CLK": clk_trace, "DATA": data_trace},
+    ...     target_frequency=2e6
+    ... )
+    >>> print(f"Detected: {result.detected_family}")
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, cast
+
+import numpy as np
+
+from oscura.analyzers.digital.extraction import (
+    LOGIC_FAMILIES,
+    detect_logic_family,
+    detect_open_collector,
+)
+from oscura.analyzers.digital.ic_database import identify_ic, validate_ic_timing
+from oscura.analyzers.digital.timing import hold_time, propagation_delay, setup_time
+from oscura.analyzers.digital.timing_paths import TimingPathResult, analyze_timing_path
+from oscura.analyzers.digital.vintage_result import (
+    BOMEntry,
+    ICIdentificationResult,
+    ModernReplacementIC,
+    VintageLogicAnalysisResult,
+)
+from oscura.core.types import WaveformTrace
+
+if TYPE_CHECKING:
+    from oscura.core.types import DigitalTrace, WaveformTrace
+
+
+# Modern IC replacement recommendations
+REPLACEMENT_DATABASE: dict[str, ModernReplacementIC] = {
+    "7400": ModernReplacementIC(
+        original_ic="7400",
+        replacement_ic="74HCT00",
+        family="74HCTxx",
+        benefits=["Lower power", "Wider voltage range", "TTL-compatible inputs"],
+        notes="HCT family maintains TTL compatibility with CMOS benefits",
+    ),
+    "7474": ModernReplacementIC(
+        original_ic="7474",
+        replacement_ic="74HCT74",
+        family="74HCTxx",
+        benefits=["Lower power", "Wider voltage range", "TTL-compatible inputs"],
+        notes="HCT family maintains TTL compatibility with CMOS benefits",
+    ),
+    "74LS00": ModernReplacementIC(
+        original_ic="74LS00",
+        replacement_ic="74HCT00",
+        family="74HCTxx",
+        benefits=["Lower power", "Similar speed", "Better availability"],
+        notes="Direct pin-compatible replacement",
+    ),
+    "74LS74": ModernReplacementIC(
+        original_ic="74LS74",
+        replacement_ic="74HCT74",
+        family="74HCTxx",
+        benefits=["Lower power", "Similar speed", "Better availability"],
+        notes="Direct pin-compatible replacement",
+    ),
+    "74LS138": ModernReplacementIC(
+        original_ic="74LS138",
+        replacement_ic="74HCT138",
+        family="74HCTxx",
+        benefits=["Lower power", "Similar speed", "Better availability"],
+        notes="Direct pin-compatible replacement",
+    ),
+    "74LS244": ModernReplacementIC(
+        original_ic="74LS244",
+        replacement_ic="74HCT244",
+        family="74HCTxx",
+        benefits=["Lower power", "Similar speed", "Better availability"],
+        notes="Direct pin-compatible replacement",
+    ),
+    "74LS245": ModernReplacementIC(
+        original_ic="74LS245",
+        replacement_ic="74HCT245",
+        family="74HCTxx",
+        benefits=["Lower power", "Similar speed", "Better availability"],
+        notes="Direct pin-compatible replacement",
+    ),
+    "74LS273": ModernReplacementIC(
+        original_ic="74LS273",
+        replacement_ic="74HCT273",
+        family="74HCTxx",
+        benefits=["Lower power", "Similar speed", "Better availability"],
+        notes="Direct pin-compatible replacement",
+    ),
+    "74LS374": ModernReplacementIC(
+        original_ic="74LS374",
+        replacement_ic="74HCT374",
+        family="74HCTxx",
+        benefits=["Lower power", "Similar speed", "Better availability"],
+        notes="Direct pin-compatible replacement",
+    ),
+}
+
+
+def analyze_vintage_logic(
+    traces: dict[str, WaveformTrace | DigitalTrace],
+    *,
+    target_frequency: float | None = None,
+    system_description: str | None = None,
+    enable_protocol_decode: bool = False,
+    timing_paths: list[tuple[str, WaveformTrace, WaveformTrace]] | None = None,
+) -> VintageLogicAnalysisResult:
+    """Complete vintage logic system analysis.
+
+    High-level API that orchestrates all vintage logic analysis steps and returns
+    a comprehensive result object suitable for reporting and export.
+
+    Args:
+        traces: Dictionary mapping channel names to traces.
+        target_frequency: Target system clock frequency in Hz.
+        system_description: Optional description for documentation.
+        enable_protocol_decode: Enable automatic protocol decoding (GPIB, ISA, etc.).
+        timing_paths: Optional list of (ic_name, input_trace, output_trace) tuples
+            for multi-IC timing path analysis.
+
+    Returns:
+        VintageLogicAnalysisResult object with complete analysis data.
+
+    Example:
+        >>> result = analyze_vintage_logic(
+        ...     traces={"CLK": clk_trace, "DATA": data_trace},
+        ...     target_frequency=2e6,
+        ...     system_description="1976 Microcomputer System"
+        ... )
+        >>> print(f"Detected: {result.detected_family}")
+        >>> print(f"ICs: {[ic.ic_name for ic in result.identified_ics]}")
+    """
+    start_time = time.time()
+    warnings: list[str] = []
+    confidence_scores: dict[str, float] = {}
+
+    # Use first trace for logic family detection
+    first_trace_name = next(iter(traces.keys()))
+    first_trace = traces[first_trace_name]
+
+    # Ensure we have a WaveformTrace for voltage-based analysis
+    if not hasattr(first_trace.data, "dtype") or first_trace.data.dtype == bool:
+        warnings.append(
+            f"Digital trace provided for {first_trace_name}, "
+            "logic family detection may be inaccurate"
+        )
+        detected_family = "unknown"
+        family_confidence = 0.0
+        voltage_levels = {}
+    else:
+        # Step 1: Detect logic family
+        # Type narrowing: we've verified this is a WaveformTrace above
+        waveform_trace = cast("WaveformTrace", first_trace)
+        detected_family, family_confidence = detect_logic_family(waveform_trace)
+        confidence_scores["logic_family"] = family_confidence
+
+        # Get voltage levels from detected family
+        if detected_family in LOGIC_FAMILIES:
+            voltage_levels = dict(LOGIC_FAMILIES[detected_family])
+        else:
+            voltage_levels = {}
+            warnings.append(f"Unknown logic family: {detected_family}")
+
+    # Step 2: Detect open-collector outputs
+    open_collector_detected = False
+    asymmetry_ratio = 1.0
+    if hasattr(first_trace.data, "dtype") and first_trace.data.dtype != bool:
+        waveform_trace = cast("WaveformTrace", first_trace)
+        open_collector_detected, asymmetry_ratio = detect_open_collector(waveform_trace)
+        if open_collector_detected:
+            warnings.append(
+                "Open-collector output detected - consider 10kΩ pull-up in modern design"
+            )
+
+    # Step 3: Measure timing parameters and identify ICs
+    identified_ics: list[ICIdentificationResult] = []
+    timing_measurements: dict[str, float] = {}
+
+    # Analyze each trace pair for timing
+    trace_list = list(traces.items())
+    for i in range(len(trace_list) - 1):
+        name1, trace1 = trace_list[i]
+        name2, trace2 = trace_list[i + 1]
+
+        # Measure propagation delay
+        try:
+            t_pd_raw = propagation_delay(trace1, trace2)
+            t_pd = (
+                float(t_pd_raw)
+                if isinstance(t_pd_raw, (int, float, np.number))
+                else float(t_pd_raw.item())
+            )
+            if t_pd > 0:
+                timing_measurements[f"{name1}→{name2}_t_pd"] = t_pd
+        except Exception as e:
+            warnings.append(f"Failed to measure propagation delay {name1}→{name2}: {e}")
+
+        # Measure setup and hold times if clock-like signal
+        try:
+            t_su_raw = setup_time(trace1, trace2)
+            t_su = (
+                float(t_su_raw)
+                if isinstance(t_su_raw, (int, float, np.number))
+                else float(t_su_raw.item())
+            )
+            if t_su > 0:
+                timing_measurements[f"{name2}_t_su"] = t_su
+        except Exception:
+            pass  # Optional measurement
+
+        try:
+            t_h_raw = hold_time(trace1, trace2)
+            t_h = (
+                float(t_h_raw)
+                if isinstance(t_h_raw, (int, float, np.number))
+                else float(t_h_raw.item())
+            )
+            if t_h > 0:
+                timing_measurements[f"{name2}_t_h"] = t_h
+        except Exception:
+            pass  # Optional measurement
+
+    # Attempt IC identification from timing measurements
+    if timing_measurements:
+        # Extract core timing parameters
+        core_params = {}
+        for key, value in timing_measurements.items():
+            if "_t_pd" in key:
+                core_params["t_pd"] = value
+            elif "_t_su" in key and "t_su" not in core_params:
+                core_params["t_su"] = value
+            elif "_t_h" in key and "t_h" not in core_params:
+                core_params["t_h"] = value
+
+        if core_params:
+            ic_name, ic_confidence = identify_ic(core_params, tolerance=0.5)
+            confidence_scores["ic_identification"] = ic_confidence
+
+            if ic_name != "unknown":
+                # Validate against database
+                try:
+                    validation = validate_ic_timing(ic_name, core_params, tolerance=0.3)
+
+                    identified_ics.append(
+                        ICIdentificationResult(
+                            ic_name=ic_name,
+                            confidence=ic_confidence,
+                            timing_params=core_params,
+                            validation=validation,
+                            family=detected_family,
+                        )
+                    )
+
+                    # Check if any parameters fail validation
+                    failed_params = [k for k, v in validation.items() if v.get("passes") is False]
+                    if failed_params:
+                        warnings.append(
+                            f"IC {ic_name} timing validation failed for: {', '.join(failed_params)}"
+                        )
+                except KeyError:
+                    warnings.append(f"IC {ic_name} not found in database")
+
+    # Step 4: Analyze timing paths if provided
+    timing_path_results: list[TimingPathResult] | None = None
+    if timing_paths:
+        try:
+            path_result = analyze_timing_path(timing_paths, target_frequency=target_frequency)
+            timing_path_results = [path_result]
+
+            if not path_result.meets_timing:
+                warnings.append(
+                    f"Timing path violation detected at stage {path_result.critical_stage_idx}"
+                )
+        except Exception as e:
+            warnings.append(f"Timing path analysis failed: {e}")
+
+    # Step 5: Protocol decoding (if enabled)
+    decoded_protocols: dict[str, list[Any]] | None = None
+    if enable_protocol_decode:
+        # Protocol decoding would be implemented here
+        # For now, just a placeholder
+        decoded_protocols = {}
+
+    # Step 6: Generate modern replacement recommendations
+    modern_replacements: list[ModernReplacementIC] = []
+    for ic_result in identified_ics:
+        if ic_result.ic_name in REPLACEMENT_DATABASE:
+            modern_replacements.append(REPLACEMENT_DATABASE[ic_result.ic_name])
+
+    # Step 7: Generate BOM
+    bom: list[BOMEntry] = []
+
+    # Add identified ICs
+    for ic_result in identified_ics:
+        bom.append(
+            BOMEntry(
+                part_number=ic_result.ic_name,
+                description=f"Original IC from {detected_family} family",
+                quantity=1,
+                category="IC",
+                notes=f"Confidence: {ic_result.confidence * 100:.1f}%",
+            )
+        )
+
+    # Add modern replacements
+    for replacement in modern_replacements:
+        bom.append(
+            BOMEntry(
+                part_number=replacement.replacement_ic,
+                description=f"Modern replacement for {replacement.original_ic}",
+                quantity=1,
+                category="IC",
+                notes=f"Benefits: {', '.join(replacement.benefits)}",
+            )
+        )
+
+    # Add supporting components
+    if open_collector_detected:
+        bom.append(
+            BOMEntry(
+                part_number="Pull-up resistor",
+                description="10kΩ resistor for open-collector pull-up",
+                quantity=len(list(traces.values())),
+                category="Resistor",
+                notes="Use for all open-collector outputs",
+            )
+        )
+
+    # Add decoupling capacitors (good practice)
+    bom.append(
+        BOMEntry(
+            part_number="0.1µF ceramic capacitor",
+            description="Decoupling capacitor",
+            quantity=len(identified_ics) * 2,
+            category="Capacitor",
+            notes="One per IC, place close to VCC/GND pins",
+        )
+    )
+
+    # Calculate analysis duration
+    analysis_duration = time.time() - start_time
+
+    return VintageLogicAnalysisResult(
+        timestamp=datetime.now(),
+        source_file=system_description,
+        analysis_duration=analysis_duration,
+        detected_family=detected_family,
+        family_confidence=family_confidence,
+        voltage_levels=voltage_levels,
+        identified_ics=identified_ics,
+        timing_measurements=timing_measurements,
+        timing_paths=timing_path_results,
+        decoded_protocols=decoded_protocols,
+        open_collector_detected=open_collector_detected,
+        asymmetry_ratio=asymmetry_ratio,
+        modern_replacements=modern_replacements,
+        bom=bom,
+        warnings=warnings,
+        confidence_scores=confidence_scores,
+    )
+
+
+__all__ = [
+    "REPLACEMENT_DATABASE",
+    "analyze_vintage_logic",
+]

oscura/analyzers/digital/vintage_result.py

@@ -0,0 +1,148 @@
+"""Vintage logic analysis result data structures.
+
+This module defines dataclasses for aggregating vintage logic analysis results,
+enabling comprehensive reporting and export capabilities.
+
+Example:
+    >>> from oscura.analyzers.digital.vintage_result import VintageLogicAnalysisResult
+    >>> result = VintageLogicAnalysisResult(
+    ...     timestamp=datetime.now(),
+    ...     detected_family="TTL",
+    ...     family_confidence=0.95,
+    ...     # ... more fields ...
+    ... )
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from oscura.analyzers.digital.timing_paths import TimingPathResult
+
+
+@dataclass
+class ICIdentificationResult:
+    """Single IC identification result.
+
+    Attributes:
+        ic_name: Identified IC part number (e.g., "74LS74").
+        confidence: Confidence score (0.0-1.0).
+        timing_params: Measured timing parameters in seconds.
+        validation: Validation results from validate_ic_timing().
+        family: Logic family of the IC.
+    """
+
+    ic_name: str
+    confidence: float
+    timing_params: dict[str, float]
+    validation: dict[str, dict[str, Any]]
+    family: str
+
+
+@dataclass
+class ModernReplacementIC:
+    """Modern IC recommendation for vintage part.
+
+    Attributes:
+        original_ic: Original vintage IC part number.
+        replacement_ic: Recommended modern replacement.
+        family: Replacement logic family (e.g., "74HCTxx").
+        benefits: List of benefits (speed, power, availability).
+        notes: Optional additional notes.
+    """
+
+    original_ic: str
+    replacement_ic: str
+    family: str
+    benefits: list[str]
+    notes: str | None = None
+
+
+@dataclass
+class BOMEntry:
+    """Bill of materials entry.
+
+    Attributes:
+        part_number: Component part number.
+        description: Component description.
+        quantity: Number of components needed.
+        category: Component category ("IC", "Capacitor", "Buffer", etc.).
+        notes: Optional notes (pinout, alternatives, etc.).
+    """
+
+    part_number: str
+    description: str
+    quantity: int
+    category: str
+    notes: str | None = None
+
+
+@dataclass
+class VintageLogicAnalysisResult:
+    """Complete vintage logic analysis result.
+
+    Aggregates all analysis outputs for comprehensive reporting and export.
+
+    Attributes:
+        timestamp: Analysis timestamp.
+        source_file: Source file path if loaded from file.
+        analysis_duration: Analysis execution time in seconds.
+        detected_family: Detected logic family name.
+        family_confidence: Logic family detection confidence (0.0-1.0).
+        voltage_levels: Measured voltage levels (VCC, VIL, VIH, VOL, VOH).
+        identified_ics: List of identified ICs.
+        timing_measurements: Dictionary of timing measurements in seconds.
+        timing_paths: Multi-IC timing path analysis results.
+        decoded_protocols: Protocol decoder results if applicable.
+        open_collector_detected: Whether open-collector output detected.
+        asymmetry_ratio: Rise/fall time asymmetry ratio.
+        modern_replacements: List of modern IC recommendations.
+        bom: Bill of materials entries.
+        warnings: List of warning messages.
+        confidence_scores: Dictionary of confidence scores by analysis type.
+    """
+
+    # Analysis metadata
+    timestamp: datetime
+    source_file: str | None
+    analysis_duration: float
+
+    # Logic family detection results
+    detected_family: str
+    family_confidence: float
+    voltage_levels: dict[str, float]  # VCC, VIL, VIH, VOL, VOH
+
+    # IC identification results
+    identified_ics: list[ICIdentificationResult] = field(default_factory=list)
+
+    # Timing measurements
+    timing_measurements: dict[str, float] = field(default_factory=dict)
+
+    # Multi-IC path analysis
+    timing_paths: list[TimingPathResult] | None = None
+
+    # Protocol decoder results (if applicable)
+    decoded_protocols: dict[str, list[Any]] | None = None
+
+    # Open-collector detection
+    open_collector_detected: bool = False
+    asymmetry_ratio: float = 1.0
+
+    # Recommendations
+    modern_replacements: list[ModernReplacementIC] = field(default_factory=list)
+    bom: list[BOMEntry] = field(default_factory=list)
+
+    # Quality metrics
+    warnings: list[str] = field(default_factory=list)
+    confidence_scores: dict[str, float] = field(default_factory=dict)
+
+
+__all__ = [
+    "BOMEntry",
+    "ICIdentificationResult",
+    "ModernReplacementIC",
+    "VintageLogicAnalysisResult",
+]

oscura/analyzers/protocols/__init__.py

@@ -2,7 +2,7 @@
 
 Provides protocol decoders for common serial and automotive protocols including
 UART, SPI, I2C, CAN, LIN, FlexRay, JTAG, SWD, I2S, USB, HDLC, Manchester, CAN-FD,
-and 1-Wire.
+1-Wire, and parallel bus protocols (GPIB, Centronics, ISA).
 """
 
 from oscura.analyzers.protocols.base import (
@@ -60,6 +60,18 @@ from oscura.analyzers.protocols.onewire import (
     OneWireTimings,
     decode_onewire,
 )
+
+# Parallel bus protocols
+from oscura.analyzers.protocols.parallel_bus import (
+    CentronicsFrame,
+    GPIBFrame,
+    GPIBMessageType,
+    ISACycleType,
+    ISATransaction,
+    decode_centronics,
+    decode_gpib,
+    decode_isa_bus,
+)
 from oscura.analyzers.protocols.spi import SPIDecoder, decode_spi
 from oscura.analyzers.protocols.swd import SWDDecoder, SWDResponse, decode_swd
 from oscura.analyzers.protocols.uart import UARTDecoder, decode_uart
@@ -91,12 +103,16 @@ __all__ = [
     "CANFDFrameType",
     "CANFrame",
     "CANFrameType",
+    # Parallel bus protocols
+    "CentronicsFrame",
     "ChannelDef",
     "DecoderState",
     # FlexRay (PRO-016)
     "FlexRayDecoder",
     "FlexRayFrame",
     "FlexRaySegment",
+    "GPIBFrame",
+    "GPIBMessageType",
     # HDLC (PRO-013)
     "HDLCDecoder",
     # I2C (PRO-004)
@@ -104,6 +120,8 @@ __all__ = [
     # I2S (PRO-011)
     "I2SDecoder",
     "I2SMode",
+    "ISACycleType",
+    "ISATransaction",
     # JTAG (PRO-009)
     "JTAGDecoder",
     # LIN (PRO-008)
@@ -135,10 +153,13 @@ __all__ = [
     "USBSpeed",
     "decode_can",
     "decode_can_fd",
+    "decode_centronics",
     "decode_flexray",
+    "decode_gpib",
     "decode_hdlc",
     "decode_i2c",
     "decode_i2s",
+    "decode_isa_bus",
     "decode_jtag",
     "decode_lin",
     "decode_manchester",