[INFRA] Mock NDIS Unit Test Harness — Close #199 Coverage Gaps (UT-CORR-001..010, VV-CORR-001..003)"

[zarfld]

Infrastructure: Mock NDIS Unit Test Harness

Type: Infrastructure / Test Engineering
Priority: P0
Phase: 07-verification-validation
Blocks: Full closure of TEST-PTP-CORR-001 (#199)

Traceability

Traces to: #149 (REQ-F-PTP-007: Hardware Timestamp Correlation)
Related to: #199 (TEST-PTP-CORR-001 — 13 tests not yet run)
Related to: #48 (REQ-F-IOCTL-PHC-004: Cross-Timestamp IOCTL — needed by Track B)
Related to: #177 (TEST-EVENT-001 — would also benefit from mock harness patterns)
Related to: #179 (TEST-EVENT-005 — would also benefit from mock harness patterns)

Context

Issue #199 was closed on 2026-03-27 with only 4 of 17 specified tests run (IT-CORR-001, 003, 004 PASS; IT-CORR-002 SKIP).
The remaining 13 tests (10 unit + 3 V&V) could not run because:

1. Missing IOCTLs (IOCTL_AVB_PHC_CROSSTIMESTAMP, IOCTL_AVB_GET_RX_TIMESTAMP)
2. Different clock epochs between FastIo TX timestamp path (QPC-relative) and PHC query (SYSTIM-relative)
3. No long-running monitoring script for 24h V&V test
4. No gPTP infrastructure for production workload V&V

#199 has been reopened. This issue tracks the infrastructure work needed.

Objective

Build the infrastructure to enable all 13 remaining tests in #199, organized into four tracks.

Work Tracks

Track A — Extend IOCTL Harness (Sprint 5, ~2 days)

Add test cases to tests/integration/ptp_corr/test_ptp_corr_extended.c.
No new driver changes required.

• UT-CORR-005: Correlation after PHC epoch reset (IOCTL_AVB_SET_TIMESTAMP(0))
• UT-CORR-006: Correlation after frequency adjustment (+100 PPM)
• UT-CORR-007: Jitter analysis — 1000 samples, stddev <100ns (rate-normalized)
• UT-CORR-008: 100-packet burst consistency — variance <100ns equivalent
• UT-CORR-009: Correlation restored after driver reload (elevated PowerShell wrapper)

Acceptance: avb_test_ptp_corr_ext.exe runs; all 5 tests PASS on ≥2 adapters.

---

Track B — IOCTL_AVB_PHC_CROSSTIMESTAMP (Sprint 5, ~3 days)

Implement IOCTL code 27 in src/device.c (per #48).
Returns {phcTimestampNs, systemTimestampTicks, correlationAccuracyNs}.

• TDD: write failing IT-CORR-002 assertion (already SKIP — enable it)
• Implement handler using ops->get_systim() + KeQueryPerformanceCounter in one critical section
• GREEN: IT-CORR-002 PASS
• Add UT-CORR-003 to test_ptp_corr_extended.c: delta <10µs

Acceptance: IT-CORR-002 no longer SKIP — PASS on all adapters. UT-CORR-003 PASS.

---

Track C — IOCTL_AVB_GET_RX_TIMESTAMP (Sprint 6, ~4 days)

Store NIC's hardware RX timestamp in AVB_ADAPTER_CONTEXT (via NDIS receive path).
Add new IOCTL (similar to IOCTL_AVB_GET_TX_TIMESTAMP).

• TDD: write failing UT-CORR-002 (RX correlation) and UT-CORR-004 (loopback causality) first
• Store RX timestamp in IndicateReceiveNetBufferLists or ReturnNetBufferLists
• Expose via new IOCTL
• GREEN: UT-CORR-002, UT-CORR-004 PASS (hardware-gated SKIP acceptable)

---

Track D — Epoch Unification (Sprint 6, ~3 days)

Unify last_ndis_tx_timestamp (currently QPC-relative) and IOCTL_AVB_GET_TIMESTAMP (currently SYSTIM epoch) so both report values in the same domain. This enables the absolute bracket test phc_before ≤ txTs ≤ phc_after.

Preferred approach (Option D1):

• At AvbBringUpHardware(), atomically read SYSTIM + QPC, compute epoch_offset_ns = systim_ns - qpc_ns

• Store epoch_offset_ns in AVB_ADAPTER_CONTEXT

• FastIo TX path: store qpc_ns (unchanged from current fix)

• IOCTL_AVB_GET_TIMESTAMP: return systim_ns - epoch_offset_ns — both now QPC-relative

• Verify gPTP callers are not sensitive to PHC absolute epoch before implementing

• Implement epoch_offset in AvbBringUpHardware()

• Adjust IOCTL_AVB_GET_TIMESTAMP handler

• UT-CORR-001: PASS (bracket test) in test_ptp_corr_extended.c

• UT-CORR-010: PASS — test graceful behavior when TX HW timestamps disabled (via error inject path)

• All existing PHC tests still PASS (full regression)

---

Track E — Long-Running V&V Scripts (Sprint 5–Future)

• VV-CORR-001 (Sprint 5, 1d): PowerShell monitor script — sample every 10s for 24h → CSV → summary stats
• VV-CORR-002 (Future): Requires gPTP grandmaster + ptp4l/pfd4l in lab — document SKIP with rationale if unavailable
• VV-CORR-003 (Sprint 6, after Track B+C): Cross-domain PHC↔System↔TX↔RX all within tolerances

---

Full Gate: #199 Can Re-close When

• UT-CORR-001: PASS (Track D)
• UT-CORR-002: PASS or HW-gated SKIP documented (Track C)
• UT-CORR-003: PASS (Track B)
• UT-CORR-004: PASS or HW-gated SKIP documented (Track C)
• UT-CORR-005..009: all PASS (Track A)
• UT-CORR-010: PASS (Track D)
• IT-CORR-002: PASS (not SKIP) (Track B)
• VV-CORR-001: 24h log PASS (Track E)
• VV-CORR-002: PASS or documented SKIP with rationale (Track E)
• VV-CORR-003: PASS or documented SKIP with rationale (Track E)

Reference Documents

• Test plan: 07-verification-validation/test-plans/TEST-PLAN-MOCK-NDIS-HARNESS.md
• Parent test spec: [TEST] TEST-PTP-CORR-001: PTP Hardware Correlation Verification #199 (full UT/IT/VV specs in issue body)
• Existing integration test: tests/integration/ptp_corr/test_ptp_corr.c

[github-actions]

❌ Test Requirements Missing

Test cases must link to the requirements they verify.

Required Action

Add the following to your issue body:

## Verified Requirements
- #N (REQ-F or REQ-NF issue)

Or in the description:

Verifies: #N, #M (requirement issues)

[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]

🤖 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]

🤖 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]

🤖 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]

🤖 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)*