TEST-NAMING-CONV-001: Verify IEEE 802.1AS-2020 Naming Convention Compliance

## Test Information

**Test ID**: TEST-NAMING-CONV-001  
**Title**: Verify IEEE 802.1AS-2020 Naming Convention Compliance  
**Test Type**: Documentation/Code Audit  
**Priority**: P1 (High - Standards Compliance)  
**Phase**: 07-verification-validation

## Traceability
- Traces to: #51 (REQ-F-NAMING-001: IEEE 802.1AS Naming Conventions)

## Test Objective

Verify that all code, IOCTLs, documentation, and comments use IEEE 802.1AS-2020 terminology (gPTP, grandmaster, time receiver) and contain NO deprecated terms (PTP, master, slave) to ensure standards compliance and inclusive language.

## Test Scope

**In-Scope**:
- Source code files (*.c, *.h, *.cpp)
- IOCTL definitions and control codes
- Public header files (filteruser.h, etc.)
- Documentation (README, design docs, comments)
- Variable names, function names, structure names
- ETW event messages and log output
- User-facing error messages
- Git commit messages and PR descriptions

**Out-of-Scope**:
- Binary compatibility with legacy IOCTLs (separate migration requirement)
- Third-party library terminology (external dependencies)
- Historical git commit messages (immutable)
- Quoted legacy documentation references

## Prerequisites

**Software**:
- Complete codebase access (all source files)
- PowerShell 5.1+ or grep tool
- Static analysis tools (optional: Visual Studio Code Search)
- Git repository access (for commit/PR audit)

**Tools**:
- PowerShell `Select-String` (grep equivalent)
- Visual Studio Code "Find in Files"
- Custom terminology audit script

## Test Cases

### Test Case 1: Audit Source Code for "PTP" → "gPTP"
**Objective**: Verify NO occurrences of standalone "PTP" (must use "gPTP")

**Steps**:
1. Run PowerShell grep audit:
   ```powershell
   Get-ChildItem -Path . -Include *.c,*.h,*.cpp -Recurse | 
       Select-String -Pattern '\bPTP\b' -CaseSensitive |
       Where-Object { $_.Line -notmatch 'gPTP' -and $_.Line -notmatch '//.*legacy' }
   ```
2. Exclude false positives:
   - Comments referencing legacy code: `// Legacy PTP API`
   - Quoted historical references: `"Migrated from PTP to gPTP"`
   - External library includes: `#include <ptp_lib.h>` (third-party)

**Expected Results**:
- ✅ **Zero matches** for standalone `\bPTP\b` in active code
- ✅ All references use `gPTP` or `GPTP_` prefix
- ✅ Legacy comments explicitly marked: `// LEGACY: PTP API (deprecated, use gPTP)`

**Pass Criteria**: Zero active code uses "PTP" (excluding marked legacy references)

---

### Test Case 2: Audit for "Master" → "Grandmaster/Time Transmitter"
**Objective**: Verify NO occurrences of "master" in clock/port contexts

**Steps**:
1. Run PowerShell grep audit:
   ```powershell
   Get-ChildItem -Path . -Include *.c,*.h,*.cpp -Recurse | 
       Select-String -Pattern '\bmaster\b' -CaseSensitive |
       Where-Object { $_.Line -notmatch 'grandmaster' -and $_.Line -notmatch 'time.transmitter' }
   ```
2. Allowed exceptions:
   - Generic master/subordinate pattern (unrelated to PTP): `master_copy`, `master_lock`
   - External API calls (third-party libraries)
3. Verify replacements:
   - Clock role: "master clock" → "grandmaster clock"
   - Port role: "master port" → "time transmitter port"

**Expected Results**:
- ✅ **Zero matches** for "master" in PTP/gPTP context
- ✅ All clock references use "grandmaster"
- ✅ All port references use "time transmitter"

**Pass Criteria**: Zero PTP-related uses of "master"

---

### Test Case 3: Audit for "Slave" → "Time Receiver"
**Objective**: Verify NO occurrences of "slave" (deprecated and non-inclusive)

**Steps**:
1. Run PowerShell grep audit:
   ```powershell
   Get-ChildItem -Path . -Include *.c,*.h,*.cpp -Recurse | 
       Select-String -Pattern '\bslave\b' -CaseSensitive
   ```
2. **Strict enforcement**: NO exceptions (term is deprecated in all contexts)
3. Verify replacements:
   - Clock role: "slave clock" → "time receiver"
   - Port role: "slave port" → "time receiver port"

