[mlir][ods] add mechanism for deprecating an `OpBuilder` in ODS

[zero9178]

Summary

This allows discouraging the use of specific build methods of an op by having TableGen generate C++ code, instructing the C++ compiler to warn on use of the build method.
The implementation uses the C++14 [[deprecated(...)]] for this purpose. I considered using LLVM_DEPRECATED`, but thought requiring a fix-it was not necassery, nor would the syntax in ODS have been very nice.

My motivation for this change is that in the future I'd like to deprecate the use build methods in the LLVM Dialect, not using explicit pointer types for ops such as llvm.load or llvm.alloca, which makes the code not future proof for opaque pointers. In-tree has to be clean first before I could commit such a change of course, but I thought the initial infrastructure change could already be submitted.

[Mogball]

Was there a discourse discussion on this? I might've missed it. If there isn't, I'm 100% behind the rationale I think is behind this change, but I would still like to see it discussed.

mlir/lib/TableGen/Class.cpp

117

qq: I assume this is relatively portable?

[zero9178]

In D143190#4100399, @Mogball wrote:

Was there a discourse discussion on this? I might've missed it. If there isn't, I'm 100% behind the rationale I think is behind this change, but I would still like to see it discussed.

I am assuming you're talking about the switch to opaque pointers? No not yet, which is why it is also not part of this change. I am planning to post a PSA on the forum once the in-tree infrastructure is there. That mostly means having conversion passes work with both typed and opaque pointers (which is what I am currently working on).
Until then users of many upstream dialects are not able to switch fully.

That said, the build methods with explicit pointer types work with typed pointers as well so we could introduce the warning earlier if we wanted to to encourage downstream to use opaque pointer compatible GEPs, loads and alloca APIs. Do you think that'd be worth doing?

mlir/lib/TableGen/Class.cpp

117

Yes, this has been a feature since C++14, so well within our supported compilers.
This is also the Form used by LLVM_DEPRECATED for compilers that aren't clang.

[rriddle]

The rationale makes sense to me, but in terms of ODS implementation have you considered defining a base "deprecated" class that is used as a mixin for OpBuilder? I'm a bit worried about adhoc additions of deprecation, and would prefer if we had a consistent story.

[zero9178]

Address review comments:
Create mixin that can be used for a consistent interface in ODS for marking an entity as deprecated within C++.
Also changes the interface from modifying OpBuilder to adding DeprecatedOpBuilder, making use of the above mixin. The reason for doing so is that OpBuilder are basically always used as anonymous defs, making it impossible to add a mixin to its instantiation. Therefore DeprecatedOpBuilder is used to keep the convenient syntax.
Other kinds of defs in ODS (such as Op ones) should not suffer from this problem. The mixin still has to be supported by the C++ code generator of a given entity, but I don't think there is any way around that.

[rriddle]

In there a nice spot in the ODS doc to add info for this?

[zero9178]

add documentation in Operations.md

[jpienaar]

Nice, thanks

mlir/include/mlir/IR/OpBase.td

 // OpBuilder<(ins "int":$integerArg, CArg<"float", "3.0f">:$floatArg)>
 // ```
 //
 // has an integer parameter and a float parameter with a default value.
 //
 // If an empty string is passed in for `body`, then *only* the builder
 // declaration will be generated; this provides a way to define complicated
 // builders entirely in C++.
