[TEST] TEST-DEV-LIFECYCLE-001: Device Lifecycle Management Verification

[zarfld]

Test Specification

Test ID: TEST-DEV-LIFECYCLE-001
Test Name: Device Lifecycle Management Verification
Component: IOCTL Handler - Device Lifecycle
Test Type: Integration Test
Priority: P0
Phase: 07-verification-validation
Estimated Effort: 4 days

Traceability

• Traces to: REQ-F-DEV-001: Device Lifecycle Management (IOCTL 20/21/31/32/37) #12 (REQ-F-DEV-001: Device Lifecycle Management)
• Implements: IOCTLs 20 (INITIALIZE_DEVICE), 21 (GET_DEVICE_INFO), 31 (ENUMERATE_ADAPTERS), 32 (OPEN_ADAPTER), 37 (GET_HW_STATE)
• Related to: REQ-F-PTP-001: PTP Hardware Clock Get/Set Timestamp (IOCTL 24/25) #2, REQ-F-PTP-002: PTP Clock Frequency Adjustment (IOCTL 38) #3, REQ-F-PTP-003: Hardware Timestamping Control (IOCTL 40 - TSAUXC) #5, REQ-F-PTP-004: Rx Packet Timestamping Configuration (IOCTL 41/42) #6 (PTP IOCTLs depend on device initialization)

Objective

Verify that device lifecycle management IOCTLs (20, 21, 31, 32, 37) correctly initialize devices, enumerate adapters, retrieve device information, and manage hardware state transitions with proper validation and error handling.

Test Environment

• Hardware: Intel I210/I225/I226 network adapter(s)
• Driver: IntelAvbFilter.sys (Debug build)
• Test Framework: User-mode test harness with IOCTL interface
• Tools: WinDbg, Device Manager, PnP diagnostics

Prerequisites

• Driver installed but device not yet initialized
• Test has administrator privileges for IOCTL access
• Multiple adapters available for enumeration tests (optional)
• Device Manager accessible for PnP verification

Test Cases

UT-DEV-INIT-001: First-Time Device Initialization

Description: Verify initial device initialization via IOCTL 20
Input:

• IOCTL: 20 (INITIALIZE_DEVICE)
• Adapter Index: 0
• Initialization Flags: Default

Expected Output:

• STATUS_SUCCESS
• Device hardware initialized
• Resources allocated (memory, interrupts)
• Device ready for operation

Acceptance Criteria:

• ✅ IOCTL completes successfully
• ✅ Hardware registers accessible
• ✅ PHC initialized
• ✅ Device in D0 power state

---

UT-DEV-INIT-002: Duplicate Initialization Prevention

Description: Verify rejection of duplicate initialization
Input:

• IOCTL: 20 (INITIALIZE_DEVICE) called twice
• Same adapter

Expected Output:

• First call: STATUS_SUCCESS
• Second call: STATUS_DEVICE_ALREADY_ATTACHED or STATUS_INVALID_DEVICE_STATE
• No resource leaks

Acceptance Criteria:

• ✅ Second initialization rejected
• ✅ Existing state preserved
• ✅ No double-allocation of resources

---

UT-DEV-INFO-001: Device Information Retrieval

Description: Verify retrieval of device information via IOCTL 21
Input:

• IOCTL: 21 (GET_DEVICE_INFO)
• Adapter Index: 0

Expected Output:

• STATUS_SUCCESS
• Device info structure populated:
  • Device ID (e.g., 0x15F2 for I225)
  • Vendor ID (0x8086 for Intel)
  • MAC address
  • Firmware version
  • Supported features

Acceptance Criteria:

• ✅ All fields valid
• ✅ MAC address matches hardware
• ✅ Device ID correct for hardware model

---

UT-DEV-INFO-002: Device Info Before Initialization

Description: Verify behavior when requesting info before initialization
Input:

• IOCTL: 21 (GET_DEVICE_INFO)
• Device not initialized

Expected Output:

• STATUS_DEVICE_NOT_READY or partial info
• Critical fields still available (Device ID, Vendor ID)
• No crash

Acceptance Criteria:

• ✅ Graceful handling
• ✅ Static info available
• ✅ Dynamic fields null/default

---

UT-DEV-ENUM-001: Single Adapter Enumeration

Description: Verify enumeration of single installed adapter
Input:

• IOCTL: 31 (ENUMERATE_ADAPTERS)

Expected Output:

• STATUS_SUCCESS
• Adapter count: 1
• Adapter info: Valid device path, friendly name, status

Acceptance Criteria:

• ✅ Correct adapter count
• ✅ Valid adapter descriptor
• ✅ Device path usable for OPEN_ADAPTER

---

UT-DEV-ENUM-002: Multiple Adapter Enumeration

Description: Verify enumeration with multiple adapters installed
Input:

