TEST-PHC-DRIFT-001: Verify PHC vs Windows System Time Clock Drift

[zarfld]

Test Description

Verify that the PHC (PTP Hardware Clock) drift relative to Windows system time
(GetSystemTimeAsFileTime) is within expected bounds for an uncorrected oscillator,
confirming that the cross-timestamp correlation path functions correctly and the PHC
is actually running at a meaningful rate.

Test Objectives

• Synchronise PHC to Windows system time via IOCTL_AVB_SET_TIMESTAMP
• Measure PHC elapsed time over 1 second against Windows wall-clock elapsed time
• Calculate drift in ppm (parts per million)
• Verify drift is within crystal oscillator tolerance

Preconditions

• AVB filter driver installed and loaded
• Intel I210, I219-V, or I226-LM NIC with PTP hardware clock
• ptp_clock_control_test.exe built (Debug configuration)
• Driver handle opened
• TIMINCA at nominal (8 ns/cycle or adapter default)

Test Cases

TC-DRIFT-001: PHC drift within crystal oscillator tolerance after 1-second window

Steps:

1. Call GetSystemTimeAsFileTime() → winTime1
2. Call IOCTL_AVB_SET_TIMESTAMP(winTime1) to sync PHC to Windows time
3. Sleep 1000 ms
4. Call GetSystemTimeAsFileTime() → winTime2
5. Call IOCTL_AVB_GET_TIMESTAMP → ptpTime2
6. Compute winDelta = winTime2 − winTime1
7. Compute ptpDelta = ptpTime2 − winTime1
8. Compute drift = ptpDelta − winDelta
9. Compute driftPpm = drift / winDelta × 1,000,000

Expected Result: |driftPpm| < 100 ppm (typical crystal oscillator; PASS)
Acceptable Result: |driftPpm| < 500 ppm (wider tolerance; WARN/PASS)
Note: High drift (>500 ppm) is logged as WARNING, not a hard FAIL — expected before gPTP synchronisation

Acceptance Criteria

• ✅ IOCTL_AVB_SET_TIMESTAMP completes without error
• ✅ IOCTL_AVB_GET_TIMESTAMP returns non-zero timestamp after 1 s
• ✅ PHC elapsed time (ptpDelta) is positive and within 500 ppm of Windows elapsed time
• ✅ Drift magnitude printed in ppm for operator review
• ℹ️ High drift (>500 ppm) logged as WARNING but not a hard FAIL (expected before gPTP sync)

Test Type

• Type: Functional, Integration
• Priority: P1 (High — validates cross-timestamp baseline)
• Automation: Automated — tests/integration/ptp/ptp_clock_control_test.c, TestClockDrift() (Test 4)
• Status: ✅ Implemented and PASSING (commit f1fba3c, 2026-04-21)

Evidence

• Test function: TestClockDrift() in tests/integration/ptp/ptp_clock_control_test.c
• Commit f1fba3c: OID wait ensures TIMINCA is stable before measurement window begins

Traceability

• Traces to: REQ-F-IOCTL-XSTAMP-001: Cross-Timestamp Query (PHC + System Time) #48 (REQ-F-IOCTL-XSTAMP-001: Cross-Timestamp Query — PHC + System Time)
• Traces to: REQ-F-PTP-001: Hardware Timestamp Correlation for PTP/gPTP Protocol Analysis #149 (REQ-F-PTP-001: Hardware Timestamp Correlation for PTP/gPTP)
• Verifies: REQ-F-IOCTL-XSTAMP-001: Cross-Timestamp Query (PHC + System Time) #48 REQ-F-PTP-001: Hardware Timestamp Correlation for PTP/gPTP Protocol Analysis #149
• Implemented in: tests/integration/ptp/ptp_clock_control_test.c

[github-actions]

🤖 Status Sync

**Automatic status update** based on issue body:
- **Body status**: Not specified
- **Previous label(s)**: (none)
- **New label**: `status:backlog`

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

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

[github-actions]

⚠️ Missing Status Field

This issue does not have a clear status field in its body.

Recommendation: Add a status field to track progress:

**Status**: Draft | In Progress | Under Review | Completed | etc.

Current label: status:backlog (auto-assigned)

See Status Management Guide for lifecycle-specific states.

[github-actions]

🤖 Status Sync

**Automatic status update** based on issue body:
- **Body status**: Not specified
- **Previous label(s)**: (none)
- **New label**: `status:backlog`

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

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

[github-actions]

⚠️ Missing Status Field

This issue does not have a clear status field in its body.

Recommendation: Add a status field to track progress:

**Status**: Draft | In Progress | Under Review | Completed | etc.

Current label: status:backlog (auto-assigned)

See Status Management Guide for lifecycle-specific states.

[github-actions]

🤖 Status Sync

**Automatic status update** based on issue body:
- **Body status**: Not specified
- **Previous label(s)**: (none)
- **New label**: `status:backlog`

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

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