**Expected Results**:
- ✅ **Absolute zero matches** for "slave"
- ✅ All references use "time receiver"

**Pass Criteria**: Absolute zero occurrences (no exceptions)

---

### Test Case 4: IOCTL Naming Convention Audit
**Objective**: Verify all IOCTL names use IEEE 802.1AS-2020 terminology

**Steps**:
1. Extract all IOCTL definitions:
   ```powershell
   Get-ChildItem -Path . -Include *.h -Recurse | 
       Select-String -Pattern '#define\s+IOCTL_'
   ```
2. Check each IOCTL name for:
   - Contains `GPTP` NOT `PTP`
   - Contains `GRANDMASTER` NOT `MASTER`
   - Contains `TIME_RECEIVER` NOT `SLAVE`
3. Example violations:
   - ❌ `IOCTL_PTP_GET_CLOCK_STATE`
   - ❌ `IOCTL_GPTP_SET_MASTER_CLOCK`
   - ❌ `IOCTL_GPTP_SLAVE_STATUS`

**Expected Results**:
- ✅ All IOCTLs use `IOCTL_GPTP_*` prefix (NOT `IOCTL_PTP_*`)
- ✅ All clock role IOCTLs use `GRANDMASTER` or `TIME_RECEIVER`
- ✅ No deprecated terms in IOCTL names

**Example Correct IOCTLs**:
```c
#define IOCTL_GPTP_GET_CLOCK_STATE      0x9C40A010
#define IOCTL_GPTP_SET_GRANDMASTER_ROLE 0x9C40A014
#define IOCTL_GPTP_GET_TIME_RECEIVER_PORT_STATUS 0x9C40A018
```

**Pass Criteria**: 100% IOCTL compliance with IEEE 802.1AS-2020 naming

---

### Test Case 5: Structure and Type Definitions Audit
**Objective**: Verify typedef/struct names use modern terminology

**Steps**:
1. Extract all structure definitions:
   ```powershell
   Get-ChildItem -Path . -Include *.h -Recurse | 
       Select-String -Pattern 'typedef\s+struct\s+_.*PTP|MASTER|SLAVE'
   ```
2. Verify naming:
   - ✅ Correct: `GPTP_PORT_STATE`, `GRANDMASTER_CLOCK_INFO`
   - ❌ Incorrect: `PTP_CONFIG`, `MASTER_CLOCK_DATA`, `SLAVE_PORT_STATUS`

**Expected Results**:
- ✅ All structures use `GPTP_` prefix
- ✅ Clock role structures use `GRANDMASTER_` or `TIME_RECEIVER_`
- ✅ No `PTP_`, `MASTER_`, or `SLAVE_` prefixes

**Pass Criteria**: 100% structure naming compliance

---

### Test Case 6: Function Names and Variables Audit
**Objective**: Verify function and variable names use modern terminology

**Steps**:
1. Audit function definitions:
   ```powershell
   Get-ChildItem -Path . -Include *.c,*.cpp -Recurse | 
       Select-String -Pattern 'NTSTATUS\s+\w*Ptp|Master|Slave'
   ```
2. Audit local variables (sample check - manual review):
   - Open 10 random source files
   - Search for variable names containing deprecated terms
3. Verify naming:
   - ✅ Correct: `ConfigureGptpPort()`, `grandmaster_clock_id`, `time_receiver_port`
   - ❌ Incorrect: `SetPtpMaster()`, `master_clock`, `slave_status`

**Expected Results**:
- ✅ All functions use `Gptp*` naming (camelCase or PascalCase)
- ✅ Variables use `grandmaster_*`, `time_receiver_*` (snake_case)
- ✅ No `Ptp*`, `*Master*`, or `*Slave*` identifiers

**Pass Criteria**: Zero violations in sampled files (spot check)

---

### Test Case 7: Documentation and Comments Audit
**Objective**: Verify README, design docs, and code comments use modern terminology

**Steps**:
1. Audit README files:
   ```powershell
   Get-ChildItem -Path . -Include README.md -Recurse | 
       Select-String -Pattern '\bPTP\b|\bmaster\b|\bslave\b' -CaseSensitive
   ```
2. Audit code comments:
   ```powershell
   Get-ChildItem -Path . -Include *.c,*.h -Recurse | 
       Select-String -Pattern '//.*\b(PTP|master|slave)\b' -CaseSensitive |
       Where-Object { $_.Line -notmatch '//.*legacy|//.*deprecated|//.*historical' }
   ```
