TEST-REGS-003: Verify Register Constants Match Intel Datasheets (C_ASSERT)

[zarfld]

Test Specification

ID: TEST-REGS-003
Type: Compile-Time Assertion Test
Test Level: Unit / Compile-Time
Priority: P1 (High)
Phase: Phase 05 - Implementation

---

Traceability

• Traces to: REQ-NF-REGS-001: Eliminate Magic Numbers Using intel-ethernet-regs Submodule #21 (REQ-NF-REGS-001: Eliminate Magic Numbers Using intel-ethernet-regs)
• Verifies: REQ-NF-REGS-001: Eliminate Magic Numbers Using intel-ethernet-regs Submodule #21 (REQ-NF-REGS-001: Eliminate Magic Numbers Using intel-ethernet-regs)
• Verifies: Requirements Completeness Audit - P0/P1 Action Items (87.8% → 90% Target) #130 (ADR-REGS-001: Register Definition Source)

---

Test Objective

Verify that auto-generated register constants from intel-ethernet-regs match the official Intel datasheets. Prevent regression where YAML definitions drift from hardware specifications.

---

Test Description

Given register definitions in YAML files (i210.yaml, i225.yaml, etc.)
When headers are generated and compiled into driver
Then register offsets match documented values from Intel datasheets (compile-time assertions)

---

Test Setup

Prerequisites

• Generated headers: intel-ethernet-regs/gen/*.h
• Intel datasheets available for reference:
  • I210: Intel 333016 Datasheet v3.7
  • I225: Intel 2407151103 Software Manual v2.6
  • I226: Same as I225 (family)

Reference Values (from Datasheets)

Register	Device	Datasheet Offset	Constant Name
SYSTIML	All	0x0B600	I210_SYSTIML, I225_SYSTIML
SYSTIMH	All	0x0B604	I210_SYSTIMH, I225_SYSTIMH
TIMINCA	All	0x0B608	I210_TIMINCA, I225_TIMINCA
TSAUXC	I210/I211/I226	0x0B640	I210_TSAUXC (not in I225!)
CTRL	All	0x00000	I210_CTRL, I225_CTRL
STATUS	All	0x00008	I210_STATUS, I225_STATUS

---

Test Procedure

Compile-Time Assertion File

Location: tests/verification/regs/test_register_constants.c

/**
 * TEST-REGS-003: Verify Register Constants Match Datasheet
 * 
 * Verifies: #21 (REQ-NF-REGS-001)
 * 
 * Uses compile-time assertions (C_ASSERT) to validate that auto-generated
 * register offsets from intel-ethernet-regs match official Intel datasheets.
 * 
 * If compilation FAILS, the YAML definition is incorrect and must be fixed.
 */

#include <ntddk.h>

// Include auto-generated headers
#include "../../../intel-ethernet-regs/gen/i210_regs.h"
#include "../../../intel-ethernet-regs/gen/i225_regs.h"
#include "../../../intel-ethernet-regs/gen/i226_regs.h"

// Compile-time assertion macro
#ifndef C_ASSERT
#define C_ASSERT(e) typedef char __C_ASSERT__[(e)?1:-1]
#endif

//
// I210 Register Verification (Intel 333016 Datasheet v3.7)
//

// PTP Registers (Section 8.14 - IEEE 1588 Timestamping)
C_ASSERT(I210_SYSTIML == 0x0B600);   // System Time Low (Table 8-3)
C_ASSERT(I210_SYSTIMH == 0x0B604);   // System Time High (Table 8-3)
C_ASSERT(I210_TIMINCA == 0x0B608);   // Time Increment Attributes (Table 8-3)
C_ASSERT(I210_TSAUXC == 0x0B640);    // Time Sync Auxiliary Control (Table 8-3)

// Generic Registers (Section 8.2 - MAC Registers)
C_ASSERT(I210_CTRL == 0x00000);      // Device Control (Table 8-1)
C_ASSERT(I210_STATUS == 0x00008);    // Device Status (Table 8-1)
C_ASSERT(I210_CTRL_EXT == 0x00018);  // Extended Device Control (Table 8-1)

// MAC Address Registers (Section 8.6 - Receive Address Registers)
C_ASSERT(I210_RAL0 == 0x05400);      // Receive Address Low 0 (Table 8-2)
C_ASSERT(I210_RAH0 == 0x05404);      // Receive Address High 0 (Table 8-2)

//
// I225 Register Verification (Intel 2407151103 Software Manual v2.6)
//

