[PATCH 6/7] docs: Add comprehensive platform filtering documentation

[<vitaly.prosyak@amd.com>]

From: Vitaly Prosyak <vitaly.prosyak@amd.com>

Add comprehensive user-facing documentation for the platform filtering
framework, including:

- Quick start guide with code examples
- Three filtering methods (config file, environment, built-in)
- Detailed format specifications
- Real-world usage examples
- Platform name reference table
- Summary comparison table
- Integration with mkdocs navigation

The documentation is written for test developers who need to skip tests
on specific platforms without modifying test source code.

v2: Address review feedback from Krzysztof Karas:
    - Added clarification that reason field is recommended but can be empty
    - Added use cases section to environment variable method
    - Added note that platform list is partial/example
    - Removed redundant checkmark from summary table
    - Fixed mkdocs.yml title to match How to pattern

Cc: Kamil Konieczny <kamil.konieczny@linux.intel.com>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Jesse Zhang <jesse.zhang@amd.com>
Cc: Christian König <christian.koenig@amd.com>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: Krzysztof Karas <krzysztof.karas@intel.com>
Signed-off-by: Vitaly Prosyak <vitaly.prosyak@amd.com>
Reviewed-by: Jesse Zhang <jesse.zhang@amd.com>
Change-Id: I40c5c5b63a1d5f9c61c3b89e21a2f7a14bb0a75f
---
 docs/platform_filtering.md | 341 +++++++++++++++++++++++++++++++++++++
 mkdocs.yml                 |   1 +
 2 files changed, 342 insertions(+)
 create mode 100644 docs/platform_filtering.md

