mlir(google/heir)operation

(1)TableGen 语法

TableGen Syntax 

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 the filename suffix .td) can be found here.

• TableGen class is similar to C++ class; it can be templated and subclassed.
• TableGen def is similar to C++ object; it can be declared by specializing a TableGen class (e.g., def MyDef : MyClass<...>;) or completely independently (e.g., def MyDef;). It cannot be further templated or subclassed.
• TableGen dag is a dedicated type for directed acyclic graph of elements. A dag has one operator and zero or more arguments. Its syntax is (operator arg0, arg1, argN). The operator can be any TableGen def; an argument can be anything, including dag itself. We can have names attached to both the operator and the arguments like (MyOp:$op_name MyArg:$arg_name).

理解：

TableGen是有自己的语法的，并且有自己的中文技术手册。TableGen源码文件后缀通常是”.td”。

• TableGen class和C++ class相似，也可以被模板化和子类化
• TableGen def和C++ object相似，既可以实例化TableGen class（比如def MyDef : MyClass<...>;），也可以独立使用（比如def MyDef;）。但是def不可以像class那样被模板化和子类化。
• TableGen dag：不常用，用到了再详细看这个。

(2)Operation定义

Operation Definition 

MLIR defines several common constructs to help operation definition and provide their semantics via a special TableGen backend: OpDefinitionsGen. These constructs are defined in OpBase.td. 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 help of the following constructs.
• The Dialect class: Operations belonging to one logical group are placed in the same dialect. The Dialect class contains dialect-level information.
• The OpTrait class hierarchy: They are used to specify special properties 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 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 Type, which stands for constraints for common C++ types.
• The AttrConstraint class hierarchy: They are used to specify the constraints over attributes. A notable subclass hierarchy is Attr, which stands for constraints for attributes whose values are of common types.
• The Property class hierarchy: They are used to specify non-attribute-backed properties that are inherent to operations. These properties can have constraints imposed on them using the predicate field or the ConfinedProp class.

理解：可以在TableGen中利用一些现成的constructs来定义operation，它的TableGen后端是llvm-project/mlir/tools/mlir-tblgen/OpDefinitionsGen.cpp，现成的TableGen op的constructs定义在llvm-project/mlir/include/mlir/IR/OpBase.td。主要的constructs如下：

• TableGen Op class：定义operation时候用；
• TableGen Dialect class：定义dialect时候用；
• 记号“ins/outs”：这两个是TableGen后端OpDefinitionsGen中内置的记号，“ins”用在operands/attributes中，“outs”用在results中。

(3)Operation的名字

Operation name 

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 rewrites.

The full operation name is composed of the dialect name and the op name, with the former provided via the dialect and the latter provided as the second template parameter to the Op class.

理解：在MLIR上下文中，每个operation的完整名字都是唯一。完整名字由两个部分组成，第一个部分是方言名字，第二部分是TableGen class “Op”中的模板中的第二个参数”string mnemonic”。比如“tf.Add”

(4)Operation的说明文档

Operation documentation 

This includes both a one-line summary and a longer human-readable description. They will be used to drive automatic generation of dialect documentation. They need to be provided in the operation’s definition body:

let summary = "...";
let description = [{
...
}];

理解：在TableGen class “op”的实例中，字段summary的值是一行字串，字段description的值是多行字串，这两个字段的值是关于此operation的说明信息。

(5)Operation的参数

Operation arguments 

There are three kinds of arguments: operands, attributes, and properties. Operands are runtime values produced by other ops; while attributes and properties are compile-time known constant values;

Properties are similar to attributes, except that they are not stored within the MLIR context but are stored inline with the operation.

Operands, attributes, and properties are specified inside the dag-typed arguments, led by ins:

let arguments = (ins
  <type-constraint>:$<operand-name>,
  ...
  <attr-constraint>:$<attr-name>,
  ...
  <property>:$<property-name>,
);

Here <type-constraint> is a TableGen def from the TypeConstraint class hierarchy. Similarly, <attr-constraint> is a TableGen def from the AttrConstraint class hierarchy and <property> is a subclass of Property (constraints can be imposed onto it using its predicate field or the ConfinedProp subclass).

理解：字段arguments的值是一个用逗号隔开的可变长度列表，列表中的元素的类型有三种：operands，attributes和properties。Operands是运行时由其他ops创建的，而attributes和properties是在编译时就可以确定的。properties和attributes类似，但是properties不会存储在MLIR context上，而是存储在operation内。字段arguments的类型是dag，该字段的值以关键字“ins”开头，例子如上。其中，<type-constraint>是TableGen中通过def对TableGen TypeConstraint class的实例，<attr-constraint>是TableGen中通过def对TableGen AttrConstraint class的实例，<property>是Property的子类。

