USB4/Thunderbolt 4 API Reference๏ƒ

The USB4/Thunderbolt 4 module provides comprehensive validation capabilities for USB4 2.0 and Thunderbolt 4 protocols, including dual-lane analysis, tunneling validation, and certification testing.

Signal Analysis {#signal-analysis}๏ƒ

Jitter Analysis {#jitter-analysis}๏ƒ

Advanced jitter decomposition for USB4 signals.

Lane Skew Analysis {#lane-skew-analysis}๏ƒ

Dual-lane skew measurement and analysis.

Compliance Testing {#compliance-testing}๏ƒ

USB4 compliance validation and testing.

Performance Testing {#performance-testing}๏ƒ

Performance benchmarking and stress testing.

Visualization {#visualization}๏ƒ

Signal visualization and plotting capabilities.

Core Classes๏ƒ

USB4Validator๏ƒ

The main class for USB4 compliance validation.

from serdes_validation_framework.protocols.usb4 import USB4Validator

validator = USB4Validator()
results = validator.validate_compliance(signal_data)

Methods๏ƒ

validate_compliance(signal_data: USB4SignalData) -> USB4ComplianceResult๏ƒ

Performs comprehensive USB4 compliance validation.

Parameters:

  • signal_data: USB4 signal data containing dual-lane measurements

Returns:

  • USB4ComplianceResult: Detailed compliance test results

Example:

# Load signal data
signal_data = USB4SignalData(
    lane0_data=lane0_voltage,
    lane1_data=lane1_voltage,
    timestamp=time_array,
    sample_rate=80e9,
    signal_mode=USB4SignalMode.GEN2X2
)

# Run compliance validation
results = validator.validate_compliance(signal_data)
print(f"Overall Status: {results.overall_status}")
analyze_signal_integrity(signal_data: USB4SignalData) -> SignalIntegrityResults๏ƒ

Analyzes signal integrity parameters including eye diagrams and jitter.

Parameters:

  • signal_data: USB4 signal data for analysis

Returns:

  • SignalIntegrityResults: Signal integrity analysis results

Example:

integrity_results = validator.analyze_signal_integrity(signal_data)
print(f"Eye Height: {integrity_results.eye_height:.3f}")
print(f"Eye Width: {integrity_results.eye_width:.3f}")
print(f"RMS Jitter: {integrity_results.jitter_rms:.4f} UI")
validate_tunneling(tunnel_data: TunnelingData) -> TunnelingResults๏ƒ

Validates USB4 tunneling protocols (PCIe, DisplayPort, USB 3.2).

Parameters:

  • tunnel_data: Tunneling protocol data

Returns:

  • TunnelingResults: Tunneling validation results

USB4SignalAnalyzer๏ƒ

Specialized class for USB4 signal analysis.

from serdes_validation_framework.protocols.usb4 import USB4SignalAnalyzer

analyzer = USB4SignalAnalyzer()

Methods๏ƒ

analyze_eye_diagram(signal_data: USB4SignalData) -> EyeDiagramResults๏ƒ

Performs detailed eye diagram analysis with USB4-specific compliance masks.

Parameters:

  • signal_data: USB4 signal data

Returns:

  • EyeDiagramResults: Eye diagram analysis results

Example:

eye_results = analyzer.analyze_eye_diagram(signal_data)
print(f"Eye Height: {eye_results.eye_height:.3f}")
print(f"Eye Width: {eye_results.eye_width:.3f}")
print(f"Crossing Percentage: {eye_results.crossing_percentage:.1f}%")
analyze_jitter(signal_data: USB4SignalData) -> JitterResults๏ƒ

Performs comprehensive jitter analysis including RJ, DJ, and PJ decomposition.

Parameters:

  • signal_data: USB4 signal data

Returns:

  • JitterResults: Jitter analysis results

Example:

jitter_results = analyzer.analyze_jitter(signal_data)
print(f"RMS Jitter: {jitter_results.rms_jitter:.4f} UI")
print(f"Peak-to-Peak Jitter: {jitter_results.pp_jitter:.4f} UI")
print(f"Random Jitter: {jitter_results.random_jitter:.4f} UI")
print(f"Deterministic Jitter: {jitter_results.deterministic_jitter:.4f} UI")
analyze_lane_skew(signal_data: USB4SignalData) -> LaneSkewResults๏ƒ

Analyzes skew between USB4 dual lanes.

Parameters:

  • signal_data: USB4 dual-lane signal data

Returns:

  • LaneSkewResults: Lane skew analysis results

Example:

skew_results = analyzer.analyze_lane_skew(signal_data)
print(f"Lane Skew: {skew_results.skew_ps:.2f} ps")
print(f"Lane Correlation: {skew_results.correlation:.3f}")
print(f"Skew in UI: {skew_results.skew_ui:.4f}")

USB4ComplianceValidator๏ƒ

Specialized validator for USB4 compliance testing.

from serdes_validation_framework.protocols.usb4 import USB4ComplianceValidator

compliance_validator = USB4ComplianceValidator()

Methods๏ƒ

validate_full_compliance(signal_data: USB4SignalData, config: dict) -> List[USB4ComplianceResult]๏ƒ

Runs the complete USB4 compliance test suite.

Parameters:

  • signal_data: USB4 signal data

  • config: Test configuration dictionary

Returns:

  • List[USB4ComplianceResult]: List of compliance test results

Example:

config = {
    'signal_mode': USB4SignalMode.GEN3_X2,
    'link_state': USB4LinkState.U0,
    'enable_ssc': True,
    'temperature': 25.0,
    'voltage': 3.3
}

compliance_results = compliance_validator.validate_full_compliance(
    signal_data, config
)

for result in compliance_results:
    status = "PASS" if result.status else "FAIL"
    print(f"{result.test_name}: {status}")

Thunderbolt 4 Classes๏ƒ

ThunderboltSecurityValidator๏ƒ

Validates Thunderbolt 4 security features.

from serdes_validation_framework.protocols.usb4.thunderbolt import ThunderboltSecurityValidator

security_validator = ThunderboltSecurityValidator()

Methods๏ƒ

test_dma_protection(config: dict) -> DMAProtectionResult๏ƒ

Tests DMA protection capabilities.

Parameters:

  • config: DMA protection configuration

Returns:

  • DMAProtectionResult: DMA protection test results

Example:

dma_config = {
    'iommu_enabled': True,
    'vt_d_support': True,
    'secure_boot': True
}

dma_result = security_validator.test_dma_protection(dma_config)
print(f"DMA Protection: {'ENABLED' if dma_result.protected else 'DISABLED'}")
test_device_authentication(config: dict) -> AuthenticationResult๏ƒ

Tests device authentication mechanisms.

Parameters:

  • config: Authentication configuration

Returns:

  • AuthenticationResult: Authentication test results

DaisyChainValidator๏ƒ

Validates Thunderbolt 4 daisy chain functionality.

from serdes_validation_framework.protocols.usb4.thunderbolt import DaisyChainValidator

daisy_validator = DaisyChainValidator()

Methods๏ƒ

validate_chain_configuration(config: dict) -> DaisyChainResult๏ƒ

Validates daisy chain configuration and bandwidth allocation.

Parameters:

  • config: Daisy chain configuration

Returns:

  • DaisyChainResult: Daisy chain validation results

Example:

chain_config = {
    'device_count': 4,
    'bandwidth_requirements': [10, 8, 6, 4]  # Gbps per device
}

chain_result = daisy_validator.validate_chain_configuration(chain_config)
print(f"Chain Valid: {chain_result.valid}")
print(f"Total Bandwidth: {chain_result.total_bandwidth:.1f} Gbps")

IntelCertificationSuite๏ƒ

Complete Intel Thunderbolt 4 certification test suite.

from serdes_validation_framework.protocols.usb4.thunderbolt import IntelCertificationSuite

cert_suite = IntelCertificationSuite()

Methods๏ƒ

run_pre_certification_checks() -> dict๏ƒ

Runs pre-certification requirement checks.

Returns:

  • dict: Pre-certification check results

create_submission_package(session_id: str, **kwargs) -> str๏ƒ

Creates certification submission package.

Parameters:

  • session_id: Test session identifier

  • **kwargs: Additional package options

Returns:

  • str: Path to submission package

Tunneling Classes๏ƒ

PCIeTunnelValidator๏ƒ

Validates PCIe over USB4 tunneling.

from serdes_validation_framework.protocols.usb4.tunneling import PCIeTunnelValidator

pcie_validator = PCIeTunnelValidator()

Methods๏ƒ

validate_tunnel_integrity(config: dict) -> PCIeTunnelResult๏ƒ

Validates PCIe tunnel integrity and performance.

Parameters:

  • config: PCIe tunnel configuration

Returns:

  • PCIeTunnelResult: PCIe tunnel validation results

Example:

pcie_config = {
    'pcie_generation': 4,
    'lane_count': 4,
    'bandwidth_allocation': 0.6,
    'latency_requirement': 1e-6
}

pcie_result = pcie_validator.validate_tunnel_integrity(pcie_config)
print(f"Tunnel Valid: {pcie_result.valid}")
print(f"Bandwidth: {pcie_result.bandwidth/1e9:.1f} Gbps")

DisplayPortTunnelValidator๏ƒ

Validates DisplayPort over USB4 tunneling.

from serdes_validation_framework.protocols.usb4.tunneling import DisplayPortTunnelValidator

dp_validator = DisplayPortTunnelValidator()

Methods๏ƒ

validate_display_configuration(config: dict) -> DisplayPortResult๏ƒ

Validates DisplayPort display configuration.

Parameters:

  • config: Display configuration

Returns:

  • DisplayPortResult: DisplayPort validation results

Example:

display_config = {
    'display_count': 2,
    'resolution': '4K',
    'refresh_rate': 60,
    'color_depth': 10
}

dp_result = dp_validator.validate_display_configuration(display_config)
print(f"Display Supported: {dp_result.supported}")
print(f"Required Bandwidth: {dp_result.bandwidth_required/1e9:.1f} Gbps")

USB32TunnelValidator๏ƒ

Validates USB 3.2 over USB4 tunneling.

from serdes_validation_framework.protocols.usb4.tunneling import USB32TunnelValidator

usb32_validator = USB32TunnelValidator()

Performance Classes๏ƒ

USB4PerformanceBenchmark๏ƒ

Performance benchmarking for USB4 devices.

from serdes_validation_framework.protocols.usb4.performance import USB4PerformanceBenchmark

benchmark = USB4PerformanceBenchmark()

Methods๏ƒ

test_sustained_bandwidth(duration: int, target_bandwidth: float) -> BandwidthResult๏ƒ

Tests sustained bandwidth performance.

Parameters:

  • duration: Test duration in seconds

  • target_bandwidth: Target bandwidth in bps

Returns:

  • BandwidthResult: Bandwidth test results

Example:

bandwidth_result = benchmark.test_sustained_bandwidth(
    duration=300,  # 5 minutes
    target_bandwidth=32e9  # 32 Gbps
)

print(f"Average Bandwidth: {bandwidth_result.average/1e9:.1f} Gbps")
print(f"Peak Bandwidth: {bandwidth_result.peak/1e9:.1f} Gbps")
test_latency_performance(packet_sizes: list, duration: int) -> LatencyResult๏ƒ

Tests latency performance with various packet sizes.

Parameters:

  • packet_sizes: List of packet sizes to test

  • duration: Test duration in seconds

Returns:

  • LatencyResult: Latency test results

USB4StressTester๏ƒ

Stress testing for USB4 devices.

from serdes_validation_framework.protocols.usb4.stress import USB4StressTester

stress_tester = USB4StressTester()

Methods๏ƒ

run_thermal_stress_test(duration: int, max_temp: float) -> ThermalStressResult๏ƒ

Runs thermal stress testing.

Parameters:

  • duration: Test duration in minutes

  • max_temp: Maximum allowed temperature in ยฐC

Returns:

  • ThermalStressResult: Thermal stress test results

Data Classes๏ƒ

USB4SignalData๏ƒ

Container for USB4 signal data.

@dataclass
class USB4SignalData:
    lane0_data: np.ndarray      # Lane 0 voltage data
    lane1_data: np.ndarray      # Lane 1 voltage data
    timestamp: np.ndarray       # Time array
    sample_rate: float          # Sample rate in Hz
    signal_mode: USB4SignalMode # Signal mode
    metadata: dict = field(default_factory=dict)

USB4ComplianceResult๏ƒ

Result of USB4 compliance testing.

@dataclass
class USB4ComplianceResult:
    test_name: str              # Test name
    status: bool                # Pass/fail status
    measured_value: float       # Measured value
    limit: USB4Limit           # Test limit
    margin: float              # Margin to limit
    timestamp: datetime        # Test timestamp
    metadata: dict = field(default_factory=dict)

USB4Limit๏ƒ

Test limit specification.

@dataclass
class USB4Limit:
    minimum: float             # Minimum allowed value
    maximum: float             # Maximum allowed value
    unit: str                  # Unit of measurement
    tolerance: float = 0.0     # Measurement tolerance

Constants and Enums๏ƒ

USB4SignalMode๏ƒ

USB4 signal mode enumeration.

class USB4SignalMode(Enum):
    GEN2_X2 = "Gen2x2"        # 20 Gbps
    GEN3_X2 = "Gen3x2"        # 40 Gbps
    ASYMMETRIC = "Asymmetric"  # Asymmetric mode

USB4LinkState๏ƒ

USB4 link state enumeration.

class USB4LinkState(Enum):
    U0 = "U0"                  # Active state
    U1 = "U1"                  # Low power state 1
    U2 = "U2"                  # Low power state 2
    U3 = "U3"                  # Suspend state

USB4TunnelingMode๏ƒ

USB4 tunneling mode enumeration.

class USB4TunnelingMode(Enum):
    PCIE = "PCIe"              # PCIe tunneling
    DISPLAYPORT = "DisplayPort" # DisplayPort tunneling
    USB32 = "USB3.2"           # USB 3.2 tunneling

Specifications Classes๏ƒ

USB4Specs๏ƒ

USB4 specification constants.

class USB4Specs:
    # Data rates
    GEN2_RATE = 20e9           # 20 Gbps
    GEN3_RATE = 40e9           # 40 Gbps
    
    # Signal integrity limits
    MIN_EYE_HEIGHT = 0.65      # Normalized
    MIN_EYE_WIDTH = 0.65       # Normalized
    MAX_RMS_JITTER = 0.025     # UI
    MAX_LANE_SKEW = 20e-12     # 20 ps
    
    # Power specifications
    MAX_POWER_CONSUMPTION = 7.5  # W
    STANDBY_POWER = 0.5        # W

ThunderboltSpecs๏ƒ

Thunderbolt 4 specification constants.

class ThunderboltSpecs:
    # Performance requirements
    TB4_BANDWIDTH = 40e9       # 40 Gbps
    TB4_POWER_DELIVERY = 100   # W
    
    # Device limits
    MAX_DAISY_DEVICES = 6      # devices
    MAX_4K_DISPLAYS = 2        # displays
    MAX_8K_DISPLAYS = 1        # display
    
    # Security requirements
    DMA_PROTECTION_REQUIRED = True
    DEVICE_AUTH_REQUIRED = True

Usage Examples๏ƒ

Basic USB4 Validation๏ƒ

# Initialize validator
validator = USB4Validator()

# Load signal data
signal_data = load_usb4_signal_data("capture.csv")

# Run validation
results = validator.validate_compliance(signal_data)

# Check results
for result in results:
    print(f"{result.test_name}: {'PASS' if result.status else 'FAIL'}")

Thunderbolt 4 Certification๏ƒ

# Initialize certification suite
cert_suite = IntelCertificationSuite()

# Configure device
device_config = {
    'vendor_id': 0x8086,
    'device_id': 0x1234,
    'firmware_version': '1.0.0'
}
cert_suite.configure_device(device_config)

# Run pre-certification checks
pre_checks = cert_suite.run_pre_certification_checks()

# Run full certification if pre-checks pass
if all(pre_checks.values()):
    cert_results = cert_suite.run_full_certification()
    print(f"Certification: {'PASS' if cert_results.passed else 'FAIL'}")

Mock Mode Testing๏ƒ

import os

# Enable mock mode
os.environ['SVF_MOCK_MODE'] = '1'

# All classes use mock implementations
validator = USB4Validator()
mock_data = validator.generate_mock_signal_data()
results = validator.validate_compliance(mock_data)

print("Mock validation completed successfully!")

For more examples and detailed usage, see: