TEST-PTP-CTRL-001: Verify PTP Clock Control IOCTLs (ADJUST_FREQUENCY, GET_CLOCK_CONFIG)

[zarfld]

Test Description

Verify that the AVB filter driver correctly implements IOCTL_AVB_ADJUST_FREQUENCY and
IOCTL_AVB_GET_CLOCK_CONFIG for production-safe PTP clock frequency control on Intel I210,
I219, and I226 NICs. Tests cover TIMINCA register encoding, readback verification, and
measured PHC rate change across the full valid increment range for each adapter type.

Test Objectives

• Validate IOCTL_AVB_ADJUST_FREQUENCY correctly programs TIMINCA for I210/I226 and I219 encoding
• Validate IOCTL_AVB_GET_CLOCK_CONFIG returns the correct TIMINCA readback
• Verify PHC clock rate changes measurably when increment_ns is changed
• Confirm test values stay within hardware IV field limits (24-bit for I219: max increment_ns=8)
• Verify correct TIMINCA restore after test (no persistent rate corruption across runs)

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; OID handler settle complete (≥300 ms after OPEN_ADAPTER)

Test Cases

TC-CTRL-001: Adjust frequency to minimum (1 ns/cycle) and verify

Steps:

1. Call IOCTL_AVB_ADJUST_FREQUENCY(increment_ns=1)
2. Call IOCTL_AVB_GET_CLOCK_CONFIG
3. Verify TIMINCA == 0x01000000 (I210/I226) OR (IP=2, IV=2,000,000) (I219)
4. Sleep 100 ms, measure PHC delta
5. Assert PHC is incrementing

TC-CTRL-002: Adjust frequency to nominal (8 ns/cycle I210/I219; 24 for I226) and verify

Steps:

1. Detect nominal_ns from current TIMINCA via GET_CLOCK_CONFIG
2. Call IOCTL_AVB_ADJUST_FREQUENCY(increment_ns=nominal_ns)
3. Verify TIMINCA readback matches expected encoding for adapter type
4. Measure PHC rate over 100 ms; assert positive increment

TC-CTRL-003: Adjust frequency to near-maximum valid value — no IV overflow

Steps:

1. For I219: val_near_max = 7 (IV = 14,000,000 ≤ 0xFFFFFF ✓)
2. For I210/I226: val_near_max = 2×nominal−2
3. Call IOCTL_AVB_ADJUST_FREQUENCY(increment_ns=val_near_max)
4. Verify TIMINCA readback (no driver clamping / mismatch)
5. Measure PHC rate

TC-CTRL-004: Adjust frequency to mid-range value and verify

Steps: Set increment_ns = midpoint([1, max_valid]), verify TIMINCA readback, assert PHC incrementing.

TC-CTRL-005: Adjust frequency to secondary low value and verify

Steps: Set increment_ns = 2 (or 3 if collides with mid), verify TIMINCA readback, assert PHC incrementing.

TC-CTRL-006: GET_CLOCK_CONFIG returns stable configuration

Steps:

1. Call IOCTL_AVB_GET_CLOCK_CONFIG
2. Verify status == 0, timinca != 0
3. Verify systim is non-zero and incrementing on second read

TC-CTRL-007: Restore original TIMINCA correctly after test

Steps:

1. Read originalTiminca via GET_CLOCK_CONFIG
2. Run TC-CTRL-001 through TC-CTRL-005
3. Restore via IOCTL_AVB_ADJUST_FREQUENCY(increment_ns=restore_ns) where:
   • I219 (IP==2, IV>0): always restore_ns=8 (hardware nominal IV=16,000,000)
   • I210/I226: restore_ns = orig_ip
4. Read TIMINCA again, verify nominal encoding

Expected Result: TIMINCA restored to nominal; TC-5b in subsequent run sees stable rate

Acceptance Criteria

• ✅ IOCTL_AVB_ADJUST_FREQUENCY succeeds for all values in [1, max_valid]
• ✅ IOCTL_AVB_GET_CLOCK_CONFIG TIMINCA readback matches expected encoding per adapter type
• ✅ PHC clock increments positively after each ADJUST_FREQUENCY call
• ✅ I219 IV field does not overflow 24 bits (no clamping / readback mismatch)
• ✅ Original TIMINCA restored correctly — verified by stable TC-5b in next run
• ✅ No residual TIMINCA corruption across consecutive test runs (second run clean)

Test Type

• Type: Functional, Integration
• Priority: P0 (Critical — production PTP clock control path)
• Automation: Automated — tests/integration/ptp/ptp_clock_control_test.c, TestClockAdjustment() (Test 2) + TestFrequencyTuning() (Test 3)
• Status: ✅ Implemented and PASSING (commit f1fba3c, 2026-04-21)

Evidence

• Test functions: TestClockAdjustment() + TestFrequencyTuning() in tests/integration/ptp/ptp_clock_control_test.c
• Commit f1fba3c: corrects I219 TIMINCA detection, overflow prevention, and restore logic
• Local result: 6/6 subtests PASS on both first and second consecutive run (stable restore verified)

Traceability

• Traces to: REQ-F-PTP-IOCTL-001: Production-Safe PTP Clock Control IOCTLs (ADJUST_FREQUENCY, GET_CLOCK_CONFIG) #326 (REQ-F-PTP-IOCTL-001: Production-Safe PTP Clock Control IOCTLs)
• Verifies: REQ-F-PTP-IOCTL-001: Production-Safe PTP Clock Control IOCTLs (ADJUST_FREQUENCY, GET_CLOCK_CONFIG) #326
• Implemented in: tests/integration/ptp/ptp_clock_control_test.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)*