I219 PCH-Based MDIO and PTP Access Implementation

[zarfld]

Type

Enhancement (P1 - High Priority)

Phase

Phase 05 - Implementation (Iteration 3)

Component

Hardware Access Layer (DES-C-HW-008)

---

Context

✅ Already Complete (Production Ready)

• I210: Full MDIO + Enhanced PTP implementation
• I225: Full MDIO + PTP + TSN (TAS/CBS/FP) implementation
• I226: Full MDIO + PTP + TSN + EEE implementation
• I217: Basic MDIO + PTP implementation

⚠️ Problem (I219 Only)

DES-C-HW-008 currently implements I219 MDIO and PTP access as stubs returning -1.

Root Cause: I219 uses PCH-based (Platform Controller Hub) management and timing mechanisms instead of standard controller MMIO registers.

Current Behavior:

// i219_mdio.c (stub implementation)
int AvbMdioReadReal_I219(device_t *dev, USHORT phy_addr, USHORT reg_addr, USHORT *value) {
    // I219 requires PCH-based access (not yet implemented)
    if (value) *value = 0;
    return -1;  // Graceful failure
}

// i219_ptp.c (stub implementation)
int AvbReadTimestampReal_I219(device_t *dev, ULONGLONG *timestamp) {
    // I219 PTP clock uses PCH-based SYSTIM equivalent
    if (timestamp) *timestamp = 0;
    return -1;  // Graceful failure
}

Impact:

• Driver loads successfully on I219 devices ✅
• Device enumeration succeeds (hw_state == BOUND) ✅
• Basic network connectivity functional ✅
• Advanced features unavailable (PTP timestamps, PHY link status) ⚠️

---

Objectives

Implement PCH-based hardware access for I219 controllers to enable full feature parity with other Intel NICs.

Success Criteria

1. ✅ I219 devices report hw_state == PTP_READY (not just BOUND)
2. ✅ PTP clock reads complete in <1µs (measured latency)
3. ✅ MDIO PHY reads succeed with correct link status
4. ✅ All unit tests pass (>85% coverage target)
5. ✅ Physical hardware validation on I219 NIC

---

Requirements

Functional Requirements

REQ-F-HW-I219-001: PCH-Based MDIO Access

Description: Implement MDIO read/write operations using PCH-specific registers instead of standard controller MMIO.

Acceptance Criteria:

• Given I219 controller initialized
• When AvbMdioRead() called with valid PHY address and register
• Then operation completes in <50µs with correct PHY register value
• And graceful error handling if PCH interface unavailable

Traceability:

• Implements: DES-C-HW-008 Section 11 (Future Enhancements)
• Traces to: DES-C-DEVICE-004: Device Abstraction Layer Design (Phase 04) #155 DESIGN-REVIEW-SUMMARY.md Gap 1

---

REQ-F-HW-I219-002: PCH-Based PTP Clock Access

Description: Implement PTP clock read/write operations using PCH-based SYSTIM equivalent.

Acceptance Criteria:

• Given I219 controller initialized with PCH interface
• When AvbReadTimestamp() called
• Then PTP clock value returned in <1µs
• And clock value is IEEE 1588 compliant (nanosecond precision)

Traceability:

• Implements: DES-C-HW-008 Section 11 (Future Enhancements)
• Traces to: DES-C-HW-008: Hardware Access Wrappers Design (Phase 04) #159 DESIGN-REVIEW-SUMMARY.md Gap 1

---

REQ-F-HW-I219-003: Transparent Interface Compatibility

Description: Maintain existing AvbMdioRead() and AvbReadTimestamp() interfaces; internal dispatch to PCH functions.

Acceptance Criteria:

• Given user-mode application using IOCTL interface
• When I219 device selected
• Then no API changes required (transparent PCH dispatch)
• And error codes consistent with other devices

Traceability:

• Implements: DES-C-DEVICE-004 (Strategy Pattern)

---

Non-Functional Requirements

REQ-NF-HW-I219-001: Performance

Target: PTP clock read <1µs (p95), MDIO operation <50µs

REQ-NF-HW-I219-002: Reliability

Target: >99.9% success rate on valid operations

REQ-NF-HW-I219-003: Test Coverage

Target: >85% code coverage (unit + integration tests)

---

Technical Approach

Phase 1: Research & Specification (2-3 days)

1. Review Intel I219 datasheet (PCH-specific sections)
2. Identify PCH register addresses for:
   • MDIO control/data registers
   • PTP clock registers (SYSTIM equivalent)
   • Status/error registers
3. Document register layouts in intel-ethernet-regs/devices/i219_pch.yaml
4. Generate header files using reggen.py