5.1 可选的类型参数

Optional operands 

To declare an optional operand, wrap the TypeConstraint for the operand with Optional<...>.

理解：字段arguments的值中的列表中的某个元素可以是可选的operand，元素类型用Optional<...>，括号里面是TableGen中通过def对TableGen TypeConstraint class的实例。

5.2 可选的属性参数

Optional attributes 

To declare an optional attribute, wrap the AttrConstraint for the attribute with OptionalAttr<...>.

理解：字段arguments的值中的列表中的某个元素可以是可选的attributes，元素类型用OptionalAttr<...>，括号里面是通过def对TableGen AttrConstraint class的实例类。

例子：

// LWE Operations are always Pure by design
class LWE_Op<string mnemonic, list<Trait> traits = []> :
        Op<LWE_Dialect, mnemonic,  traits # [Pure]> {
  let cppNamespace = "::mlir::heir::lwe";
  let assemblyFormat = [{
    operands attr-dict `:`  functional-type(operands, results)
  }];
}

def LWE_TrivialEncryptOp: LWE_Op<"trivial_encrypt", [
    EncodingsMatch<"input", "LWEPlaintextType", "output", "LWECiphertextType">]> {
  let summary = "Create a trivial encryption of a plaintext.";

  let arguments = (ins
    LWEPlaintext:$input,
    OptionalAttr<LWE_LWEParams>:$params
  );

  let results = (outs LWECiphertext:$output);

  let assemblyFormat = [{
    operands attr-dict `:`  qualified(type(operands)) `to` qualified(type(results))
  }];

  // Verify that the LWE params matches the output ciphertext LWE params and
  // that the encodings of the input and output match.
  let hasVerifier = 1;
}

 (6)operation的返回值

Operation results ¶

Similar to operands, results are specified inside the dag-typed results, led by outs:

let results = (outs
  <type-constraint>:$<result-name>,
  ...
);

理解：跟操作数（operands）类似，op的返回值用“let results=...”表示，其中字段results的类型是dag-typed，字段的值的开头要用记号“outs”。

(7)TableGen Op class的C++代码

Generated C++ code ¶

OpDefinitionsGen processes the op definition spec file and generates two files containing the corresponding C++ code: one for declarations, the other for definitions. The former is generated via the -gen-op-decls command-line option, while the latter is via the -gen-op-defs option.

The definition file contains all the op method definitions, which can be included and enabled by defining GET_OP_CLASSES. For each operation, OpDefinitionsGen generates an operation class and an operand adaptor class. Besides, it also contains a comma-separated list of all defined ops, which can be included and enabled by defining GET_OP_LIST.

理解：ODS（Operation Defination Specification）的TableGen后端llvm-project/mlir/tools/mlir-tblgen/OpDefinitionsGen.cpp可以基于TableGen文件（*.td）创建两个C++源码文件，给工具mlir-tblgen传入参数“-gen-op-decls”会创建用于声明性C++源码文件（*.h.inc），给工具mlir-tblgen传入参数“-gen-op-defs”会创建定义性C++源码文件（*.cpp.inc）。定义性C++源码文件里面给出了所有op的函数实现，启用这些定义性C++源码文件需要“#define GET_OP_CLASSES”。OpDefinitionsGen会给每一个op创建一个operation class，所有operation class类名，都会声明式地放在定义性C++源码文件的开头，比如：

mlir-tblgen  -gen-op-defs code/heir-private/lib/Dialect/LWE/IR/LWEOps.td -o LWEOps.cpp.inc

mlir-tblgen  -gen-op-decls code/heir-private/lib/Dialect/LWE/IR/LWEOps.td -o LWEOps.h.inc

#ifdef GET_OP_LIST
#undef GET_OP_LIST

::mlir::heir::lwe::AddOp,
::mlir::heir::lwe::EncodeOp,
::mlir::heir::lwe::MulScalarOp,
::mlir::heir::lwe::RAddOp,
::mlir::heir::lwe::RLWEDecodeOp,
::mlir::heir::lwe::RLWEDecryptOp,
::mlir::heir::lwe::RLWEEncodeOp,
::mlir::heir::lwe::RLWEEncryptOp,
::mlir::heir::lwe::RMulOp,
::mlir::heir::lwe::RNegateOp,
::mlir::heir::lwe::RSubOp,
::mlir::heir::lwe::TrivialEncryptOp,
::mlir::heir::lwe::ReinterpretApplicationDataOp
#endif  // GET_OP_LIST

