TEST-TSN-TERMS-001: Verify TSN Terminology Compliance and Documentation Standards

[zarfld]

Test Case Summary

Test ID: TEST-TSN-TERMS-001
Test Type: Documentation + Compliance
Priority: P2 (High)
Phase: Phase 07 - Verification & Validation
Requirement: REQ-F-TSN-SEMANTICS-001: TSN vs AVB Terminology

---

Traceability

• Traces to: REQ-F-TSN-SEMANTICS-001: TSN vs AVB Terminology #54 (REQ-F-TSN-TERMS-001: TSN vs AVB Terminology)

---

Test Objectives

Verify that the Intel AVB Filter Driver documentation uses correct IEEE TSN terminology and semantics to avoid confusion between AVB (legacy) and TSN (modern) standards, including:

1. Terminology mapping table present in documentation
2. Code comments use modern TSN terms (not legacy AVB)
3. Variable naming conventions follow TSN semantics
4. Documentation standards enforced in issue titles and bodies
5. Glossary completeness in README
6. Legacy term handling (user tolerance + internal mapping)
7. Automated terminology audit (CI/CD integration)
8. Code review checklist includes terminology validation
9. Issue title format compliance (IEEE standard references)
10. README updates when new IEEE standards adopted

---

Test Environment

• Repository: IntelAvbFilter (GitHub)
• Tools:
  • grep (terminology audit)
  • PowerShell (automated scanning)
  • GitHub Actions (CI/CD validation)
  • Markdown linter (documentation format)
  • Code review checklist (PR template)
  • Documentation generator (glossary validation)

---

Test Cases

TC-TSN-TERMS-001: Terminology Mapping Table Exists

Objective: Verify driver documentation includes AVB→TSN terminology mapping table.

Preconditions:

• Repository cloned locally
• README.md or docs/terminology.md exists

Test Steps:

1. Search for terminology mapping table in docs/
2. Verify table contains all required mappings:
   • AVB → TSN
   • Class A/B → Traffic Class (TC)
   • SRP → MSRP
   • gPTP → IEEE 1588 PTP
   • QAV → CBS (Credit-Based Shaper)
   • QBV → TAS (Time-Aware Shaper)
   • QBU → Frame Preemption (FPE)
3. Verify IEEE standard references included
4. Verify usage notes provided

Expected Results:

• Terminology mapping table found in README.md or docs/terminology.md
• All 10+ legacy→modern mappings documented
• Each entry includes IEEE standard reference (e.g., "802.1Qav-2009")
• Usage notes explain when to use each term

Automation:

# PowerShell test script
$readmePath = "README.md"
$content = Get-Content $readmePath -Raw

# Verify table exists
if ($content -notmatch "Terminology Mapping" -and $content -notmatch "TSN Terminology") {
    throw "Terminology mapping table not found in README"
}

# Verify key mappings present
$requiredMappings = @(
    "AVB.*TSN",
    "Class A.*Traffic Class",
    "SRP.*MSRP",
    "QAV.*CBS",
    "QBV.*TAS"
)

foreach ($mapping in $requiredMappings) {
    if ($content -notmatch $mapping) {
        throw "Required mapping not found: $mapping"
    }
}

Write-Host "✅ Terminology mapping table validated"

---

TC-TSN-TERMS-002: Code Comments Use TSN Terminology

Objective: Verify all code comments use modern TSN terms (not legacy AVB).

Test Steps:

1. Run grep to find "AVB" in source files
2. Verify matches are only in:
   • Legacy compatibility layer (legacy_avb_compat.c)
   • Historical comments referencing IEEE AVB standards
   • NOT in new feature implementation
3. Verify "TSN" used instead of "AVB" in new code

Expected Results:

• No "AVB" found in new source files (*.c, *.h) except legacy compat
• All comments use "TSN stream", "TSN talker", "TSN listener"
• Legacy AVB references marked with "(legacy)" or "(deprecated)"

Automation:

# Scan for legacy AVB terms in code
$cFiles = Get-ChildItem -Recurse -Include *.c,*.h -Exclude legacy_avb_compat.*

