[EH] Rename option/pass names for new EH (exnref) (WebAssembly#6592)

We settled on the name `WASM_EXNREF` for the new setting in Emscripten
for the name for the new EH option.
https://github.com/emscripten-core/emscripten/blob/2bc5e3156f07e603bc4f3580cf84c038ea99b2df/src/settings.js#L782-L786
"New EH" sounds vague and I'm not sure if "experimental" is really
necessary anyway, given that the potential users of this option is aware
that this is a new spec that has been adopted recently.

To make the option names consistent, this renames `--translate-to-eh`
(the option that only runs the translator) to `--translate-to-exnref`,
and `--experimental-new-eh` to `--emit-exnref` (the option that runs the
translator at the end of the whole pipeline), and renames the pass and
variable names in the code accordingly as well.

In case anyone is using the old option names (and also to make the
Chromium CI pass), this does not delete the old options.

src/passes/TranslateEH.cpp

@@ -15,7 +15,7 @@
  */
 
 //
-// TranslateToNewEH translates the old Phase 3 EH instructions, which include
+// TranslateToExnref translates the old Phase 3 EH instructions, which include
 // try, catch, catch_all, delegate, and rethrow, into the new EH instructions,
 // which include try_table (with catch / catch_ref / catch_all / catch_all_ref)
 // and throw_ref, passed at the Oct 2023 CG meeting. This translator can be used
@@ -39,7 +39,7 @@ namespace {
 // Translates the old EH instructions (try / catch / catch_all / delegate /
 // rethrow) into the new ones (try_table (+ catch / catch_ref / catch_all /
 // catch_all_ref) / throw_ref).
-struct TranslateToNewEH : public WalkerPass<PostWalker<TranslateToNewEH>> {
+struct TranslateToExnref : public WalkerPass<PostWalker<TranslateToExnref>> {
   bool isFunctionParallel() override { return true; }
 
   // Scans and records which try labels are targeted by delegates and rethrows.
@@ -195,7 +195,7 @@ struct TranslateToNewEH : public WalkerPass<PostWalker<TranslateToNewEH>> {
   std::unordered_map<Type, Index> typeToScratchLocal;
 
   std::unique_ptr<Pass> create() override {
-    return std::make_unique<TranslateToNewEH>();
+    return std::make_unique<TranslateToExnref>();
   }
 
   // Get a scratch local for a given type. These locals are used to contain
@@ -814,6 +814,6 @@ struct TranslateToNewEH : public WalkerPass<PostWalker<TranslateToNewEH>> {
 
 } // namespace
 
-Pass* createTranslateToNewEHPass() { return new TranslateToNewEH(); }
+Pass* createTranslateToExnrefPass() { return new TranslateToExnref(); }
 
 } // namespace wasm

src/passes/pass.cpp

@@ -501,8 +501,11 @@ void PassRegistry::registerPasses() {
                "strip the wasm target features section",
                createStripTargetFeaturesPass);
   registerPass("translate-to-new-eh",
-               "translate old EH instructions to new ones",
-               createTranslateToNewEHPass);
+               "deprecated; same as translate-to-exnref",
+               createTranslateToExnrefPass);
+  registerPass("translate-to-exnref",
+               "translate old Phase 3 EH instructions to new ones with exnref",
+               createTranslateToExnrefPass);
   registerPass("trap-mode-clamp",
                "replace trapping operations with clamping semantics",
                createTrapModeClamp);

src/passes/passes.h

@@ -166,7 +166,7 @@ Pass* createStripEHPass();
 Pass* createStubUnsupportedJSOpsPass();
 Pass* createSSAifyPass();
 Pass* createSSAifyNoMergePass();
-Pass* createTranslateToNewEHPass();
+Pass* createTranslateToExnrefPass();
 Pass* createTrapModeClamp();
 Pass* createTrapModeJS();
 Pass* createTupleOptimizationPass();

src/tools/wasm-opt.cpp

@@ -91,7 +91,7 @@ int main(int argc, const char* argv[]) {
   std::string inputSourceMapFilename;
   std::string outputSourceMapFilename;
   std::string outputSourceMapUrl;
-  bool experimentalNewEH = false;
+  bool emitExnref = false;
 
   const std::string WasmOptOption = "wasm-opt options";
 
@@ -240,16 +240,20 @@ int main(int argc, const char* argv[]) {
                       o->extra["infile"] = argument;
                     })
     .add("--experimental-new-eh",
+         "",
+         "Deprecated; same as --emit-exnref",
+         WasmOptOption,
+         Options::Arguments::Zero,
+         [&emitExnref](Options*, const std::string&) { emitExnref = true; })
+    .add("--emit-exnref",
          "",
          "After running all requested transformations / optimizations, "
          "translate the instruction to use the new EH instructions at the end. "
          "Depending on the optimization level specified, this may do some more "
          "post-translation optimizations.",
          WasmOptOption,
          Options::Arguments::Zero,
-         [&experimentalNewEH](Options*, const std::string&) {
-           experimentalNewEH = true;
-         });
+         [&emitExnref](Options*, const std::string&) { emitExnref = true; });
   options.parse(argc, argv);
 
   Module wasm;
@@ -356,11 +360,10 @@ int main(int argc, const char* argv[]) {
     std::cout << "[extra-fuzz-command first output:]\n" << firstOutput << '\n';
   }
 
-  bool translateToNewEH =
-    wasm.features.hasExceptionHandling() && experimentalNewEH;
+  bool translateToExnref = wasm.features.hasExceptionHandling() && emitExnref;
 
   if (!options.runningPasses()) {
-    if (!options.quiet && !translateToNewEH) {
+    if (!options.quiet && !translateToExnref) {
       std::cerr << "warning: no passes specified, not doing any work\n";
     }
   } else {
@@ -397,12 +400,10 @@ int main(int argc, const char* argv[]) {
     }
   }
 
-  if (translateToNewEH) {
+  if (translateToExnref) {
     BYN_TRACE("translating to new EH instructions...\n");
     PassRunner runner(&wasm, options.passOptions);
-    runner.add("translate-to-new-eh");
-    // Perform Stack IR optimizations here, at the very end of the
-    // optimization pipeline.
+    runner.add("translate-to-exnref");
     runner.run();
     if (options.passOptions.validate) {
       bool valid = WasmValidator().validate(wasm, options.passOptions);

test/lit/help/wasm-opt.test

@@ -79,7 +79,10 @@
 ;; CHECK-NEXT:   --new-wat-parser                              Use the experimental new WAT
 ;; CHECK-NEXT:                                                 parser
 ;; CHECK-NEXT:
-;; CHECK-NEXT:   --experimental-new-eh                         After running all requested
+;; CHECK-NEXT:   --experimental-new-eh                         Deprecated; same as
+;; CHECK-NEXT:                                                 --emit-exnref
+;; CHECK-NEXT:
+;; CHECK-NEXT:   --emit-exnref                                 After running all requested
 ;; CHECK-NEXT:                                                 transformations / optimizations,
 ;; CHECK-NEXT:                                                 translate the instruction to use
 ;; CHECK-NEXT:                                                 the new EH instructions at the
@@ -502,8 +505,12 @@
 ;; CHECK-NEXT:
 ;; CHECK-NEXT:   --symbolmap                                   (alias for print-function-map)
 ;; CHECK-NEXT:
-;; CHECK-NEXT:   --translate-to-new-eh                         translate old EH instructions to
-;; CHECK-NEXT:                                                 new ones
+;; CHECK-NEXT:   --translate-to-exnref                         translate old Phase 3 EH
+;; CHECK-NEXT:                                                 instructions to new ones with
+;; CHECK-NEXT:                                                 exnref
+;; CHECK-NEXT:
+;; CHECK-NEXT:   --translate-to-new-eh                         deprecated; same as
+;; CHECK-NEXT:                                                 translate-to-exnref
 ;; CHECK-NEXT:
 ;; CHECK-NEXT:   --trap-mode-clamp                             replace trapping operations with
 ;; CHECK-NEXT:                                                 clamping semantics

test/lit/help/wasm2js.test

@@ -452,8 +452,12 @@
 ;; CHECK-NEXT:
 ;; CHECK-NEXT:   --symbolmap                                   (alias for print-function-map)
 ;; CHECK-NEXT:
-;; CHECK-NEXT:   --translate-to-new-eh                         translate old EH instructions to
-;; CHECK-NEXT:                                                 new ones
+;; CHECK-NEXT:   --translate-to-exnref                         translate old Phase 3 EH
+;; CHECK-NEXT:                                                 instructions to new ones with
+;; CHECK-NEXT:                                                 exnref
+;; CHECK-NEXT:
+;; CHECK-NEXT:   --translate-to-new-eh                         deprecated; same as
+;; CHECK-NEXT:                                                 translate-to-exnref
 ;; CHECK-NEXT:
 ;; CHECK-NEXT:   --trap-mode-clamp                             replace trapping operations with
 ;; CHECK-NEXT:                                                 clamping semantics

test/lit/passes/emit-exnref.wast

@@ -0,0 +1,28 @@
+;; When given alone, --emit-exnref just runs --translate-to-exnref
+;; RUN: wasm-opt %s -all --translate-to-exnref -S -o %t1.wasm
+;; RUN: wasm-opt %s -all --emit-exnref -S -o %t2.wasm
+;; RUN: diff %t1.wasm %t2.wasm
+
+;; When given with other flags, --emit-exnref runs the translator after running
+;; other passes. If --optimize-level >=3, --experimenal-new-eh also runs StackIR
+;; (+ local2stack) optimization. So running '-O --emit-exnref' should be the
+;; same as running all these passes separately.
+;; RUN: wasm-opt %s -all -O --translate-to-exnref --optimize-level=3 --generate-stack-ir --optimize-stack-ir -o %t1.wasm
+;; RUN: wasm-opt %s -all -O --emit-exnref -o %t2.wasm
+;; RUN: diff %t1.wasm %t2.wasm
+
+(module
+  (import "env" "foo" (func $foo))
+  (start $test)
+  (func $test
+    (try $l
+      (do
+        (call $foo)
+      )
+      (catch_all
+        (call $foo)
+        (rethrow $l)
+      )
+    )
+  )
+)

test/lit/passes/translate-to-new-eh.wast → test/lit/passes/translate-to-exnref.wast

@@ -1,6 +1,6 @@
 ;; NOTE: Assertions have been generated by update_lit_checks.py --all-items and should not be edited.
-;; RUN: wasm-opt %s -all --translate-to-new-eh -S -o - | filecheck %s
-;; RUN: wasm-opt %s -all --translate-to-new-eh -S -o %t
+;; RUN: wasm-opt %s -all --translate-to-exnref -S -o - | filecheck %s
+;; RUN: wasm-opt %s -all --translate-to-exnref -S -o %t
 ;; RUN: wasm-opt %t -all --optimize-level=3 --generate-stack-ir --optimize-stack-ir --print-stack-ir | filecheck %s --check-prefix STACKIR-OPT
 
 (module