REQ-F-IOCTL-PHC-003: PHC Offset Adjustment

[zarfld]

Traces to: #28 (StR-001: gPTP Stack Integration), #34 (REQ-F-IOCTL-PHC-001: PHC Time Query)

Requirement Information

Requirement ID: REQ-F-IOCTL-PHC-003
Title: PHC Offset Adjustment
Priority: Critical
Status: Draft

Requirement Statement

The system shall provide an IOCTL to adjust the PHC by a specified nanosecond offset, enabling stepwise clock correction.

Rationale

gPTP servo requires the ability to adjust PHC time when the clock offset exceeds a threshold (typically >100ns), implementing the PTP clock adjustment mechanism per IEEE 1588-2019.

Detailed Specification

Inputs

Input Parameter	Type	Format	Range/Constraints	Required?
DeviceHandle	HANDLE	Windows handle	Valid driver handle	Yes
IoctlCode	DWORD	0x9C40A090	PHC_OFFSET_ADJUST	Yes
OffsetNanoseconds	INT64	Signed nanoseconds	±10^9 ns (±1 second)	Yes
OutputBuffer	PPHC_ADJUST_RESULT	Pointer	Valid memory	Yes

Processing Rules

1. Rule 1: Validate offset is within bounds (±1 second)
2. Rule 2: Acquire PHC spin lock
3. Rule 3: Read current SYSTIML/SYSTIMH
4. Rule 4: Add offset (handle underflow/overflow)
5. Rule 5: Write new time to SYSTIML/SYSTIMH atomically
6. Rule 6: Release spin lock

Outputs

Output	Type	Format	Description
old_phc_time_ns	UINT64	Nanoseconds (TAI)	PHC time before adjustment
new_phc_time_ns	UINT64	Nanoseconds (TAI)	PHC time after adjustment
actual_offset_ns	INT64	Nanoseconds	Actual offset applied
NtStatus	NTSTATUS	Windows error code	STATUS_SUCCESS or error

Acceptance Criteria (Gherkin Format)

Scenario 1: Positive Offset Adjustment

Given PHC time is 1000000000 ns
When user-mode application requests +500 ns offset adjustment
Then IOCTL returns STATUS_SUCCESS
  And old_phc_time_ns = 1000000000 ns
  And new_phc_time_ns = 1000000500 ns
  And actual_offset_ns = +500 ns

Scenario 2: Negative Offset Adjustment

Given PHC time is 2000000000 ns
When user-mode application requests -1000 ns offset adjustment
Then IOCTL returns STATUS_SUCCESS
  And new_phc_time_ns = 1999999000 ns

Error Handling

Error Scenario	NTSTATUS Code	User Impact	Recovery Action
Hardware not initialized	STATUS_DEVICE_NOT_READY	IOCTL fails immediately	Initialize hardware via attach/power-up
Output buffer too small	STATUS_BUFFER_TOO_SMALL	IOCTL fails, returns required size	Retry with correct buffer size (32 bytes)
Output buffer NULL	STATUS_INVALID_PARAMETER	IOCTL fails immediately	Provide valid buffer pointer
Offset out of range (>±1s)	STATUS_INVALID_PARAMETER	IOCTL fails, no adjustment made	Validate offset ±1,000,000,000 ns range
Input buffer NULL	STATUS_INVALID_PARAMETER	IOCTL fails immediately	Provide valid input buffer with offset
Input buffer too small	STATUS_BUFFER_TOO_SMALL	IOCTL fails immediately	Provide buffer with INT64 offset value
Hardware write timeout	STATUS_IO_TIMEOUT	IOCTL fails after 1ms, no change	Check hardware state, retry or reset
Register write failure	STATUS_DEVICE_HARDWARE_ERROR	IOCTL fails, PHC may be inconsistent	Verify PCI config, may require hardware reset
Concurrent access collision	Internal retry (transparent)	Slight latency increase	Spin lock retry (max 3 attempts)
IRQL too high	STATUS_INVALID_DEVICE_STATE	IOCTL fails immediately	Call from PASSIVE_LEVEL context
PHC rollover during adjustment	Handled internally	Transparent to caller	64-bit arithmetic handles overflow correctly
Adjustment would cause negative time	STATUS_INVALID_PARAMETER	IOCTL fails, time cannot go negative	Validate adjustment keeps time ≥ 0

