diff --git a/mlir/docs/Tools/LinalgOpDsl.md b/mlir/docs/Dialects/Linalg/OpDSL.md rename from mlir/docs/Tools/LinalgOpDsl.md rename to mlir/docs/Dialects/Linalg/OpDSL.md --- 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 rename from mlir/docs/Dialects/Linalg.md rename to mlir/docs/Dialects/Linalg/_index.md --- a/mlir/docs/Dialects/Linalg.md +++ b/mlir/docs/Dialects/Linalg/_index.md @@ -10,7 +10,7 @@ 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 @@ -37,9 +37,9 @@ ## High-Level Description of Linalg Ops 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 @@ 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 @@ -492,7 +492,7 @@ `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 @@ } ``` -### YAML Based Named Structured Ops +### YAML Based Named Structured Ops 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 --- a/mlir/docs/Rationale/RationaleLinalgDialect.md +++ b/mlir/docs/Rationale/RationaleLinalgDialect.md @@ -102,9 +102,9 @@ 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 @@ requirements when producing an implementation based on MLIR. ### Algorithms + Data Structures = Programs + 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 This is probably the most surprising and counter-intuitive @@ -615,9 +615,8 @@ MLIR Codegen Flow -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.