diff --git a/docs/platform_filtering.md b/docs/platform_filtering.md
new file mode 100644
index 000000000..2d2dab372
--- /dev/null
+++ b/docs/platform_filtering.md
@@ -0,0 +1,341 @@
+# IGT Platform Filtering - Usage Guide
+
+## Overview
+
+The IGT platform filtering framework allows tests to be skipped based on
+platform characteristics without modifying test source code.
+
+**Key Feature**: **Automatic Filtering** - No manual calls needed in subtests!
+
+Tests only need to initialize platform filtering once in `igt_fixture`,
+and the IGT framework automatically checks each subtest before execution.
+
+## Quick Start
+
+### 1. Initialize in Test (One Time)
+
+```c
+#include "lib/amdgpu/amd_platform.h"
+
+int igt_main(void)
+{
+    struct amdgpu_gpu_info gpu_info;
+
+    igt_fixture {
+        fd = drm_open_driver(DRIVER_AMDGPU);
+        amdgpu_query_gpu_info(device, &gpu_info);
+
+        /* Initialize platform filtering - enables automatic filtering */
+        amd_platform_filter_init(&gpu_info);
+    }
+
+    igt_subtest("my-test") {
+        /* No manual filtering call needed - automatic! */
+        test_code();
+    }
+}
+```
+
+### 2. Configure Filtering Rules
+
+Use one of three methods (checked in priority order):
+
+1. **Built-in rules** (highest priority) - Compiled into test
+2. **Config file** (recommended) - `/etc/igt/platform_skip.conf`
+3. **Environment variable** (lowest priority) - `IGT_PLATFORM_SKIP_CONFIG`
+
+---
+
+## Method 1: Config File (RECOMMENDED)
+
+**Best for**: Large test lists, team-wide configuration, CI/CD
+
+**Location**: `/etc/igt/platform_skip.conf`
+
+**Format**: `platform:test:subtest:reason`
+
+**Note**: The reason field is recommended but can be empty. If omitted, "No reason" is automatically inserted.
+
+### Example Config File
+
+```bash
+cat > /etc/igt/platform_skip.conf << 'EOF'
+# Platform filtering configuration
+# Format: platform:test:subtest:reason
+# Use * as wildcard
+
+# Skip all UMQ tests on Navi48 during platform bringup
+navi48:amd_basic:*-UMQ:SWDEV-88888 - UMQ stabilization in progress
+
+# Skip specific tests with ticket references
+navi31:amd_basic:cs-gfx-with-IP-GFX-UMQ:SWDEV-12345
+navi31:amd_basic:cs-compute-with-IP-COMPUTE-UMQ:SWDEV-12345
+navi31:amd_basic:cs-sdma-with-IP-DMA-UMQ:SWDEV-12346
+
+# Skip tests on early samples
+strix_halo:amd_basic:*:Platform not ready - ES samples
+
+# Skip known flaky test across all platforms
+*:amd_basic:eviction-test-with-IP-DMA:SWDEV-99999 - Intermittent failure
+
+# Skip entire test binary on specific platform
+navi10:amd_vcn:*:VCN encoding issues on Navi10 A0
+
+# Skip all tests on discontinued platform
+vega10:*:*:Platform no longer supported
+EOF
+```
+
+### Run Tests
+
+```bash
+# Config file is loaded automatically - no environment variable needed
+./build/tests/amdgpu/amd_basic
+
+# Output shows:
+# Subtest cs-gfx-with-IP-GFX-UMQ: SKIP
+# Platform filtering (config): SWDEV-12345
+```
+
+### Advantages
+
+✅ Persistent across sessions
+✅ Easy to manage many rules (add/remove/edit)
+✅ Team-wide configuration
+✅ CI/CD friendly
+✅ No rebuild required
+✅ No environment variables to remember
+
+---
+
+## Method 2: Environment Variable
+
+**Best for**: Quick testing, temporary overrides, single test skip
+
+**Variable**: `IGT_PLATFORM_SKIP_CONFIG`
+
+**Format**: Same as config file, semicolon-separated
+
+### Example - Skip Single Test
+
+```bash
+export IGT_PLATFORM_SKIP_CONFIG="navi48:amd_basic:cs-compute-with-IP-COMPUTE-UMQ:Testing"
+./build/tests/amdgpu/amd_basic
+```
+
+### Example - Skip Multiple Tests
+
+```bash
+export IGT_PLATFORM_SKIP_CONFIG="navi48:amd_basic:*-UMQ:Testing;navi31:amd_basic:cs-gfx-*:Known issue"
+./build/tests/amdgpu/amd_basic
+```
+
+### Use Cases
+
+- **Quick one-off testing**: Temporarily skip a test without modifying config files
+- **Debugging**: Isolate specific failures by skipping known issues
+- **CI pipeline overrides**: Inject test skips for specific job runs
+- **Developer testing**: Skip tests during development without persistent config
+- **Testing the filter**: Verify filtering system works correctly
+
+### Disadvantages
+
+❌ Not persistent (lost when session ends)
+❌ Inconvenient for large test lists
+❌ Easy to forget it's set
+❌ Hard to manage multiple rules
+
+**Recommendation**: Use config file for managing test exclusions at scale.
+
+---
+
+## Method 3: Built-in Rules
+
+**Best for**: Permanent production exclusions
+
+**Location**: Vendor implementation (e.g., `lib/amdgpu/amd_platform.c`)
+
+### Example
+
+```c
+static const struct platform_skip_entry amd_builtin_rules[] = {
+    {
+        .test_name = "amd_security",
+        .subtest_glob = "secure-bounce",
+        .reason = "Not supported on APUs",
+        .platform_data = &apu_platforms,
+    },
+};
+```
+
+### Advantages
+
+✅ Fast (no file I/O)
+✅ Guaranteed to be applied
+✅ Version controlled with code
+
+### Use Cases
+
+- **Quick one-off testing**: Temporarily skip a test without modifying config files
+- **Debugging**: Isolate specific failures by skipping known issues
+- **CI pipeline overrides**: Inject test skips for specific job runs
+- **Developer testing**: Skip tests during development without persistent config
+- **Testing the filter**: Verify filtering system works correctly
+
+### Disadvantages
+
+❌ Requires rebuild to change
+❌ Not flexible for temporary exclusions
+
+---
+
+## Wildcard Patterns
+
+All methods support wildcards (`*`) for flexible matching:
+
+```
+# Platform wildcards
+*:amd_basic:my-test:Reason           # All platforms
+navi*:amd_basic:my-test:Reason       # All Navi (navi10, navi31, navi48, etc.)
+
+# Test wildcards
+navi48:*:my-subtest:Reason           # All test binaries
+navi48:amd_*:my-subtest:Reason       # All AMD tests
+
+# Subtest wildcards
+navi48:amd_basic:*:Reason            # All subtests in amd_basic
+navi48:amd_basic:*-UMQ:Reason        # All UMQ subtests
+navi48:amd_basic:cs-*:Reason         # All CS tests
+```
+
+---
+
+## Priority System
+
+When multiple rules could match, first match wins (highest to lowest priority):
+
+1. **Built-in rules** (compiled into test)
+2. **Config file** (`/etc/igt/platform_skip.conf`)
+3. **Environment variable** (`IGT_PLATFORM_SKIP_CONFIG`)
+
+Example:
+```
+Built-in: navi48:amd_basic:cs-gfx-*:Production exclusion
+Config:   navi48:amd_basic:*:Config exclusion
+Env:      navi48:amd_basic:cs-compute-*:Env exclusion
+
+Results:
+- cs-gfx-with-IP-GFX → Skipped by built-in rule
+- cs-compute-with-IP-COMPUTE → Skipped by config file
+- cs-sdma-with-IP-DMA → Runs normally
+```
+
+---
+
+## Skip Message Format
+
+Automatic filtering shows the source in skip messages:
+
+```
+Subtest cs-gfx-with-IP-GFX-UMQ: SKIP
+Platform filtering (config): SWDEV-12345 - UMQ unstable on Navi48
+```
+
+Source indicators:
+- `(built-in)` - From vendor's compiled rules
+- `(config)` - From config file
+- `(env)` - From environment variable
+
+---
+
+## Platform Names
+
+**Note:** This is a partial list for examples. See vendor-specific backend files
+(e.g., `lib/amdgpu/amd_platform.c`) for the complete list.
+
+Platform names are vendor-specific. For AMD:
+
+- `vega10`, `vega20` - Vega family
+- `navi10`, `navi14`, `navi21`, `navi22`, `navi23`, `navi24` - RDNA1/2
+- `navi31`, `navi32`, `navi33` - RDNA3
+- `navi48`, `navi44` - RDNA4
+- `strix_halo`, `phoenix` - APUs
+- `arcturus` - MI100
+- `aldebaran` - MI210/MI250
+
+Use `*` to match all platforms.
+
+---
+
+## Best Practices
+
+### For Development - Quick Testing
+
+Use environment variable:
+```bash
+# Temporarily skip broken test
+export IGT_PLATFORM_SKIP_CONFIG="*:amd_basic:broken-test:WIP"
+./build/tests/amdgpu/amd_basic
+unset IGT_PLATFORM_SKIP_CONFIG
+```
+
+### For Teams - Shared Exclusions
+
+Use config file with ticket references:
+```
+# /etc/igt/platform_skip.conf
+# Updated: 2026-06-29
+
+# Navi48 bringup exclusions
+navi48:amd_basic:*-UMQ:SWDEV-88888 - UMQ stabilization
+navi48:amd_vcn:vcn-encoder-*:SWDEV-88889 - VCN bringup
+
+# Cross-platform known issues
+*:amd_basic:eviction-test-with-IP-DMA:SWDEV-77777 - Flaky
+```
+
+### For CI/CD
+
+Deploy config file with test infrastructure:
+```bash
+#!/bin/bash
+# CI pipeline setup
+echo "Deploying test exclusions..."
+scp ci-skip-rules.conf test-machine:/etc/igt/platform_skip.conf
+ssh test-machine "./run-igt-suite.sh"
+```
+
+### For Production
+
+Use built-in rules for permanent exclusions:
+```c
+// In lib/amdgpu/amd_platform.c
+static const struct platform_skip_entry amd_builtin_rules[] = {
+    {
+        .test_name = "amd_basic",
+        .subtest_glob = "*-UMQ",
+        .reason = "User queues not supported in production",
+        .platform_data = &all_platforms,
+    },
+};
+```
+
+---
+
+## Summary
+
+| Method | Use Case | Persistent | Rebuild Required |
+|--------|----------|------------|------------------|
+| **Config file** ✅ | Team/CI exclusions | Yes | No |
+| **Environment** | Quick testing | No | No |
+| **Built-in** | Production rules | Yes | Yes |
+
+**Recommendation**: Use **config file** for managing test exclusions at scale.
+
+---
+
+## See Also
+
+- `lib/igt_platform_filter.h` - API documentation
+- `lib/igt_platform_filter.c` - Framework implementation
+- `lib/amdgpu/amd_platform.c` - AMD backend reference
diff --git a/mkdocs.yml b/mkdocs.yml
index 0abb76704..f220674b3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -29,6 +29,7 @@ nav:
     - How to document tests: 'test_documentation.md'
     - How to categorize tests: 'test_categories.md'
     - How to blocklist tests: 'blocklists.md'
+    - How to filter platforms: 'platform_filtering.md'
     - How to get code coverage: 'code_coverage.md'
     - How to port new IGT driver: 'new_driver.md'
     - How to plan a new test: 'test_plan.md'
-- 
2.54.0