Performance Requirements

Metric	Target	Measurement Method
IOCTL Latency (P50)	<5µs	RDTSC before/after IOCTL call
IOCTL Latency (P99)	<12µs	RDTSC percentile analysis (10K calls)
Register Write Time	<3µs	GPIO toggle + oscilloscope (write SYSTIML/SYSTIMH)
Lock Acquisition	<1µs	Spin lock instrumentation
Lock Contention (Max)	<5µs	Worst-case wait time under load
Throughput (Single Thread)	>50K ops/sec	Sustained IOCTL rate measurement
Throughput (4 Threads)	>100K ops/sec	Concurrent load test with 4 threads
Adjustment Precision	±1ns	Verify actual offset matches requested
Atomic Write Guarantee	100%	No torn writes to 64-bit PHC register
Offset Range Validation	<500ns	Input parameter boundary check time
Rollover Handling	<2µs	64-bit overflow arithmetic overhead
Read-Modify-Write Sequence	<4µs	Complete transaction time (read + add + write)

Traceability

• Traces to: StR-GPTP-HARDWARE-001: Hardware Abstraction for External gPTP Stack #28 (StR-001: gPTP Stack Integration), REQ-F-IOCTL-PHC-001: PHC Time Query #34 (REQ-F-IOCTL-PHC-001: PHC Time Query)
• Depends on: REQ-F-IOCTL-PHC-001: PHC Time Query #34 (REQ-F-IOCTL-PHC-001: PHC Time Query)
• Related: REQ-F-IOCTL-TS-001: TX Timestamp Retrieval #35, REQ-F-IOCTL-TS-002: RX Timestamp Retrieval #37 (TX/RX timestamp retrieval)
• Verified by: TEST-PHC-OFFSET-001 (Phase 07)
• Verified by: [TEST] TEST-IOCTL-OFFSET-001: PHC Time Offset Adjustment IOCTL Verification #194 (TEST-IOCTL-OFFSET-001)
• Satisfies: Success Criteria REQ-F-PTP-002: PTP Clock Frequency Adjustment (IOCTL 38) #3 in StR-001 (PHC adjustment capability)

Priority Justification

• Business Impact: CRITICAL - Clock servo cannot function without offset adjustment
• User Impact: All gPTP users (100%)
• Dependencies: Blocks PTP synchronization servo
• Estimated Effort: M (Medium) - ~2 days

[zarfld]

Requirement Enhancement - Error Handling & Performance Requirements Added

Summary: Enhanced requirement specification with comprehensive error handling table and detailed performance metrics specific to PHC offset adjustment (write operation).

Error Handling Section

Added 12 error scenarios with specific NTSTATUS codes, user impact assessment, and recovery actions:

• Hardware initialization failures
• Buffer validation errors (input and output, size, NULL pointer)
• Write-Specific: Offset out of range (±1 second boundary validation)
• Write-Specific: Hardware write timeout (1ms threshold)
• Write-Specific: Register write failure (PHC may be inconsistent)
• Write-Specific: PHC rollover during adjustment (64-bit arithmetic)
• Write-Specific: Adjustment would cause negative time (boundary check)
• Concurrency collision handling
• IRQL context validation

Performance Requirements Section

Added 12 measurable performance metrics with targets and measurement methods:

• IOCTL Latency: P50 <5µs, P99 <12µs (slightly higher due to write operation)
• Register Write: <3µs (GPIO + oscilloscope for SYSTIML/SYSTIMH write)
• Throughput: >50K ops/sec (single thread), >100K ops/sec (4 threads) - lower than reads
• Adjustment Precision: ±1ns (verify actual offset matches requested)
• Atomic Write: 100% guarantee (no torn writes to 64-bit register)
• Offset Validation: <500ns (input parameter boundary check)
• Rollover Handling: <2µs (64-bit overflow arithmetic)
• Read-Modify-Write: <4µs (complete transaction time)

Rationale

• Write Operation: Inherently slower than read operations (register writes take longer)
• Data Integrity: Atomic write guarantee critical for clock consistency
• Servo Requirements: gPTP servo uses offset adjustment for stepwise corrections >100ns
• Range Validation: ±1 second limit prevents excessive time jumps
• Standards Compliance: IEEE 1588-2019 clock adjustment mechanism