[Branch Hinting] Add useful passes to generate and log branch hints (#7695)

--instrument-branch-hints adds logging on every branch hint, which at
runtime reports a unique ID, the branch hint prediction, and whether the
branch was taken at runtime. This can be used to verify that branch
hints are actually valid in practice.

Also add --randomize-branch-hints, which just adds random hints in code,
basically sets things up for fuzzing. Of course, branch hints may be inaccurate
50% of the time, but we can still fuzz and see if the inaccuracy was preserved.

Author: kripken

scripts/test/fuzzing.py

@@ -133,6 +133,8 @@
     'string-lifting-section.wast',
     # TODO: fuzzer support for uninhabitable imported globals
     'exact-references.wast',
+    # We do not have full suppor for these imports in all parts of the fuzzer.
+    'instrument-branch-hints.wast',
 ]
 
 

src/passes/CMakeLists.txt

@@ -52,6 +52,7 @@ set(passes_SOURCES
   HeapStoreOptimization.cpp
   I64ToI32Lowering.cpp
   Inlining.cpp
+  InstrumentBranchHints.cpp
   InstrumentLocals.cpp
   InstrumentMemory.cpp
   Intrinsics.cpp
@@ -102,6 +103,7 @@ set(passes_SOURCES
   Strip.cpp
   StripTargetFeatures.cpp
   TraceCalls.cpp
+  RandomizeBranchHints.cpp
   RedundantSetElimination.cpp
   RemoveImports.cpp
   RemoveMemoryInit.cpp

src/passes/InstrumentBranchHints.cpp

@@ -0,0 +1,162 @@
+/*
+ * Copyright 2025 WebAssembly Community Group participants
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+//
+// Instruments branch hints and their targets, adding logging that allows us to
+// see if the hints were valid or not. We turn
+//
+//  @metadata.branch.hint B
+//  if (condition) {
+//    X
+//  } else {
+//    Y
+//  }
+//
+// into
+//
+//  @metadata.branch.hint B
+//  ;; log the ID of the condition (123), the prediction (B), and the actual
+//  ;; runtime result (temp == condition).
+//  if (temp = condition; log(123, B, temp); temp) {
+//    X
+//  } else {
+//    Y
+//  }
+//
+// Concretely, we emit calls to this logging function:
+//
+//  (import "fuzzing-support" "log-branch"
+//    (func $log-branch (param i32 i32 i32)) ;; ID, prediction, actual
+//  )
+//
+// This can be used to verify that branch hints are accurate, by implementing
+// the import like this for example:
+//
+//  imports['fuzzing-support']['log-branch'] = (id, prediction, actual) => {
+//    // We only care about truthiness of the expected and actual values.
+//    expected = +!!expected;
+//    actual = +!!actual;
+//    // Throw if the hint said this branch would be taken, but it was not, or
+//    // vice versa.
+//    if (expected != actual) throw `Bad branch hint! (${id})`;
+//  };
+//
+
+#include "ir/eh-utils.h"
+#include "ir/names.h"
+#include "ir/properties.h"
+#include "pass.h"
+#include "wasm-builder.h"
+#include "wasm.h"
+
+namespace wasm {
+
+namespace {
+
+// The branch id, which increments as we go.
+int branchId = 1;
+
+struct InstrumentBranchHints
+  : public WalkerPass<PostWalker<InstrumentBranchHints>> {
+
+  using Super = WalkerPass<PostWalker<InstrumentBranchHints>>;
+
+  // The module and base names of our import.
+  const Name MODULE = "fuzzing-support";
+  const Name BASE = "log-branch";
+
+  // The internal name of our import.
+  Name logBranch;
+
+  void visitIf(If* curr) { processCondition(curr); }
+
+  void visitBreak(Break* curr) {
+    if (curr->condition) {
+      processCondition(curr);
+    }
+  }
+
+  // TODO: BrOn, but the condition there is not an i32
+
+  bool addedInstrumentation = false;
+
+  template<typename T> void processCondition(T* curr) {
+    if (curr->condition->type == Type::unreachable) {
+      // This branch is not even reached.
+      return;
+    }
+
+    auto likely = getFunction()->codeAnnotations[curr].branchLikely;
+    if (!likely) {
+      return;
+    }
+
+    Builder builder(*getModule());
+
+    // Pick an ID for this branch.
+    int id = branchId++;
+
+    // Instrument the condition.
+    auto tempLocal = builder.addVar(getFunction(), Type::i32);
+    auto* set = builder.makeLocalSet(tempLocal, curr->condition);
+    auto* idConst = builder.makeConst(Literal(int32_t(id)));
+    auto* guess = builder.makeConst(Literal(int32_t(*likely)));
+    auto* get1 = builder.makeLocalGet(tempLocal, Type::i32);
+    auto* log = builder.makeCall(logBranch, {idConst, guess, get1}, Type::none);
+    auto* get2 = builder.makeLocalGet(tempLocal, Type::i32);
+    curr->condition = builder.makeBlock({set, log, get2});
+    addedInstrumentation = true;
+  }
+
+  void doWalkFunction(Function* func) {
+    Super::doWalkFunction(func);
+
+    // Our added blocks may have caused nested pops.
+    if (addedInstrumentation) {
+      EHUtils::handleBlockNestedPops(func, *getModule());
+      addedInstrumentation = false;
+    }
+  }
+
+  void doWalkModule(Module* module) {
+    // Find our import, if we were already run on this module.
+    for (auto& func : module->functions) {
+      if (func->module == MODULE && func->base == BASE) {
+        logBranch = func->name;
+        break;
+      }
+    }
+    // Otherwise, add it.
+    if (!logBranch) {
+      auto* func = module->addFunction(Builder::makeFunction(
+        Names::getValidFunctionName(*module, BASE),
+        Signature({Type::i32, Type::i32, Type::i32}, Type::none),
+        {}));
+      func->module = MODULE;
+      func->base = BASE;
+      logBranch = func->name;
+    }
+
+    // Walk normally, using logBranch as we go.
+    Super::doWalkModule(module);
+  }
+};
+
+} // anonymous namespace
+
+Pass* createInstrumentBranchHintsPass() { return new InstrumentBranchHints(); }
+
+} // namespace wasm

src/passes/RandomizeBranchHints.cpp

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2025 WebAssembly Community Group participants
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+//
+// Apply random branch hints. This is really only useful for fuzzing. The
+// randomness here is deterministic, so that reducing can work.
+//
+
+#include "pass.h"
+#include "support/hash.h"
+#include "wasm-builder.h"
+#include "wasm.h"
+
+namespace wasm {
+
+struct RandomizeBranchHints
+  : public WalkerPass<
+      PostWalker<RandomizeBranchHints,
+                 UnifiedExpressionVisitor<RandomizeBranchHints>>> {
+
+  uint64_t hash = 42;
+
+  void visitExpression(Expression* curr) {
+    // Add some deterministic randomness as we go.
+    deterministic_hash_combine(hash, curr->_id);
+  }
+
+  void visitIf(If* curr) {
+    deterministic_hash_combine(hash, 1337);
+    processCondition(curr);
+  }
+
+  void visitBreak(Break* curr) {
+    deterministic_hash_combine(hash, 99999);
+    if (curr->condition) {
+      processCondition(curr);
+    }
+  }
+
+  template<typename T> void processCondition(T* curr) {
+    auto& likely = getFunction()->codeAnnotations[curr].branchLikely;
+    switch (hash % 3) {
+      case 0:
+        likely = true;
+        break;
+      case 1:
+        likely = false;
+        break;
+      case 2:
+        likely = {};
+        break;
+    }
+  }
+};
+
+Pass* createRandomizeBranchHintsPass() { return new RandomizeBranchHints(); }
+
+} // namespace wasm

src/passes/pass.cpp

@@ -259,6 +259,9 @@ void PassRegistry::registerPasses() {
     "trace-calls",
     "instrument the build with code to intercept specific function calls",
     createTraceCallsPass);
+  registerPass("instrument-branch-hints",
+               "instrument branch hints so we can see which guessed right",
+               createInstrumentBranchHintsPass);
   registerPass(
     "instrument-locals",
     "instrument the build with code to intercept all loads and stores",
@@ -409,6 +412,9 @@ void PassRegistry::registerPasses() {
   registerPass("propagate-globals-globally",
                "propagate global values to other globals (useful for tests)",
                createPropagateGlobalsGloballyPass);
+  registerTestPass("randomize-branch-hints",
+                   "randomize branch hints (for fuzzing)",
+                   createRandomizeBranchHintsPass);
   registerPass("remove-non-js-ops",
                "removes operations incompatible with js",
                createRemoveNonJSOpsPass);

src/passes/passes.h

@@ -79,6 +79,7 @@ Pass* createLocalSubtypingPass();
 Pass* createLogExecutionPass();
 Pass* createIntrinsicLoweringPass();
 Pass* createTraceCallsPass();
+Pass* createInstrumentBranchHintsPass();
 Pass* createInstrumentLocalsPass();
 Pass* createInstrumentMemoryPass();
 Pass* createLLVMMemoryCopyFillLoweringPass();
@@ -130,6 +131,7 @@ Pass* createPrintCallGraphPass();
 Pass* createPrintFeaturesPass();
 Pass* createPrintFunctionMapPass();
 Pass* createPropagateGlobalsGloballyPass();
+Pass* createRandomizeBranchHintsPass();
 Pass* createRemoveNonJSOpsPass();
 Pass* createRemoveImportsPass();
 Pass* createRemoveMemoryInitPass();

test/lit/help/wasm-metadce.test

@@ -208,6 +208,9 @@
 ;; CHECK-NEXT:   --inlining-optimizing                         inline functions and optimizes
 ;; CHECK-NEXT:                                                 where we inlined
 ;; CHECK-NEXT:
+;; CHECK-NEXT:   --instrument-branch-hints                     instrument branch hints so we
+;; CHECK-NEXT:                                                 can see which guessed right
+;; CHECK-NEXT:
 ;; CHECK-NEXT:   --instrument-locals                           instrument the build with code
 ;; CHECK-NEXT:                                                 to intercept all loads and
 ;; CHECK-NEXT:                                                 stores

test/lit/help/wasm-opt.test

@@ -232,6 +232,9 @@
 ;; CHECK-NEXT:   --inlining-optimizing                         inline functions and optimizes
 ;; CHECK-NEXT:                                                 where we inlined
 ;; CHECK-NEXT:
+;; CHECK-NEXT:   --instrument-branch-hints                     instrument branch hints so we
+;; CHECK-NEXT:                                                 can see which guessed right
+;; CHECK-NEXT:
 ;; CHECK-NEXT:   --instrument-locals                           instrument the build with code
 ;; CHECK-NEXT:                                                 to intercept all loads and
 ;; CHECK-NEXT:                                                 stores

test/lit/help/wasm2js.test

@@ -172,6 +172,9 @@
 ;; CHECK-NEXT:   --inlining-optimizing                         inline functions and optimizes
 ;; CHECK-NEXT:                                                 where we inlined
 ;; CHECK-NEXT:
+;; CHECK-NEXT:   --instrument-branch-hints                     instrument branch hints so we
+;; CHECK-NEXT:                                                 can see which guessed right
+;; CHECK-NEXT:
 ;; CHECK-NEXT:   --instrument-locals                           instrument the build with code
 ;; CHECK-NEXT:                                                 to intercept all loads and
 ;; CHECK-NEXT:                                                 stores