From 53fc0686ec196a82eebeeecea0266ffd578d0236 Mon Sep 17 00:00:00 2001 From: Lucy Fox Date: Wed, 13 Nov 2019 09:58:53 -0800 Subject: [PATCH] Create and begin writing glossary. This creates a central place in the documentation where MLIR-specific terminology is defined. See discussion on the MLIR forum (https://groups.google.com/a/tensorflow.org/g/mlir/c/5YXDSdu76Hk). PiperOrigin-RevId: 280220365 Change-Id: I370d5bd7bc329b81212d9cca37f107dd0d8243be --- third_party/mlir/g3doc/Glossary.md | 155 +++++++++++++++++++++++++++++ third_party/mlir/g3doc/LangRef.md | 6 +- 2 files changed, 158 insertions(+), 3 deletions(-) create mode 100644 third_party/mlir/g3doc/Glossary.md diff --git a/third_party/mlir/g3doc/Glossary.md b/third_party/mlir/g3doc/Glossary.md new file mode 100644 index 00000000000..1c94f5f849c --- /dev/null +++ b/third_party/mlir/g3doc/Glossary.md @@ -0,0 +1,155 @@ +# MLIR Glossary + +This glossary contains definitions of MLIR-specific terminology. It is intended +to be a quick reference document. For terms which are well-documented elsewhere, +definitions are kept brief and the header links to the more in-depth +documentation. + + + +[Block](LangRef.md#blocks) {#block} +: A sequential list of operations without control flow. + +: Also called a [basic block](https://en.wikipedia.org/wiki/Basic_block). + +Conversion {#conversion} +: The transformation of code represented in one dialect into a semantically + equivalent representation in another dialect (i.e. inter-dialect conversion) + or the same dialect (i.e. intra-dialect conversion). + +: In the context of MLIR, conversion is distinct from + [translation](#translation). Conversion refers to a transformation between + (or within) dialects, but all still within MLIR, whereas translation refers + to a transformation between MLIR and an external representation. + +[Declarative Rewrite Rule](DeclarativeRewrites.md) (DRR) {#drr} +: A [rewrite rule](https://en.wikipedia.org/wiki/Graph_rewriting) which can be + defined declaratively (e.g. through specification in a + [TableGen](https://llvm.org/docs/TableGen/) record). At compiler build time, + these rules are expanded into an equivalent `mlir::RewritePattern` subclass. + +[Dialect](LangRef.md#dialects) {#dialect} +: A dialect is a grouping of functionality which can be used to extend the + MLIR system. + +: A dialect creates a unique `namespace` within which new + [operations](#operation), [attributes](LangRef.md#attributes), and + [types](LangRef.md#type-system) are defined. This is the fundamental method + by which to extend MLIR. + +: In this way, MLIR is a meta-IR: its extensible framework allows it to be + leveraged in many different ways (e.g. at different levels of the + compilation process). Dialects provide an abstraction for the different uses + of MLIR while recognizing that they are all a part of the meta-IR that is + MLIR. + +: The tutorial provides an example of + [interfacing with MLIR](Tutorials/Toy/Ch-2.md#interfacing-with-mlir) in this + way. + +: (Note that we have intentionally selected the term "dialect" instead of + "language", as the latter would wrongly suggest that these different + namespaces define entirely distinct IRs.) + +Export {#export} +: To transform code represented in MLIR into a semantically equivalent + representation which is external to MLIR. + +: The tool that performs such a transformation is called an exporter. + +: See also: [translation](#translation). + +[Function](LangRef.md#functions) {#function} +: An [operation](#operation) with a name containing one [region](#region). + +: The region of a function is not allowed to implicitly capture values defined + outside of the function, and all external references must use function + arguments or attributes that establish a symbolic connection. + +Import {#import} +: To transform code represented in an external representation into a + semantically equivalent representation in MLIR. + +: The tool that performs such a transformation is called an importer. + +: See also: [translation](#translation). + +Legalization {#legalization} +: The process of transforming operations into a semantically equivalent + representation which adheres to the requirements set by the + [conversion target](DialectConversion.md#conversion-target). + +: That is, legalization is accomplished if and only if the new representation + contains only operations which are legal, as specified in the conversion + target. + +Lowering {#lowering} +: The process of transforming a higher-level representation of an operation + into a lower-level, but semantically equivalent, representation. + +: In MLIR, this is typically accomplished through + [dialect conversion](DialectConversion.md). This provides a framework by + which to define the requirements of the lower-level representation, called + the [conversion target](DialectConversion.md#conversion-target), by + specifying which operations are legal versus illegal after lowering. + +: See also: [legalization](#legalization). + +[Module](LangRef.md#module) {#module} +: An [operation](#operation) which contains a single region containing a + single block that is comprised of operations. + +: This provides an organizational structure for MLIR operations, and is the + expected top-level operation in the IR: the textual parser returns a Module. + +[Operation](LangRef.md#operations) (op) {#operation} +: A unit of code in MLIR. Operations are the building blocks for all code and + computations represented by MLIR. They are fully extensible (there is no + fixed list of operations) and have application-specific semantics. + +: An operation can have zero or more [regions](#region). Note that this + creates a nested IR structure, as regions consist of blocks, which in turn, + consist of a list of operations. + +[Region](LangRef.md#regions) {#region} +: A [CFG](https://en.wikipedia.org/wiki/Control-flow_graph) of MLIR + [blocks](#block). + +Round-trip {#round-trip} +: The process of converting from a source format to a target format and then + back to the source format. + +: This is a good way of gaining confidence that the target format richly + models the source format. This is particularly relevant in the MLIR context, + since MLIR's multi-level nature allows for easily writing target dialects + that model a source format (such as TensorFlow GraphDef or another non-MLIR + format) faithfully and have a simple conversion procedure. Further + cleanup/lowering can be done entirely within the MLIR representation. This + separation - making the [importer](#importer) as simple as possible and + performing all further cleanups/lowering in MLIR - has proven to be a useful + design pattern. + +[Terminator operation](LangRef.md#terminator-operations) {#terminator-operations} +: An [operation](#operation) which *must* terminate a [block](#block). + Terminator operations are a special category of operations. + +Transitive lowering {#transitive-lowering} +: An A->B->C [lowering](#lowering); that is, a lowering in which multiple + patterns may be applied in order to fully transform an illegal operation + into a set of legal ones. + +: This provides the flexibility that the [conversion](#conversion) framework + may perform the lowering in multiple stages of applying patterns (which may + utilize intermediate patterns not in the conversion target) in order to + fully legalize an operation. This is accomplished through + [partial conversion](DialectConversion.md#modes-of-conversion). + +Translation {#translation} +: The transformation of code represented in an external (non-MLIR) + representation into a semantically equivalent representation in MLIR (i.e. + [importing](#import)), or the inverse (i.e. [exporting](#export)). + +: In the context of MLIR, translation is distinct from + [conversion](#conversion). Translation refers to a transformation between + MLIR and an external representation, whereas conversion refers to a + transformation within MLIR (between or within dialects). diff --git a/third_party/mlir/g3doc/LangRef.md b/third_party/mlir/g3doc/LangRef.md index 3409b9fac83..204bbd6df31 100644 --- a/third_party/mlir/g3doc/LangRef.md +++ b/third_party/mlir/g3doc/LangRef.md @@ -12,8 +12,8 @@ continuous design provides a framework to lower from dataflow graphs to high-performance target-specific code. This document defines and describes the key concepts in MLIR, and is intended to -be a dry reference document - [rationale documentation](Rationale.md) and other -content is hosted elsewhere. +be a dry reference document - the [rationale documentation](Rationale.md), +[glossary](Glossary.md), and other content are hosted elsewhere. MLIR is designed to be used in three different forms: a human-readable textual form suitable for debugging, an in-memory form suitable for programmatic @@ -285,7 +285,7 @@ printing operations. In the operation sets listed below, we show both forms. ### Terminator Operations -These are a special class of operations that *must* terminate a block, for +These are a special category of operations that *must* terminate a block, for example [branches](Dialects/Standard.md#terminator-operations). These operations may also have a list of successors ([blocks](#blocks) and their arguments).