$violations = @()
foreach ($file in $cFiles) {
    $matches = Select-String -Path $file.FullName -Pattern "\bAVB\b" -CaseSensitive
    
    foreach ($match in $matches) {
        # Exclude historical references
        if ($match.Line -notmatch "(legacy|deprecated|IEEE.*AVB|formerly)") {
            $violations += "$($file.Name):$($match.LineNumber): $($match.Line.Trim())"
        }
    }
}

if ($violations.Count -gt 0) {
    Write-Host "❌ Legacy AVB terms found:"
    $violations | ForEach-Object { Write-Host $_ }
    throw "Code comments contain legacy AVB terms"
} else {
    Write-Host "✅ All code comments use TSN terminology"
}

---

TC-TSN-TERMS-003: Variable Naming Conventions

Objective: Verify variable names follow TSN semantics (no Avb* prefixes).

Test Steps:

1. Scan source files for variable/function names containing "Avb"
2. Verify matches are only in legacy compatibility layer
3. Verify new code uses "Tsn*" prefix

Expected Results:

• No Avb* variable names in new code
• All structs use TSN_* prefix (e.g., TSN_STREAM_CONFIG)
• Legacy compatibility uses LEGACY_AVB_* prefix for clarity

Automation:

# Scan for Avb* variable names
$violations = Select-String -Path *.c,*.h -Pattern "\b(Avb[A-Z]|avb_[a-z])" `
    -Exclude legacy_avb_compat.* | Where-Object {
    $_.Line -notmatch "//.*legacy" -and $_.Line -notmatch "LEGACY_AVB"
}

if ($violations.Count -gt 0) {
    Write-Host "❌ Legacy Avb* variable names found:"
    $violations | ForEach-Object { Write-Host "$($_.Filename):$($_.LineNumber)" }
    throw "Variables use legacy Avb* naming"
} else {
    Write-Host "✅ All variables use TSN* naming conventions"
}

---

TC-TSN-TERMS-004: Documentation Standards (Issue Titles)

Objective: Verify all requirement issues follow title format with IEEE standard reference.

Test Steps:

1. Query GitHub API for all REQ-F issues
2. Verify title format: REQ-F-XXX-NNN: Feature Name (IEEE 802.1Qxx)
3. Check that IEEE standard is correct for feature

Expected Results:

• All REQ-F issues include IEEE standard in title
• Format matches: (IEEE 802.1Qxx) or (IEEE 1588)
• Standard reference is accurate (e.g., Qbv for TAS, Qav for CBS)

Automation:

# GitHub API query (requires gh CLI)
$issues = gh issue list --label "type:requirement:functional" --state all --json number,title | ConvertFrom-Json

$violations = @()
foreach ($issue in $issues) {
    # Skip legacy issues created before terminology standard
    if ($issue.number -lt 100) { continue }
    
    # Verify IEEE standard in title
    if ($issue.title -notmatch "\(IEEE (802\.1Q[a-z]{2}|1588|802\.3br)\)") {
        $violations += "#$($issue.number): $($issue.title)"
    }
}

if ($violations.Count -gt 0) {
    Write-Host "❌ Issues missing IEEE standard in title:"
    $violations | ForEach-Object { Write-Host $_ }
    throw "Issue titles do not follow standard format"
} else {
    Write-Host "✅ All issue titles include IEEE standard reference"
}

---

TC-TSN-TERMS-005: Glossary Completeness in README

Objective: Verify README contains comprehensive TSN glossary.

Test Steps:

1. Open README.md
2. Verify glossary section exists
3. Check for required entries:
   • TSN definition
   • TSN Stream
   • Traffic Class (TC)
   • TSN Talker/Listener
   • IEEE 802.1AS, 802.1Qav, 802.1Qbv, 802.1Qbu references
   • Legacy terms marked as deprecated

Expected Results:

• Glossary section titled "TSN Terminology Glossary"
• All 15+ TSN terms defined
• Each IEEE standard listed with year (e.g., "IEEE 802.1Qav-2009")
• Legacy terms have "(Deprecated)" marker

Automation:

$readme = Get-Content README.md -Raw

# Verify glossary section exists
if ($readme -notmatch "(?s)##\s+TSN.*Glossary") {
    throw "README missing TSN Glossary section"
}

# Verify required terms
$requiredTerms = @(
    "TSN \(Time-Sensitive Networking\)",
    "TSN Stream",
    "Traffic Class \(TC\)",
    "TSN Talker",
    "TSN Listener",
    "IEEE 802\.1AS",
    "IEEE 802\.1Qav",
    "IEEE 802\.1Qbv",
    "IEEE 802\.1Qbu",
    "Credit-Based Shaper \(CBS\)",
    "Time-Aware Shaper \(TAS\)",
    "Frame Preemption \(FPE\)",
    "AVB.*Deprecated"
)

$missing = @()
foreach ($term in $requiredTerms) {
    if ($readme -notmatch $term) {
        $missing += $term
    }
}

if ($missing.Count -gt 0) {
    Write-Host "❌ Missing glossary terms:"
    $missing | ForEach-Object { Write-Host "  - $_" }
    throw "Glossary incomplete"
} else {
    Write-Host "✅ Glossary contains all required TSN terms"
}

---

TC-TSN-TERMS-006: Legacy Term Tolerance (Internal Mapping)

Objective: Verify driver tolerates legacy terms from users but maps internally to TSN.

Test Steps:

1. Review code for user-facing interfaces (IOCTLs, config files)
2. Verify legacy terms accepted (e.g., "AVB Class A" in user comment)
3. Verify internal mapping to TSN equivalent
4. Verify warning logged when legacy term used

Expected Results:

• User can use "AVB" or "Class A" in configuration
• Driver internally converts to "TSN high-priority" or "Traffic Class 4"
• Warning logged: "Legacy term 'AVB' used; prefer 'TSN'"
• No runtime errors from legacy terms

Automation:

// C++ Unit Test
TEST(TsnTerminology, LegacyTermTolerance) {
    // User configuration with legacy term
    const char* userConfig = R"(
        {
            "streamType": "AVB Class A",
            "bandwidth": "25%"
        }
    )";
    
    // Parse configuration
    TSN_STREAM_CONFIG config;
    NTSTATUS status = ParseUserConfig(userConfig, &config);
    
    // Verify legacy term accepted
    ASSERT_EQ(status, STATUS_SUCCESS);
    
    // Verify internal mapping to TSN
    ASSERT_EQ(config.TsnTrafficClass, 4); // Class A → TC 4
    ASSERT_EQ(config.CbsIdleSlope, 25000); // 25% bandwidth
    
    // Verify warning logged (check ETW trace)
    auto events = GetEtwEvents();
    ASSERT_TRUE(std::any_of(events.begin(), events.end(), [](const auto& evt) {
        return evt.Message.find("Legacy term 'AVB'") != std::string::npos;
    }));
}

---

TC-TSN-TERMS-007: Automated Terminology Audit (CI/CD)

Objective: Verify CI pipeline runs automated terminology audit.

Test Steps:

1. Commit code with legacy "AVB" term
2. Push to PR branch
3. Verify CI fails with terminology violation
4. Fix term to "TSN"
5. Verify CI passes

Expected Results:

• CI workflow includes scripts/terminology_audit.sh
• Workflow fails if "AVB" found in new files
• Failure message: "Terminology violation: Use 'TSN' instead of 'AVB'"
• Fixed PR passes CI

Automation:

# GitHub Actions workflow (.github/workflows/terminology-audit.yml)
name: Terminology Audit

on:
  pull_request:
    paths:
      - '**.c'
      - '**.h'
      - 'docs/**'

jobs:
  audit-terminology:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Run terminology audit
        run: |
          # Check for legacy AVB terms in new/modified files
          git diff --name-only origin/master...HEAD | grep -E '\.(c|h|md)$' | while read file; do
            if grep -n "\bAVB\b" "$file" | grep -v "legacy\|deprecated\|IEEE.*AVB"; then
              echo "❌ Legacy AVB term found in $file"
              exit 1
            fi
          done
          
          echo "✅ All files use TSN terminology"
      
      - name: Verify glossary updated
        if: contains(github.event.pull_request.labels.*.name, 'new-standard')
        run: |
          if ! grep -q "IEEE 802.1Q" README.md; then
            echo "❌ Glossary not updated for new standard"
            exit 1
          fi

---

TC-TSN-TERMS-008: Code Review Checklist

Objective: Verify PR template includes terminology validation checklist.

Test Steps:

1. Open PR template (.github/pull_request_template.md)
2. Verify checklist includes terminology items
3. Submit test PR and verify checklist enforced

Expected Results:

• PR template contains:
  • No legacy AVB terms in code/comments
  • Variables use TSN* naming
  • Issue references use correct IEEE standards
  • Glossary updated if new standard added

Automation:

$prTemplate = Get-Content .github/pull_request_template.md -Raw

$requiredChecks = @(
    "No legacy AVB terms",
    "TSN\* naming",
    "IEEE standard",
    "Glossary updated"
)

$missing = @()
foreach ($check in $requiredChecks) {
    if ($prTemplate -notmatch $check) {
        $missing += $check
    }
}

if ($missing.Count -gt 0) {
    Write-Host "❌ PR template missing checks:"
    $missing | ForEach-Object { Write-Host "  - $_" }
    throw "PR template incomplete"
} else {
    Write-Host "✅ PR template includes all terminology checks"
}

---

TC-TSN-TERMS-009: Issue Body Terminology

Objective: Verify issue bodies use TSN terms consistently.

Test Steps:

1. Query GitHub API for recent issues
2. Scan issue bodies for legacy terms
3. Verify TSN terms used instead

Expected Results:

• Issues use "TSN stream" not "AVB stream"
• Issues use "Credit-Based Shaper (CBS)" not "QAV algorithm"
• Issues use "Time-Aware Shaper (TAS)" not "QBV scheduler"
• Issues use "Frame Preemption (FPE)" not "QBU preemption"

Automation:

# Query recent issues
$issues = gh issue list --limit 50 --json number,body | ConvertFrom-Json

$violations = @()
foreach ($issue in $issues) {
    $body = $issue.body
    
    # Check for legacy terms
    if ($body -match "\bAVB stream\b" -and $body -notmatch "legacy|deprecated") {
        $violations += "#$($issue.number): Uses 'AVB stream' instead of 'TSN stream'"
    }
    if ($body -match "\bQAV algorithm\b") {
        $violations += "#$($issue.number): Uses 'QAV algorithm' instead of 'Credit-Based Shaper (CBS)'"
    }
}

if ($violations.Count -gt 0) {
    Write-Host "⚠️ Issues with legacy terminology:"
    $violations | ForEach-Object { Write-Host $_ }
    # Warning only, not fatal (legacy issues exist)
} else {
    Write-Host "✅ All recent issues use TSN terminology"
}

---

TC-TSN-TERMS-010: README Update Frequency

Objective: Verify README glossary updated when new IEEE standards adopted.

Test Steps:

1. Identify new IEEE standard adoption (e.g., 802.1Qcr)
2. Verify glossary entry added within 1 week
3. Verify entry includes standard year and description

Expected Results:

• New standard entry in glossary within 7 days
• Entry format: **IEEE 802.1Qcr-2020**: Asynchronous Traffic Shaping (ATS)
• Usage notes provided

Manual Verification:

## Process for New Standard Adoption

1. **Identify New Standard**: IEEE publishes new TSN standard (e.g., 802.1Qcr-2020)
2. **Update Glossary** (within 7 days):
   - Add entry to README.md glossary section
   - Format: `**IEEE 802.1Qcr-2020**: Asynchronous Traffic Shaping (ATS) - ...`
   - Include usage notes and relationship to other standards
3. **Update Terminology Table**: Add any new legacy→modern mappings
4. **Notify Team**: Announce in Slack/email with glossary link
5. **PR Review**: Ensure all reviewers check glossary completeness

---

Pass/Fail Criteria

Pass Criteria:

• ✅ All 10 test cases pass
• ✅ Terminology mapping table exists and complete
• ✅ No legacy AVB terms in new code/comments
• ✅ Variables use TSN* naming conventions
• ✅ All REQ-F issues include IEEE standard in title
• ✅ README glossary contains 15+ TSN terms
• ✅ Legacy terms tolerated from users (with internal mapping)
• ✅ CI/CD terminology audit configured
• ✅ PR template includes terminology checklist
• ✅ README updated within 7 days of new standard

Fail Criteria:

• ❌ Any test case fails
• ❌ Legacy AVB terms found in new code
• ❌ Issue titles missing IEEE standards
• ❌ Glossary incomplete or missing
• ❌ CI/CD audit not configured
• ❌ PR template missing terminology checks

---

Risks and Mitigations

Risk	Impact	Mitigation
Legacy code uses AVB	Terminology inconsistency	Mark legacy code with LEGACY_AVB_* prefix; document migration plan
Intel datasheets use AVB	External reference mismatch	Add note in glossary: "Intel docs may use 'AVB'; equivalent to 'TSN'"
User confusion (AVB vs TSN)	Support burden	Maintain glossary with clear AVB→TSN mapping; FAQ section
New IEEE standard adopted	Glossary outdated	Process for 7-day glossary update; team notification
CI audit false positives	Developer friction	Exclude legitimate AVB references (legacy compat, historical context)

---

Traceability Matrix

Test Case	Requirement Section	Verification Method
TC-TSN-TERMS-001	TSN-TERMS-001.1 (Mapping Table)	Grep search in docs
TC-TSN-TERMS-002	TSN-TERMS-001.2 (Code Comments)	Grep audit
TC-TSN-TERMS-003	TSN-TERMS-001.3 (Variable Naming)	Pattern matching
TC-TSN-TERMS-004	TSN-TERMS-001.4 (Documentation Standards)	GitHub API query
TC-TSN-TERMS-005	TSN-TERMS-001.5 (Glossary)	Markdown parsing
TC-TSN-TERMS-006	Error Handling (Legacy Term Tolerance)	Unit test
TC-TSN-TERMS-007	Performance (Audit Automation)	CI workflow validation
TC-TSN-TERMS-008	Performance (Code Review)	PR template check
TC-TSN-TERMS-009	Documentation Standards (Issue Bodies)	GitHub API scan
TC-TSN-TERMS-010	Performance (README Updates)	Manual verification

---

Dependencies

Prerequisites:

• REQ-F-TSN-SEMANTICS-001: TSN vs AVB Terminology #54 (REQ-F-TSN-TERMS-001) implemented
• GitHub repository access
• grep utility (Windows/Linux)
• GitHub CLI (gh) installed
• CI/CD pipeline configured

Tools:

• PowerShell (Windows)
• bash (Linux)
• GitHub Actions
• Markdown linter
• grep/ripgrep

---

Execution Schedule

Estimated Time: 2 hours

• TC-TSN-TERMS-001 (Mapping Table): 10 minutes
• TC-TSN-TERMS-002 (Code Comments): 20 minutes
• TC-TSN-TERMS-003 (Variable Naming): 15 minutes
• TC-TSN-TERMS-004 (Issue Titles): 10 minutes
• TC-TSN-TERMS-005 (Glossary): 15 minutes
• TC-TSN-TERMS-006 (Legacy Tolerance): 20 minutes
• TC-TSN-TERMS-007 (CI Audit): 15 minutes
• TC-TSN-TERMS-008 (PR Template): 10 minutes
• TC-TSN-TERMS-009 (Issue Bodies): 10 minutes
• TC-TSN-TERMS-010 (README Updates): 5 minutes (manual)

---

Test Case Owner: Documentation Team
Created: 2025-12-20
Last Updated: 2025-12-20
Status: Ready for Execution

[github-actions]

❌ Test Requirements Missing

Test cases must link to the requirements they verify.

Required Action

Add the following to your issue body:

## Verified Requirements
- #N (REQ-F or REQ-NF issue)

Or in the description:

Verifies: #N, #M (requirement issues)

[github-actions]

🤖 Status Sync

**Automatic status update** based on issue body:
- **Body status**: Ready for Execution
- **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**: Ready for Execution
- **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**: Ready for Execution
- **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**: Ready for Execution
- **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**: Ready for Execution
- **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)*