[Mlir-commits] [mlir] 226f925 - [mlir][linalg][python] Update integration of OpDSL doc (NFC).
Tobias Gysi
llvmlistbot at llvm.org
Thu Jul 1 00:59:00 PDT 2021
Author: Tobias Gysi
Date: 2021-07-01T07:41:32Z
New Revision: 226f925c3f3461cbd3e76f383069b01b5f7db2f3
URL: https://github.com/llvm/llvm-project/commit/226f925c3f3461cbd3e76f383069b01b5f7db2f3
DIFF: https://github.com/llvm/llvm-project/commit/226f925c3f3461cbd3e76f383069b01b5f7db2f3.diff
LOG: [mlir][linalg][python] Update integration of OpDSL doc (NFC).
Move the OpDSL doc to a linalg sub folder and updated the integration in the main linalg documentation.
Differential Revision: https://reviews.llvm.org/D105188
Added:
mlir/docs/Dialects/Linalg/OpDSL.md
mlir/docs/Dialects/Linalg/_index.md
Modified:
mlir/docs/Rationale/RationaleLinalgDialect.md
Removed:
mlir/docs/Dialects/Linalg.md
mlir/docs/Tools/LinalgOpDsl.md
################################################################################
diff --git a/mlir/docs/Tools/LinalgOpDsl.md b/mlir/docs/Dialects/Linalg/OpDSL.md
similarity index 96%
rename from mlir/docs/Tools/LinalgOpDsl.md
rename to mlir/docs/Dialects/Linalg/OpDSL.md
index f7be38ec6f656..bdfd58f88fb66 100644
--- a/mlir/docs/Tools/LinalgOpDsl.md
+++ b/mlir/docs/Dialects/Linalg/OpDSL.md
@@ -1,12 +1,12 @@
-# linalg_opdsl tool
+# Linalg OpDSL
Python based DSL for authoring Linalg op definitions and generating
`linalg.generic` IR based on them for samples.
-The tool `linalg_opdsl` provides a high level DSL for constructing structured op
-definitions in a way that can be exported to built-in, named structured ops via
-the above YAML-based definitions or used interactively to emit corresponding
-`linalg.generic` IR for the composition.
+The Linalg OpDSL is a high level DSL for constructing structured op definitions
+in a way that can be exported to built-in, named structured ops via
+[YAML-based definitions](_index.md/#yaml-gen) or used interactively to emit
+corresponding `linalg.generic` IR for the composition.
## Basic usage
diff --git a/mlir/docs/Dialects/Linalg.md b/mlir/docs/Dialects/Linalg/_index.md
similarity index 97%
rename from mlir/docs/Dialects/Linalg.md
rename to mlir/docs/Dialects/Linalg/_index.md
index 65fe07567d5ad..01415dd2c53a5 100644
--- a/mlir/docs/Dialects/Linalg.md
+++ b/mlir/docs/Dialects/Linalg/_index.md
@@ -10,7 +10,7 @@ Linalg is designed to solve the High-level Hierarchical Optimization (HHO box)
in MLIR and to interoperate nicely within a *Mixture Of Expert Compilers*
environment (i.e. the *CGSel* box).
-The [Rationale Document](../Rationale/RationaleLinalgDialect.md) goes into
+The [Rationale Document](../../Rationale/RationaleLinalgDialect.md) goes into
significantly more design and architectural decision details.
## Set of Key Transformations<a name="key_transformations"></a>
@@ -37,9 +37,9 @@ Linalg IR and that have influenced its design:
## High-Level Description of Linalg Ops<a name="linalg_ops"></a>
Linalg takes at least some inspiration from all previously
-[listed prior art](../Rationale/RationaleLinalgDialect.md/#prior-art). The design enables the definition of
-***CustomOps*** with generic properties that enable
-[key transformations](#key_transformations), including lowering to scalar
+[listed prior art](../../Rationale/RationaleLinalgDialect.md/#prior-art). The
+design enables the definition of ***CustomOps*** with generic properties that
+enable [key transformations](#key_transformations), including lowering to scalar
load/store and other operations or to external library calls and intrinsics.
These ops can have ***either tensor or buffer*** as both input and output
@@ -70,7 +70,7 @@ abstraction on tensors and buffers. This `linalg.generic` operation can express
custom operations that optionally have *indexing semantics* (by accessing the
iteration indices using the `linalg.index` operation). The properties of
`linalg.generic` are the result of applying the guiding principles described in
-the [Rationale Document](../Rationale/RationaleLinalgDialect.md). They are
+the [Rationale Document](../../Rationale/RationaleLinalgDialect.md). They are
listed next, with a brief example and discussion for each.
#### Property 1: Input and Output Operands Define The Iteration Space<a name="prop1"></a>
@@ -492,7 +492,7 @@ As it stands, the six properties above define the semantics of a
`linalg.generic` op. It is an open question whether all of these semantics are
strictly necessary in practice and whether some should or could be derived
automatically while still maintaining the
-[core guiding principles](../Rationale/RationaleLinalgDialect.md/#core-guiding-principlesa-nameguiding_principlesa).
+[core guiding principles](../../Rationale/RationaleLinalgDialect.md/#core-guiding-principlesa-nameguiding_principlesa).
For the time being, we have settled on the combination of these properties
because of empirical evidence building and working on multiple high-level
@@ -662,13 +662,16 @@ void batchmatmul::regionBuilder(ArrayRef<BlockArgument> args) {
}
```
-### YAML Based Named Structured Ops
+### YAML Based Named Structured Ops<a name="yaml-gen"></a>
Linalg provides a declarative generation tool (`mlir-linalg-ods-yaml-gen`) to
automatically produce named ops from a YAML-based op description format intended
-to capture the structure of the named ops and be generated from a higher level
-"mathy" DSL syntax. This facility is currently in flight and is intended to
-subsume the above when ready. See the C++ class to YAML mapping traits in
+to capture the structure of the named ops. The YAML-based op descriptions are
+generated from a higher level [DSL](OpDSL.md) and are not meant to be edited
+directly.
+
+This facility is currently in flight and is intended to subsume the above when
+ready. See the C++ class to YAML mapping traits in
`mlir-mlinalg-ods-yaml-gen.cpp` as the source of truth for the schema.
Most of the above documentation roughly applies to this path and will be ported
diff --git a/mlir/docs/Rationale/RationaleLinalgDialect.md b/mlir/docs/Rationale/RationaleLinalgDialect.md
index 102e5f52efe62..c8dca244a4cb4 100644
--- a/mlir/docs/Rationale/RationaleLinalgDialect.md
+++ b/mlir/docs/Rationale/RationaleLinalgDialect.md
@@ -102,9 +102,9 @@ to the *structured control flow* dialect (named `LoopOps`).
More components can be extracted, redesigned and generalized when new uses or
requirements arise.
-Several [design questions](../Dialects/Linalg.md/#open_issues) remain open in Linalg, which does not
-claim to be a general solution to all compilation problems.
-It does aim at driving thinking and implementations of domain-specific
+Several [design questions](../Dialects/Linalg/_index.md/#open_issues) remain
+open in Linalg, which does not claim to be a general solution to all compilation
+problems. It does aim at driving thinking and implementations of domain-specific
abstractions where programmer's intent can be captured at a very high level,
directly in the IR.
@@ -566,18 +566,18 @@ reconcile [core guiding principles](#guiding_principles) with real-world
requirements when producing an implementation based on MLIR.
### Algorithms + Data Structures = Programs<a name="data_and_compute"></a>
+
This is a twist on Niklaus Wirth's formulation but captures the essence of the
design of Linalg: control-flow does not exist in a vacuum, independently of
-data.
-On the contrary, there is a very strong relationship between control-flow and
-data structures: one cannot exist without the other. This has multiple
-implications on the [semantics of Linalg Ops](../Dialects/Linalg.md/#linalg_op) and their
-transformations. In particular, this observation influences whether
-certain transformations are better done:
-- as control flow or data structure manipulation,
-- on Linalg ops attributes or on loops after some partial lowering
-occurred,
-- as extensions to the Linalg dialect in terms of new ops or attributes.
+data. On the contrary, there is a very strong relationship between control-flow
+and data structures: one cannot exist without the other. This has multiple
+implications on the
+[semantics of Linalg Ops](../Dialects/Linalg/_index.md/#linalg_ops) and their
+transformations. In particular, this observation influences whether certain
+transformations are better done: - as control flow or data structure
+manipulation, - on Linalg ops attributes or on loops after some partial lowering
+occurred, - as extensions to the Linalg dialect in terms of new ops or
+attributes.
### The Dialect Need not be Closed Under Transformations<a name="dialect_not_closed"></a>
This is probably the most surprising and counter-intuitive
@@ -615,9 +615,8 @@ Principles](#guiding_principles)---with the following picture.
<img width="1200" alt="MLIR Codegen Flow"
src="https://user-images.githubusercontent.com/10148468/73613904-2f720a00-45c8-11ea-8265-1c856c02525b.png">
-This figure is not meant to be perfectly accurate but a rough map of
-how we view the distribution of structural information in existing
-systems, from a codegen-friendly angle. Unsurprisingly, the
-[Linalg Dialect](../Dialects/Linalg.md) and its
-future evolutions aspire to a position in the top-right of this map.
-
+This figure is not meant to be perfectly accurate but a rough map of how we view
+the distribution of structural information in existing systems, from a
+codegen-friendly angle. Unsurprisingly, the
+[Linalg Dialect](../Dialects/Linalg/_index.md) and its future evolutions aspire
+to a position in the top-right of this map.
More information about the Mlir-commits
mailing list