diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # The LLVM Compiler Infrastructure -This directory and its sub-directories contain source code for LLVM, +This directory and its sub-directories contains the source code for LLVM, a toolkit for the construction of highly optimized compilers, optimizers, and run-time environments. @@ -33,8 +33,7 @@ ### Getting the Source Code and Building LLVM -The LLVM Getting Started documentation may be out of date. The [Clang -Getting Started](http://clang.llvm.org/get_started.html) page might have more +The LLVM Getting Started documentation may be out of date. The Clang [Getting Started](http://clang.llvm.org/get_started.html) page might have more accurate information. This is an example work-flow and configuration to get and build the LLVM source: @@ -101,7 +100,7 @@ LLVM sub-projects generate their own ``check-`` target. * Running a serial build will be **slow**. To improve speed, try running a - parallel build. That's done by default in Ninja; for ``make``, use the option + parallel build. That's done by default in Ninja; for ``make``, use the option ``-j NNN``, where ``NNN`` is the number of parallel jobs to run. In most cases, you get the best performance if you specify the number of CPU threads you have. On some Unix systems, you can specify this with ``-j$(nproc)``. @@ -120,3 +119,4 @@ The LLVM project has adopted a [code of conduct](https://llvm.org/docs/CodeOfConduct.html) for participants to all modes of communication within the project. + diff --git a/mlir/docs/Interfaces.md b/mlir/docs/Interfaces.md --- a/mlir/docs/Interfaces.md +++ b/mlir/docs/Interfaces.md @@ -37,7 +37,7 @@ referenced later. Once the interface has been defined, dialects can override it using dialect-specific information. The interfaces defined by a dialect are registered via `addInterfaces<>`, a similar mechanism to Attributes, Operations, -Types, etc +Types, etc. ```c++ /// Define a base inlining interface class to allow for dialects to opt-in to @@ -86,7 +86,7 @@ #### DialectInterfaceCollection An additional utility is provided via `DialectInterfaceCollection`. This class -allows for collecting all of the dialects that have registered a given interface +allows collecting all of the dialects that have registered a given interface within an instance of the `MLIRContext`. This can be useful to hide and optimize the lookup of a registered dialect interface. @@ -394,7 +394,7 @@ accessed with full name qualification. * Extra Shared Class Declarations (Optional: `extraSharedClassDeclaration`) - Additional C++ code that is injected into the declarations of both the - interface and trait class. This allows for defining methods and more + interface and the trait class. This allows for defining methods and more that are exposed on both the interface and trait class, e.g. to inject utilties on both the interface and the derived entity implementing the interface (e.g. attribute, operation, etc.). @@ -617,7 +617,7 @@ } // Operation interfaces can optionally be wrapped inside -// DeclareOpInterfaceMethods. This would result in autogenerating declarations +// `DeclareOpInterfaceMethods`. This would result in autogenerating declarations // for members `foo`, `bar` and `fooStatic`. Methods with bodies are not // declared inside the op declaration but instead handled by the op interface // trait directly. diff --git a/mlir/docs/LangRef.md b/mlir/docs/LangRef.md --- a/mlir/docs/LangRef.md +++ b/mlir/docs/LangRef.md @@ -18,9 +18,9 @@ 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 +form suitable for debugging; an in-memory form suitable for programmatic transformations and analysis, and a compact serialized form suitable for storage -and transport. The different forms all describe the same semantic content. This +and transport. All the different forms describes the same semantic content. This document describes the human-readable textual form. [TOC] @@ -44,7 +44,7 @@ gates. These different concepts are represented by different operations in MLIR and the set of operations usable in MLIR can be arbitrarily extended. -MLIR also provides an extensible framework for transformations on operations, +MLIR also provides an extensible framework for the transformations on operations, using familiar concepts of compiler [Passes](Passes.md). Enabling an arbitrary set of passes on an arbitrary set of operations results in a significant scaling challenge, since each transformation must potentially take into account the @@ -369,7 +369,7 @@ A region with a single block may not include a [terminator operation](#terminator-operations). The enclosing op can opt-out of this requirement with the `NoTerminator` trait. The top-level `ModuleOp` is an -example of such operation which defined this trait and whose block body does not +example of such operation which defines this trait and whose block body does not have a terminator. Blocks in MLIR take a list of block arguments, notated in a function-like way. @@ -568,7 +568,7 @@ #### Closure -Regions allow defining an operation that creates a closure, for example by +Regions allow defining an operation that creates a closure; for example by “boxing” the body of the region into a value they produce. It remains up to the operation to define its semantics. Note that if an operation triggers asynchronous execution of the region, it is under the responsibility of the @@ -769,7 +769,7 @@ dialect prefix. - *discardable attributes* have semantics defined externally to the operation - itself, but must be compatible with the operations's semantics. These + itself, but must be compatible with the operations' semantics. These attributes must have names that start with a dialect prefix. The dialect indicated by the dialect prefix is expected to verify these attributes. An example is the `gpu.container_module` attribute. @@ -839,7 +839,7 @@ characters that are not allowed in the lighter syntax, as well as unbalanced `<>` characters. -See [here](AttributesAndTypes.md) on how to define dialect attribute values. +See [here](AttributesAndTypes.md) about how to define dialect attribute values. ### Builtin Attribute Values diff --git a/mlir/docs/OpDefinitions.md b/mlir/docs/OpDefinitions.md --- a/mlir/docs/OpDefinitions.md +++ b/mlir/docs/OpDefinitions.md @@ -23,7 +23,7 @@ problem, e.g., repetitive string comparisons during optimization and analysis passes, unintuitive accessor methods (e.g., generic/error prone `getOperand(3)` vs self-documenting `getStride()`) with more generic return types, verbose and -generic constructors without default arguments, verbose textual IR dump, and so +generic constructors without default arguments, verbose textual IR dumps, and so on. Furthermore, operation verification is: 1. best case: a central string-to-verification-function map, @@ -57,7 +57,7 @@ We use TableGen as the language for specifying operation information. TableGen itself just provides syntax for writing records; the syntax and constructs -allowed in a TableGen file (typically with filename suffix `.td`) can be found +allowed in a TableGen file (typically with the filename suffix `.td`) can be found [here][TableGenProgRef]. * TableGen `class` is similar to C++ class; it can be templated and @@ -80,7 +80,7 @@ MLIR defines several common constructs to help operation definition and provide their semantics via a special [TableGen backend][TableGenBackend]: [`OpDefinitionsGen`][OpDefinitionsGen]. These constructs are defined in -[`OpBase.td`][OpBase]. The main ones are +[`OpBase.td`][OpBase]. The main ones are: * The `Op` class: It is the main construct for defining operations. All facts regarding the operation are specified when specializing this class, with the @@ -91,7 +91,7 @@ and constraints of the operation, including whether the operation has side effect or whether its output has the same shape as the input. * The `ins`/`outs` marker: These are two special markers builtin to the - `OpDefinitionsGen` backend. They lead the definitions of operands/attributes + `OpDefinitionsGen` backend. They lead to the definitions of operands/attributes and results respectively. * The `TypeConstraint` class hierarchy: They are used to specify the constraints over operands or results. A notable subclass hierarchy is @@ -134,7 +134,7 @@ ### Operation name -The operation name is a unique identifier of the operation within MLIR, e.g., +The operation name is a unique identifier for the operation within MLIR, e.g., `tf.Add` for addition operation in the TensorFlow dialect. This is the equivalent of the mnemonic in assembly language. It is used for parsing and printing in the textual format. It is also used for pattern matching in graph @@ -207,12 +207,13 @@ the return type (in the case of attributes the return type will be constructed from the storage type, while for operands it will be `Value`). Each attribute's raw value (e.g., as stored) can also be accessed via generated `Attr` -getters for use in transformation passes where the more user friendly return +getters for use in transformation passes where the more user-friendly return type is less suitable. -All the arguments should be named to 1) provide documentation, 2) drive -auto-generation of getter methods, 3) provide a handle to reference for other -places like constraints. +All the arguments should be named to: +1) provide documentation. +2) drive auto-generation of getter methods. +3) provide a handle to reference for other places like constraints. #### Variadic operands @@ -221,7 +222,7 @@ Normally operations have no variadic operands or just one variadic operand. For the latter case, it is easy to deduce which dynamic operands are for the static -variadic operand definition. Though, if an operation has more than one variable +variadic operand definition. However, if an operation has more than one variable length operands (either optional or variadic), it would be impossible to attribute dynamic operands to the corresponding static variadic operand definitions without further information from the operation. Therefore, either @@ -425,7 +426,7 @@ same form regardless of the exact op. This is particularly useful for implementing declarative pattern rewrites. -The second and third forms are good for use in manually written code given that +The second and third forms are good for use in manually written code, given that they provide better guarantee via signatures. The third form will be generated if any of the op's attribute has different @@ -434,14 +435,14 @@ Additionally, for the third form, if an attribute appearing later in the `arguments` list has a default value, the default value will be supplied in the declaration. This works for `BoolAttr`, `StrAttr`, `EnumAttr` for now and the -list can grow in the future. So if possible, default valued attribute should be +list can grow in the future. So if possible, the default valued attribute should be placed at the end of the `arguments` list to leverage this feature. (This behavior is essentially due to C++ function parameter default value placement restrictions.) Otherwise, the builder of the third form will still be generated but default values for the attributes not at the end of the `arguments` list will not be supplied in the builder's signature. -ODS will generate a builder that doesn't require return type specified if +ODS will generate a builder that doesn't require the return type specified if * Op implements InferTypeOpInterface interface; * All return types are either buildable types or are the same as a given @@ -585,7 +586,7 @@ attributes, .etc. 1. Other Traits/Interfaces that have marked their verifier as `verifyTrait` or `verifyWithRegions=0`. -1. Custom verifier which is defined in the op and has marked `hasVerifier=1` +1. Custom verifier which is defined in the op and has been marked `hasVerifier=1` If an operation has regions, then it may have the second phase, diff --git a/mlir/docs/PDLL.md b/mlir/docs/PDLL.md --- a/mlir/docs/PDLL.md +++ b/mlir/docs/PDLL.md @@ -29,11 +29,11 @@ This section provides details on various design decisions, their rationale, and alternatives considered when designing PDLL. Given the nature of software development, this section may include references to areas of the MLIR compiler -that no longer exist. +that no longer exists. ### Why build a new language instead of improving TableGen DRR? -Note: The section assumes familiarity with +Note: This section assumes familiarity with [TDRR](https://mlir.llvm.org/docs/DeclarativeRewrites/), please refer the relevant documentation before continuing. diff --git a/mlir/docs/PassManagement.md b/mlir/docs/PassManagement.md --- a/mlir/docs/PassManagement.md +++ b/mlir/docs/PassManagement.md @@ -39,7 +39,7 @@ * When multithreading, a specific pass instance may not even execute on all operations within the IR. As such, a pass should not rely on running on all operations. -* Must not maintain any global mutable state, e.g. static variables within the +* Must not maintain any global mutable states, e.g. static variables within the source file. All mutable state should be maintained by an instance of the pass. * Must be copy-constructible @@ -128,7 +128,7 @@ (operations, types, attributes, ...) can be created. Dialects must also be loaded before starting the execution of a multi-threaded pass pipeline. To this end, a pass that may create an entity from a dialect that isn't guaranteed to -already ne loaded must express this by overriding the `getDependentDialects()` +already loaded, must express this by overriding the `getDependentDialects()` method and declare this list of Dialects explicitly. ### Initialization @@ -256,7 +256,7 @@ // that no transformation was performed. markAllAnalysesPreserved(); - // Mark specific analyses as preserved. This is used if some transformation + // Mark-specific analyses as preserved. This is used if some transformation // was performed, but some analyses were either unaffected or explicitly // preserved. markAnalysesPreserved(); @@ -818,7 +818,7 @@ contains the following fields: * `summary` - - A short one line summary of the pass, used as the description when + - A short one-line summary of the pass, used as the description when registering the pass. * `description` - A longer, more detailed description of the pass. This is used when @@ -847,7 +847,7 @@ * default value - The default option value. * description - - A one line description of the option. + - A one-line description of the option. * additional option flags - A string containing any additional options necessary to construct the option. @@ -870,7 +870,7 @@ * element type - The C++ type of the list element. * description - - A one line description of the option. + - A one-line description of the option. * additional option flags - A string containing any additional options necessary to construct the option. @@ -894,7 +894,7 @@ * display name - The name used when displaying the statistic. * description - - A one line description of the statistic. + - A one-line description of the statistic. ```tablegen def MyPass : Pass<"my-pass"> { @@ -938,7 +938,7 @@ Instrumentations added to the PassManager are run in a stack like fashion, i.e. the last instrumentation to execute a `runBefore*` hook will be the first to execute the respective `runAfter*` hook. The hooks of a `PassInstrumentation` -class are guaranteed to be executed in a thread safe fashion, so additional +class are guaranteed to be executed in a thread-safe fashion, so additional synchronization is not necessary. Below in an example instrumentation that counts the number of times the `DominanceInfo` analysis is computed: diff --git a/mlir/docs/PatternRewriter.md b/mlir/docs/PatternRewriter.md --- a/mlir/docs/PatternRewriter.md +++ b/mlir/docs/PatternRewriter.md @@ -232,7 +232,7 @@ ## Pattern Application After a set of patterns have been defined, they are collected and provided to a -specific driver for application. A driver consists of several high levels parts: +specific driver for application. A driver consists of several high level parts: * Input `RewritePatternSet` @@ -255,7 +255,7 @@ `PatternApplicator` class. This class takes as input the `RewritePatternSet` and transforms the patterns based upon a provided cost model. This cost model computes a final benefit for a given pattern, using -whatever driver specific information necessary. After a cost model has been +whatever driver specific information is necessary. After a cost model has been computed, the driver may begin to match patterns against operations using `PatternApplicator::matchAndRewrite`. diff --git a/mlir/docs/README.md b/mlir/docs/README.md new file mode 100644 --- /dev/null +++ b/mlir/docs/README.md @@ -0,0 +1,6 @@ +# MLIR documentation + +Please note that the MLIR's rendered documentation is displayed [here](https://mlir.llvm.org). The viewing experience on GitHub or elsewhere may not match with those of the website. For any changes please verify instead, that they work on the main website first. + +See [this](https://github.com/llvm/mlir-www) for the website's generation information. + diff --git a/mlir/docs/README.txt b/mlir/docs/README.txt deleted file mode 100644 --- a/mlir/docs/README.txt +++ /dev/null @@ -1,9 +0,0 @@ -MLIR documentation -================== - -Please note mlir.llvm.org is where MLIR's rendered documentation is displayed. -The viewing experience on GitHub or elsewhere may not match those of the -website. For any changes please verify instead that they work on the main -website first. - -See https://github.com/llvm/mlir-www for the website generation information.