[PATCH] D78044: [mlir][ods] Update doc regarding attribute definitions

[Lei Zhang via Phabricator via llvm-commits]

antiagainst created this revision.
antiagainst added reviewers: jpienaar, rriddle.
Herald added subscribers: llvm-commits, frgossen, grosul1, Joonsoo, liufengdb, aartbik, lucyrfox, mgester, arpith-jacob, nicolasvasilache, shauheen, burmako, mehdi_amini.
Herald added a project: LLVM.

Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D78044

Files:
  mlir/docs/OpDefinitions.md


Index: mlir/docs/OpDefinitions.md
===================================================================
--- mlir/docs/OpDefinitions.md
+++ mlir/docs/OpDefinitions.md
@@ -1016,6 +1016,35 @@
 
 ## Attribute Definition
 
+An attribute is a compile-time known constant of an operation.
+
+ODS provides attribute wrappers over C++ attribute classes. There are a few
+common C++ [attribute classes][AttrClasses] defined in MLIR's core IR library
+and one is free to define dialect-specific attribute classes. ODS allows one
+to use these attributes in TableGen to define operations, potentially with
+more fine-grained constraints. For example, `StrAttr` directly maps to
+`StringAttr`; `F32Attr`/`F64Attr` requires the `FloatAttr` to additionally
+be of a certain bitwidth.
+
+ODS attributes are defined as having a storage type (corresponding to a backing
+`mlir::Attribute` that _stores_ the attribute), a return type (corresponding to
+the C++ _return_ type of the generated of the helper getters) as well as method
+to convert between the internal storage and the helper method.
+
+### Attribute decorators
+
+There are a few important attribute adapters/decorators/modifers that can be
+applied to ODS attributes to specify common additional properties like
+optionality, default values, etc.:
+
+*   `DefaultValuedAttr`: decorates an attribute with a default value. See
+    [attributes with default values](#attributes-with-default-values) for
+    how to use.
+*   `OptionalAttr`: marks an attribute as optional. See
+    [optional attributes](#optional-attributes) for how to use.
+*   `Confined`: adapts an attribute with further constraints. See
+    [confining attributes](#confining-attributes) for how to use.
+
 ### Enum attributes
 
 Some attributes can only take values from an predefined enum, e.g., the
@@ -1228,19 +1257,6 @@
 }
 ```
 
-TODO(b/132506080): This following is outdated. Update it.
-
-An attribute is a compile time known constant of an operation. Attributes are
-required to be known to construct an operation (e.g., the padding behavior is
-required to fully define the `conv2d` op).
-
-Attributes are defined as having a storage type (corresponding to a derived
-class of `mlir::Attribute`), a return type (that corresponds to the C++ type to
-use in the generation of the helper accessors) as well as method to convert
-between the internal storage and the helper method. Derived attributes are a
-special class of attributes that do not have storage but are instead calculated
-based on the operation and its attributes.
-
 ## Debugging Tips
 
 ### Run `mlir-tblgen` to see the generated content
@@ -1344,3 +1360,4 @@
 [EnumsGen]: ../tools/mlir-tblgen/EnumsGen.cpp
 [StringAttr]: LangRef.md#string-attribute
 [IntegerAttr]: LangRef.md#integer-attribute
+[AttrClasses]: https://github.com/llvm/llvm-project/blob/master/mlir/include/mlir/IR/Attributes.h


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D78044.257052.patch
Type: text/x-patch
Size: 2882 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20200413/2b4a35a0/attachment.bin>