[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/docs/DefiningDialects/Operations.md

 # To see op interface C++ class definition
 mlir-tblgen --gen-op-interface-defs -I /path/to/mlir/include /path/to/input/td/file
 # To see op interface documentation
 mlir-tblgen --gen-op-interface-doc -I /path/to/mlir/include /path/to/input/td/file
 ```
 
 ## Appendix
 
-### Reporting deprecation
+### Reporting deprecation in TableGen
 
 Classes/defs can be marked as deprecated by using the `Deprecate` helper class,
 e.g.,
 
 ```tablegen
 def OpTraitA : NativeOpTrait<"OpTraitA">, Deprecated<"use `bar` instead">;
 ```
 
 would result in marking `OpTraitA` as deprecated and mlir-tblgen can emit a
 warning (default) or error (depending on `-on-deprecated` flag) to make
 deprecated state known.
 
+### Reporting deprecation in C++
+
+TableGen generated C++ entities, such as classes, functions or methods, can be
+marked as deprecated using the `CppDeprecated` mixin:
+
+```tablegen
+def MyOp : Op<MyDialect, "my.op">, CppDeprecated<"use 'your.op' instead">;
+```
+
+This differs to the deprecation mechanic for TableGen, in that no warning is
+emitted by mlir-tblgen. Rather, a warning with the given reason is emitted by
+the C++ compiler on use of the given entity.
+
+To allow more convenient syntax, helper classes exist for TableGen classes
+which are commonly used as anonymous definitions. These currently include:
+
+* `DeprecatedOpBuilder`: Can be used in place of `OpBuilder` with the same
+  arguments except taking the reason as first argument, e.g. 
+  `DeprecatedOpBuilder<"use 'build' with foo instead", (ins "int":$bar)>`
+
+Note: Support for the `CppDeprecated` mechanism has to be implemented by 
+every code generator separately. 
+
 ### Requirements and existing mechanisms analysis
 
 The op description should be as declarative as possible to allow a wide range of
 tools to work with them and query methods generated from them. In particular
 this means specifying traits, constraints and shape inference information in a
 way that is easily analyzable (e.g., avoid opaque calls to C++ functions where
 possible).
 

mlir/include/mlir/IR/DialectBase.td

 //===-- DialectBase.td - Base Dialect definition file ------*- tablegen -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
 // This file contains the base set of constructs for defining Dialect classes.
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef DIALECTBASE_TD
 #define DIALECTBASE_TD
 
-// Helper for marking deprecated classes or defs. To mark a def as deprecated,
-// mix in the `Deprecate` class with a reason.
+// Helper for marking deprecated classes or defs in TableGen. To mark a def as
+// deprecated, mix in the `Deprecate` class with a reason.
+// Usage of a deprecated def within TableGen will cause a warning with the
+// given message.
 class Deprecated<string reason> {
   string odsDeprecated = reason;
 }
 
+// Helper for marking entities in ODS generated C++ as deprecated.
+// Usage of such an entity from C++ code will cause a warning being emitted by
+// the C++ compiler with the given message.
+//
+// Note: Support has to be implemented by the code generator of a given
+// entity.
+class CppDeprecated<string reason> {
+  string odsCppDeprecated = reason;
+}
+
 //===----------------------------------------------------------------------===//
 // Dialect definitions
 //===----------------------------------------------------------------------===//
 
 class EmitFolderBase;
 // Generate 'fold' method with 'ArrayRef<Attribute>' parameter.
 // New code should prefer using 'kEmitFoldAdaptorFolder' and
 // consider 'kEmitRawAttributesFolder' deprecated and to be

mlir/include/mlir/IR/OpBase.td

 // 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 = ""> {
   dag dagParams = p;
   code body = b;
 }
 
+// OpBuilder like the above, but the emitted 'build' method is marked as
+// deprecated in C++. Use of it will emit a warning by the C++ compiler
+// with the given reason.
+class DeprecatedOpBuilder<string reason, dag p, code b = "">
+  : OpBuilder<p, b>, CppDeprecated<reason>;
+
 // 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 = "",
                  list<OpVariableDecorator> varDecorators = []> {
   // The constraint, either attribute or type, of the argument.

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("odsCppDeprecated");
+  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)>,
+                  DeprecatedOpBuilder<"the deprecation message",
+                            (ins "float":$something)>];
   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