[TEST] TEST-PTP-CORR-001: PTP Hardware Correlation Verification

[zarfld]

🧪 Test Case Specification: PTP Hardware Correlation Verification

Test ID: TEST-PTP-CORR-001
Test Name: PTP Hardware Correlation Verification
Priority: P0 (Critical)
Test Type: Unit, Integration, V&V
Phase: 07-verification-validation

---

🔗 Traceability

Traces to: #149 (REQ-F-PTP-007: Hardware Timestamp Correlation)
Verifies: #149
Related to: #2 (REQ-F-PTP-001: PHC Get/Set), #48 (REQ-F-IOCTL-PHC-004: Cross-Timestamp), #58 (REQ-NF-PERF-PHC-001: PHC Read Latency)
Related Quality Scenarios: #110 (QA-SC-PERF-001: PHC Performance), #104 (QA-SC-USABILITY-002: Clock Correlation)

---

📋 Test Objective

Validates hardware timestamp correlation between PHC (Precision Hardware Clock), packet TX/RX timestamps, and system time. Verifies:

1. TX Timestamp Correlation: Hardware TX timestamps use same PHC time base as PHC queries
2. RX Timestamp Correlation: Hardware RX timestamps use same PHC time base as PHC queries
3. Cross-Domain Correlation: PHC, TX/RX hardware timestamps, and system time all correlated accurately
4. Correlation Accuracy: Delta between correlated timestamps <1µs
5. Jitter Analysis: Timestamp correlation jitter <100ns (standard deviation)
6. Boundary Conditions: Correlation maintained across epoch resets, frequency adjustments, and driver reloads

---

🎯 Test Coverage

10 Unit Tests (Google Test, Mock NDIS)

UT-CORR-001: PHC-TX Timestamp Correlation

Objective: Verify TX hardware timestamp uses same PHC time base as PHC query.

Test Steps:

1. Read PHC timestamp: phc1 = ReadPhcTimestamp() (e.g., 1,000,000,000 ns)
2. Transmit packet and capture TX timestamp: txTimestamp (hardware-captured at transmission)
3. Read PHC timestamp: phc2 = ReadPhcTimestamp()
4. Verify correlation: phc1 <= txTimestamp <= phc2
5. Verify delta: (txTimestamp - phc1) < 1µs (TX occurred shortly after first PHC read)

Expected Result:

• TX timestamp falls within PHC read window: [phc1, phc2]
• Delta <1µs from PHC baseline

Acceptance Criteria:

UINT64 phc1 = ReadPhcTimestamp();
UINT64 txTimestamp = TransmitPacketAndCaptureTxTimestamp();
UINT64 phc2 = ReadPhcTimestamp();
EXPECT_GE(txTimestamp, phc1); // TX after first PHC read
EXPECT_LE(txTimestamp, phc2); // TX before second PHC read
EXPECT_LT(txTimestamp - phc1, 1000); // Delta <1µs

---

UT-CORR-002: PHC-RX Timestamp Correlation

Objective: Verify RX hardware timestamp uses same PHC time base as PHC query.

Test Steps:

1. Read PHC timestamp: phc1 = ReadPhcTimestamp()
2. Receive packet and capture RX timestamp: rxTimestamp (hardware-captured at reception)
3. Read PHC timestamp: phc2 = ReadPhcTimestamp()
4. Verify correlation: phc1 <= rxTimestamp <= phc2
5. Verify delta: (rxTimestamp - phc1) < 1µs

Expected Result:

• RX timestamp falls within PHC read window: [phc1, phc2]
• Delta <1µs from PHC baseline

---

UT-CORR-003: Cross-Timestamp Correlation Accuracy

Objective: Verify cross-timestamp correlation between PHC and system time <10µs.

Test Steps:

