Re: [PATCH v6 4/4] docs: Update platform filtering documentation per review feedback

Hi Zhang,,
On 2026-08-20 at 02:03:18 +0000, Zhang, Jesse(Jie) wrote:
> AMD General
> 
> Review-by: Jesse Zhang <[email protected]>
> 

Applied, thank you all.
I corrected a subject here, please do not write about review in subject,
so I changed it into:

[PATCH v6 4/4] docs: Add platform filtering documentation

Also applied few last corrections using checkpatch.pl help.

Regards,
Kamil

> > -----Original Message-----
> > From: [email protected] <[email protected]>
> > Sent: Thursday, August 20, 2026 9:27 AM
> > To: [email protected]
> > Cc: [email protected]; [email protected];
> > [email protected]; [email protected]; Zhang,
> > Jesse(Jie) <[email protected]>; Koenig, Christian
> > <[email protected]>; Deucher, Alexander
> > <[email protected]>; Prosyak, Vitaly <[email protected]>;
> > Pawel Sikora <[email protected]>
> > Subject: [PATCH v6 4/4] docs: Update platform filtering documentation per review
> > feedback
> >
> > From: Vitaly Prosyak <[email protected]>
> >
> > Update the platform filtering usage guide to clarify method priority ordering, replace
> > Advantages/Disadvantages with When-to-Use/Trade-offs, and add runtime
> > methods for discovering platform names.
> >
> > Suggested-by: Krzysztof Kozlowski <[email protected]>
> > Cc: Kamil Konieczny <[email protected]>
> > Cc: Pawel Sikora <[email protected]>
> > Cc: Jani Nikula <[email protected]>
> > Cc: Jesse Zhang <[email protected]>
> > Cc: Christian Koenig <[email protected]>
> > Cc: Alex Deucher <[email protected]>
> > Signed-off-by: Vitaly Prosyak <[email protected]>
> > Acked-by: Kamil Konieczny <[email protected]>
> > ---
> >  docs/platform_filtering.md | 351 +++++++++++++++++++++++++++++++++++++
> >  mkdocs.yml                 |   1 +
> >  2 files changed, 352 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..7d3202a94
> > --- /dev/null
> > +++ b/docs/platform_filtering.md
> > @@ -0,0 +1,351 @@
> > +# 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: Built-in Rules (Highest Priority)
> > +
> > +**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,
> > +    },
> > +};
> > +```
> > +
> > +### When to Use Built-in Rules
> > +
> > +- Permanent production exclusions that should never run
> > +- Platform limitations known at development time
> > +- Tests that fundamentally cannot work on certain hardware
> > +- Vendor-specific restrictions that apply globally
> > +
> > +**Trade-offs:**
> > +- [+] Fast (no file I/O at runtime)
> > +- [+] Guaranteed to be applied
> > +- [+] Version controlled with code
> > +- [-] Requires rebuild to change
> > +- [-] Not flexible for temporary exclusions
> > +
> > +---
> > +
> > +## Method 2: Config File (RECOMMENDED)
> > +
> > +**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 ```
> > +
> > +### When to Use Config File
> > +
> > +- Managing multiple test exclusions
> > +- Team-wide or CI/CD configurations
> > +- Persistent filtering rules across sessions
> > +- Easy add/remove/edit without rebuilding
> > +- No need to remember environment variables
> > +- Sharing skip rules across test infrastructure
> > +
> > +---
> > +
> > +## Method 3: Environment Variable (Lowest Priority)
> > +
> > +**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
> > +```
> > +
> > +### When to Use Environment Variable
> > +
> > +- Quick one-off testing without editing files
> > +- Temporary overrides during debugging sessions
> > +- Testing filter patterns before adding to config file
> > +- Single test runs where config file would be overkill
> > +- Overriding config file rules for specific test runs
> > +- CI pipeline job-specific overrides
> > +
> > +**Trade-offs:**
> > +- [+] No file editing required
> > +- [+] Quick to set and unset
> > +- [+] Can override config file for testing
> > +- [-] Not persistent (lost when session ends)
> > +- [-] Easy to forget it's set
> > +- [-] Inconvenient for large test lists
> > +
> > +---
> > +
> > +## 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:amd_*:my-test:Reason          # All amd_* tests
> > +
> > +# Subtest wildcards
> > +navi48:amd_basic:*-UMQ:Reason        # All subtests ending with -UMQ
> > +navi48:amd_basic:cs-*:Reason         # All subtests starting with cs-
> > +
> > +# Combined wildcards
> > +*:*:*-UMQ:Reason                     # All UMQ tests on all platforms
> > +```
> > +
> > +### Wildcard Examples
> > +
> > +```bash
> > +# Skip all user queue tests during bringup navi48:*:*-UMQ:Platform
> > +bringup - UMQ not ready
> > +
> > +# Skip all VCN tests on specific platform navi10:amd_vcn:*:Known VCN
> > +issues
> > +
> > +# Skip specific test pattern across all platforms
> > +*:amd_basic:eviction-*:Intermittent failures
> > +
> > +# Skip all tests on EOL platform
> > +vega10:*:*:Platform no longer supported ```
> > +
> > +### Pattern Matching Rules
> > +
> > +- `*` matches zero or more characters
> > +- Patterns are case-sensitive
> > +- Empty field is NOT a wildcard (use `*` explicitly)
> > +- Priority order: Built-in > Config file > Environment variable
> > +
> > +### Example Subtest Matching
> > +
> > +Given config: `navi48:amd_basic:*-UMQ:Testing`
> > +
> > +- cs-gfx-with-IP-GFX-UMQ → **Skipped** (matches)
> > +- cs-compute-with-IP-COMPUTE-UMQ → **Skipped** (matches)
> > +- cs-sdma-with-IP-DMA → Runs normally (doesn't match)
> > +
> > +---
> > +
> > +## 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
> > +
> > +Platform names are vendor-specific and defined in vendor backend code.
> > +
> > +**For AMD platforms**, see `lib/amdgpu/amd_platform.c` for the complete list.
> > +
> > +**Examples:**
> > +- RDNA2/3 discrete GPUs: `navi21`, `navi31`, `navi33`
> > +- RDNA4: `navi48`, `navi44`
> > +- APUs: `strix_halo`, `phoenix`
> > +- Data center: `aldebaran` (MI250)
> > +
> > +**To find your platform name:**
> > +
> > +```bash
> > +# Method 1: Run any test with debug output
> > +./build/tests/amdgpu/amd_basic --debug # Look for: "Platform detected:
> > +<name>"
> > +
> > +# Method 2: Check dmesg for GPU info
> > +dmesg | grep -i amdgpu | grep -i asic
> > +
> > +# Method 3: Check /sys
> > +cat /sys/class/drm/card0/device/asic_name  # If available ```
> > +
> > +**Note:** Platform names may change with new hardware generations. Check
> > vendor backend code for current platform definitions. The list above is provided as
> > examples only.
> > +
> > +---
> > +
> > +## 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-07-09
> > +
> > +# 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 |
> > +|--------|----------|------------|------------------|
> > +| **Built-in** | Production rules | Yes | Yes | **Config file** |
> > +| Team/CI exclusions | Yes | No |
> > +| **Environment** | Quick testing | No | No |
> > +
> > +**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..1819b7b6c 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 tests per platform: '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
>