• IOCTL: 31 (ENUMERATE_ADAPTERS)
• System with 2+ Intel AVB adapters

Expected Output:

• STATUS_SUCCESS
• Adapter count: N (actual count)
• Each adapter: Unique device path, distinct MAC

Acceptance Criteria:

• ✅ All adapters detected
• ✅ No duplicates
• ✅ Each adapter distinguishable

---

UT-DEV-ENUM-003: Enumeration with No Adapters

Description: Verify enumeration when no compatible adapters present
Input:

• IOCTL: 31 (ENUMERATE_ADAPTERS)
• No Intel AVB-capable adapters installed

Expected Output:

• STATUS_SUCCESS or STATUS_NOT_FOUND
• Adapter count: 0
• Empty adapter list

Acceptance Criteria:

• ✅ Graceful zero-count handling
• ✅ No null pointer dereferences
• ✅ Clear result

---

UT-DEV-OPEN-001: Open First Available Adapter

Description: Verify opening adapter by index via IOCTL 32
Input:

• IOCTL: 32 (OPEN_ADAPTER)
• Adapter Index: 0
• Access Mode: Read/Write

Expected Output:

• STATUS_SUCCESS
• Adapter handle returned
• Exclusive access granted (if requested)

Acceptance Criteria:

• ✅ Valid handle returned
• ✅ Adapter accessible via handle
• ✅ Reference count incremented

---

UT-DEV-OPEN-002: Open by Device Path

Description: Verify opening adapter by symbolic link path
Input:

• IOCTL: 32 (OPEN_ADAPTER)
• Device Path: "\Device\IntelAvbFilter0"

Expected Output:

• STATUS_SUCCESS
• Same adapter handle as index-based open
• Path resolved correctly

Acceptance Criteria:

• ✅ Path resolution works
• ✅ Correct adapter opened
• ✅ Equivalent to index-based open

---

UT-DEV-OPEN-003: Invalid Adapter Index Rejection

Description: Verify rejection of out-of-range adapter index
Input:

• IOCTL: 32 (OPEN_ADAPTER)
• Adapter Index: 99 (non-existent)

Expected Output:

• STATUS_INVALID_PARAMETER or STATUS_NO_SUCH_DEVICE
• No handle returned
• Error logged

Acceptance Criteria:

• ✅ Open fails gracefully
• ✅ No resource allocation
• ✅ Appropriate error code

---

UT-DEV-OPEN-004: Concurrent Open Requests

Description: Verify handling of multiple simultaneous open requests
Input:

• IOCTL: 32 (OPEN_ADAPTER)
• Same adapter, multiple threads

Expected Output:

• All requests succeed (shared mode) OR
• First succeeds, others fail (exclusive mode)
• Proper synchronization

Acceptance Criteria:

• ✅ No race conditions
• ✅ Access mode enforced
• ✅ Reference counting correct

---

UT-DEV-HW-STATE-001: Hardware State Retrieval - D0

Description: Verify hardware state query while adapter active (D0)
Input:

• IOCTL: 37 (GET_HW_STATE)
• Adapter in D0 (fully operational)

Expected Output:

• STATUS_SUCCESS
• Power State: D0
• Link Status: Up/Down (actual)
• PHC Status: Running
• Resource Status: All allocated

Acceptance Criteria:

• ✅ State accurately reflects hardware
• ✅ All fields populated
• ✅ Consistent with Device Manager

---

UT-DEV-HW-STATE-002: Hardware State During D3 Transition

Description: Verify hardware state query during low-power transition
Input:

• IOCTL: 37 (GET_HW_STATE)
• Trigger D3 transition (sleep mode)
• Query state during transition

Expected Output:

• STATUS_SUCCESS or STATUS_DEVICE_NOT_READY
• Power State: D3 (or transitioning)
• Link Status: Down
• PHC Status: Stopped or Low Power

Acceptance Criteria:

• ✅ Transitional state reported
• ✅ No crash during transition
• ✅ State consistent with PnP

---

UT-DEV-HW-STATE-003: Link State Detection

Description: Verify link up/down detection in hardware state
Input:

• IOCTL: 37 (GET_HW_STATE)
• Toggle link (cable plug/unplug)

Expected Output:

• Link Status: Up → Down → Up
• State change reflected in <5 seconds
• Event notifications (if subscribed)

Acceptance Criteria:

• ✅ Link state accurate
• ✅ Timely detection
• ✅ Consistent with NIC LEDs

---

UT-DEV-HW-STATE-004: Resource Allocation Status

Description: Verify resource allocation status in hardware state
Input:

• IOCTL: 37 (GET_HW_STATE)
• Query after initialization

Expected Output:

