oscura 0.4.0__tar.gz → 0.5.0__tar.gz

{oscura-0.4.0 → oscura-0.5.0}/.gitignore

@@ -292,3 +292,4 @@ validation_results/
 
 # Exceptions: legitimate documentation with these keywords in name
 # (none currently - add here if needed)
+*.json

{oscura-0.4.0 → oscura-0.5.0}/CHANGELOG.md

@@ -7,6 +7,164 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-01-22
+
+### Added
+
+- **Vintage Logic Family Support** (`src/oscura/analyzers/digital/extraction.py`):
+  - **ECL** (Emitter-Coupled Logic): ECL 10K and ECL 100K series support with differential signaling
+  - **RTL** (Resistor-Transistor Logic): 1960s-era logic family (3.6V supply)
+  - **DTL** (Diode-Transistor Logic): Pre-TTL logic family
+  - **PMOS/NMOS**: Negative and positive MOS logic (-12V and +12V rails)
+  - Auto-detection of logic family from voltage levels (`detect_logic_family()`)
+  - Open-collector/open-drain detection (`detect_open_collector()`)
+  - Test coverage: Comprehensive tests for all vintage families
+
+- **IC Timing Database** (`src/oscura/analyzers/digital/ic_database.py`):
+  - Comprehensive database of 14+ common ICs (74xx series, 4000 series)
+  - Standard TTL: 7400, 7474 with typical 1970s timing
+  - LS-TTL: 74LS00, 74LS74, 74LS138, 74LS244, 74LS245, 74LS273, 74LS374
+  - HC-CMOS: 74HC00, 74HC74, 74HC595 with modern fast timing
+  - 4000 series CMOS: 4011, 4013 with wide voltage range support
+  - IC identification from measured timings (`identify_ic()`)
+  - Timing validation against specifications (`validate_ic_timing()`)
+  - Automatic spec compliance checking
+
+- **Parallel Bus Protocol Decoders** (`src/oscura/analyzers/protocols/parallel_bus.py`):
+  - **IEEE-488 (GPIB)**: Complete GPIB protocol decoder for instrument control
+    - Talk/listen address decoding
+    - Universal and addressed command recognition
+    - EOI (End-Or-Identify) support
+    - Data and control byte interpretation
+  - **Centronics**: Parallel printer interface decoder
+    - ASCII character extraction
+    - Control signal monitoring (STROBE, BUSY, ACK)
+    - Printable character detection
+  - **ISA Bus**: Industry Standard Architecture bus analyzer
+    - Memory read/write transaction decoding
+    - I/O read/write transaction decoding
+    - 20-bit address support
+    - DMA and interrupt detection
+
+- **WaveDrom Timing Diagram Export** (`src/oscura/export/wavedrom.py`):
+  - WaveDrom JSON format generation
+  - Clock signal generation with configurable period/duty cycle
+  - Digital signal edge-based waveform generation
+  - Data bus visualization with hex value labels
+  - Timing annotation arrows with labels
+  - Direct export from DigitalTrace objects
+  - Compatible with wavedrom-cli and online renderers
+
+- **State-of-the-Art Digital Logic Visualizations** (`src/oscura/visualization/digital_advanced.py`):
+  - **Logic Analyzer View**: Professional multi-channel timeline display
+    - Bus grouping with hex value overlays
+    - Automatic time axis formatting (ns/μs/ms/s)
+    - Timing cursors with delta-time measurements
+    - Stacked waveform display
+  - **Timing Diagram with Annotations**: Publication-quality timing diagrams
+    - Setup/hold time visualization
+    - Propagation delay arrows
+    - Custom timing parameter annotations
+  - **IC Timing Validation Overlay**: Visual spec compliance checking
+    - Real-time pass/fail indicators
+    - Measured vs. specification comparison
+    - Error percentage display
+  - **Multi-IC Timing Path Visualization**: Cascaded IC timing analysis
+    - End-to-end delay visualization
+    - Per-stage timing breakdown
+    - Critical path highlighting
+  - **Bus Eye Diagram**: Signal quality analysis for multi-bit buses
+    - Per-bit eye diagram overlays
+    - Symbol period alignment
+    - Quality assessment
+
+- **Multi-IC Timing Path Analysis** (`src/oscura/analyzers/digital/timing_paths.py`):
+  - Cascaded IC propagation delay analysis
+  - Critical path identification
+  - Timing budget calculation and allocation
+  - Setup/hold time analysis for synchronous paths
+  - Path slack calculation
+  - Automatic spec violation detection
+  - Support for clock and data path correlation
+
+- **Vintage Logic Analysis High-Level API** (`src/oscura/analyzers/digital/vintage.py`):
+  - Unified `analyze_vintage_logic()` function for complete system analysis
+  - Orchestrates logic family detection, IC identification, timing analysis, and protocol decoding
+  - Returns consolidated `VintageLogicAnalysisResult` object
+  - Modern IC replacement recommendations (74LSxx → 74HCTxx)
+  - Automatic BOM generation with supporting components
+  - Open-collector detection and pull-up recommendations
+  - Comprehensive warning system
+
+- **Vintage Logic Analysis Result Structures** (`src/oscura/analyzers/digital/vintage_result.py`):
+  - `VintageLogicAnalysisResult`: Complete analysis aggregation
+  - `ICIdentificationResult`: IC identification with validation
+  - `ModernReplacementIC`: Replacement recommendations
+  - `BOMEntry`: Bill of materials entries
+  - Structured data for reporting and export
+
+- **Comprehensive Vintage Logic Reporting** (`src/oscura/reporting/vintage_logic_report.py`):
+  - Professional HTML reports with embedded plots
+  - Markdown summary generation
+  - PDF export guidance (HTML→PDF workflow)
+  - Interactive visualizations with base64-embedded images
+  - Automated table generation (IC specs, timing, BOM)
+  - Warning and confidence score display
+  - `generate_vintage_logic_report()` unified API
+
+- **Figure Management System** (`src/oscura/visualization/figure_manager.py`):
+  - Multi-format figure saving (PNG, SVG, PDF)
+  - Base64 encoding for HTML embedding
+  - Figure registry and path management
+  - Configurable DPI and save options
+  - Automatic directory creation
+
+- **Vintage Logic CSV Exporters** (`src/oscura/exporters/vintage_logic_csv.py`):
+  - Timing measurements export with parameter classification
+  - IC identification results export with validation status
+  - Bill of materials export (procurement-ready format)
+  - Voltage levels export
+  - `export_all_vintage_logic_csv()` batch export
+
+- **Enhanced JSON Export** (`src/oscura/exporters/json_export.py`):
+  - `export_vintage_logic_json()` convenience function
+  - Automatic dataclass serialization for vintage logic results
+  - Complete analysis export with metadata
+
+- **All-in-One Visualization Suite** (`src/oscura/visualization/digital_advanced.py`):
+  - `generate_all_vintage_logic_plots()`: Generate all relevant plots
+  - Automatic plot selection based on analysis results
+  - Multi-format save support
+  - Integration with FigureManager
+
+### Enhanced
+
+- **LOGIC_FAMILIES Dictionary**: Expanded from 7 to 14 logic families
+- **Digital Analysis Module** (`src/oscura/analyzers/digital/__init__.py`):
+  - Now exports vintage logic high-level API: `analyze_vintage_logic()`
+  - Exports vintage logic result structures: `VintageLogicAnalysisResult`, `ICIdentificationResult`, `ModernReplacementIC`, `BOMEntry`
+  - Exports IC replacement database: `REPLACEMENT_DATABASE`
+- **Protocol Decoders**: Added parallel bus protocols alongside existing serial protocols
+- **Export Module**: WaveDrom timing diagram generation added
+- **Visualization Module** (`src/oscura/visualization/digital_advanced.py`):
+  - Added `generate_all_vintage_logic_plots()` for automated visualization suite generation
+  - Enhanced existing plot functions with vintage logic support
+- **Reporting Module** (`src/oscura/reporting/__init__.py`):
+  - Now exports `generate_vintage_logic_report()` and `VintageLogicReport`
+  - Unified API for report generation and multi-format export
+- **Examples** (`examples/vintage_logic_reverse_engineering.py`):
+  - Updated to demonstrate new high-level API and reporting features
+  - Shows complete workflow: analysis → visualization → reporting → export
+
+### Infrastructure
+
+- **Test Coverage**: Comprehensive tests for all new features
+  - IC database validation (14 test cases)
+  - Logic family detection (8 test cases)
+  - Open-collector detection (7 test cases)
+  - Parallel bus protocols (15+ test cases)
+  - All features verified with standalone tests
+
 ## [0.4.0] - 2026-01-22
 
 ### BREAKING CHANGES