#ifdef GET_OP_CLASSES
#undef GET_OP_CLASSES
...
//operation class的完整定义
...
#endif  // GET_OP_CLASSES

namespace mlir {
namespace heir {
namespace lwe {
class AddOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
namespace mlir {
namespace heir {
namespace lwe {
class EncodeOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
namespace mlir {
namespace heir {
namespace lwe {
class MulScalarOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
namespace mlir {
namespace heir {
namespace lwe {
class RAddOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
namespace mlir {
namespace heir {
namespace lwe {
class RLWEDecodeOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
namespace mlir {
namespace heir {
namespace lwe {
class RLWEDecryptOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
namespace mlir {
namespace heir {
namespace lwe {
class RLWEEncodeOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
namespace mlir {
namespace heir {
namespace lwe {
class RLWEEncryptOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
namespace mlir {
namespace heir {
namespace lwe {
class RMulOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
namespace mlir {
namespace heir {
namespace lwe {
class RNegateOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
namespace mlir {
namespace heir {
namespace lwe {
class RSubOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
namespace mlir {
namespace heir {
namespace lwe {
class TrivialEncryptOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
namespace mlir {
namespace heir {
namespace lwe {
class ReinterpretApplicationDataOp;
} // namespace lwe
} // namespace heir
} // namespace mlir
#ifdef GET_OP_CLASSES
#undef GET_OP_CLASSES

namespace mlir {
namespace heir {
namespace lwe {

//===----------------------------------------------------------------------===//
// ::mlir::heir::lwe::AddOp declarations
//===----------------------------------------------------------------------===//
.................

} // namespace lwe
} // namespace heir
} // namespace mlir
MLIR_DECLARE_EXPLICIT_TYPE_ID(::mlir::heir::lwe::ReinterpretApplicationDataOp)


#endif  // GET_OP_CLASSES

(8)TableGen Op的mlir格式

Declarative Assembly Format ¶

The custom assembly form of the operation may be specified in a declarative string that matches the operations operands, attributes, etc. With the ability to express additional information that needs to be parsed to build the operation:

def CallOp : Std_Op<"call", ...> {
  let arguments = (ins FlatSymbolRefAttr:$callee, Variadic<AnyType>:$args);
  let results = (outs Variadic<AnyType>);
  let assemblyFormat = [{
    $callee `(` $args `)` attr-dict `:` functional-type($args, results)
  }];
}

理解：指令格式是指用于解析和打印的mlir格式，在TableGen中用“let assemblyFormat”定义op的mlir格式，字段assemblyFormat的值由三部分组成：指令、字面量、变量。

8.1.变量

Variables ¶

A variable is an entity that has been registered on the operation itself, i.e. an argument(attribute or operand), region, result, successor, etc. In the CallOp example above, the variables would be $callee and $args.

理解：op TableGen中的字段assemblyFormat的值中的变量是美元符号“$”开头的，取值字段arguments和字段results中的值。

8.2 字面量

Literals ¶

A literal is either a keyword or punctuation surrounded by ``.

理解：字面量是用符号``抱起来的关键字或者标点符号。有效的标点符号有：

:, ,, =, <, >, (, ), {, }, [, ], ->, ?, +, *

 以下符号表示是空白的换行符：

\n,

例子：

let assemblyFormat = [{
  `{` `\n` ` ` ` ` `this_is_on_a_newline` `\n` `}` attr-dict
}];
对应的MLIR格式：
%results = my.operation {
  this_is_on_a_newline
}

8.3.指令

Directives ¶

A directive is a type of builtin function, with an optional set of arguments. The available directives are as follows:

1.attr-dict

• l Represents the attribute dictionary of the operation.
• l Any inherent attributes that are not used elsewhere in the format are printed as part of the attribute dictionary unless a prop-dict is present.
• l Discardable attributes are always part of the attr-dict.

2.functional-type ( inputs , outputs )

• l Formats the inputs and outputs arguments as a function type.
• l The constraints on inputs and outputs are the same as the input of the type directive.

3.operands

• l Represents all of the operands of an operation.

4.results

• l Represents all of the results of an operation.

5.type ( input )

• l Represents the type of the given input.
• l input must be either an operand or result variable, the operands directive, or the results directive.

6.qualified ( type_or_attribute )

• l Wraps a type directive or an attribute parameter.
• l Used to force printing the type or attribute prefixed with its dialect and mnemonic. For example the vector.multi_reduction operation has a kind attribute ; by default the declarative assembly will print: vector.multi_reduction <minf>, ... but using qualified($kind) in the declarative assembly format will print it instead as: vector.multi_reduction #vector.kind<minf>, ....

理解：指令是指TableGen op的内建函数，有的指令还要求输入参数。以下是常用指令：

1.attr-dict: op的属性字典

2.functional-type(inputs,outputs): 表示从inputs到outpust的映射，语法如下：

// Function types may have multiple results.
function-result-type ::= type-list-parens | non-function-type
function-type ::= type-list-parens `->` function-result-type