-class OpBuilder<dag p, code b = ""> {
+//
+// Optionally, a deprecation message can be passed as third parameter, marking
+// the generated 'build' method as deprecated using the specified message if
+// the message is not empty.
+class OpBuilder<dag p, code b = "", string d = ""> {
   dag dagParams = p;
   code body = b;
+  string deprecated_message = d;
 }
 
 // A base decorator class that may optionally be added to OpVariables.
 class OpVariableDecorator;
 
 // Class for providing additional information on the variables, i.e. arguments
 // and results, of an operation.
 class OpVariable<Constraint varConstraint, string desc = "",

mlir/include/mlir/TableGen/Builder.h

public:
   Builder(const llvm::Record *record, ArrayRef<SMLoc> loc);
 
   /// Return a list of parameters used in this build method.
   ArrayRef<Parameter> getParameters() const { return parameters; }
 
   /// Return an optional string containing the body of the builder.
   std::optional<StringRef> getBody() const;
 
+  /// Return the deprecation message of the builder.
+  /// Empty optional if the builder is not deprecated.
+  std::optional<StringRef> getDeprecatedMessage() const;
+
 protected:
   /// The TableGen definition of this builder.
   const llvm::Record *def;
 
 private:
   /// A collection of parameters to the builder.
   SmallVector<Parameter> parameters;
 };
 
 } // namespace tblgen
 } // namespace mlir
 
 #endif // MLIR_TABLEGEN_BUILDER_H_

mlir/include/mlir/TableGen/Class.h

public:
 
   // Define move constructor and assignment operator to prevent copying.
   Method(Method &&) = default;
   Method &operator=(Method &&) = default;
 
   /// Get the method body.
   MethodBody &body() { return methodBody; }
 
+  /// Sets or removes the deprecation message of the method.
+  void setDeprecated(std::optional<StringRef> message) {
+    this->deprecationMessage = message;
+  }
+
   /// Returns true if this is a static method.
   bool isStatic() const { return properties & Static; }
 
   /// Returns true if this is a private method.
   bool isPrivate() const { return properties & Private; }
 
   /// Returns true if this is an inline method.
   bool isInline() const { return properties & Inline; }

 
 protected:
   /// A collection of method properties.
   Properties properties;
   /// The signature of the method.
   MethodSignature methodSignature;
   /// The body of the method, if it has one.
   MethodBody methodBody;
+  /// Deprecation message if the method is deprecated.
+  std::optional<std::string> deprecationMessage;
 };
 
 /// This enum describes C++ inheritance visibility.
 enum class Visibility { Public, Protected, Private };
 
 /// Write "public", "protected", or "private".
 llvm::raw_ostream &operator<<(llvm::raw_ostream &os,
                               mlir::tblgen::Visibility visibility);

mlir/lib/TableGen/Builder.cpp

Builder::Builder(const llvm::Record *record, ArrayRef<SMLoc> loc)
   }
 }
 
 /// Return an optional string containing the body of the builder.
 std::optional<StringRef> Builder::getBody() const {
   std::optional<StringRef> body = def->getValueAsOptionalString("body");
   return body && !body->empty() ? body : std::nullopt;
 }
+
+std::optional<StringRef> Builder::getDeprecatedMessage() const {
+  std::optional<StringRef> message =
+      def->getValueAsOptionalString("deprecated_message");
+  return message && !message->empty() ? message : std::nullopt;
+}

mlir/lib/TableGen/Class.cpp

