REQ-F-TAS-001: Time-Aware Scheduler (IOCTL 26 - 802.1Qbv TAS)

[zarfld]

Traces to: #1 (StR-HWAC-001: Intel NIC AVB/TSN Feature Access), #30 (StR-003: Standards Semantics Alignment)

Description

Implement Time-Aware Shaper (TAS) for scheduled traffic as specified in IEEE 802.1Qbv and add_spec.md Section 5.

IOCTL: IOCTL_AVB_SETUP_TAS (code 26, 0x0000001A)

Struct: AVB_TAS_REQUEST (contains struct tsn_tas_config from intel.h)

Functional Requirements

REQ-F-TAS-001: Time-Aware Scheduler Configuration

Purpose: Configure time-based gate control for TSN scheduled traffic (802.1Qbv) - opens/closes queue transmission gates based on repeating time cycles.

Input (via tsn_tas_config):

• cycle_time - Total length of scheduling cycle (nanoseconds)
• base_time - Absolute time when cycle starts (nanoseconds)
• gate_control_list[] - Array of gate events (queue open/close times)
• num_entries - Number of gate control entries

Hardware Operations:

1. Configure QbvCycleT - Cycle time in nanoseconds
2. Write BASET_L/H - Base time (when schedule starts)
3. For each gate control entry:
   • Write StQT[n] - Start Queue Time (when gate opens)
   • Write EndQT[n] - End Queue Time (when gate closes)
4. Enable TAS operation

Output:

• status - NDIS_STATUS value

Registers (from add_spec.md):

• QbvCycleT - Cycle time configuration
• BASET_L (0x3578), BASET_H (0x357C) - Base Time
• StQT[n] - Start Queue Time per queue
• EndQT[n] - End Queue Time per queue

Time-Aware Scheduler Concept (IEEE 802.1Qbv)

Gate Control List defines repeating time windows:

Time:     0ns        500ns       1000ns      1500ns     2000ns (cycle repeats)
Queue 0:  |==OPEN===|==CLOSED==================|==OPEN===|
Queue 1:  |==CLOSED==|==OPEN=====|==CLOSED=================|
Queue 2:  |==CLOSED================|==OPEN=====|==CLOSED==|

Example: 2ms cycle for mixed traffic:

• 0-0.5ms: Queue 0 open (time-critical control messages)
• 0.5-1.5ms: Queue 1 open (AVB audio/video)
• 1.5-2ms: Queue 2 open (best-effort traffic)

Error Handling

Error Scenario	NTSTATUS Code	User Impact	Recovery Action
TAS not supported on controller	STATUS_NOT_SUPPORTED	Feature unavailable	Use I225/I226 or newer; fallback to CBS-only QoS
Invalid gate control list (overlapping windows)	STATUS_INVALID_PARAMETER	Schedule rejected	Fix overlaps; ensure start < end times per queue
Cycle time too short (< 1µs)	STATUS_INVALID_PARAMETER	Schedule rejected	Use cycle_time >= 1000 ns (1 µs minimum)
Cycle time too long (> 1 second)	STATUS_INVALID_PARAMETER	Schedule rejected	Use cycle_time <= 1,000,000,000 ns (1 second max)
Gate control entries exceed limit (> 64)	STATUS_INVALID_PARAMETER	Schedule rejected	Reduce num_entries to <= 64 (hardware limit)
Base time in past (< current SYSTIM)	STATUS_INVALID_PARAMETER	Schedule won't activate	Set base_time to future (current + margin)
Hardware write failure	STATUS_IO_DEVICE_ERROR	TAS not configured	Check BAR0 mapping; verify adapter status; retry
Null buffer	STATUS_INVALID_PARAMETER	No action taken	Provide valid AVB_TAS_REQUEST buffer

Performance Requirements

Metric	Target	Measurement Method
TAS Configuration Latency	<50µs	GPIO toggle + oscilloscope (register writes)
Gate Schedule Programming Time	<100µs	RDTSC before/after full schedule write
Gate Open/Close Precision	±100ns	IEEE 802.1Qbv requirement; measure with traffic generator
Schedule Reconfiguration Time	<1ms	GPIO toggle for full reprogram (64 entries)
IOCTL Throughput	>200 Hz	Loop 2000 schedule updates/sec
Memory Footprint	<5KB	Gate control list storage (WinDbg !vm)
CPU Usage	<1%	TAS active @ 1 Gbps (PerfMon)

