[llvm-branch-commits] [mlir] [mlir][Interfaces][NFC] Document that `RegionBranchTerminatorOpInterface` is mandatory (PR #174978)

[Matthias Springer via llvm-branch-commits]

https://github.com/matthias-springer created https://github.com/llvm/llvm-project/pull/174978

Document that implementing the `RegionBranchTerminatorOpInterface` is mandatory. Omitting this interface on a block terminator that models region branching may lead to invalid/incomplete analyses and transformations.

This commit does not change the op/interface semantics. It just puts in writing an assumption that is made throughout the code base. For example:

- It is baked into the API design of the `RegionBranchOpInterface`. You cannot query the region successors of block terminators that do not implement the `RegionBranchTerminatorOpInterface`: `RegionBranchOpInterface::getSuccessors()` takes a `RegionBranchPoint` parameter, and such region branch points can be constructed only from `RegionBranchTerminatorOpInterface` and not arbitrary `Operation *`.
- Helper functions + default interface method implementations enumerate region branch points by looking for `RegionBranchTerminatorOpInterface` and ignoring other operations. E.g., `RegionBranchOpInterface::getAllRegionBranchPoints`, default implementation of `RegionBranchOpInterface::getSuccessorRegions(Region &)`, default implementation of `RegionBranchOpInterface::getPredecessorValues`.
- Core analyses such as `DeadCodeAnalysis` look for `RegionBranchTerminatorOpInterface` and misbehave when the interface is not implemented. The analysis does not (and cannot) query region successors of a region branching terminator that does not implement the `RegionBranchTerminatorOpInterface`. In practice, this means that forgetting to implement the `RegionBranchTerminatorOpInterface` may incorrectly classify regions as dead.
- Other analyses / transformations that look for and depend on the implementation of `RegionBranchTerminatorOpInterface`: `mlir::getControlFlowPredecessors`, `AbstractDenseBackwardDataFlowAnalysis`, ownership-based buffer deallocation pass.


>From ff3af1d7cf29ba23b04721a471175f884c5f3fa9 Mon Sep 17 00:00:00 2001
From: Matthias Springer <me at m-sp.org>
Date: Thu, 8 Jan 2026 12:58:02 +0000
Subject: [PATCH] [mlir][Interfaces] Document that
 `RegionBranchTerminatorOpInterface` is mandatory

---
 .../mlir/Interfaces/ControlFlowInterfaces.td      | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td b/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
index ff99e220c179f..74c7841d52b3f 100644
--- a/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
+++ b/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
@@ -127,7 +127,8 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
 
     A "region branch point" indicates a point from which a branch originates. It
     can indicate:
-    1. A terminator in any of the immediately nested region of this op.
+    1. A `RegionBranchTerminatorOpInterface` terminator in any of the
+       immediately nested region of this op.
     2. `RegionBranchPoint::parent()`: the branch originates from outside of the
        op, i.e., when first executing this op.
 
@@ -147,6 +148,15 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
     results must have the same type. `areTypesCompatible` can be implemented to
     allow non-equal types.
 
+    Note: This interface works in conjunction with
+    `RegionBranchTerminatorOpInterface`. All immediately nested block
+    terminators that model branching between regions must implement the
+    `RegionBranchTerminatorOpInterface`. Otherwise, analyses/transformations
+    may miss control flow edges and produce incorrect results. Not every block
+    terminator is necessarily a region branch terminator: e.g., in the presence
+    of unstructured control flow, a block terminator could indicate a branch to
+    a different block within the same region.
+
     Example:
 
     ```
@@ -379,7 +389,8 @@ def RegionBranchTerminatorOpInterface :
   let description = [{
     This interface provides information for branching terminator operations
     in the presence of a parent `RegionBranchOpInterface` implementation. It
-    specifies which operands are passed to which region successor.
+    acts as a marker for valid region branch points and specifies which
+    operands are passed to which region successor.
   }];
   let cppNamespace = "::mlir";