3. Allowed exceptions:
   - Historical references: `// Migrated from PTP to gPTP in v2.0`
   - Legacy compatibility notes: `// LEGACY: master clock API (deprecated)`

**Expected Results**:
- ✅ All active documentation uses IEEE 802.1AS-2020 terms
- ✅ Comments explicitly mark legacy references: `// LEGACY: ...`
- ✅ README glossary defines gPTP, grandmaster, time receiver

**Pass Criteria**: Zero active documentation uses deprecated terms (excluding marked legacy notes)

---

### Test Case 8: ETW Event Messages Audit
**Objective**: Verify Event Tracing for Windows (ETW) messages use modern terminology

**Steps**:
1. Search for `EventWrite*` calls:
   ```powershell
   Get-ChildItem -Path . -Include *.c,*.cpp -Recurse | 
       Select-String -Pattern 'EventWrite.*".*\b(PTP|master|slave)\b"' -CaseSensitive
   ```
2. Check event manifest file (if exists): `IntelAvbFilter.man`
3. Verify event message templates use modern terms

**Expected Results**:
- ✅ All event messages use "gPTP", "grandmaster", "time receiver"
- ✅ No user-visible messages contain deprecated terms
- ✅ Event manifest defines modern terminology

**Example Correct Messages**:
```c
EventWriteGptpGrandmasterClockSelected("Selected grandmaster clock ID: %llx", clockId);
EventWriteGptpTimeReceiverPortEnabled("Time receiver port %d enabled", portNum);
```

**Pass Criteria**: 100% ETW message compliance

---

### Test Case 9: Error Messages and User-Facing Strings Audit
**Objective**: Verify all user-facing strings (error messages, log output) use modern terminology

**Steps**:
1. Search for string literals in source code:
   ```powershell
   Get-ChildItem -Path . -Include *.c,*.cpp -Recurse | 
       Select-String -Pattern '".*\b(PTP|master|slave)\b.*"' -CaseSensitive
   ```
2. Categorize by context:
   - Error messages: `"PTP configuration failed"` → `"gPTP configuration failed"`
   - Log output: `"Master clock selected"` → `"Grandmaster clock selected"`
   - Status strings: `"Slave port active"` → `"Time receiver port active"`

**Expected Results**:
- ✅ All error messages use modern terminology
- ✅ All log output uses modern terminology
- ✅ No user-visible deprecated terms

**Pass Criteria**: Zero user-facing deprecated terms

---

### Test Case 10: Git Commit Messages and PR Descriptions Audit
**Objective**: Verify new commits/PRs use modern terminology (recent history only)

**Steps**:
1. Audit recent commit messages (last 100 commits):
   ```powershell
   git log --oneline -100 | Select-String -Pattern '\bPTP\b|\bmaster\b|\bslave\b'
   ```
2. Audit open pull request descriptions:
   - Use GitHub API or manual review
   - Check PR titles and bodies for deprecated terms
3. Focus: FUTURE commits/PRs only (historical commits are immutable)

**Expected Results**:
- ✅ Recent commits (last 100) use IEEE 802.1AS-2020 terminology
- ✅ Open PRs use modern terminology
- ⚠️ Historical commits allowed (immutable, informational only)

**Pass Criteria**: Zero deprecated terms in recent commits/PRs (last 30 days)

---

### Test Case 11: Terminology Glossary Existence
**Objective**: Verify README contains glossary defining IEEE 802.1AS-2020 terms

**Steps**:
1. Open README.md
2. Search for "Glossary" or "Terminology" section
3. Verify definitions present:
   - gPTP (generalized Precision Time Protocol)
   - Grandmaster clock (best clock in domain)
   - Time receiver (clock synchronized to grandmaster)
   - Time transmitter port (port transmitting sync messages)
   - Time receiver port (port receiving sync messages)
   - BMCA (Best Master Clock Algorithm)

**Expected Results**:
- ✅ README contains dedicated glossary section
- ✅ All 6 key terms defined with IEEE 802.1AS-2020 references
- ✅ Glossary includes deprecated term mapping table

**Example Glossary Entry**:
```markdown
## Glossary

- **gPTP (generalized Precision Time Protocol)**: IEEE 802.1AS-2020 time synchronization protocol (formerly "PTP")
- **Grandmaster clock**: Best available clock in a gPTP domain (formerly "master clock")
- **Time receiver**: Clock that synchronizes to grandmaster (formerly "slave clock")
...
```

**Pass Criteria**: Glossary exists with all 6 terms defined

---