// PTP Registers (Section 7.2.3.19 - PTP Registers)
C_ASSERT(I225_SYSTIML == 0x0B600);   // System Time Low
C_ASSERT(I225_SYSTIMH == 0x0B604);   // System Time High
C_ASSERT(I225_TIMINCA == 0x0B608);   // Time Increment Attributes
// NOTE: I225 does NOT have TSAUXC register (different PTP implementation)

// Generic Registers
C_ASSERT(I225_CTRL == 0x00000);      // Device Control
C_ASSERT(I225_STATUS == 0x00008);    // Device Status
C_ASSERT(I225_CTRL_EXT == 0x00018);  // Extended Device Control

// TSN-Specific Registers (Section 7.2.3.20 - Time Aware Shaper)
C_ASSERT(I225_TAS_CTRL == 0x08600);  // TAS Control (I225 only)

//
// I226 Register Verification (Same as I225 family)
//

// PTP Registers
C_ASSERT(I226_SYSTIML == 0x0B600);   // System Time Low
C_ASSERT(I226_SYSTIMH == 0x0B604);   // System Time High
C_ASSERT(I226_TIMINCA == 0x0B608);   // Time Increment Attributes
C_ASSERT(I226_TSAUXC == 0x0B640);    // Time Sync Auxiliary Control (I226 has it)

// Generic Registers
C_ASSERT(I226_CTRL == 0x00000);      // Device Control
C_ASSERT(I226_STATUS == 0x00008);    // Device Status

//
// Cross-Device Consistency Checks
//

// Verify common registers have same offset across devices
C_ASSERT(I210_SYSTIML == I225_SYSTIML);  // SYSTIML consistent
C_ASSERT(I210_SYSTIMH == I225_SYSTIMH);  // SYSTIMH consistent
C_ASSERT(I210_TIMINCA == I225_TIMINCA);  // TIMINCA consistent

C_ASSERT(I210_CTRL == I225_CTRL);        // CTRL consistent
C_ASSERT(I210_STATUS == I225_STATUS);    // STATUS consistent

// Verify device-specific differences
#ifdef COMPILE_TIME_VERIFY_I225_NO_TSAUXC
// I225 should NOT define TSAUXC (different PTP architecture)
// This would fail to compile if I225_TSAUXC exists
// C_ASSERT(I225_TSAUXC == 0x0B640);  // Should NOT exist
#endif

/**
 * Entry point for test (never executed - compile-time only)
 */
NTSTATUS DriverEntry(PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath) {
    UNREFERENCED_PARAMETER(DriverObject);
    UNREFERENCED_PARAMETER(RegistryPath);
    
    // This driver is never loaded - it's compile-time verification only
    return STATUS_NOT_IMPLEMENTED;
}

Build Script

Location: tests/verification/regs/Build-TEST-REGS-003.ps1

#Requires -Version 5.1
[CmdletBinding()]
param()

$ErrorActionPreference = 'Stop'
$RepoRoot = (Get-Item $PSScriptRoot).Parent.Parent.Parent.FullName

Write-Host "TEST-REGS-003: Register Constant Verification (Compile-Time)" -ForegroundColor Cyan

# Step 1: Ensure headers are up-to-date
Write-Host "`n[STEP 1] Regenerating headers..." -ForegroundColor Yellow

$Devices = @('i210', 'i225', 'i226')
foreach ($device in $Devices) {
    $yamlPath = Join-Path $RepoRoot "intel-ethernet-regs\devices\$device.yaml"
    $genPath = Join-Path $RepoRoot "intel-ethernet-regs\gen"
    
    py -3 (Join-Path $RepoRoot "intel-ethernet-regs\tools\reggen.py") $yamlPath $genPath
    
    if ($LASTEXITCODE -ne 0) {
        Write-Error "Failed to generate header for $device"
    }
    Write-Host "  ✓ Generated: $device`_regs.h" -ForegroundColor Green
}

# Step 2: Compile test file (C_ASSERT checks happen at compile time)
Write-Host "`n[STEP 2] Compiling assertion test..." -ForegroundColor Yellow

$TestSource = Join-Path $PSScriptRoot "test_register_constants.c"
$OutputObj = Join-Path $PSScriptRoot "test_register_constants.obj"

$IncludePaths = @(
    "/I", (Join-Path $RepoRoot "intel-ethernet-regs\gen"),
    "/I", "C:\Program Files (x86)\Windows Kits\10\Include\10.0.22621.0\km"
)

$CompileArgs = @(
    "/nologo"
    "/c"               # Compile only (don't link)
    "/W4"              # Warning level 4
    "/WX"              # Treat warnings as errors
    "/Zi"              # Debug info
    "/Od"              # Disable optimization
    "/kernel"          # Kernel mode
    $IncludePaths
    $TestSource
    "/Fo:$OutputObj"
)