@@ -995,7 +1153,7 @@ trace = builder.build()  # Returns WaveformTrace directly
 
 ### Initial Public Release
 
-Oscura 0.4.0 is the first public release of the comprehensive hardware reverse engineering framework for security researchers, right-to-repair advocates, defense analysts, and commercial intelligence teams.
+Oscura 0.5.0 is the first public release of the comprehensive hardware reverse engineering framework for security researchers, right-to-repair advocates, defense analysts, and commercial intelligence teams.
 
 ### Core Features
 

{oscura-0.4.0 → oscura-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oscura
-Version: 0.4.0
+Version: 0.5.0
 Summary: Unified hardware reverse engineering framework. Extract all information from any system through signals and data. Unknown protocol discovery, state machine extraction, CRC recovery, security analysis. 16+ protocols, IEEE-compliant measurements.
 Project-URL: Homepage, https://github.com/oscura-re/oscura
 Project-URL: Documentation, https://github.com/oscura-re/oscura/tree/main/docs

{oscura-0.4.0 → oscura-0.5.0}/pyproject.toml

@@ -6,7 +6,7 @@
 
 [project]
 name = "oscura"
-version = "0.4.0"
+version = "0.5.0"
 description = "Unified hardware reverse engineering framework. Extract all information from any system through signals and data. Unknown protocol discovery, state machine extraction, CRC recovery, security analysis. 16+ protocols, IEEE-compliant measurements."
 readme = "README.md"
 requires-python = ">=3.12"

{oscura-0.4.0 → oscura-0.5.0}/src/oscura/__init__.py

@@ -46,7 +46,7 @@ Example:
 For more information, see https://github.com/oscura-re/oscura
 """
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 __author__ = "Oscura Contributors"
 
 # Core types

{oscura-0.4.0 → oscura-0.5.0}/src/oscura/analyzers/digital/__init__.py

@@ -52,9 +52,17 @@ from oscura.analyzers.digital.edges import (
 from oscura.analyzers.digital.extraction import (
     LOGIC_FAMILIES,
     detect_edges,
+    detect_logic_family,
+    detect_open_collector,
     get_logic_threshold,
     to_digital,
 )
+from oscura.analyzers.digital.ic_database import (
+    IC_DATABASE,
+    ICTiming,
+    identify_ic,
+    validate_ic_timing,
+)
 from oscura.analyzers.digital.quality import (
     Glitch,
     NoiseMarginResult,
@@ -97,13 +105,37 @@ from oscura.analyzers.digital.timing import (
     skew,
     slew_rate,
 )
+from oscura.analyzers.digital.timing_paths import (
+    ICStage,
+    SetupHoldAnalysis,
+    TimingPathResult,
+    analyze_setup_hold,
+    analyze_timing_path,
+    calculate_timing_budget,
+    find_critical_paths,
+)
+from oscura.analyzers.digital.vintage import (
+    REPLACEMENT_DATABASE,
+    analyze_vintage_logic,
+)
+from oscura.analyzers.digital.vintage_result import (
+    BOMEntry,
+    ICIdentificationResult,
+    ModernReplacementIC,
+    VintageLogicAnalysisResult,
+)
 
 __all__ = [
+    # IC Database
+    "IC_DATABASE",
     # Extraction
     "LOGIC_FAMILIES",
+    "REPLACEMENT_DATABASE",
     "AdaptiveThresholdResult",
     # Adaptive Thresholds (RE-THR-001)
     "AdaptiveThresholder",
+    # Vintage Logic Analysis
+    "BOMEntry",
     # Clock Recovery (DSP-002)
     "BaudRateResult",
     # Bus Decoding (DSP-003)
@@ -125,6 +157,10 @@ __all__ = [
     "EdgeTimingViolation",
     # Quality
     "Glitch",
+    "ICIdentificationResult",
+    "ICStage",
+    "ICTiming",
+    "ModernReplacementIC",
     # Multi-Level Logic (RE-THR-002)
     "MultiLevelDetector",
     "MultiLevelResult",
@@ -132,18 +168,25 @@ __all__ = [
     # Signal Quality (DSP-005)
     "NoiseMargins",
     "ParallelBusConfig",
+    "SetupHoldAnalysis",
     "SignalIntegrityReport",
     "SignalQualityAnalyzer",
     "SimpleQualityMetrics",
     "ThresholdConfig",
     "TimingConstraint",
+    "TimingPathResult",
     "TimingViolation",
     "TransitionMetrics",
+    "VintageLogicAnalysisResult",
     "Violation",
     "align_by_trigger",
+    "analyze_setup_hold",
     "analyze_signal_integrity",
+    "analyze_timing_path",
+    "analyze_vintage_logic",
     "apply_adaptive_threshold",
     "calculate_threshold_snr",
+    "calculate_timing_budget",
     "check_timing_constraints",
     "classify_edge_quality",
     "correlate_channels",
@@ -153,10 +196,14 @@ __all__ = [
     "detect_edges",
     "detect_edges_advanced",
     "detect_glitches",
+    "detect_logic_family",
     "detect_multi_level",
+    "detect_open_collector",
     "detect_violations",
+    "find_critical_paths",
     "get_logic_threshold",
     "hold_time",
+    "identify_ic",
     "interpolate_edge_time",
     "measure_clock_jitter",
     "measure_edge_timing",
@@ -174,4 +221,5 @@ __all__ = [
     "skew",
     "slew_rate",
     "to_digital",
+    "validate_ic_timing",
 ]

{oscura-0.4.0 → oscura-0.5.0}/src/oscura/analyzers/digital/extraction.py

@@ -25,6 +25,7 @@ if TYPE_CHECKING:
 # Standard logic family threshold constants
 # Reference: Various IC manufacturer datasheets
 LOGIC_FAMILIES: dict[str, dict[str, float]] = {
+    # Modern logic families (5V)
     "TTL": {
         "VIL_max": 0.8,  # Maximum input low voltage
         "VIH_min": 2.0,  # Minimum input high voltage
@@ -74,6 +75,63 @@ LOGIC_FAMILIES: dict[str, dict[str, float]] = {
         "VOH_min": 1.1,
         "VCC": 1.2,
     },
+    # Vintage logic families (1960s-1970s)
+    "ECL": {
+        "VIL_max": -1.475,  # ECL 10K series
+        "VIH_min": -1.105,
+        "VOL_max": -1.630,  # Typical -1.63V
+        "VOH_min": -0.980,  # Typical -0.98V
+        "VCC": 0.0,  # Ground-referenced
+        "VEE": -5.2,  # Negative supply
+        "differential": True,  # Differential signaling
+    },
+    "ECL_100K": {
+        "VIL_max": -1.810,  # ECL 100K series (faster)
+        "VIH_min": -1.620,
+        "VOL_max": -1.950,
+        "VOH_min": -1.650,
+        "VCC": 0.0,
+        "VEE": -5.2,
+        "differential": True,
+    },
+    "RTL": {
+        "VIL_max": 0.4,  # Resistor-Transistor Logic
+        "VIH_min": 0.9,
+        "VOL_max": 0.2,
+        "VOH_min": 3.6,  # Typical 3.6V high output
+        "VCC": 3.6,  # 3.6V supply common
+    },
+    "DTL": {
+        "VIL_max": 0.5,  # Diode-Transistor Logic
+        "VIH_min": 2.0,
+        "VOL_max": 0.4,
+        "VOH_min": 4.0,  # Typical 4V high output
+        "VCC": 5.0,
+    },
+    "MOS": {
+        "VIL_max": -3.0,  # P-channel MOS (negative logic)
+        "VIH_min": -10.0,
+        "VOL_max": -0.5,
+        "VOH_min": -11.5,
+        "VCC": 0.0,  # Ground
+        "VDD": -12.0,  # Negative supply
+    },
+    "PMOS": {
+        "VIL_max": -3.0,  # PMOS (4000 series at -12V)
+        "VIH_min": -9.0,
+        "VOL_max": -0.5,
+        "VOH_min": -11.5,
+        "VCC": 0.0,
+        "VDD": -12.0,
+    },
+    "NMOS": {
+        "VIL_max": 1.5,  # NMOS (positive logic, 12V)
+        "VIH_min": 8.0,
+        "VOL_max": 0.5,
+        "VOH_min": 11.5,
+        "VCC": 12.0,
+        "VSS": 0.0,
+    },
 }
 
 
@@ -405,9 +463,146 @@ def get_logic_threshold(
         raise ValueError(f"Unknown threshold_type: {threshold_type}")
 
 
+def detect_logic_family(
+    trace: WaveformTrace,
+    *,
+    confidence_threshold: float = 0.8,
+) -> tuple[str, float]:
+    """Auto-detect logic family from signal voltage levels.
+
+    Analyzes the signal to determine which logic family it most likely represents
+    based on voltage levels.
+
+    Args:
+        trace: Input analog waveform trace.
+        confidence_threshold: Minimum confidence (0-1) to return a match.
+
+    Returns:
+        Tuple of (family_name, confidence_score).
+        Returns ("unknown", 0.0) if no match above threshold.
+
+    Example:
+        >>> family, conf = detect_logic_family(trace)
+        >>> print(f"Detected: {family} ({conf*100:.1f}% confidence)")
+    """
+    if len(trace.data) < 10:
+        return ("unknown", 0.0)
+
+    data = np.asarray(trace.data)
+
+    # Find voltage levels using percentiles
+    p10, p90 = np.percentile(data, [10, 90])
+    vlow = p10
+    vhigh = p90
+
+    # Calculate midpoint and swing
+    vmid = (vlow + vhigh) / 2.0
+    vswing = vhigh - vlow
+
+    if vswing < 0.1:  # Insufficient signal
+        return ("unknown", 0.0)
+
+    # Score each logic family
+    scores: dict[str, float] = {}
+
+    for family_name, levels in LOGIC_FAMILIES.items():
+        # Check if voltage levels match this family
+        vil_max = levels["VIL_max"]
+        vih_min = levels["VIH_min"]
+        vcc = levels.get("VCC", 5.0)
+
+        # Expected midpoint for this family
+        expected_mid = (vil_max + vih_min) / 2.0
+
+        # Score based on:
+        # 1. Midpoint proximity
+        # 2. High level proximity to VOH
+        # 3. Low level proximity to VOL
+
+        mid_error = abs(vmid - expected_mid)
+        high_error = abs(vhigh - levels.get("VOH_min", vih_min))
+        low_error = abs(vlow - levels.get("VOL_max", vil_max))
+
+        # Normalize errors (handle VCC=0 for ECL/PMOS)
+        if vcc != 0:
+            mid_score = max(0, 1.0 - mid_error / abs(vcc))
+            high_score = max(0, 1.0 - high_error / abs(vcc))
+            low_score = max(0, 1.0 - low_error / abs(vcc))
+        else:
+            # For VCC=0 families (ECL), use voltage range instead
+            voltage_range = abs(vih_min - vil_max)
+            if voltage_range > 0:
+                mid_score = max(0, 1.0 - mid_error / voltage_range)
+                high_score = max(0, 1.0 - high_error / voltage_range)
+                low_score = max(0, 1.0 - low_error / voltage_range)
+            else:
+                mid_score = high_score = low_score = 0.0
+
+        # Combined score (weighted average)
+        total_score = mid_score * 0.5 + high_score * 0.25 + low_score * 0.25
+        scores[family_name] = total_score
+
+    # Find best match
+    if not scores:
+        return ("unknown", 0.0)
+
+    best_family = max(scores.items(), key=lambda x: x[1])
+
+    if best_family[1] < confidence_threshold:
+        return ("unknown", best_family[1])
+
+    return best_family
+
+
+def detect_open_collector(
+    trace: WaveformTrace,
+    *,
+    asymmetry_threshold: float = 3.0,
+) -> tuple[bool, float]:
+    """Detect open-collector or open-drain output.
+
+    Open-collector outputs have slow rise times (limited by pull-up resistor)
+    and fast fall times (active transistor).
+
+    Args:
+        trace: Input analog waveform trace.
+        asymmetry_threshold: Minimum rise/fall ratio to indicate open-collector.
+
+    Returns:
+        Tuple of (is_open_collector, asymmetry_ratio).
+
+    Example:
+        >>> is_oc, ratio = detect_open_collector(trace)
+        >>> if is_oc:
+        ...     print(f"Open-collector detected (rise/fall = {ratio:.1f})")
+    """
+    from oscura.analyzers.waveform.measurements import fall_time, rise_time
+
+    if len(trace.data) < 10:
+        return (False, 1.0)
+
+    # Measure rise and fall times
+    tr = rise_time(trace, ref_levels=(0.1, 0.9))
+    tf = fall_time(trace, ref_levels=(0.9, 0.1))
+
+    # Check for valid measurements
+    if np.isnan(tr) or np.isnan(tf) or tf == 0:
+        return (False, 1.0)
+
+    # Calculate asymmetry ratio
+    asymmetry = tr / tf
+
+    # Open-collector has slow rise, fast fall
+    is_oc = bool(asymmetry >= asymmetry_threshold)
+
+    return (is_oc, float(asymmetry))
+
+
 __all__ = [
     "LOGIC_FAMILIES",
     "detect_edges",
+    "detect_logic_family",
+    "detect_open_collector",
     "get_logic_threshold",
     "to_digital",
 ]