[Mlir-commits] [mlir] [mlir][Interfaces] Document completeness requirement of `RegionBranchOpInterface` (PR #202018)
Matthias Springer
llvmlistbot at llvm.org
Tue Jun 9 02:04:13 PDT 2026
https://github.com/matthias-springer updated https://github.com/llvm/llvm-project/pull/202018
>From d81a62a8b9ca61b9593288d8b01230f355cc3235 Mon Sep 17 00:00:00 2001
From: Matthias Springer <me at m-sp.org>
Date: Sat, 6 Jun 2026 09:04:49 +0000
Subject: [PATCH 1/2] [mlir][Interfaces] Document completeness requirement of
`RegionBranchOpInterface`
---
.../mlir/Interfaces/ControlFlowInterfaces.td | 16 ++++++++++++----
1 file changed, 12 insertions(+), 4 deletions(-)
diff --git a/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td b/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
index 06fa724e05fab..3de8de9b5c760 100644
--- a/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
+++ b/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
@@ -118,15 +118,23 @@ def BranchOpInterface : OpInterface<"BranchOpInterface"> {
def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
let description = [{
This interface provides information for region-holding operations that
- exhibit branching behavior between held regions. I.e., this interface allows
- for expressing control flow information for region holding operations.
+ exhibit branching behavior between held regions. It models the control flow
+ edges between regions (and between the op and its regions), as well as the
+ data flow (value propagation) that occurs along those control flow edges.
This interface is meant to model well-defined cases of control-flow and
value propagation, where what occurs along control-flow edges is assumed to
be side-effect free.
- A "region branch point" indicates a point from which a branch originates. It
- can indicate:
+ Completeness is a core contract of this interface: the implementation must
+ model all possible control flow edges, so that callers can rely on the
+ returned information as a complete picture. Failing to report a possible
+ edge is an incorrect implementation and may cause analyses/transformations
+ to produce incorrect results. (It is acceptable to over-approximate by
+ reporting edges that turn out to be infeasible at runtime.)
+
+ A "region branch point" indicates the point from which a branch (edge)
+ originates. It can indicate:
1. A `RegionBranchTerminatorOpInterface` terminator in any of the
immediately nested regions of this op.
2. `RegionBranchPoint::parent()`: the branch originates from outside of the
>From 544af82396645e65d77d6765ccacfc05874f307e Mon Sep 17 00:00:00 2001
From: Matthias Springer <me at m-sp.org>
Date: Tue, 9 Jun 2026 09:03:40 +0000
Subject: [PATCH 2/2] address comments
---
.../mlir/Interfaces/ControlFlowInterfaces.td | 44 ++++++++++++++++---
1 file changed, 37 insertions(+), 7 deletions(-)
diff --git a/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td b/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
index 3de8de9b5c760..bf27521301313 100644
--- a/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
+++ b/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
@@ -126,13 +126,6 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
value propagation, where what occurs along control-flow edges is assumed to
be side-effect free.
- Completeness is a core contract of this interface: the implementation must
- model all possible control flow edges, so that callers can rely on the
- returned information as a complete picture. Failing to report a possible
- edge is an incorrect implementation and may cause analyses/transformations
- to produce incorrect results. (It is acceptable to over-approximate by
- reporting edges that turn out to be infeasible at runtime.)
-
A "region branch point" indicates the point from which a branch (edge)
originates. It can indicate:
1. A `RegionBranchTerminatorOpInterface` terminator in any of the
@@ -218,6 +211,14 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
Note: The control flow does not necessarily have to enter any region of
this op.
+ The returned successors must be complete with respect to the constant
+ operand information in `operands`: every region successor that could be
+ taken on entry must be included unless it is ruled out by an entry in
+ `operands`. Omitting a successor that is possible is an incorrect
+ implementation and may cause analyses/transformations to produce
+ incorrect results. It is acceptable to over-approximate by reporting
+ successors that turn out to be infeasible at runtime.
+
Example: In the above example, this method may return two region
region successors: the single region of the `scf.for` op and the
`scf.for` operation (that implements this interface). If %lb, %ub, %step
@@ -242,6 +243,13 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
returns the successor regions when branching from the region indicated
by `point`.
+ The returned successors must include every region successor that
+ control flow could reach from `point`. Omitting a successor that is
+ possible from `point` is an incorrect implementation and may cause
+ analyses/transformations to produce incorrect results. It is acceptable
+ to over-approximate by reporting successors that turn out to be
+ infeasible at runtime.
+
Example: In the above example, this method returns the region of the
`scf.for` and `parent` for either region branch point. An implementation
may choose to filter out region successors when it is statically known
@@ -255,6 +263,13 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
InterfaceMethod<[{
Returns the potential region successors when branching from any
terminator in `region`.
+
+ The returned successors must include every region successor that any
+ `RegionBranchTerminatorOpInterface` terminator in `region` could
+ branch to. Omitting a successor reachable from any such terminator is
+ an incorrect implementation and may cause analyses/transformations to
+ produce incorrect results. It is acceptable to over-approximate by
+ reporting successors that turn out to be infeasible at runtime.
}],
"void", "getSuccessorRegions",
(ins "::mlir::Region&":$region,
@@ -286,6 +301,13 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
InterfaceMethod<[{
Returns the potential branching points (predecessors) for a given
region successor.
+
+ The returned predecessors must include every `RegionBranchPoint` from
+ which control flow could reach `successor`. Omitting a possible
+ predecessor is an incorrect implementation and may cause
+ analyses/transformations to produce incorrect results. It is acceptable
+ to over-approximate by reporting predecessors that turn out to be
+ infeasible at runtime.
}],
"void", "getPredecessors",
(ins "::mlir::RegionSuccessor":$successor,
@@ -456,6 +478,14 @@ def RegionBranchTerminatorOpInterface :
The default implementation simply dispatches to the parent
`RegionBranchOpInterface`'s `getSuccessorRegions` implementation.
+
+ The returned successors must be complete with respect to the constant
+ operand information in `operands`: every region successor that this
+ terminator could branch to must be included unless it is ruled out by
+ an entry in `operands`. Omitting a successor that is possible is an
+ incorrect implementation and may cause analyses/transformations to
+ produce incorrect results. It is acceptable to over-approximate by
+ reporting successors that turn out to be infeasible at runtime.
}],
"void", "getSuccessorRegions",
(ins "::llvm::ArrayRef<::mlir::Attribute>":$operands,
More information about the Mlir-commits
mailing list