 实例：以下“(%arg0 : i64) -> i64”就是functional-type的实例

func.func @add_one(%arg0 : i64) -> i64 {
  %c1 = arith.constant 1 : i64
  %0 = arith.addi %arg0, %c1 : i64
  return %0 : i64
}

 3.operands: 表示op TableGen中的“let arguments=...”。

4.results: 表示op TableGen中的“let results=...”。

5.type(input): 表示input的type，其中输入参数input必须取之“let arguments=...”或者“let results=...”中的一个变量。

6.qualified(type_or_attribute): 其中type_or_attribute常常就是指令type，比如qualified(type($input))。指令qualified会强制输出type或者attribute的带有dialect和mnemonic的前缀，比如vector.multi_reduction operation有一个attribute类型的变量$kind，默认情况下会输出格式“vector.multi_reduction <minf>”,但是当使用qualified($kind)后，输出格式变成了“ vector.multi_reduction #vector.kind<minf>”。

(9)约束

Constraints ¶

Constraint is a core concept in table-driven operation definition: operation verification and graph operation matching are all based on satisfying constraints. So both the operation definition and rewrite rules specification significantly involve writing constraints. We have the Constraint class in OpBase.td as the common base class for all constraints.

An operation’s constraint can cover different range; it may

• l Only concern a single attribute (e.g. being a 32-bit integer greater than 5),
• l Multiple operands and results (e.g., the 1st result’s shape must be the same as the 1st operand), or
• l Intrinsic to the operation itself (e.g., having no side effect).

We call them as single-entity constraint, multi-entity constraint, and traits, respectively.

约束（constraints）是基于表驱动的TableGen中定义op的核心概念，operation verification和graph operation matching都是基于约束（constraints）实现的。所以TableGen中的op定义和rewrite rules都都很多关于约束（constraints）的实现。在llvm-project/mlir/include/mlir/IR/OpBase.td中定义的TableGen Constraint class是所有约束（constraints）的公共基类。一个op的约束可以分为三类：

• l 单实例约束：只对一个attribute或type的约束（比如约束一个32-bit整数值必须大于5）
• l 多实例约束：会对多个operants和results做约束（比如约束第一个results必须和第一个operand的类型必须是相同的）
• l 特征（traits）：operation本身的固有约束。

9.1.单实例约束

Single-entity constraint ¶

Constraints scoped to a single operand, attribute, or result are specified at the entity’s declaration place as described in Operation arguments and Operation results.

To help modelling constraints of common types, a set of TypeConstraints are created; they are the Type subclass hierarchy. It includes F32 for the constraints of being a float, TensorOf<[F32]> for the constraints of being a float tensor, and so on.

Similarly, a set of AttrConstraints are created for helping modelling constraints of common attribute kinds. They are the Attr subclass hierarchy. It includes F32Attr for the constraints of being a float attribute, F32ArrayAttr for the constraints of being a float array attribute, and so on.

理解：单实例约束是只约束单个operand，或者单个attribute，或者单个result。

常见的type约束模型的定义在“llvm-project/mlir/include/mlir/IR/CommonTypeConstraints.td”，type约束模型是TableGen Type class的子类，比如F32表示32位浮点类型。`TensorOf<[F32]>` 是 MLIR 中用于描述 **元素类型为 32 位浮点数（`F32`）的张量** 的类型约束。它确保操作的输入或输出类型是张量，并且其元素类型为 `F32`。

常见的attribute约束模型的定义在“llvm-project/mlir/include/mlir/IR/CommonAttrConstraints.td”，attribute约束模型是TableGen Attr class的子类，比如F32Attr。

例子：

1.使用F32Attr，属性约束，用于描述和验证操作的属性值是否是 32 位浮点数。
def SomeOp : Op<"some_op", []> {
  let arguments = (ins F32Attr:$attr);
}
%result = some_op {attr = 3.14 : f32}

2.使用F32，类型约束，用于描述和验证操作的输入或输出类型是否是 32 位浮点类型。
def SomeOp : Op<"some_op", []> {
  let arguments = (ins F32:$input);
  let results = (outs F32:$output);
}
%result = some_op %input : f32 -> f32

9.2.多实例约束

Multi-entity constraint ¶

Constraints involving more than one operand/attribute/result are quite common on operations, like the element type and shape relation between operands and results. These constraints should be specified as the Op class template parameter as described in Operation traits and constraints.

Multi-entity constraints are modeled as PredOpTrait (a subclass of OpTrait) in OpBase.td.A bunch of constraint primitives are provided to help specification. See OpBase.td for the complete list.

理解：多实例约束是指对多个operand/attribute/result同时约束。多实例约束应该在TablGen Op class的模板参数中指定。多实例约束是定义在文件llvm-project/mlir/include/mlir/IR/OpBase.td里面的TableGen PredOpTrait class的子类。

例子：

class HasEncoding<
  string encodingHolder,
  string encoding,
  string ty,
  string comparator = "std::equal_to<>()"
> : PredOpTrait<
    "the first arg's type's encoding matches the given encoding",
    CPred<
      comparator # "(" #
      "::llvm::cast<lwe::" # ty # ">($" # encodingHolder # ".getType()).getEncoding(), " #
      "$" # encoding # ")"
    >
  >;


// LWE Operations are always Pure by design
class LWE_Op<string mnemonic, list<Trait> traits = []> :
        Op<LWE_Dialect, mnemonic,  traits # [Pure]> {
  let cppNamespace = "::mlir::heir::lwe";
  let assemblyFormat = [{
    operands attr-dict `:`  functional-type(operands, results)
  }];
}


def LWE_EncodeOp : LWE_Op<"encode", [HasEncoding<"output", "encoding", "LWEPlaintextType">]> {
  let summary = "Encode an integer to yield an LWE plaintext";
  let description = [{
    Encode an integer to yield an LWE plaintext.

    This op uses a an encoding attribute to encode the bits of the integer into
    an LWE plaintext value that can then be encrypted.

    Examples:

    ```
    %Y = lwe.encode %value {encoding = #enc}: i1 to !lwe.lwe_plaintext<encoding = #enc>
    ```
  }];

  let arguments = (ins
    SignlessIntegerOrFloatLike:$input,
    AnyLWEEncodingAttr:$encoding
  );

  let results = (outs LWEPlaintext:$output);
  let assemblyFormat = "$input attr-dict `:` qualified(type($input)) `to` qualified(type($output))";

  // Verify that the input type and the encoding are compatible.
  let hasVerifier = 1;
}

mlir-tblgen  -gen-op-defs code/heir-private/lib/Dialect/LWE/IR/LWEOps.td -o LWEOps.cpp.inc

::llvm::LogicalResult EncodeOp::verifyInvariantsImpl() {
  auto tblgen_encoding = getProperties().encoding; (void)tblgen_encoding;
  if (!tblgen_encoding) return emitOpError("requires attribute 'encoding'");

  if (::mlir::failed(__mlir_ods_local_attr_constraint_LWEOps1(*this, tblgen_encoding, "encoding")))
    return ::mlir::failure();
  {
    unsigned index = 0; (void)index;
    auto valueGroup0 = getODSOperands(0);

    for (auto v : valueGroup0) {
      if (::mlir::failed(__mlir_ods_local_type_constraint_LWEOps2(*this, v.getType(), "operand", index++)))
        return ::mlir::failure();
    }
  }
  {
    unsigned index = 0; (void)index;
    auto valueGroup0 = getODSResults(0);

    for (auto v : valueGroup0) {
      if (::mlir::failed(__mlir_ods_local_type_constraint_LWEOps3(*this, v.getType(), "result", index++)))
        return ::mlir::failure();
    }
  }
  if (!((std::equal_to<>()(::llvm::cast<lwe::LWEPlaintextType>((*this->getODSResults(0).begin()).getType()).getEncoding(), getEncoding()))))
    return emitOpError("failed to verify that the first arg's type's encoding matches the given encoding");
  return ::mlir::success();
}

9.3.特征

Trait ¶

Traits are intrinsic properties of the operation like having side effect or not, commutative or not, whether is a terminator, etc. These constraints should be specified as the Op class template parameter as described in Operation traits and constraints.

Traits are modeled as NativeOpTrait (a subclass of OpTrait) in OpBase.td. They are backed and will be translated into the corresponding C++ mlir::OpTrait classes.

理解：特征（trait）是operation的固有属性，这类约束也是在TableGen Op class的模板参数中指定。特征（trait）是定义在文件llvm-project/mlir/include/mlir/IR/OpBase.td里面的TableGen NativeOpTrait class的子类。