Deprecate MHLO input conversion pipeline (iree-org#13870)

As we continue the migration to the stablehlo input conversion pipeline, mark the mhlo pipeline as deprecated and rename the option to `--iree-input-type=mhlo_legacy`. This was proposed and announced in the following RFC: https://groups.google.com/g/iree-discuss/c/s6dBpDtWhtk. Users are encouraged to try the new pipeline: `--iree-input-type=stablehlo` and report any issues or missing features, as we plan to drop the legacy mhlo pipeline in a few weeks. Update tests to use the new flag name. Update documents to suggest either the new pipeline or the new flag. Next, we will have to migrate existing test and samples to use StableHLO as the input format: iree-org#13869. Issue: iree-org#12678
plaidml · Aug 24, 2023 · aec4254 · aec4254
1 parent 99fe7c6
commit aec4254
Show file tree

Hide file tree

Showing 42 changed files with 115 additions and 107 deletions.
diff --git a/build_tools/cmake/iree_static_linker_test.cmake b/build_tools/cmake/iree_static_linker_test.cmake
@@ -40,7 +40,7 @@
 #     FUNCTION_INPUTS
 #       "1x128x128xf32"
 #     COMPILER_FLAGS
-#       "--iree-input-type=mhlo"
+#       "--iree-input-type=stablehlo"
 #   )
 function(iree_static_linker_test)
   if(NOT IREE_BUILD_TESTS)

diff --git a/compiler/bindings/c/iree/compiler/loader/loader_test.c b/compiler/bindings/c/iree/compiler/loader/loader_test.c
@@ -34,7 +34,7 @@ static bool manipulateFlags(iree_compiler_session_t *session) {
     printf("FLAG GET ERROR. Abort\n");
     return 1;
   }
-  const char *flag1 = "--iree-input-type=mhlo";
+  const char *flag1 = "--iree-input-type=stablehlo";
   const char *badFlag1 = "--iree-non-existing-flag=foobar";
   const char *flagArgv[] = {
       flag1,

diff --git a/compiler/bindings/python/iree/compiler/tools/core.py b/compiler/bindings/python/iree/compiler/tools/core.py
@@ -41,10 +41,12 @@ class InputType(Enum):
   `CompilerOptions.input_type`.
   """
   NONE = "none"
-  MHLO = "mhlo"
+  STABLEHLO = "stablehlo"
+  STABLEHLO_XLA = "stablehlo_xla"
   TOSA = "tosa"
   TM_TENSOR = "tm_tensor"
-  XLA = "xla"
+  MHLO_LEGACY = "mhlo_legacy"
+  XLA_LEGACY = "xla_legacy"
 
   @staticmethod
   def parse(spec: Union[str, InputType]) -> InputType:
@@ -64,6 +66,9 @@ def parse(spec: Union[str, InputType]) -> InputType:
                        f"{', '.join(InputType.__members__.keys())}")
     return InputType[spec]
 
+  def __str__(self):
+    return self.value
+
 
 class OutputFormat(Enum):
   """The output format of the compiler."""
@@ -89,6 +94,9 @@ def parse(spec: Union[str, OutputFormat]) -> OutputFormat:
                        f"{', '.join(OutputFormat.__members__.keys())}")
     return OutputFormat[spec]
 
+  def __str__(self):
+    return self.value
+
 
 @dataclass
 class CompilerOptions:
@@ -167,8 +175,8 @@ def build_compile_command_line(input_file: str, tfs: TempFileSaver,
   cl = [
       iree_compile,
       input_file,
-      f"--iree-input-type={options.input_type.value}",
-      f"--iree-vm-bytecode-module-output-format={options.output_format.value}",
+      f"--iree-input-type={options.input_type!s}",
+      f"--iree-vm-bytecode-module-output-format={options.output_format!s}",
   ]
   for target_backend in options.target_backends:
     cl.append(f"--iree-hal-target-backends={target_backend}")

diff --git a/compiler/bindings/python/iree/compiler/tools/tf.py b/compiler/bindings/python/iree/compiler/tools/tf.py
@@ -97,7 +97,7 @@ class ImportOptions(CompilerOptions):
   exported_names: Sequence[str] = ()
   import_only: bool = False
   import_type: ImportType = ImportType.OBJECT_GRAPH
-  input_type: Union[InputType, str] = InputType.XLA
+  input_type: Union[InputType, str] = InputType.XLA_LEGACY
   saved_model_tags: Set[str] = field(default_factory=set)
   save_temp_iree_input: Optional[str] = None
 

diff --git a/compiler/bindings/python/test/tools/compiler_core_test.py b/compiler/bindings/python/test/tools/compiler_core_test.py
@@ -105,7 +105,7 @@ def testOutputFbText(self):
   def testBadInputType(self):
     with self.assertRaisesRegex(
         ValueError, "For input_type= argument, expected one of: "
-        "NONE, MHLO, TOSA"):
+        "NONE, STABLEHLO, STABLEHLO_XLA, TOSA"):
       _ = iree.compiler.tools.compile_str(
           SIMPLE_MUL_ASM,
           input_type="not-existing",
@@ -124,7 +124,7 @@ def testBadOutputFormat(self):
   def testOutputFbTextParsed(self):
     text = iree.compiler.tools.compile_str(
         SIMPLE_MUL_ASM,
-        input_type='mhlo',
+        input_type='stablehlo',
         output_format='flatbuffer_text',
         target_backends=iree.compiler.tools.DEFAULT_TESTING_BACKENDS).decode(
             "utf-8")

diff --git a/compiler/src/iree/compiler/Pipelines/Options.cpp b/compiler/src/iree/compiler/Pipelines/Options.cpp
@@ -45,17 +45,17 @@ void InputDialectOptions::bindOptions(OptionsBinder &binder) {
                      "Analyze the input program to choose conversion.")
   // clang-format off
 #ifdef IREE_HAVE_MHLO_INPUT
-        , clEnumValN(InputDialectOptions::Type::mhlo, "mhlo",
-                     "Legalize from MHLO ops.")
-        , clEnumValN(InputDialectOptions::Type::xla, "xla",
-            "Legalize from MHLO ops (with XLA cleanup preprocessing).")
         , clEnumValN(InputDialectOptions::Type::stablehlo,
             "stablehlo",
-            "Legalize from StableHLO ops. WARNING: This is work in progress.")
+            "Legalize from StableHLO ops.")
         , clEnumValN(InputDialectOptions::Type::stablehlo_xla,
             "stablehlo_xla",
-            "Legalize from StableHLO ops (with XLA cleanup preprocessing). "
-            "WARNING: This is work in progress.")
+            "Legalize from StableHLO ops (with XLA cleanup preprocessing). ")
+        , clEnumValN(InputDialectOptions::Type::mhlo_legacy, "mhlo_legacy",
+                     "Legalize from MHLO ops. (Deprecated.)")
+        , clEnumValN(InputDialectOptions::Type::xla_legacy, "xla_legacy",
+            "Legalize from MHLO ops (with XLA cleanup preprocessing). "
+            "(Deprecated.)")
 #endif  // IREE_HAVE_MHLO_INPUT
 #ifdef IREE_HAVE_TORCH_INPUT
         , clEnumValN(InputDialectOptions::Type::tm_tensor, "tm_tensor",

diff --git a/compiler/src/iree/compiler/Pipelines/Options.h b/compiler/src/iree/compiler/Pipelines/Options.h
@@ -37,16 +37,16 @@ struct InputDialectOptions {
     // Analyses the input to determine what input dialect pipeline to use.
     auto_detect,
 #ifdef IREE_HAVE_MHLO_INPUT
-    // Legalizes input defined over MHLO ops.
-    mhlo,
-    // Special case of 'mhlo' legalization which also performs some XLA
-    // cleanup activities.
-    xla,
     // Legalizes input defined over StableHLO ops.
     stablehlo,
     // Special case of 'stablehlo' legalization which also performs some XLA
     // preprocessing, e.g., flattening of tuples.
     stablehlo_xla,
+    // Legalizes input defined over MHLO ops. (Deprecated.)
+    mhlo_legacy,
+    // Special case of 'mhlo' legalization which also performs some XLA
+    // cleanup activities. (Deprecated.)
+    xla_legacy,
 #endif  // IREE_HAVE_MHLO_INPUT
 #ifdef IREE_HAVE_TORCH_INPUT
     // Legalizes input defined over TMTensor ops.

diff --git a/compiler/src/iree/compiler/Pipelines/Pipelines.cpp b/compiler/src/iree/compiler/Pipelines/Pipelines.cpp
@@ -60,18 +60,18 @@ void buildIREEVMTransformPassPipeline(
       passManager.addPass(createAutoInputConversionPipelinePass());
       break;
 #ifdef IREE_HAVE_MHLO_INPUT
-    case InputDialectOptions::Type::mhlo:
-      MHLO::buildMHLOInputConversionPassPipeline(passManager);
-      break;
-    case InputDialectOptions::Type::xla:
-      MHLO::buildXLAInputConversionPassPipeline(passManager);
-      break;
     case InputDialectOptions::Type::stablehlo:
       stablehlo::buildStableHLOInputConversionPassPipeline(passManager);
       break;
     case InputDialectOptions::Type::stablehlo_xla:
       stablehlo::buildStableHLOXLAInputConversionPassPipeline(passManager);
       break;
+    case InputDialectOptions::Type::mhlo_legacy:
+      MHLO::buildMHLOInputConversionPassPipeline(passManager);
+      break;
+    case InputDialectOptions::Type::xla_legacy:
+      MHLO::buildXLAInputConversionPassPipeline(passManager);
+      break;
 #endif  // IREE_HAVE_MHLO_INPUT
 #ifdef IREE_HAVE_TORCH_INPUT
     case InputDialectOptions::Type::tm_tensor:

diff --git a/docs/developers/debugging/compile_time_regressions.md b/docs/developers/debugging/compile_time_regressions.md
@@ -97,7 +97,7 @@ INPUT_FILE_PATH="/path/to/program.mlirbc"
 TMP_DIR="../iree-tmp"
 
 declare -a COMPILER_FLAGS=(
-  "--iree-input-type=mhlo"
+  "--iree-input-type=stablehlo"
   "--iree-hal-target-backends=cuda"
   "--iree-hal-cuda-llvm-target-arch=sm_80"
 )

diff --git a/docs/developers/debugging/tf_integrations_test_repro.md b/docs/developers/debugging/tf_integrations_test_repro.md
@@ -71,6 +71,6 @@ All steps here assume starting from the IREE root directory.
     ```bash
     iree-compile \
       --iree-hal-target-backends=llvm-cpu \
-      --iree-input-type=mhlo \
+      --iree-input-type=stablehlo \
       iree_input.mlir
     ```
diff --git a/docs/developers/developing_iree/benchmarking.md b/docs/developers/developing_iree/benchmarking.md
@@ -107,7 +107,7 @@ dispatch functions, generate an IREE module with the
 
 ```shell
 $ build/tools/iree-compile \
-  --iree-input-type=mhlo \
+  --iree-input-type=stablehlo \
   --iree-flow-export-benchmark-funcs \
   --iree-hal-target-backends=vmvx \
   tests/e2e/models/fullyconnected.mlir \

diff --git a/docs/developers/developing_iree/developer_overview.md b/docs/developers/developing_iree/developer_overview.md
@@ -144,7 +144,7 @@ runner for the IREE [check framework](./testing_guide.md#end-to-end-tests).
 
 ```shell
 $ ../iree-build/tools/iree-compile \
-  --iree-input-type=mhlo \
+  --iree-input-type=stablehlo \
   --iree-hal-target-backends=vmvx \
   $PWD/tests/e2e/xla_ops/abs.mlir \
   -o /tmp/abs.vmfb

diff --git a/docs/developers/developing_iree/profiling_vulkan_gpu.md b/docs/developers/developing_iree/profiling_vulkan_gpu.md
@@ -50,29 +50,29 @@ IREE core libraries together with a specific VM bytecode invocation into an
 Android app. The wrapper and its documentation are placed at
 [`tools/android/run_module_app/`](https://github.com/openxla/iree/tree/main/tools/android/run_module_app).
 
-For example, to package a module compiled from the following `mhlo-dot.mlir` as
+For example, to package a module compiled from the following `stablehlo-dot.mlir` as
 an Android app:
 
 ```mlir
 func @dot(%lhs: tensor<2x4xf32>, %rhs: tensor<4x2xf32>) -> tensor<2x2xf32> {
-  %0 = "mhlo.dot"(%lhs, %rhs) : (tensor<2x4xf32>, tensor<4x2xf32>) -> tensor<2x2xf32>
+  %0 = "stablehlo.dot"(%lhs, %rhs) : (tensor<2x4xf32>, tensor<4x2xf32>) -> tensor<2x2xf32>
   return %0 : tensor<2x2xf32>
 }
 ```
 
 ```shell
 # First compile into a VM bytecode module
 $ /path/to/iree/build/tools/iree-compile -- \
-  --iree-input-type=mhlo \
+  --iree-input-type=stablehlo \
   --iree-hal-target-backends=vulkan-spirv \
-  /path/to/mhlo-dot.mlir \
-  -o /tmp/mhlo-dot.vmfb
+  /path/to/stablehlo-dot.mlir \
+  -o /tmp/stablehlo-dot.vmfb
 
 # Then package the Android app
 $ /path/to/iree/source/tools/android/run_module_app/build_apk.sh \
   ./build-apk \
   --device vulkan \
-  --module /tmp/mhlo-dot.vmfb \
+  --module /tmp/stablehlo-dot.vmfb \
   --function dot \
   --input=...
 ```

diff --git a/docs/website/docs/deployment-configurations/cpu.md b/docs/website/docs/deployment-configurations/cpu.md
@@ -95,7 +95,7 @@ import tool):
 ``` shell hl_lines="2"
 iree-compile \
     --iree-hal-target-backends=llvm-cpu \
-    --iree-input-type=mhlo \
+    --iree-input-type=stablehlo \
     iree_input.mlir -o mobilenet_cpu.vmfb
 ```
 

diff --git a/docs/website/docs/deployment-configurations/gpu-cuda-rocm.md b/docs/website/docs/deployment-configurations/gpu-cuda-rocm.md
@@ -115,7 +115,7 @@ following command:
     iree-compile \
         --iree-hal-target-backends=cuda \
         --iree-hal-cuda-llvm-target-arch=<...> \
-        --iree-input-type=mhlo \
+        --iree-input-type=stablehlo \
         iree_input.mlir -o mobilenet-cuda.vmfb
     ```
 
@@ -141,7 +141,7 @@ following command:
         --iree-rocm-target-chip=<...> \
         --iree-rocm-link-bc=true \
         --iree-rocm-bc-dir=<...> \
-        --iree-input-type=mhlo \
+        --iree-input-type=stablehlo \
         iree_input.mlir -o mobilenet-rocm.vmfb
     ```
 

diff --git a/docs/website/docs/deployment-configurations/gpu-vulkan.md b/docs/website/docs/deployment-configurations/gpu-vulkan.md
@@ -152,7 +152,7 @@ import tool):
 iree-compile \
     --iree-hal-target-backends=vulkan-spirv \
     --iree-vulkan-target-triple=<...> \
-    --iree-input-type=mhlo \
+    --iree-input-type=stablehlo \
     iree_input.mlir -o mobilenet-vulkan.vmfb
 ```
 

diff --git a/experimental/web/sample_dynamic/build_sample.sh b/experimental/web/sample_dynamic/build_sample.sh
@@ -61,7 +61,7 @@ COMPILE_TOOL="${INSTALL_ROOT}/bin/iree-compile"
 compile_sample() {
   echo "  Compiling '$1' sample..."
   "${COMPILE_TOOL}" "$2" \
-    --iree-input-type=mhlo \
+    --iree-input-type=mhlo_legacy \
     --iree-hal-target-backends=llvm-cpu \
     --iree-llvmcpu-target-triple=wasm32-unknown-emscripten \
     --iree-llvmcpu-target-cpu-features=+atomics,+bulk-memory,+simd128 \

diff --git a/experimental/web/sample_static/build_sample.sh b/experimental/web/sample_static/build_sample.sh
@@ -63,7 +63,7 @@ INPUT_PATH="${ROOT_DIR}/samples/models/mnist.mlir"
 
 echo "=== Compiling MLIR to static library output (.vmfb, .h, .o) ==="
 "${COMPILE_TOOL}" "${INPUT_PATH}" \
-  --iree-input-type=mhlo \
+  --iree-input-type=mhlo_legacy \
   --iree-hal-target-backends=llvm-cpu \
   --iree-llvmcpu-target-triple=wasm32-unknown-unknown \
   --iree-llvmcpu-target-cpu-features=+simd128 \

diff --git a/runtime/src/iree/hal/local/executable_library_benchmark.md b/runtime/src/iree/hal/local/executable_library_benchmark.md
@@ -114,7 +114,7 @@ inspect the IR to find the proper way to call their kernels.
 
 ```
 iree-compile \
-    --iree-input-type=mhlo \
+    --iree-input-type=stablehlo \
     iree/samples/simple_embedding/simple_embedding_test.mlir \
     -o=module.vmfb \
     --iree-hal-target-backends=llvm-cpu \

diff --git a/samples/dynamic_shapes/README.md b/samples/dynamic_shapes/README.md
@@ -83,7 +83,7 @@ them.
     ```
     ../iree-build/tools/iree-compile \
         --iree-hal-target-backends=llvm-cpu \
-        --iree-input-type=mhlo \
+        --iree-input-type=mhlo_legacy \
         dynamic_shapes.mlir -o dynamic_shapes_cpu.vmfb
     ```
 

diff --git a/samples/dynamic_shapes/test.sh b/samples/dynamic_shapes/test.sh
@@ -28,7 +28,7 @@ cmake --build ${BUILD_DIR} --target iree-compile -- -k 0
 # 3. Compile `dynamic_shapes.mlir` using `iree-compile`.
 ${BUILD_DIR}/tools/iree-compile \
   --iree-hal-target-backends=llvm-cpu \
-  --iree-input-type=mhlo \
+  --iree-input-type=mhlo_legacy \
   ${ARTIFACTS_DIR}/dynamic_shapes.mlir -o ${ARTIFACTS_DIR}/dynamic_shapes_cpu.vmfb
 
 # 4. Build the `iree_samples_dynamic_shapes` CMake target.

diff --git a/samples/variables_and_state/README.md b/samples/variables_and_state/README.md
@@ -93,7 +93,7 @@ and compile the imported `counter.mlir` file using `iree-compile`:
 ```
 ../iree-build/tools/iree-compile \
     --iree-hal-target-backends=llvm-cpu \
-    --iree-input-type=mhlo \
+    --iree-input-type=stablehlo \
     counter.mlir -o counter_cpu.vmfb
 ```
 

diff --git a/samples/vision_inference/README.md b/samples/vision_inference/README.md
@@ -20,7 +20,7 @@ From this directory:
 # Compile the MNIST program.
 iree-compile \
     ../models/mnist.mlir \
-    --iree-input-type=mhlo \
+    --iree-input-type=mhlo_legacy \
     --iree-hal-target-backends=llvm-cpu \
     -o /tmp/mnist_cpu.vmfb
 

diff --git a/tests/e2e/models/BUILD.bazel b/tests/e2e/models/BUILD.bazel
@@ -54,7 +54,7 @@ iree_lit_test_suite(
 iree_check_single_backend_test_suite(
     name = "check_llvm-cpu_local-task",
     srcs = CHECK_FRAMEWORK_TESTS,
-    compiler_flags = ["--iree-input-type=mhlo"],
+    compiler_flags = ["--iree-input-type=mhlo_legacy"],
     driver = "local-task",
     target_backend = "llvm-cpu",
 )
@@ -71,7 +71,7 @@ iree_check_single_backend_test_suite(
     name = "check_vulkan-spirv_vulkan",
     timeout = "long",
     srcs = CHECK_FRAMEWORK_TESTS,
-    compiler_flags = ["--iree-input-type=mhlo"],
+    compiler_flags = ["--iree-input-type=mhlo_legacy"],
     driver = "vulkan",
     target_backend = "vulkan-spirv",
 )
@@ -80,7 +80,7 @@ iree_check_single_backend_test_suite(
     name = "check_cuda_cuda",
     timeout = "long",
     srcs = CHECK_FRAMEWORK_TESTS,
-    compiler_flags = ["--iree-input-type=mhlo"],
+    compiler_flags = ["--iree-input-type=mhlo_legacy"],
     driver = "cuda",
     tags = [
         # CUDA cuInit fails with sanitizer on.