1. Capture cross-timestamp: {phcNs, systemTicks, accuracy}
2. Convert system ticks to nanoseconds: systemNs = systemTicks * 1e9 / QPF
3. Calculate delta: delta = |phcNs - systemNs|
4. Verify delta: delta < 10,000 (10µs, per REQ-F-IOCTL-XSTAMP-001: Cross-Timestamp Query (PHC + System Time) #48 specification)
5. Verify reported accuracy: accuracy < 10,000

Expected Result:

• PHC and system time correlated within 10µs
• Reported accuracy matches measured delta

---

UT-CORR-004: TX-RX Timestamp Correlation (Loopback)

Objective: Verify TX and RX timestamps correlated for loopback packets.

Test Steps:

1. Enable loopback mode (or use external loopback cable)
2. Transmit packet and capture TX timestamp: txTimestamp
3. Receive loopback packet and capture RX timestamp: rxTimestamp
4. Calculate propagation delay: delay = rxTimestamp - txTimestamp
5. Verify delay realistic: 0 < delay < 10µs (loopback latency)

Expected Result:

• RX timestamp > TX timestamp (causality preserved)
• Propagation delay <10µs (realistic for loopback)

---

UT-CORR-005: Correlation After Epoch Reset

Objective: Verify timestamp correlation maintained after PHC epoch reset.

Test Steps:

1. Read PHC: phc1 = 1,000,000,000 ns
2. Transmit packet: txTimestamp1 ≈ phc1
3. Reset epoch: SetPhcTimestamp(0)
4. Read PHC: phc2 = 0 ns
5. Transmit packet: txTimestamp2 ≈ phc2
6. Verify both TX timestamps correlated with respective PHC states

Expected Result:

• TX timestamps track PHC epoch changes
• Correlation maintained before and after reset

---

UT-CORR-006: Correlation After Frequency Adjustment

Objective: Verify timestamp correlation maintained during PHC frequency adjustment.

Test Steps:

1. Read PHC: phc1
2. Adjust frequency: SetPhcFrequencyAdjustment(+100 PPM) (speed up by 100 PPM)
3. Wait 100ms (PHC gains 10µs: 100ms × 100 PPM)
4. Read PHC: phc2
5. Transmit packet: txTimestamp
6. Verify correlation: txTimestamp ≈ phc2 (not phc1)

Expected Result:

• TX timestamp reflects adjusted PHC rate
• Correlation maintained during frequency adjustment

---

UT-CORR-007: Correlation Jitter Analysis

Objective: Verify timestamp correlation jitter <100ns (standard deviation).

Test Steps:

1. Collect 1000 samples:
   • Read PHC: phc[i]
   • Transmit packet: tx[i]
   • Calculate delta: delta[i] = tx[i] - phc[i]
2. Calculate statistics:
   • Mean delta: mean = avg(delta[])
   • Standard deviation: stddev = stdev(delta[])
3. Verify jitter: stddev < 100 (100ns)

Expected Result:

• Mean delta <1µs (systematic offset)
• Standard deviation <100ns (jitter)

---

UT-CORR-008: Multi-Packet Correlation Consistency

Objective: Verify correlation consistent across multiple consecutive packets.

Test Steps:

1. Transmit burst of 100 packets at 1ms intervals
2. For each packet:
   • Read PHC before TX: phc[i]
   • Capture TX timestamp: tx[i]
   • Calculate delta: delta[i] = tx[i] - phc[i]
3. Verify all deltas <1µs
4. Verify delta variance <100ns (consistent correlation)

Expected Result:

• All 100 deltas <1µs
• Variance <100ns (stable correlation)

---

UT-CORR-009: Correlation After Driver Reload

Objective: Verify timestamp correlation restored after driver unload/reload.

Test Steps:

1. Read PHC: phc1
2. Transmit packet: tx1 (verify tx1 ≈ phc1)
3. Unload driver
4. Reload driver (PHC may reset or persist)
5. Read PHC: phc2
6. Transmit packet: tx2 (verify tx2 ≈ phc2)

Expected Result:

• Correlation maintained before and after reload
• TX timestamps track PHC state (whether reset or persistent)

---

UT-CORR-010: Null Timestamp Handling

Objective: Verify graceful handling when hardware timestamps unavailable.

Test Steps:

1. Configure hardware to NOT provide TX timestamps (e.g., feature disabled)
2. Transmit packet
3. Verify TX timestamp query returns:
   • STATUS_NOT_SUPPORTED, or
   • Timestamp = 0 (invalid marker)
4. PHC remains functional (no correlation required when timestamps disabled)

Expected Result:

• Graceful error when timestamps unavailable
• PHC continues functioning independently

---

4 Integration Tests (Google Test + Mock NDIS + User-Mode Harness)

IT-CORR-001: End-to-End gPTP Sync with Hardware Timestamps

Objective: Verify gPTP synchronization using correlated hardware RX/TX timestamps and PHC.

Test Steps:

1. Configure gPTP master (external device) with known PHC time
2. Enable gPTP slave mode on DUT (Device Under Test)
3. Capture sync messages:
   • RX timestamp of Sync message: rxSync
   • TX timestamp of Delay_Req message: txDelayReq
   • RX timestamp of Delay_Resp message: rxDelayResp
4. Verify PHC adjusts to master within 1µs over 100 sync intervals
5. Verify all timestamps correlated (RX/TX timestamps track PHC adjustments)

Expected Result:

• gPTP slave synchronizes to master within 1µs
• All hardware timestamps correlated with PHC adjustments

---

IT-CORR-002: User-Mode Cross-Timestamp IOCTL

Objective: Verify user-mode application can correlate PHC with system time via IOCTL.

Test Steps:

1. Open device handle: \\.\IntelAvbFilter0
2. Call IOCTL_AVB_PHC_CROSSTIMESTAMP
3. Verify output:
   • phcTimestampNs valid (>0)
   • systemTimestampTicks valid (>0)
   • correlationAccuracyNs <10µs
4. Validate correlation: Call QueryPerformanceCounter independently and verify agreement within 50µs

Expected Result:

• User-mode app successfully correlates PHC and system time
• Correlation accuracy <10µs

---

IT-CORR-003: Multi-Adapter Correlation Independence

Objective: Verify each adapter maintains independent PHC-timestamp correlation.

Test Steps:

1. Configure 4 adapters with different PHC epochs:
   • Adapter 0: PHC = 1,000,000,000 ns
   • Adapter 1: PHC = 2,000,000,000 ns
   • Adapter 2: PHC = 3,000,000,000 ns
   • Adapter 3: PHC = 4,000,000,000 ns
2. For each adapter:
   • Read PHC: phc[i]
   • Transmit packet: tx[i]
   • Verify correlation: tx[i] ≈ phc[i]
3. Verify no cross-adapter interference (each TX timestamp matches its own PHC, not others)

Expected Result:

• Each adapter's TX timestamps correlate with its own PHC independently
• No cross-contamination between adapters

---

IT-CORR-004: Correlation Under High Packet Rate

Objective: Verify timestamp correlation maintained under high TX/RX packet rate (10,000 pps).

Test Steps:

1. Configure traffic generator: 10,000 packets/second (100µs inter-packet gap)
2. Transmit and receive packets for 10 seconds (100,000 packets total)
3. For random sample of 1000 packets:
   • Read PHC: phc[i]
   • Capture TX timestamp: tx[i]
   • Verify correlation: |tx[i] - phc[i]| < 1µs
4. Verify correlation accuracy does not degrade over time (first 100 vs last 100 samples)

Expected Result:

• All 1000 samples <1µs correlation
• No degradation over 10-second test

---

3 V&V Tests (User-Mode Harness, Quantified Metrics)

VV-CORR-001: Long-Term Correlation Stability (24 Hours)

Objective: Verify timestamp correlation remains <1µs over 24-hour continuous operation.

Test Steps:

1. Run continuous test for 24 hours:
   • Sample PHC-TX correlation every 10 seconds (8640 samples)
   • Measure correlation delta: delta[i] = tx[i] - phc[i]
2. Verify statistics:
   • Mean delta <1µs
   • Standard deviation <100ns
   • Max delta <2µs (allow occasional outliers)
   • No drift over time (first hour vs last hour)

Expected Result:

• Correlation stable over 24 hours
• No systematic drift

---

VV-CORR-002: Production gPTP Workload Correlation

Objective: Verify timestamp correlation during production gPTP synchronization workload.

Test Steps:

1. Configure production gPTP setup:
   • Master: External high-precision PTP grandmaster
   • Slave: DUT running IntelAvbFilter driver
   • Sync rate: 8 Hz (125ms intervals)
2. Run for 1 hour (28,800 sync messages)
3. Verify:
   • gPTP offset <1µs (slave synchronized)
   • Hardware RX/TX timestamps correlate with PHC (<1µs delta)
   • No correlation errors (all timestamps valid)

Expected Result:

• gPTP achieves <1µs synchronization
• All timestamps correlated correctly

---

VV-CORR-003: Cross-Domain Correlation Accuracy

Objective: Verify cross-domain correlation (PHC ↔ System Time ↔ TX/RX Timestamps) <10µs.

Test Steps:

1. Capture cross-domain correlation sample:
   • Read PHC: phcNs
   • Query system time: systemNs
   • Transmit packet: txNs
   • Receive loopback packet: rxNs
2. Verify all domains correlated:
   • |phcNs - systemNs| < 10µs (PHC ↔ System)
   • |phcNs - txNs| < 1µs (PHC ↔ TX)
   • |phcNs - rxNs| < 10µs (PHC ↔ RX, includes loopback delay)
3. Repeat 1000 samples, verify 99.9% within tolerances

Expected Result:

• All clock domains correlated within specified tolerances
• 99.9% success rate

---

🎯 Acceptance Criteria

1. Functional Correctness:

   • ✅ TX hardware timestamps correlate with PHC (<1µs delta)
   • ✅ RX hardware timestamps correlate with PHC (<1µs delta)
   • ✅ Cross-timestamp (PHC ↔ System) correlation <10µs
   • ✅ TX-RX loopback correlation (RX > TX, delay <10µs)

2. Correlation Accuracy:

   • ✅ Mean correlation delta <1µs
   • ✅ Jitter (standard deviation) <100ns
   • ✅ Max delta <2µs (99.9% of samples)

3. Boundary Conditions:

   • ✅ Correlation maintained after epoch reset
   • ✅ Correlation maintained during frequency adjustment
   • ✅ Correlation restored after driver reload

4. Concurrency & Scalability:

   • ✅ Multi-packet correlation consistency (100 packets, variance <100ns)
   • ✅ Multi-adapter independence (4 adapters, no cross-contamination)
   • ✅ High packet rate (10,000 pps, correlation maintained)

5. Long-Term Stability:

   • ✅ 24-hour stability (mean <1µs, stddev <100ns, no drift)
   • ✅ Production gPTP workload (1 hour, >99.6% correlation success)

6. Error Handling:

   • ✅ Null timestamp when hardware timestamps disabled
   • ✅ PHC remains functional independently

7. Traceability:

   • ✅ All tests reference requirement REQ-F-PTP-001: Hardware Timestamp Correlation for PTP/gPTP Protocol Analysis #149
   • ✅ Test results logged with issue references

---

📊 Test Metrics

Metric	Target	Measurement Method
PHC-TX Correlation	<1µs	`
PHC-RX Correlation	<1µs	`
Cross-Timestamp Correlation	<10µs	`
Correlation Jitter (Stddev)	<100ns	Standard deviation of deltas
Mean Correlation Delta	<1µs	Average of 1000 samples
Max Correlation Delta	<2µs	Max of 1000 samples
24-Hour Stability	No drift >100ns	First hour vs last hour mean
gPTP Production Success	>99.6%	Successful correlations / total samples
High Packet Rate	10,000 pps	100,000 packets, correlation maintained

---

Status: Ready for implementation (after Phase 05 unblocked by 40% test linkage)
Assignee: TBD
Estimated Effort: 4-5 days (10 unit + 4 integration + 3 V&V tests)
Dependencies: Hardware TX/RX timestamp support, gPTP stack integration

[github-actions]

❌ Traceability Link Missing

This requirement must link to its parent issue.

Required Action

Add the following to your issue body:

## Traceability
- Traces to:  #N (parent issue)

Traceability Rules

• REQ-F / REQ-NF → Link to parent StR issue
• ADR → Link to requirements it satisfies
• ARC-C → Link to ADRs and requirements
• TEST → Link to requirements being verified
• QA-SC → Link to related requirements

Standard: ISO/IEC/IEEE 29148:2018 (Bidirectional Traceability)

[github-actions]

🤖 Status Sync

**Automatic status update** based on issue body:
- **Body status**: Ready for implementation (after Phase 05 unblocked by 40% test linkage)
- **Previous label(s)**: (none)
- **New label**: `status:blocked`

This sync ensures consistency between issue status and labels for tracking purposes.

---
*Automated by [project-sync.yml](.github/workflows/project-sync.yml)*

[github-actions]

🤖 Status Sync

**Automatic status update** based on issue body:
- **Body status**: Ready for implementation (after Phase 05 unblocked by 40% test linkage)
- **Previous label(s)**: (none)
- **New label**: `status:blocked`

This sync ensures consistency between issue status and labels for tracking purposes.

---
*Automated by [project-sync.yml](.github/workflows/project-sync.yml)*

[github-actions]

🤖 Status Sync

**Automatic status update** based on issue body:
- **Body status**: Ready for implementation (after Phase 05 unblocked by 40% test linkage)
- **Previous label(s)**: (none)
- **New label**: `status:blocked`

This sync ensures consistency between issue status and labels for tracking purposes.

---
*Automated by [project-sync.yml](.github/workflows/project-sync.yml)*

[github-actions]

🤖 Status Sync

**Automatic status update** based on issue body:
- **Body status**: Ready for implementation (after Phase 05 unblocked by 40% test linkage)
- **Previous label(s)**: (none)
- **New label**: `status:blocked`

This sync ensures consistency between issue status and labels for tracking purposes.

---
*Automated by [project-sync.yml](.github/workflows/project-sync.yml)*

[github-actions]

🤖 Status Sync

**Automatic status update** based on issue body:
- **Body status**: Ready for implementation (after Phase 05 unblocked by 40% test linkage)
- **Previous label(s)**: (none)
- **New label**: `status:blocked`

This sync ensures consistency between issue status and labels for tracking purposes.

---
*Automated by [project-sync.yml](.github/workflows/project-sync.yml)*

[github-actions]

🤖 Status Sync

**Automatic status update** based on issue body:
- **Body status**: Ready for implementation (after Phase 05 unblocked by 40% test linkage)
- **Previous label(s)**: (none)
- **New label**: `status:blocked`

This sync ensures consistency between issue status and labels for tracking purposes.

---
*Automated by [project-sync.yml](.github/workflows/project-sync.yml)*