[Mlir-commits] [mlir] [mlir][spirv][nfc] Update documentation to describe the testing strategy (PR #158962)

[Igor Wodiany]

https://github.com/IgWod-IMG updated https://github.com/llvm/llvm-project/pull/158962

>From b16628f74f701d8a416477feca7ccf978fdc84e2 Mon Sep 17 00:00:00 2001
From: Igor Wodiany <igor.wodiany at imgtec.com>
Date: Tue, 16 Sep 2025 10:58:12 +0100
Subject: [PATCH 1/3] [mlir][spirv][nfc] Update documentation to describe the
 testing strategy

---
 mlir/docs/Dialects/SPIR-V.md | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/mlir/docs/Dialects/SPIR-V.md b/mlir/docs/Dialects/SPIR-V.md
index 1e8c1c7be9f6a..f2d8c17bab009 100644
--- a/mlir/docs/Dialects/SPIR-V.md
+++ b/mlir/docs/Dialects/SPIR-V.md
@@ -1375,7 +1375,7 @@ the proper file in test/Dialect/SPIRV/.
 
 The generated op will automatically gain the logic for (de)serialization.
 However, tests still need to be coupled with the change to make sure no
-surprises. Serialization tests live in test/Dialect/SPIRV/Serialization.
+surprises (see more "Add a new test(s)" below).
 
 ### Add a new enum
 
@@ -1416,6 +1416,37 @@ conversion][MlirDialectConversionSignatureConversion] might be needed as well.
 operations contained within its region are valid operations in the SPIR-V
 dialect.
 
+### Add a new test(s)
+
+Currently the SPIR-V dialect has two types of tests that should be added or
+updated accordingly:
+
+1.  **Dialect tests** - Those tests check different aspects of the op in isolation.
+    They should include both positive and negative case, and exercise the verifier,
+    parser and printer. Dialect tests do not have to form a valid SPIR-V code and
+    should be kept as simple as possible. They are run with `mlir-opt`; and are
+    also used to test transformations.
+
+2.  **Target tests** - Those tests are designed to exercise serialization and
+    deserialization, so each module should be a valid SPIR-V module. (De)serialization
+    is tested using the `mlir-translate --test-spirv-roundtrip` option.
+
+    To ensure that the SPIR-V MLIR forms and serializes into a valid SPIR-V, the
+    `spriv-val` tool should be run on a serialized binary (`--serialize-spirv`).
+    This can be automated by adding a conditional validation section to the test:
+
+    ```
+    // RUN: %if spirv-tools %{ rm -rf %t %}
+    // RUN: %if spirv-tools %{ mkdir %t %}
+    // RUN: %if spirv-tools %{ mlir-translate --no-implicit-module --serialize-spirv --split-input-file --spirv-save-validation-files-with-prefix=%t/module %s %}
+    // RUN: %if spirv-tools %{ spirv-val %t %}
+    ```
+
+    This sequence serializes and dumps each MLIR SPIR-V module into a separate
+    SPIR-V binary (MLIR allows multiple modules per files, however the SPIR-V
+    spec restricts each binary to a single module), and then runs `spirv-val`
+    on each of the file.
+
 ## Operation definitions
 
 [include "Dialects/SPIRVOps.md"]

>From 8e42a0e821b1bcabff381ac0eee363107be7c818 Mon Sep 17 00:00:00 2001
From: Igor Wodiany <igor.wodiany at imgtec.com>
Date: Tue, 16 Sep 2025 15:42:55 +0100
Subject: [PATCH 2/3] Link test section

---
 mlir/docs/Dialects/SPIR-V.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/mlir/docs/Dialects/SPIR-V.md b/mlir/docs/Dialects/SPIR-V.md
index f2d8c17bab009..7766a1548fd4f 100644
--- a/mlir/docs/Dialects/SPIR-V.md
+++ b/mlir/docs/Dialects/SPIR-V.md
@@ -1375,7 +1375,7 @@ the proper file in test/Dialect/SPIRV/.
 
 The generated op will automatically gain the logic for (de)serialization.
 However, tests still need to be coupled with the change to make sure no
-surprises (see more "Add a new test(s)" below).
+surprises (see [Add a new test](#add-a-new-test) below).
 
 ### Add a new enum
 
@@ -1416,7 +1416,7 @@ conversion][MlirDialectConversionSignatureConversion] might be needed as well.
 operations contained within its region are valid operations in the SPIR-V
 dialect.
 
-### Add a new test(s)
+### Add a new test
 
 Currently the SPIR-V dialect has two types of tests that should be added or
 updated accordingly:

>From 66e58389e015c36ef2f82fd61722496228bec095 Mon Sep 17 00:00:00 2001
From: Igor Wodiany <igor.wodiany at imgtec.com>
Date: Tue, 16 Sep 2025 16:12:14 +0100
Subject: [PATCH 3/3] Add integration tests

---
 mlir/docs/Dialects/SPIR-V.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/mlir/docs/Dialects/SPIR-V.md b/mlir/docs/Dialects/SPIR-V.md
index 7766a1548fd4f..716dd7773aefa 100644
--- a/mlir/docs/Dialects/SPIR-V.md
+++ b/mlir/docs/Dialects/SPIR-V.md
@@ -1418,7 +1418,7 @@ dialect.
 
 ### Add a new test
 
-Currently the SPIR-V dialect has two types of tests that should be added or
+Currently the SPIR-V dialect has three types of tests that should be added or
 updated accordingly:
 
 1.  **Dialect tests** - Those tests check different aspects of the op in isolation.
@@ -1447,6 +1447,9 @@ updated accordingly:
     spec restricts each binary to a single module), and then runs `spirv-val`
     on each of the file.
 
+3.  **Integration tests** - Those tests execute the MLIR code using the `mlir-runner`
+    to verify its functional correctness.
+
 ## Operation definitions
 
 [include "Dialects/SPIRVOps.md"]