Traceability
Description
Verification tests for the shared memory ring buffer mechanism (IOCTL 33: TS_SUBSCRIBE, IOCTL 34: TS_RING_MAP) that enables zero-copy, lock-free timestamp event delivery from kernel-mode driver to user-mode application.
Test File: tests/ioctl/test_ioctl_ts_event_sub.c
IOCTLs Under Test: 33 (IOCTL_AVB_TS_SUBSCRIBE), 34 (IOCTL_AVB_TS_RING_MAP)
Test Cases
UT-TS-RING-001: Ring Buffer Mapping
Requirement: REQ-F-TSRING-001.2 (Shared Memory Ring Buffer Mapping)
Given application has subscribed to timestamp events (ring_id obtained)
When application calls IOCTL_AVB_TS_RING_MAP with ring_id and length=65536
Then driver allocates 65536 bytes non-paged pool
And creates section object and returns shm_token
And application maps ring buffer using shm_token
And ring buffer pointer is non-NULL
Expected Result: PASS (with driver loaded), SKIP (without driver)
Status in CI: SKIP (no hardware driver required for this test tier)
UT-TS-RING-002: Ring Buffer Size Negotiation
Requirement: REQ-F-TSRING-001.2
Given application requests ring buffer of specified size
When driver allocates and maps the ring buffer
Then actual_size >= requested size (driver rounds up to page boundary)
And actual_size <= MAX_RING_BUFFER_SIZE (1MB)
Expected Result: PASS (with driver loaded), SKIP (without driver)
UT-TS-RING-003: Ring Buffer Wraparound
Requirement: REQ-F-TSRING-001.3 (Lock-Free Ring Buffer Protocol) + REQ-F-TSRING-001.4 (Overflow Handling)
Given ring buffer is mapped and operational
When producer_index reaches capacity-1
Then producer_index wraps around to 0
And ring buffer continues to accept events without corruption
And no memory writes outside allocated buffer
Expected Result: PASS (with driver loaded), SKIP (without driver)
UT-TS-SUB-001: Subscribe to Rx Timestamp Events
Requirement: REQ-F-TSRING-001.1 (Ring Buffer Allocation and Subscription)
Given NIC driver is loaded and initialized
When application calls IOCTL_AVB_TS_SUBSCRIBE with types_mask=TS_EVENT_RX
Then driver returns ring_id != 0
And status = NDIS_STATUS_SUCCESS
UT-TS-SUB-002: Subscribe to All Timestamp Events
Requirement: REQ-F-TSRING-001.1
Given NIC driver is loaded
When application calls IOCTL_AVB_TS_SUBSCRIBE with types_mask=0xF (all types)
Then driver allocates ring for all event types: TX_TS, RX_TS, TARGET_TIME, AUX_TS
And returns ring_id != 0
UT-TS-OVERFLOW-001: Ring Buffer Full — Drop Newest Policy
Requirement: REQ-F-TSRING-001.4 (Ring Buffer Overflow Handling)
Given ring buffer is full (producer_index+1 == consumer_index)
When driver receives 100 new timestamp events
Then all 100 events are dropped (ring is not overwritten)
And driver logs "Timestamp ring buffer full, dropped N events"
And application is not blocked
Acceptance Criteria (from #19)
| REQ Sub-ID |
Scenario |
Expected |
| 001.1 |
Subscribe → ring_id allocated |
ring_id != 0, STATUS_SUCCESS |
| 001.2 |
Map ring buffer → shm_token returned |
Non-NULL mapped address |
| 001.2 |
Both KM and UM map same physical pages |
Write in KM visible in UM |
| 001.3 |
Lock-free post: producer_index advances |
No locks, atomic visibility |
| 001.3 |
Consumer reads in FIFO order |
consumer_index advances correctly |
| 001.4 |
Ring full: drop newest |
Events dropped, no crash, no overwrite |
Implementation Notes
Critical Sequence to Test:
- Call
IOCTL_AVB_TS_SUBSCRIBE → get ring_id
- Call
IOCTL_AVB_TS_RING_MAP with ring_id → get shm_token
- Call
MapViewOfFile((HANDLE)shm_token) → map buffer into user-mode
- Read
producer_index from ring header to detect new events
- Advance
consumer_index after consuming events
- Call
UnmapViewOfFile() + CloseHandle(shm_token) on teardown
Test Infrastructure: Tests in test_ioctl_ts_event_sub.c require driver loaded on real hardware for PASS results. CI will report SKIP for hardware-gated subtests.
Performance Targets (from #19)
| Metric |
Target |
| Event posting latency |
<1µs |
| Ring throughput |
10K events/sec |
| Mapping overhead |
<5ms |
Standards
- IEEE 1012-2016 (Verification & Validation)
- ISO/IEC/IEEE 12207:2017 (Implementation Process)
Traceability
Description
Verification tests for the shared memory ring buffer mechanism (IOCTL 33: TS_SUBSCRIBE, IOCTL 34: TS_RING_MAP) that enables zero-copy, lock-free timestamp event delivery from kernel-mode driver to user-mode application.
Test File:
tests/ioctl/test_ioctl_ts_event_sub.cIOCTLs Under Test: 33 (
IOCTL_AVB_TS_SUBSCRIBE), 34 (IOCTL_AVB_TS_RING_MAP)Test Cases
UT-TS-RING-001: Ring Buffer Mapping
Requirement: REQ-F-TSRING-001.2 (Shared Memory Ring Buffer Mapping)
Expected Result: PASS (with driver loaded), SKIP (without driver)
Status in CI: SKIP (no hardware driver required for this test tier)
UT-TS-RING-002: Ring Buffer Size Negotiation
Requirement: REQ-F-TSRING-001.2
Expected Result: PASS (with driver loaded), SKIP (without driver)
UT-TS-RING-003: Ring Buffer Wraparound
Requirement: REQ-F-TSRING-001.3 (Lock-Free Ring Buffer Protocol) + REQ-F-TSRING-001.4 (Overflow Handling)
Expected Result: PASS (with driver loaded), SKIP (without driver)
UT-TS-SUB-001: Subscribe to Rx Timestamp Events
Requirement: REQ-F-TSRING-001.1 (Ring Buffer Allocation and Subscription)
UT-TS-SUB-002: Subscribe to All Timestamp Events
Requirement: REQ-F-TSRING-001.1
UT-TS-OVERFLOW-001: Ring Buffer Full — Drop Newest Policy
Requirement: REQ-F-TSRING-001.4 (Ring Buffer Overflow Handling)
Acceptance Criteria (from #19)
Implementation Notes
Critical Sequence to Test:
IOCTL_AVB_TS_SUBSCRIBE→ getring_idIOCTL_AVB_TS_RING_MAPwithring_id→ getshm_tokenMapViewOfFile((HANDLE)shm_token)→ map buffer into user-modeproducer_indexfrom ring header to detect new eventsconsumer_indexafter consuming eventsUnmapViewOfFile()+CloseHandle(shm_token)on teardownTest Infrastructure: Tests in
test_ioctl_ts_event_sub.crequire driver loaded on real hardware for PASS results. CI will report SKIP for hardware-gated subtests.Performance Targets (from #19)
Standards