From 6b07a978350ff738b81866c6c9114770f997b2fc Mon Sep 17 00:00:00 2001 From: Sean Silva Date: Thu, 4 Feb 2021 16:17:45 -0800 Subject: [PATCH] [mlir] Introduce more intuitive wording for attributes. After discussion, it seems like we want to go with "inherent/discardable". These seem to best capture the relationship with the op semantics and don't conflict with other terms. Please let me know your preferences. Some of the other contenders are: ``` "intrinsic" side | "annotation" side -----------------+------------------ characteristic | annotation closed | open definitional | advisory essential | discardable expected | unexpected innate | acquired internal | external intrinsic | extrinsic known | unknown local | global native | foreign inherent | acquired ``` Rationale: - discardable: good. discourages use for stable data. - inherent: good - annotation: redundant and doesn't convey difference - intrinsic: confusable with "compiler intrinsics". - definitional: too much of a mounthful - extrinsic: too exotic of a word and hard to say - acquired: doesn't convey the relationship to the semantics - internal/external: not immediately obvious: what is internal to what? - innate: similar to intrinsic but worse - acquired: we don't typically think of an op as "acquiring" things - known/unknown: by who? - local/global: to what? - native/foreign: to where? - advisory: confusing distinction: is the attribute itself advisory or is the information it provides advisory? - essential: an intrinsic attribute need not be present. - expected: same issue as essential - unexpected: by who/what? - closed/open: whether the set is open or closed doesn't seem essential to the attribute being intrinsic. Also, in theory an op can have an unbounded set of intrinsic attributes (e.g. `arg` for func). - characteristic: unless you have a math background this probably doesn't make as much sense Differential Revision: https://reviews.llvm.org/D96093 --- mlir/docs/LangRef.md | 57 +++++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/mlir/docs/LangRef.md b/mlir/docs/LangRef.md index a40d309c1531..1ccc5026a0da 100644 --- a/mlir/docs/LangRef.md +++ b/mlir/docs/LangRef.md @@ -304,9 +304,9 @@ operations](#target-specific-operations). The internal representation of an operation is simple: an operation is identified by a unique string (e.g. `dim`, `tf.Conv2d`, `x86.repmovsb`, `ppc.eieio`, etc), can return zero or more results, take zero or more -operands, may have zero or more attributes, may have zero or more successors, -and zero or more enclosed [regions](#regions). The generic printing form -includes all these elements literally, with a function type to indicate the +operands, has a dictionary of [attributes](#attributes), has zero or more +successors, and zero or more enclosed [regions](#regions). The generic printing +form includes all these elements literally, with a function type to indicate the types of the results and operands. Example: @@ -321,7 +321,7 @@ Example: // Invoke a TensorFlow function called tf.scramble with two inputs // and an attribute "fruit". -%2 = "tf.scramble"(%result#0, %bar) {fruit: "banana"} : (f32, i32) -> f32 +%2 = "tf.scramble"(%result#0, %bar) {fruit = "banana"} : (f32, i32) -> f32 ``` In addition to the basic syntax above, dialects may register known operations. @@ -1308,34 +1308,37 @@ shape `(0, 42)` and zero shapes are not allowed. Syntax: ``` -attribute-entry ::= dialect-attribute-entry | dependent-attribute-entry -dialect-attribute-entry ::= dialect-namespace `.` bare-id `=` attribute-value -dependent-attribute-entry ::= dependent-attribute-name `=` attribute-value -dependent-attribute-name ::= ((letter|[_]) (letter|digit|[_$])*) - | string-literal +attribute-entry ::= (bare-id | string-literal) `=` attribute-value +attribute-value ::= attribute-alias | dialect-attribute | builtin-attribute ``` Attributes are the mechanism for specifying constant data on operations in places where a variable is never allowed - e.g. the comparison predicate of a -[`cmpi` operation](Dialects/Standard.md#stdcmpi-cmpiop), or the stride of a -convolution. They consist of a name and a concrete attribute value. The set of -expected attributes, their structure, and their interpretation are all -contextually dependent on what they are attached to. +[`cmpi` operation](Dialects/Standard.md#stdcmpi-cmpiop). Each operation has an +attribute dictionary, which associates a set of attribute names to attribute +values. MLIR's builtin dialect provides a rich set of +[builtin attribute values](#builtin-attribute-values) out of the box (such as +arrays, dictionaries, strings, etc.). Additionally, dialects can define their +own [dialect attribute values](#dialect-attribute-values). -There are two main classes of attributes: dependent and dialect. Dependent -attributes derive their structure and meaning from what they are attached to; -e.g., the meaning of the `index` attribute on a `dim` operation is defined by -the `dim` operation. Dialect attributes, on the other hand, derive their context -and meaning from a specific dialect. An example of a dialect attribute may be a -`swift.self` function argument attribute that indicates an argument is the -self/context parameter. The context of this attribute is defined by the `swift` -dialect and not the function argument. +The top-level attribute dictionary attached to an operation has special +semantics. The attribute entries are considered to be of two different kinds +based on whether their dictionary key has a dialect prefix: -Attribute values are represented by the following forms: +- *inherent attributes* are inherent to the definition of an operation's + semantics. The operation itself is expected to verify the consistency of these + attributes. An example is the `predicate` attribute of the `std.cmpi` op. + These attributes must have names that do not start with a dialect prefix. -``` -attribute-value ::= attribute-alias | dialect-attribute | builtin-attribute -``` +- *discardable attributes* have semantics defined externally to the operation + itself, but must be compatible with the operations's 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. + +Note that attribute values are allowed to themselves be dictionary attributes, +but only the top-level dictionary attribute attached to the operation is subject +to the classification above. ### Attribute Value Aliases @@ -1404,8 +1407,8 @@ attribute values. ### Builtin Attribute Values Builtin attributes are a core set of -[dialect attributes](#dialect-attribute-values) that are defined in a builtin -dialect and thus available to all users of MLIR. +[dialect attribute values](#dialect-attribute-values) that are defined in a +builtin dialect and thus available to all users of MLIR. ``` builtin-attribute ::= affine-map-attribute