### Test Case 12: CI/CD Pipeline Terminology Check
**Objective**: Verify automated CI/CD pipeline includes terminology audit

**Steps**:
1. Check `.github/workflows/` for terminology audit workflow
2. Verify workflow runs on PRs (before merge)
3. Test workflow by creating PR with deprecated term
4. Verify workflow fails with clear error message

**Expected Workflow** (`.github/workflows/terminology-audit.yml`):
```yaml
name: Terminology Audit
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check for deprecated terms
        run: |
          if grep -r '\bPTP\b' --include='*.c' --include='*.h' . | grep -v 'gPTP' | grep -v 'legacy'; then
            echo "ERROR: Found deprecated term 'PTP' (use 'gPTP')"
            exit 1
          fi
          if grep -r '\bmaster\b' --include='*.c' --include='*.h' . | grep -v 'grandmaster' | grep -v 'legacy'; then
            echo "ERROR: Found deprecated term 'master' (use 'grandmaster' or 'time transmitter')"
            exit 1
          fi
          if grep -r '\bslave\b' --include='*.c' --include='*.h' .; then
            echo "ERROR: Found deprecated term 'slave' (use 'time receiver')"
            exit 1
          fi
```

**Expected Results**:
- ✅ Workflow exists in `.github/workflows/terminology-audit.yml`
- ✅ Workflow runs on all PRs
- ✅ Workflow fails if deprecated terms found
- ✅ Clear error messages guide developers to correct terms

**Pass Criteria**: CI/CD enforces terminology automatically

---

## Test Data

**Deprecated Terms to Search**:
- `\bPTP\b` (case-sensitive, word boundary)
- `\bmaster\b` (case-sensitive, in PTP context)
- `\bslave\b` (case-sensitive, NO exceptions)

**Allowed Exceptions** (must be explicitly marked):
- Comments: `// LEGACY: PTP API (deprecated, use gPTP)`
- Quotes: `"Migrated from PTP to gPTP in version 2.0"`
- External includes: `#include <third_party/ptp_lib.h>`

**Modern Terminology Reference**:
| Context | IEEE 802.1AS-2020 Term |
|---------|----------------------|
| Protocol name | gPTP (generalized Precision Time Protocol) |
| Best clock | Grandmaster clock |
| Synchronized clock | Time receiver |
| Sync sender port | Time transmitter port |
| Sync receiver port | Time receiver port |
| Selection algorithm | BMCA (Best Master Clock Algorithm) |

## Test Environment

**Operating System**: Any (PowerShell/grep available)  
**Tools**: PowerShell 5.1+, Git, Visual Studio Code (optional)  
**Codebase**: IntelAvbFilter repository (all branches)

## Pass/Fail Criteria

**Test Suite Passes If**:
- ✅ All 12 test cases pass
- ✅ Zero deprecated terms in active code (excluding marked legacy)
- ✅ 100% IOCTL naming compliance
- ✅ 100% structure/function naming compliance
- ✅ Glossary exists in README
- ✅ CI/CD pipeline enforces terminology

**Test Suite Fails If**:
- ❌ Any active code uses "PTP" instead of "gPTP"
- ❌ Any code uses "master" or "slave" in PTP context
- ❌ Any IOCTL/structure uses deprecated naming
- ❌ Missing glossary in documentation
- ❌ No CI/CD enforcement

## Traceability Matrix

| Test Case | Requirement Coverage | Audit Method |
|-----------|---------------------|--------------|
| TC1 | PTP → gPTP | PowerShell grep |
| TC2 | Master → Grandmaster/Time Transmitter | PowerShell grep |
| TC3 | Slave → Time Receiver | PowerShell grep (strict) |
| TC4 | IOCTL naming | Grep `#define IOCTL_` |
| TC5 | Structure naming | Grep `typedef struct` |
| TC6 | Function/variable naming | Grep + manual review |
| TC7 | Documentation/comments | Grep README + comments |
| TC8 | ETW messages | Grep `EventWrite*` |
| TC9 | Error messages | Grep string literals |
| TC10 | Git commits/PRs | Git log audit |
| TC11 | Glossary existence | Manual README check |
| TC12 | CI/CD enforcement | Workflow verification |

## Test Execution Log