if (bodyRef.back() != '\n')
     os << "\n";
 }
 
 //===----------------------------------------------------------------------===//
 // Method definitions
 //===----------------------------------------------------------------------===//
 
 void Method::writeDeclTo(raw_indented_ostream &os) const {
+  if (deprecationMessage) {
+    os << "[[deprecated(\"";
+    os.write_escaped(*deprecationMessage);
+    os << "\")]]\n";
+  }
   if (isStatic())
     os << "static ";
   if (properties & ConstexprValue)
     os << "constexpr ";
   methodSignature.writeDeclTo(os);
   if (isConst())
     os << " const";
   if (!isInline()) {

mlir/test/mlir-tblgen/op-decl-and-defs.td

let results = (outs
     Variadic<F32>:$s
   );
 
   let regions = (region
     AnyRegion:$someRegion,
     VariadicRegion<AnyRegion>:$someRegions
   );
   let builders = [OpBuilder<(ins "Value":$val)>,
-                  OpBuilder<(ins CArg<"int", "0">:$integer)>];
+                  OpBuilder<(ins CArg<"int", "0">:$integer)>,
+                  OpBuilder<(ins "float":$something), "",
+                            "the deprecation message">];
   let hasCustomAssemblyFormat = 1;
 
   let hasCanonicalizer = 1;
   let hasFolder = 1;
   let hasVerifier = 1;
 
   let extraClassDeclaration = [{
     // Display a graph for debugging purposes.

 // CHECK:   ::mlir::MutableArrayRef<::mlir::Region> getSomeRegions();
 // CHECK:   ::mlir::IntegerAttr getAttr1Attr()
 // CHECK:   uint32_t getAttr1();
 // CHECK:   ::mlir::FloatAttr getSomeAttr2Attr()
 // CHECK:   ::std::optional< ::llvm::APFloat > getSomeAttr2();
 // CHECK:   ::mlir::Attribute removeSomeAttr2Attr();
 // CHECK:   static void build(::mlir::OpBuilder &odsBuilder, ::mlir::OperationState &odsState, Value val);
 // CHECK:   static void build(::mlir::OpBuilder &odsBuilder, ::mlir::OperationState &odsState, int integer = 0);
+// CHECK{LITERAL}:   [[deprecated("the deprecation message")]]
+// CHECK:   static void build(::mlir::OpBuilder &odsBuilder, ::mlir::OperationState &odsState, float something);
 // CHECK:   static void build(::mlir::OpBuilder &odsBuilder, ::mlir::OperationState &odsState, ::mlir::Type r, ::mlir::TypeRange s, ::mlir::Value a, ::mlir::ValueRange b, ::mlir::IntegerAttr attr1, /*optional*/::mlir::FloatAttr some_attr2, unsigned someRegionsCount)
 // CHECK:   static void build(::mlir::OpBuilder &odsBuilder, ::mlir::OperationState &odsState, ::mlir::TypeRange resultTypes, ::mlir::Value a, ::mlir::ValueRange b, ::mlir::IntegerAttr attr1, /*optional*/::mlir::FloatAttr some_attr2, unsigned someRegionsCount);
 // CHECK:   static void build(::mlir::OpBuilder &odsBuilder, ::mlir::OperationState &odsState, ::mlir::Type r, ::mlir::TypeRange s, ::mlir::Value a, ::mlir::ValueRange b, uint32_t attr1, /*optional*/::mlir::FloatAttr some_attr2, unsigned someRegionsCount)
 // CHECK:   static void build(::mlir::OpBuilder &odsBuilder, ::mlir::OperationState &odsState, ::mlir::TypeRange resultTypes, ::mlir::Value a, ::mlir::ValueRange b, uint32_t attr1, /*optional*/::mlir::FloatAttr some_attr2, unsigned someRegionsCount);
 // CHECK:   static void build(::mlir::OpBuilder &, ::mlir::OperationState &odsState, ::mlir::TypeRange resultTypes, ::mlir::ValueRange operands, ::llvm::ArrayRef<::mlir::NamedAttribute> attributes, unsigned numRegions)
 // CHECK:   static ::mlir::ParseResult parse(::mlir::OpAsmParser &parser, ::mlir::OperationState &result);
 // CHECK:   void print(::mlir::OpAsmPrinter &p);
 // CHECK:   ::mlir::LogicalResult verifyInvariants();

mlir/tools/mlir-tblgen/OpDefinitionsGen.cpp

for (const Builder &builder : op.getBuilders()) {
 
     std::optional<StringRef> body = builder.getBody();
     auto properties = body ? Method::Static : Method::StaticDeclaration;
     auto *method =
         opClass.addMethod("void", "build", properties, std::move(arguments));
     if (body)
       ERROR_IF_PRUNED(method, "build", op);
 
+    if (method)
+      method->setDeprecated(builder.getDeprecatedMessage());
+
     FmtContext fctx;
     fctx.withBuilder(odsBuilder);
     fctx.addSubst("_state", builderOpState);
     if (body)
       method->body() << tgfmt(*body, &fctx);
   }
 
   // Generate default builders that requires all result type, operands, and