Acceptance Criteria

Scenario: Configure 3-queue TAS schedule
  Given driver is initialized on I225/I226 controller
  When user calls IOCTL_AVB_SETUP_TAS with:
    cycle_time = 2000000 ns (2ms)
    base_time = current_systim + 10ms
    gate_control_list[0] = {queue=0, start=0, end=500000}
    gate_control_list[1] = {queue=1, start=500000, end=1500000}
    gate_control_list[2] = {queue=2, start=1500000, end=2000000}
  Then driver writes QbvCycleT = 2000000
  And writes BASET_L/H = base_time
  And writes StQT[0]=0, EndQT[0]=500000
  And writes StQT[1]=500000, EndQT[1]=1500000
  And writes StQT[2]=1500000, EndQT[2]=2000000
  And TAS schedule activates at base_time
  And queues open/close according to schedule
  And status = NDIS_STATUS_SUCCESS

Scenario: TAS not supported on controller
  Given driver is initialized on I210 (no TAS support)
  When user calls IOCTL_AVB_SETUP_TAS
  Then status = NDIS_STATUS_NOT_SUPPORTED
  And error message indicates "TAS requires I225/I226 or newer"

Scenario: Invalid gate control list
  Given gate_control_list has overlapping time windows
  When user calls IOCTL_AVB_SETUP_TAS
  Then status = NDIS_STATUS_INVALID_PARAMETER
  And error message indicates "Overlapping gate windows"

Scenario: Cycle time validation
  Given user specifies cycle_time = 10 ns (too short)
  When user calls IOCTL_AVB_SETUP_TAS
  Then status = NDIS_STATUS_INVALID_PARAMETER
  And error message indicates "Minimum cycle time = 1000 ns"

Implementation Notes

Hardware Constraints:

• I225/I226 only: TAS not available on I210, I217, I219
• Minimum cycle time: 1 µs (1000 ns)
• Maximum cycle time: 1 second
• Maximum gate control entries: 64 (hardware limit)
• Base time must be in future (> current SYSTIM)

Gate Control List Validation:

• No overlapping time windows for same queue
• All times within cycle_time range
• Start time < End time for each entry
• Sum of all windows ≤ cycle_time

Synchronization:

• TAS schedule must be PTP-synchronized across network
• Use base_time to align schedule with gPTP domain time

Traceability

• Implements: add_spec.md Section 5 - Time-Aware Shaper (802.1Qbv)
• Implements: IEEE 802.1Qbv-2015 (Enhancements for Scheduled Traffic)
• Depends on: REQ-F-PTP-001: PTP Hardware Clock Get/Set Timestamp (IOCTL 24/25) #2 (REQ-F-PTP-001: PTP clock running and synchronized)
• Related: REQ-F-QAV-001: Credit-Based Shaper (IOCTL 35 - 802.1Qav CBS) #8 (REQ-F-QAV-001: Credit-Based Shaper)
• Verified by: TEST-TAS-SCHEDULE-001 (to be created)

Hardware Support

• ❌ Intel I210 (no TAS support)
• ❌ Intel I217/I219 (no TAS support)
• ✅ Intel I225 (full TAS support)
• ✅ Intel I226 (full TAS support)
• ❓ Intel E810 (likely supported, needs validation)

Priority

P1 - Important for TSN scheduled traffic (not critical for basic AVB)

Definition of Done

• IOCTL handler implemented
• Hardware capability check (I225/I226 only)
• QbvCycleT register write
• BASET_L/H register writes
• StQT[n]/EndQT[n] register writes (per gate entry)
• Gate control list validation (overlap check, time range)
• Cycle time validation (min/max bounds)
• Base time validation (must be future)
• Unit tests (valid schedule, overlaps, unsupported controller)
• Integration test: packet capture showing gate open/close
• Documentation with TAS schedule diagram