• STATUS_SUCCESS
• Resources Allocated: Yes
• Memory Mapped: Base address valid
• Interrupt Vector: Assigned
• DMA Resources: Available

Acceptance Criteria:

• ✅ All resources reported
• ✅ Addresses/vectors valid
• ✅ Matches resource list

---

UT-DEV-LIFECYCLE-001: Full Lifecycle Sequence

Description: Verify complete device lifecycle: init → open → use → close
Input:

• Sequence of IOCTLs: 20 → 31 → 32 → 21 → 37 → (use) → (close)

Expected Output:

• All operations succeed in order
• Device usable after initialization
• Clean shutdown on close

Acceptance Criteria:

• ✅ Entire sequence succeeds
• ✅ No state corruption
• ✅ Resources properly cleaned up

---

UT-DEV-LIFECYCLE-002: Initialization After Failed Start

Description: Verify recovery from failed device start
Input:

• Simulate initialization failure (e.g., hardware fault)
• Retry IOCTL 20 (INITIALIZE_DEVICE)

Expected Output:

• First attempt: STATUS_DEVICE_HARDWARE_ERROR
• Retry (after fault cleared): STATUS_SUCCESS
• Device recovers and becomes operational

Acceptance Criteria:

• ✅ Failure handled gracefully
• ✅ Retry succeeds
• ✅ No lingering error state

---

UT-DEV-LIFECYCLE-003: Hot-Plug Device Detection

Description: Verify device lifecycle during hot-plug event
Input:

• IOCTL: 31 (ENUMERATE_ADAPTERS) before/after hot-plug
• Insert Thunderbolt/USB adapter during test

Expected Output:

• Adapter count increases
• New adapter enumerated
• Existing adapters unaffected

Acceptance Criteria:

• ✅ Hot-plug detected
• ✅ Dynamic enumeration works
• ✅ No disruption to other adapters

---

UT-DEV-LIFECYCLE-004: Graceful Shutdown Sequence

Description: Verify graceful device shutdown
Input:

• Active device with open handles
• Initiate system shutdown or driver unload

Expected Output:

• Handles closed gracefully
• Resources released
• Hardware reset to safe state
• No BSOD or hang

Acceptance Criteria:

• ✅ Clean shutdown
• ✅ No resource leaks
• ✅ Hardware left in good state

---

UT-DEV-LIFECYCLE-005: PnP Remove and Re-Add

Description: Verify device lifecycle through PnP remove/add cycle
Input:

• Device Manager: Disable device
• Re-enable device
• Query state via IOCTL 37

Expected Output:

• Device removed cleanly
• Re-initialization succeeds
• Device returns to operational state

Acceptance Criteria:

• ✅ PnP events handled
• ✅ Clean re-initialization
• ✅ No phantom devices

---

Success Criteria

• ✅ All 19 test cases pass
• ✅ Device initialization robust and repeatable
• ✅ Enumeration accurate for 0, 1, or N adapters
• ✅ Open/close operations leak-free
• ✅ Hardware state accurately reported
• ✅ Full lifecycle sequences successful
• ✅ PnP events handled gracefully
• ✅ Code coverage >95% for device lifecycle IOCTLs
• ✅ No crashes, hangs, or BSODs

Test Execution Notes

Setup

1. Ensure driver installed but devices not initialized
2. Prepare multiple test adapters if available
3. Enable device manager for PnP verification
4. Configure logging for lifecycle events

Execution

• Run initialization tests first
• Test enumeration with varying adapter counts
• Verify state transitions thoroughly
• Test hot-plug if hardware supports it

Cleanup

• Ensure all handles closed
• Verify resources released
• Check Device Manager for proper state
• Document any adapter-specific behaviors

Dependencies

• Hardware: One or more Intel AVB-capable network adapters
• Driver: IOCTLs 20, 21, 31, 32, 37 implemented
• OS: PnP subsystem functional
• Privileges: Administrator access for device control

Risk Assessment

• Medium Risk: Improper initialization can corrupt device state
• Mitigation: Implement rollback on init failure
• Mitigation: Reset hardware to known state before tests
• Low Risk: Enumeration and queries are non-destructive

Notes

• Some tests require multiple adapters - document when unavailable
• Hot-plug tests may not work on desktop PCIe adapters
• Power state transitions timing-sensitive (wait for completion)
• Device paths are OS-specific (Windows symbolic links)

---

Created: 2025-12-31
Last Updated: 2025-12-31
Status: 🟡 Pending Implementation

[github-actions]

🤖 Status Sync

**Automatic status update** based on issue body:
- **Body status**: 🟡 Pending Implementation
- **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**: 🟡 Pending Implementation
- **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**: 🟡 Pending Implementation
- **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**: 🟡 Pending Implementation
- **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**: 🟡 Pending Implementation
- **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**: 🟡 Pending Implementation
- **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)*