$process = Start-Process -FilePath "cl.exe" `
                         -ArgumentList $CompileArgs `
                         -NoNewWindow `
                         -Wait `
                         -PassThru `
                         -RedirectStandardOutput (Join-Path $PSScriptRoot "compile.log") `
                         -RedirectStandardError (Join-Path $PSScriptRoot "compile_errors.log")

if ($process.ExitCode -ne 0) {
    Write-Host "`n❌ COMPILATION FAILED" -ForegroundColor Red
    Write-Host "   C_ASSERT failure indicates YAML definition mismatch with datasheet" -ForegroundColor Red
    
    Get-Content (Join-Path $PSScriptRoot "compile_errors.log")
    
    Write-Host "`n========================================" -ForegroundColor Red
    Write-Host "❌ TEST-REGS-003 FAILED" -ForegroundColor Red
    Write-Host "   Fix YAML definitions in intel-ethernet-regs/devices/" -ForegroundColor Red
    Write-Host "========================================" -ForegroundColor Red
    
    exit 1
}

Write-Host "  ✓ Compilation succeeded (all C_ASSERT checks passed)" -ForegroundColor Green

# Step 3: Cleanup
Remove-Item $OutputObj -ErrorAction SilentlyContinue

Write-Host "`n========================================" -ForegroundColor Cyan
Write-Host "✅ TEST-REGS-003 PASSED" -ForegroundColor Green
Write-Host "   All register constants match datasheets" -ForegroundColor Green
Write-Host "========================================" -ForegroundColor Cyan

exit 0

---

Expected Results

Pass Criteria

✅ Compilation succeeds (exit code 0)
✅ All C_ASSERT checks pass (no compiler errors)
✅ Register offsets match datasheets (I210, I225, I226)
✅ Cross-device consistency verified (common registers have same offset)

Fail Criteria (C_ASSERT Failures)

❌ Compilation error: static assertion failed for I210_SYSTIML
❌ Offset mismatch: YAML defines 0x0B064 but datasheet says 0x0B604
❌ Device-specific error: I225_TSAUXC defined but shouldn't exist

Example Failure Output:

test_register_constants.c(25): error C2118: negative subscript
  C_ASSERT(I210_SYSTIML == 0x0B600);
           ^
  Expected 0x0B600, got 0x0B064 (YAML typo)

---

Performance Metrics

Target: PM-REGS-003 - Register definition coverage >95%

Measurement: Count assertions vs. total AVB-related registers

Current Coverage:

• I210: 9 registers asserted
• I225: 8 registers asserted
• I226: 6 registers asserted
• Total: 23 critical registers verified

Total AVB Registers (from datasheets): ~25
Coverage: 23/25 = 92% (close to target)

---

CI Integration

Add to .github/workflows/ci-standards-compliance.yml:

  test-regs-003-constant-verification:
    name: "TEST-REGS-003: Register Constant Verification"
    runs-on: windows-latest
    needs: [setup]
    
    steps:
      - name: Checkout repository (with submodules)
        uses: actions/checkout@v4
        with:
          submodules: recursive
      
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.9'
      
      - name: Setup MSVC
        uses: ilammy/msvc-dev-cmd@v1
      
      - name: Run TEST-REGS-003
        run: |
          powershell -NoProfile -ExecutionPolicy Bypass `
            -File tests\verification\regs\Build-TEST-REGS-003.ps1

---

Baseline Execution

Run Date: (TBD - after creating test file)

Expected Result: ✅ PASS (headers already generated and presumably correct)

Validation: Manually cross-check 3-5 register offsets against Intel datasheets

---

Related Tests

• TEST-REGS-001: Build Verification (full driver compile)
• TEST-REGS-002: Magic Number Detection (static analysis)

---

Status: Draft (Test Created - Awaiting Test File Creation)
Created: 2025-12-30
Next Step: Create test_register_constants.c and execute baseline run

[github-actions]

🤖 Status Sync

**Automatic status update** based on issue body:
- **Body status**: Draft (Test Created - Awaiting Test File Creation)
- **Previous label(s)**: (none)
- **New label**: `status:in-progress`

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**: Draft (Test Created - Awaiting Test File Creation)
- **Previous label(s)**: (none)
- **New label**: `status:in-progress`

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**: Draft (Test Created - Awaiting Test File Creation)
- **Previous label(s)**: (none)
- **New label**: `status:in-progress`

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**: Draft (Test Created - Awaiting Test File Creation)
- **Previous label(s)**: (none)
- **New label**: `status:in-progress`

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**: Draft (Test Created - Awaiting Test File Creation)
- **Previous label(s)**: (none)
- **New label**: `status:in-progress`

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

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