Phase 2: Implementation (5-7 days)

MDIO Implementation

// i219_mdio_pch.c (new file)
#include "i219_pch_regs.h"  // Generated from YAML

int AvbPchMdioRead(device_t *dev, USHORT phy_addr, USHORT reg_addr, USHORT *value) {
    // Step 1: Validate PCH interface available
    if (!dev->pch_base) return -ENODEV;
    
    // Step 2: Write PHY address + register to PCH control register
    WRITE_PCH_REG(dev, MDIO_CTRL, (phy_addr << 8) | reg_addr);
    
    // Step 3: Trigger operation (set READ bit)
    WRITE_PCH_REG(dev, MDIO_CMD, MDIO_CMD_READ);
    
    // Step 4: Busy-wait for completion (timeout 50µs)
    for (int i = 0; i < 100; i++) {
        ULONG status = READ_PCH_REG(dev, MDIO_STATUS);
        if (status & MDIO_STATUS_READY) {
            *value = (USHORT)READ_PCH_REG(dev, MDIO_DATA);
            return 0;
        }
        KeStallExecutionProcessor(1);  // 1µs delay
    }
    
    return -ETIMEDOUT;
}

PTP Clock Implementation

// i219_ptp_pch.c (new file)
int AvbPchReadTimestamp(device_t *dev, ULONGLONG *timestamp) {
    // Step 1: Validate PCH interface
    if (!dev->pch_base) return -ENODEV;
    
    // Step 2: Atomic read of PCH SYSTIM registers
    ULONG systiml_first = READ_PCH_REG(dev, SYSTIML);
    ULONG systimh = READ_PCH_REG(dev, SYSTIMH);
    ULONG systiml_second = READ_PCH_REG(dev, SYSTIML);
    
    // Step 3: Detect rollover (retry if SYSTIML wrapped)
    if (systiml_second < systiml_first) {
        systimh = READ_PCH_REG(dev, SYSTIMH);
        systiml_first = systiml_second;
    }
    
    // Step 4: Combine into 64-bit timestamp
    *timestamp = ((ULONGLONG)systimh << 32) | systiml_first;
    return 0;
}

Device Operations Table Update

// i219_device.c (update)
const struct intel_device_ops i219_ops = {
    .init = intel_i219_init,
    .read_phc = AvbPchReadTimestamp,      // ← PCH function
    .adjust_clock = AvbPchAdjustClock,    // ← PCH function
    .mdio_read = AvbPchMdioRead,          // ← PCH function
    .mdio_write = AvbPchMdioWrite,        // ← PCH function
    // TSN ops remain NULL (not supported by I219 hardware)
};

Phase 3: Testing (3-4 days)

Unit Tests (User-Mode)

// test_i219_pch.c
void test_pch_mdio_read_success(void) {
    // Mock PCH register interface
    device_t *dev = create_mock_i219_device();
    
    // Simulate successful PHY read
    set_pch_register(dev, MDIO_DATA, 0x1234);
    set_pch_register(dev, MDIO_STATUS, MDIO_STATUS_READY);
    
    USHORT value;
    int ret = AvbPchMdioRead(dev, 0x00, 0x01, &value);
    
    assert(ret == 0);
    assert(value == 0x1234);
}

void test_pch_timestamp_read_no_rollover(void) {
    device_t *dev = create_mock_i219_device();
    
    set_pch_register(dev, SYSTIML, 0x12345678);
    set_pch_register(dev, SYSTIMH, 0xABCDEF00);
    
    ULONGLONG timestamp;
    int ret = AvbPchReadTimestamp(dev, &timestamp);
    
    assert(ret == 0);
    assert(timestamp == 0xABCDEF0012345678ULL);
}

Integration Tests (Kernel Driver)

• PCH interface initialization during FilterAttach
• End-to-end MDIO read with physical I219 NIC
• PTP clock synchronization test

Hardware Validation

• Physical I219 NIC required
• Verify PHY link status reads correctly
• Measure PTP clock read latency (<1µs target)

---

Implementation Plan

Iteration 3 Tasks (2 weeks, 1 developer)

Week 1: Research + Implementation

• Day 1-2: I219 datasheet research (PCH register documentation)
• Day 3: Create i219_pch.yaml register definitions
• Day 4-5: Implement AvbPchMdioRead() / AvbPchMdioWrite()

Week 2: Testing + Validation

• Day 1-2: Implement AvbPchReadTimestamp() / AvbPchWriteTimestamp()
• Day 3: Unit tests (>85% coverage)
• Day 4: Integration tests + physical hardware validation
• Day 5: Documentation updates (DES-C-HW-008 Section 7.4)

