[MLIR][OpenMP] Document entry block argument-defining clauses (NFC)

[skatrak]

This patch adds general information on the proposed approach to unify the handling and representation of clauses that define entry block arguments attached to operations that accept them.

[llvmbot]

@llvm/pr-subscribers-mlir-openmp

@llvm/pr-subscribers-mlir

Author: Sergio Afonso (skatrak)

Changes

This patch adds general information on the proposed approach to unify the handling and representation of clauses that define entry block arguments attached to operations that accept them.

---

Full diff: https://github.com/llvm/llvm-project/pull/109811.diff

1 Files Affected:

• (modified) mlir/docs/Dialects/OpenMPDialect/_index.md (+69-1)

diff --git a/mlir/docs/Dialects/OpenMPDialect/_index.md b/mlir/docs/Dialects/OpenMPDialect/_index.md
index 88437b8cf828cc..3c30b29d09356b 100644
--- a/mlir/docs/Dialects/OpenMPDialect/_index.md
+++ b/mlir/docs/Dialects/OpenMPDialect/_index.md
@@ -285,7 +285,75 @@ argument's type:
   specific `mlir::Attribute` subclass) will be used instead.
   - Other attribute types will be represented with their `storageType`.
 - It will create `<Name>Operands` structure for each operation, which is an
-empty structure subclassing all operand structures defined for the corresponding `OpenMP_Op`'s clauses.
+empty structure subclassing all operand structures defined for the corresponding
+`OpenMP_Op`'s clauses.
+
+### Entry Block Argument-Defining Clauses
+
+Certain OpenMP clauses introduce in their MLIR representation mappings between
+outside values and entry block arguments for the region of the MLIR operation
+they are applied to. This enables, for example, the introduction of private
+copies of the same underlying variable. Currently, clauses with this property
+can be classified in three main categories:
+  - Map-like clauses: `map`, `use_device_addr` and `use_device_ptr`.
+  - Reduction-like clauses: `in_reduction`, `reduction` and `task_reduction`.
+  - Privatization clause: `private`.
+
+All three kinds of entry block argument-defining clauses use a similar custom
+assembly format representation, only differing based on the different pieces of
+information attached to each kind. Below, one example of each is shown:
+
+```mlir
+omp.target map_entries(%x -> %x.m, %y -> %y.m : !llvm.ptr, !llvm.ptr) {
+  // Use %x.m, %y.m in place of %x and %y...
+}
+
+omp.wsloop reduction(@add.i32 %x -> %x.r, byref @add.f32 %y -> %y.r : !llvm.ptr, !llvm.ptr) {
+  // Use %x.r, %y.r in place of %x and %y...
+}
+
+omp.parallel private(@x.privatizer %x -> %x.p, @y.privatizer %y -> %y.p : !llvm.ptr, !llvm.ptr) {
+  // Use %x.p, %y.p in place of %x and %y...
+}
+```
+
+As a consequence of parsing and printing the operation's first region entry
+block argument names together with the custom assembly format of these clauses,
+entry block arguments (i.e. the `^bb0(...):` line) must not be explicitly
+defined for these operations. Additionally, it is not possible to implement this
+feature while allowing each clause to be independently parsed and printed,
+because they need to be printed/parsed together with the corresponding
+operation's first region. They must have a well-defined ordering in which
+multiple of these clauses are specified for a given operation, as well.
+
+The parsing/printing of these clauses together with the region provides the
+ability to define entry block arguments directly after the `->`. Forcing a
+specific ordering between these clauses makes the block argument ordering
+well-defined, which is the property used to easily match each clause with the
+entry block arguments defined by it.
+
+Custom printers and parsers for operation regions based on the entry block
+argument-defining clauses they take are implemented based on the
+`{parse,print}BlockArgRegion` functions, which take care of the sorting and
+formatting of each kind of clause, minimizing code duplication resulting from
+this approach. One example of the custom assembly format of an operation taking
+the `private` and `reduction` clauses is the following:
+
+```tablegen
+let assemblyFormat = clausesAssemblyFormat # [{
+  custom<PrivateReductionRegion>($region, $private_vars, type($private_vars),
+      $private_syms, $reduction_vars, type($reduction_vars), $reduction_byref,
+      $reduction_syms) attr-dict
+}];
+```
+
+The `BlockArgOpenMPOpInterface` has been introduced to simplify the addition and
+handling of these kinds of clauses. It holds `num<ClauseName>BlockArgs()`
+functions that by default return 0, to be overriden by each clause through the
+`extraClassDeclaration` property. Based on these functions and the expected
+alphabetical sorting between entry block argument-defining clauses, it
+implements `get<ClauseName>BlockArgs()` functions that are the intended method
+of accessing clause-defined block arguments.
 
 ## Loop-Associated Directives
 

[skatrak]

PR stack:

• [MLIR][OpenMP] Normalize handling of entry block arguments #109808
• [MLIR][OpenMP] Normalize representation of entry block arg-defining clauses #109809
• [MLIR][OpenMP] Use map format to represent use_device_{addr,ptr} #109810
• [MLIR][OpenMP] Document entry block argument-defining clauses (NFC) #109811
• [MLIR][OpenMP] Improve omp.section block arguments handling #110266
• [Flang][OpenMP] Improve entry block argument creation and binding #110267

[tblah]

LGTM, thanks!

[bhandarkar-pranav]

LGTM. Given how reviewing docs essentially turns into a series of subjective opinions or preferences, please consider most all of my comments as nits, except the one about alphabetical sorting of clauses.

[bhandarkar-pranav]

I am assuming the tablegen backend for openmp that you have implemented doesn't do the sorting and the onus for the alphabetical sorting is on the user, correct? If that's the case i think that expectation must be made explicit, either here or (preferably) in Adding an Operation

[skatrak]

In reality the alphabetical sorting of entry block argument-defining clauses is enforced by the custom parsers/printers and the interface itself, regardless of the order in which these clauses are specified in the operation's definition by the user. Either way, I think it's a good idea to state in the section you mention that the convention is to specify clauses in alphabetical order.

[skatrak]

Thanks for the feedback Pranav, let me know if the changes address your concerns.

[skatrak]

In reality the alphabetical sorting of entry block argument-defining clauses is enforced by the custom parsers/printers and the interface itself, regardless of the order in which these clauses are specified in the operation's definition by the user. Either way, I think it's a good idea to state in the section you mention that the convention is to specify clauses in alphabetical order.

[bhandarkar-pranav]

Thanks for the feedback Pranav, let me know if the changes address your concerns.

Thank you for the changes. This LGTM.

[bhandarkar-pranav]

LGTM