[mlir] Introduce more intuitive wording for attributes.

[silvas]

Summary

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<N> for func).
• characteristic: unless you have a math background this probably doesn't make as much sense

[silvas]

slight tweak

[jdd]

“Intrinsic” makes me think of compiler intrinsics, which this is not. I like “property” since they are necessary properties of ops. I don’t have a strong preference other than the rejection reasons you give.

[mehdi_amini]

@jdd raises a good point about "intrinsic" being overloaded, which would tilt the scale towards "inherent" instead for me.

[silvas]

In D96093#2543846, @jdd wrote:

“Intrinsic” makes me think of compiler intrinsics, which this is not. I like “property” since they are necessary properties of ops. I don’t have a strong preference other than the rejection reasons you give.

Agreed the clash with the notion of "compiler intrinsics" is a bit unfortunate. "inherent" is a bit better in that regard, but doesn't read as well.

I don't like "property" because it is ambiguous between two meanings, and they aren't a terribly good fit anyway:

1. the abstract notion of "property" of a thing (e.g. a dog has a property which is its "fur color")
2. the object oriented notion of property (e.g. related to getters, setters) which is just an abstract slot on an object.

I reject 1) because frequently a single "abstract property" is spread across multiple different intrinsic attributes. E.g. you might have 2 parallel array attributes that relate to each other and overall define an abstract property, but individually they do not. E.g. "foo.dog" { fur_color_regions = ["head", "body", "tail"], fur_colors = ["black", "brown", "spotted"] }.

I reject 2) because "slot on an object" doesn't really carry much information in this context -- I would prefer something that suggests "the op has special knowledge of these attributes" somehow.

[lattner]

I think that "inherent" is a bit more specific than "intrinsic" and avoids confusion with llvm intrinsics etc, but it is a slight difference either way.

I don't think that "annotation attributes" works well. That seems redundant and doesn't convey the difference here well. I'd go with something like: discardable, foreign, unknown, external, extensible, etc. I am not sure what the concern about negative connotations is. If anything, we *want* to discourage people from using these for stable data, that's the whole idea :-)

mlir/docs/LangRef.md

305

s/dim/std.dim/ ?

[bondhugula]

"inherent" (or "core") and "external" are looking good to me. Thanks!

[silvas]

Switch to inherent/discardable.

[silvas]

minor wording tweak

[mehdi_amini]

(please wait for at least one more LGTM)

[rriddle]

LGTM. +1 on inherent/discardable

mlir/docs/LangRef.md

1334

[silvas]

Address River's comment

[lattner]

This is great, thank you again for clarifying this!

mlir/docs/LangRef.md

 many different levels of abstractions and computations. Operations in MLIR are
 fully extensible (there is no fixed list of operations) and have
 application-specific semantics. For example, MLIR supports [target-independent
 operations](Dialects/Standard.md#memory-operations), [affine
 operations](Dialects/Affine.md), and [target-specific machine
 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:
 
 ```mlir
 // An operation that produces two results.
 // The results of %result can be accessed via the <name> `#` <opNo> syntax.
 %result:2 = "foo_div"() : () -> (f32, i32)
 
 // Pretty form that defines a unique name for each result.
 %foo, %bar = "foo_div"() : () -> (f32, i32)
 
 // 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.
 This allows those dialects to support _custom assembly form_ for parsing and
 printing operations. In the operation sets listed below, we show both forms.
 
 ### Terminator Operations
 

 `vector<0x42xi32>` is invalid because it is interpreted as a 2D vector with
 shape `(0, 42)` and zero shapes are not allowed.
 
 ## Attributes
 
 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.
-
-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.
-
-Attribute values are represented by the following forms:
-
-```
-attribute-value ::= attribute-alias | dialect-attribute | builtin-attribute
-```
+[`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).
+
+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:
+
+- *intrinsic attributes* are intrinsic 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.
+
+- *annotation attributes* have semantics defined externally to the operation
+  itself and must be compatible with the operations's semantics. The dialect
+  indicated by the dialect prefix is expected to verify these attributes. An
+  example is the `gpu.container_module` attribute. These attributes must have
+  names that start with a dialect prefix.
+
+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
 
 ```
 attribute-alias-def ::= '#' alias-name '=' attribute-value
 attribute-alias ::= '#' alias-name
 ```
 

 `<>` characters.
 
 See [here](Tutorials/DefiningAttributesAndTypes.md) on how to define dialect
 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
                        | array-attribute
                        | bool-attribute
                        | dictionary-attribute
                        | elements-attribute
                        | float-attribute