---

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
PCH register docs unavailable	Medium	High	Use reverse engineering (Linux e1000e driver)
PCH interface latency >1µs	Low	Medium	Accept <5µs as fallback target
I219 hardware unavailable	Low	High	Use emulator/simulator during development
PCH register access requires special mode	Medium	High	Implement mode switching logic

---

Dependencies

• Hardware: Physical I219 NIC for validation
• Documentation: Intel I219 datasheet (PCH section)
• Tools: reggen.py script (register header generation)
• Design Docs: DES-C-HW-008 (updated with I219 PCH access)

---

Testing Strategy

Test Pyramid

• Unit Tests (70%): Mock PCH interface, verify logic
• Integration Tests (20%): Kernel driver with mock NIC
• Hardware Tests (10%): Physical I219 NIC validation

Coverage Targets

• Line coverage: >85%
• Branch coverage: >80%
• Critical path coverage: 100%

---

Acceptance Criteria (Definition of Done)

• PCH-based MDIO read/write implemented
• PCH-based PTP clock read/write implemented
• i219_ops vtable updated with PCH functions
• Unit tests written and passing (>85% coverage)
• Integration tests passing
• Physical hardware validation complete
• Performance targets met (PTP <1µs, MDIO <50µs)
• DES-C-HW-008 updated with I219 PCH implementation
• Code review approved
• PR merged to master

---

Traceability

Parent Requirements

• Traces to: DESIGN-REVIEW-SUMMARY.md (Gap 1: Device Hardware Support)
• Traces to: DES-C-HW-008 Section 11 (Future Enhancements)

Design Documents

• Implements: DES-C-HW-008 (Hardware Access Wrappers)
• Modifies: DES-C-DEVICE-004 (I219 device operations table)

Standards Compliance

• IEEE 1588: PTP clock interface (nanosecond precision)
• ISO/IEC/IEEE 12207: Implementation process (Phase 05)

---

Related Issues

• Part of Phase 05 Iteration 3
• Unblocks I219 device full feature support

---

Labels

type:enhancement, priority:p1, phase:05-implementation, component:hardware-access, device:i219

[zarfld]

Implementation Complete — Closing

All implementation gaps described in this issue have been resolved.

What was implemented in devices/intel_i219_impl.c

Function	Status	Description
mdio_read()	✅ Implemented	Full PCH MDIC path: acquire EXTCNF_CTRL.SWFLAG → write MDIC cmd → poll ready bit → release SWFLAG
mdio_write()	✅ Implemented	Same path with write opcode
i219_acquire_swsm()	✅ Implemented	Polls EXTCNF_CTRL.SWFLAG clear (200 × 50µs) then sets it
i219_release_swsm()	✅ Implemented	Clears SWFLAG after MDIO operation
get_systime()	✅ Implemented	SYSTIMH read (latches SYSTIML) → raw/200000 + i219_systim_offset
set_systime()	✅ Implemented	Pure software-offset update: offset = target − raw/200000
enable_packet_timestamping()	✅ Implemented	TSYNCRXCTL TYPE=4 (all pkts) + TSYNCTXCTL EN=1

All functions use SSOT register definitions from intel-ethernet-regs/gen/i219_regs.h — no raw hex magic numbers. The i219_ops vtable wires .mdio_read and .mdio_write to the real implementations.

Test Coverage Added

Two new test cases added to tests/device_specific/i219/avb_test_i219.c:

• Test 10: MDIO PHY Register Read (TEST-HW-I219-MDIO-001)
  Reads PHY Control Register (reg 0) and PHY Status Register (reg 1) via IOCTL_AVB_MDIO_READ.
  Verifies the MDIC/SWFLAG path end-to-end. Fails if value == 0xFFFF (bus non-responsive).

• Test 11: MDIO PHY Identifier OUI verification
  Reads PHY Identifier registers (reg 2, reg 3) and reconstructs the 24-bit OUI.
  Confirms OUI ≠ 0x000000 and ≠ 0xFFFFFF (strongest MDIO bus verification without writes).

Traceability

• Implements: I219 PCH-Based MDIO and PTP Access Implementation #153 (I219 PCH-Based MDIO and PTP Access Implementation)
• Implements: Implement I219 Direct MDIO Register Access (Post-MVP) #151 (Implement I219 Direct MDIO Register Access)
• Test file: tests/device_specific/i219/avb_test_i219.c (Tests 10-11)
• Build: avb_test_i219 in Run-Tests-CI.ps1 $HardwareIntegrationTests (committed in 50198c7)

[github-actions]

🤖 Status Sync

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

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

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