REQ-F-DEVICE-ABS-003: Register Access via Device Abstraction Layer

[zarfld]

Requirement Information

Requirement ID: REQ-F-DEVICE-ABS-003
Title: Register Access via Device Abstraction Layer
Priority: Critical
Status: Draft

Requirement Statement

The system shall perform all Intel NIC hardware register access exclusively through the device abstraction layer (devices/intel_device_interface.h) to enable hardware portability across Intel NIC families.

Rationale

Direct MMIO register access must be abstracted through device-specific implementations to support multiple Intel NIC families (I210, I217, I219, I225, I226, I350, 82575, 82576, 82580). This enables the filter driver to operate across hardware variants without conditional compilation or runtime device-specific branching in core logic.

Detailed Specification

[Previous detailed specification preserved - Architecture Overview, Device Operations Interface, Processing Rules, Integration Pattern, Device-Specific Implementation Example, Supported Hardware Abstraction Operations]

Error Handling

Error Scenario	NTSTATUS Code	User Impact	Recovery Action
Device ops NULL pointer	NDIS_STATUS_FAILURE	All register access fails	Device abstraction not initialized, reinitialize or reboot
Unsupported operation (device lacks feature)	NDIS_STATUS_NOT_SUPPORTED	Feature unavailable	Query capabilities before calling ops, use alternative method
BAR0 base address invalid	NDIS_STATUS_INVALID_ADDRESS	Cannot access hardware registers	BAR0 mapping failed during FilterAttach, reattach or replace NIC
Register read timeout (hardware unresponsive)	NDIS_STATUS_DEVICE_NOT_READY	Operation fails, retry may succeed	Hardware fault or power issue, retry or reset NIC
Register write verification failed	NDIS_STATUS_UNSUCCESSFUL	Write may not have taken effect	Read-back mismatch, retry write or report hardware fault
Device-specific exception (paging fault)	NDIS_STATUS_UNSUCCESSFUL	Kernel crash risk	Structured exception handler catches, log event, fail gracefully
HwAddr parameter NULL	NDIS_STATUS_INVALID_PARAMETER	Caller programming error	Validate context before device ops call
Device type mismatch	NDIS_STATUS_NOT_SUPPORTED	Wrong device ops assigned	Registry lookup failed, unsupported PCI Device ID
Concurrent access without lock	NDIS_STATUS_UNSUCCESSFUL	Race condition, corrupted register state	Always acquire RegisterLock before device ops call
Register offset out of bounds	NDIS_STATUS_INVALID_PARAMETER	Device-specific impl error	Validate register offsets against BAR0 size

Error Handling Notes:

• All device operations return NTSTATUS for consistent error propagation
• Structured exception handling (__try/__except) protects against paging faults during MMIO access
• Device ops NULL check required before every call (defensive programming)
• Register access must be within spin lock protection (see REQ-F-REG-ACCESS-001: Safe Register Access via Spin Locks #45)

Performance Requirements

Metric	Target	Measurement Method
Function Pointer Overhead	<10ns	Inline call vs. direct call comparison (RDTSC)
Device Ops Lookup (registry)	<50µs	Cache lookup after first resolution
Single Register Read (via abstraction)	<500ns	RDTSC around device_ops->get_systime() single MMIO read
Single Register Write (via abstraction)	<1µs	RDTSC around device_ops->set_systime() single MMIO write
64-bit Atomic Read (2 registers)	<2µs	SYSTIML+SYSTIMH read sequence
Multi-Register Write (TAS/CBS)	Linear O(n)	Per-register <3µs, 16 registers <50µs
Memory Footprint (ops structure)	<256 bytes	sizeof(intel_device_ops_t) + device context
Cache Efficiency	>95% L1 hit rate	CPU performance counters for device ops calls
Abstraction Penalty	<5% vs. direct access	Compare abstracted vs. direct register access latency

Performance Notes:

• Device ops function pointers cached in DEVICE_CONTEXT - no repeated lookups
• Compiler may inline device-specific implementations if static linkage used
• MMIO overhead dominates (PCI bus latency ~100ns), function pointer indirection negligible
• Batch operations (TAS config) amortize abstraction overhead across multiple registers
• Register access within spin lock - total latency includes lock acquisition overhead

Measurement Infrastructure:

• RDTSC: Cycle-level timing for device ops calls
• GPIO: Oscilloscope validation of hardware access timing
• Performance counters: Cache hit/miss rates, branch prediction
• ETW tracing: Per-operation breakdown (lookup, call, MMIO, return)

Acceptance Criteria (Gherkin Format)

[Previous acceptance criteria preserved]

Traceability

• Traces to: StR-002: Intel AVB Register Abstraction Compatibility (intel_avb Library) #29 (StR-002: Device Abstraction Layer for Hardware Portability)
• Traces to: StR-002: Intel AVB Register Abstraction Compatibility (intel_avb Library) #29 (StR-002: Device Abstraction Layer for Hardware Portability)
• Traces to: QA-SC-AVAIL-001: Driver Stability Under Continuous Load (24-Hour Stress Test) #108, QA-SC-SCAL-001: Multi-Adapter System Scalability (4+ Adapters) #109, QA-SC-RELI-001: Driver Recovery from Hardware Failure #136
• Depends on: REQ-F-NDIS-ATTACH-001: FilterAttach/FilterDetach #36 (FilterAttach/FilterDetach), REQ-F-HW-DETECT-001: Hardware Capability Detection #44 (Hardware Capability Detection)
• Verified by: TEST-DEVICE-ABS-001 (Phase 07)
• Implemented by: devices/intel_device_interface.h, devices/intel_device_registry.c, devices/intel_*_impl.c
• Satisfies: Hardware Portability requirement in StR-002

Priority Justification

• Business Impact: CRITICAL - Foundation for multi-device support
• Technical Impact: Enables filter driver to support 9+ Intel NIC families without core logic changes
• User Impact: All users across different Intel NICs (100%)
• Estimated Effort: L (Large) - Already implemented in Phase 05

Notes

Architecture Clarification:

• external/intel_avb/ is a consumer library (user-mode applications using the filter driver)
• Filter driver does NOT call intel_avb functions
• intel_avb calls filter driver via IOCTLs defined in include/avb_ioctl.h
• Device abstraction is implemented within the filter driver via devices/* files