[mlir] Decouple enum generation from attributes, adding EnumInfo and EnumCase (#132148)

This commit pulls apart the inherent attribute dependence of classes
like EnumAttrInfo and EnumAttrCase, factoring them out into simpler
EnumCase and EnumInfo variants. This allows specifying the cases of an
enum without needing to make the cases, or the EnumInfo itself, a
subclass of SignlessIntegerAttrBase.

The existing classes are retained as subclasses of the new ones, both
for backwards compatibility and to allow attribute-specific information.

In addition, the new BitEnum class changes its default printer/parser
behavior: cases when multiple keywords appear, like having both nuw and
nsw in overflow flags, will no longer be quoted by the operator<<, and
the FieldParser instance will now expect multiple keywords. All
instances of BitEnumAttr retain the old behavior.

Author: krzysz00

mlir/docs/DefiningDialects/Operations.md

@@ -1498,22 +1498,17 @@ optionality, default values, etc.:
 *   `AllAttrOf`: adapts an attribute with
     [multiple constraints](#combining-constraints).
 
-### Enum attributes
+## Enum definition
 
-Some attributes can only take values from a predefined enum, e.g., the
-comparison kind of a comparison op. To define such attributes, ODS provides
-several mechanisms: `IntEnumAttr`, and `BitEnumAttr`.
+MLIR is capabable of generating C++ enums, both those that represent a set
+of values drawn from a list or that can hold a combination of flags
+using the `IntEnum` and `BitEnum` classes, respectively.
 
-*   `IntEnumAttr`: each enum case is an integer, the attribute is stored as a
-    [`IntegerAttr`][IntegerAttr] in the op.
-*   `BitEnumAttr`: each enum case is a either the empty case, a single bit,
-    or a group of single bits, and the attribute is stored as a
-    [`IntegerAttr`][IntegerAttr] in the op.
-
-All these `*EnumAttr` attributes require fully specifying all of the allowed
-cases via their corresponding `*EnumAttrCase`. With this, ODS is able to
+All these `IntEnum` and `BitEnum` classes require fully specifying all of the allowed
+cases via a `EnumCase` or `BitEnumCase` subclass, respectively. With this, ODS is able to
 generate additional verification to only accept allowed cases. To facilitate the
-interaction between `*EnumAttr`s and their C++ consumers, the
+interaction between tablegen enums and the attributes or properties that wrap them and
+to make them easier to use in C++, the
 [`EnumsGen`][EnumsGen] TableGen backend can generate a few common utilities: a
 C++ enum class, `llvm::DenseMapInfo` for the enum class, conversion functions
 from/to strings. This is controlled via the `-gen-enum-decls` and
@@ -1522,10 +1517,10 @@ from/to strings. This is controlled via the `-gen-enum-decls` and
 For example, given the following `EnumAttr`:
 
 ```tablegen
-def Case15: I32EnumAttrCase<"Case15", 15>;
-def Case20: I32EnumAttrCase<"Case20", 20>;
+def Case15: I32EnumCase<"Case15", 15>;
+def Case20: I32EnumCase<"Case20", 20>;
 
-def MyIntEnum: I32EnumAttr<"MyIntEnum", "An example int enum",
+def MyIntEnum: I32Enum<"MyIntEnum", "An example int enum",
                            [Case15, Case20]> {
   let cppNamespace = "Outer::Inner";
   let stringToSymbolFnName = "ConvertToEnum";
@@ -1611,14 +1606,17 @@ std::optional<MyIntEnum> symbolizeMyIntEnum(uint32_t value) {
 Similarly for the following `BitEnumAttr` definition:
 
 ```tablegen
-def None: I32BitEnumAttrCaseNone<"None">;
-def Bit0: I32BitEnumAttrCaseBit<"Bit0", 0, "tagged">;
-def Bit1: I32BitEnumAttrCaseBit<"Bit1", 1>;
-def Bit2: I32BitEnumAttrCaseBit<"Bit2", 2>;
-def Bit3: I32BitEnumAttrCaseBit<"Bit3", 3>;
-
-def MyBitEnum: BitEnumAttr<"MyBitEnum", "An example bit enum",
-                           [None, Bit0, Bit1, Bit2, Bit3]>;
+def None: I32BitEnumCaseNone<"None">;
+def Bit0: I32BitEnumCaseBit<"Bit0", 0, "tagged">;
+def Bit1: I32BitEnumCaseBit<"Bit1", 1>;
+def Bit2: I32BitEnumCaseBit<"Bit2", 2>;
+def Bit3: I32BitEnumCaseBit<"Bit3", 3>;
+
+def MyBitEnum: I32BitEnum<"MyBitEnum", "An example bit enum",
+                           [None, Bit0, Bit1, Bit2, Bit3]> {
+  // Note: this is the default value, and is listed for illustrative purposes.
+  let separator = "|";
+}
 ```
 
 We can have:
@@ -1738,6 +1736,26 @@ std::optional<MyBitEnum> symbolizeMyBitEnum(uint32_t value) {
 }
 ```
 
+### Wrapping enums in attributes
+
+There are several mechanisms for creating an `Attribute` whose values are
+taken from a `*Enum`.
+
+The most common of these is to use the `EnumAttr` class, which takes
+an `EnumInfo` (either a `IntEnum` or `BitEnum`) as a parameter and constructs
+an attribute that holds one argument - value of the enum. This attribute
+is defined within a dialect and can have its assembly format customized to,
+for example, print angle brackets around the enum value or assign a mnemonic.
+
+An older form involves using the `*IntEnumAttr` and `*BitEnumATtr` classes
+and their corresponding `*EnumAttrCase` classes (which can be used
+anywhere a `*EnumCase` is needed). These classes store their values
+as a `SignlessIntegerAttr` of their bitwidth, imposing the constraint on it
+that it has a value within the valid range of the enum. If their
+`genSpecializedAttr` parameter is set, they will also generate a
+wrapper attribute instead of using a bare signless integer attribute
+for storage.
+
 ## Debugging Tips
 
 ### Run `mlir-tblgen` to see the generated content