```
[PLACEHOLDER - To be filled during test execution]

Test Run ID: TR-NAMING-001-YYYYMMDD-HHMMSS
Tester: [Name]
Date: [YYYY-MM-DD]
Codebase Commit: [SHA]

Results:
- TC1: PASS (zero "PTP" violations)
- TC2: PASS (zero "master" violations)
- TC3: PASS (absolute zero "slave")
- TC4: PASS (all IOCTLs compliant)
- TC5: PASS (all structures compliant)
- TC6: PASS (spot check 10 files clean)
- TC7: PASS (documentation clean)
- TC8: PASS (ETW messages clean)
- TC9: PASS (error messages clean)
- TC10: PASS (recent commits clean)
- TC11: PASS (glossary exists)
- TC12: PASS (CI/CD enforces)

Overall: PASS
```

## Notes

- This is a **one-time audit** + **continuous enforcement** requirement
- CI/CD pipeline provides ongoing compliance (PR gate)
- Legacy code migration may require phased approach (mark deprecated, refactor later)
- External libraries (third-party) exempt from audit (document dependency)
- Historical git commits immutable (focus on future commits only)
- Glossary should be updated when new IEEE 802.1AS terms introduced

## References

- IEEE 802.1AS-2020: Timing and Synchronization for Time-Sensitive Applications
- IEEE 802.1AS-Rev: Inclusive Language Guidelines
- IntelAvbFilter Coding Standards: Naming Conventions
- IETF RFC 8575: YANG Data Model for the Precision Time Protocol (uses inclusive language)

---

**Test Prepared By**: Standards Compliance Team  
**Review Status**: Draft  
**Last Updated**: 2025-12-20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

TEST-NAMING-CONV-001: Verify IEEE 802.1AS-2020 Naming Convention Compliance #282

Test Information

Traceability

Test Objective

Test Scope

Prerequisites

Test Cases

Test Case 1: Audit Source Code for "PTP" → "gPTP"

Test Case 2: Audit for "Master" → "Grandmaster/Time Transmitter"

Test Case 3: Audit for "Slave" → "Time Receiver"

Test Case 4: IOCTL Naming Convention Audit

Test Case 5: Structure and Type Definitions Audit

Test Case 6: Function Names and Variables Audit

Test Case 7: Documentation and Comments Audit

Test Case 8: ETW Event Messages Audit

Test Case 9: Error Messages and User-Facing Strings Audit

Test Case 10: Git Commit Messages and PR Descriptions Audit

Test Case 11: Terminology Glossary Existence

Test Case 12: CI/CD Pipeline Terminology Check

Test Data

Test Environment

Pass/Fail Criteria

Traceability Matrix

Test Execution Log

Notes

References

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Context	IEEE 802.1AS-2020 Term
Protocol name	gPTP (generalized Precision Time Protocol)
Best clock	Grandmaster clock
Synchronized clock	Time receiver
Sync sender port	Time transmitter port
Sync receiver port	Time receiver port
Selection algorithm	BMCA (Best Master Clock Algorithm)

Test Case	Requirement Coverage	Audit Method
TC1	PTP → gPTP	PowerShell grep
TC2	Master → Grandmaster/Time Transmitter	PowerShell grep
TC3	Slave → Time Receiver	PowerShell grep (strict)
TC4	IOCTL naming	Grep `#define IOCTL_`
TC5	Structure naming	Grep `typedef struct`
TC6	Function/variable naming	Grep + manual review
TC7	Documentation/comments	Grep README + comments
TC8	ETW messages	Grep `EventWrite*`
TC9	Error messages	Grep string literals
TC10	Git commits/PRs	Git log audit
TC11	Glossary existence	Manual README check
TC12	CI/CD enforcement	Workflow verification

Uh oh!

TEST-NAMING-CONV-001: Verify IEEE 802.1AS-2020 Naming Convention Compliance #282

Description

Test Information

Traceability

Test Objective

Test Scope

Prerequisites

Test Cases

Test Case 1: Audit Source Code for "PTP" → "gPTP"

Test Case 2: Audit for "Master" → "Grandmaster/Time Transmitter"

Test Case 3: Audit for "Slave" → "Time Receiver"

Test Case 4: IOCTL Naming Convention Audit

Test Case 5: Structure and Type Definitions Audit

Test Case 6: Function Names and Variables Audit

Test Case 7: Documentation and Comments Audit

Test Case 8: ETW Event Messages Audit

Test Case 9: Error Messages and User-Facing Strings Audit

Test Case 10: Git Commit Messages and PR Descriptions Audit

Test Case 11: Terminology Glossary Existence

Test Case 12: CI/CD Pipeline Terminology Check

Test Data

Test Environment

Pass/Fail Criteria

Traceability Matrix

Test Execution Log

Notes

References

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions