[mlir][ods] Add Deprecate helper

[jpienaar]

Summary

Add method to tag classes/defs as deprecated. Previously deprecations
were only verbally communicated and folks didn't have an active warning
while building about impending removal. Add mechanism to tag defs as
deprecated to allow warning users.

This doesn't change any policy, it just moves deprecation warnings from
comments to something more user visible.

[Mogball]

mlir/tools/mlir-tblgen/mlir-tblgen.cpp

86

spel out the auto?

94

same here

99

and here

mlir/docs/OpDefinitions.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
+
+Classes/defs can be marked as deprecated by using the `Deprecate` helper class,
+e.g.,
+
+```td
+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.
+
 ### 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/OpBase.td

 //
 // StrConcat<["a", "b", "c"]>.result
 //
 // to get the string "abc"
 class StrFunc<string r> {
   string result = r;
 }
 
+// Helper for marking deprecated classes or defs. To mark a def as deprecated,
+// mix in the `Deprecate` class with a reason.
+class Deprecated<string reason> {
+  string odsDeprecated = reason;
+}
+
 //===----------------------------------------------------------------------===//
 // Predicate definitions
 //===----------------------------------------------------------------------===//
 
 // Base class for logical predicates.
 //
 // Predicates are used to compose constraints (see next section for details).
 // There are two categories of predicates:

mlir/test/mlir-tblgen/deprecation.td

+// RUN: not mlir-tblgen -on-deprecated=error -gen-op-decls -I %S/../../include -DERROR1 %s 2>&1 | FileCheck --check-prefix=ERROR1 %s
+
+include "mlir/IR/OpBase.td"
+
+def Test_Dialect : Dialect {
+  let name = "test_dialect";
+}
+
+#ifdef ERROR1
+def OpTraitA : NativeOpTrait<"OpTraitA">, Deprecated<"use `bar` instead">;
+
+// ERROR1: warning: Using deprecated def `OpTraitA`
+// ERROR1: use `bar` instead
+def OpTraitWithoutDependentTrait : Op<Test_Dialect, "default_value", [OpTraitA]> {}
+#endif

mlir/tools/mlir-tblgen/mlir-tblgen.cpp

 #include "llvm/TableGen/Error.h"
 #include "llvm/TableGen/Main.h"
 #include "llvm/TableGen/Record.h"
 #include "llvm/TableGen/TableGenBackend.h"
 
 using namespace llvm;
 using namespace mlir;
 
+enum DeprecatedAction { None, Warn, Error };
+llvm::cl::opt<DeprecatedAction> actionOnDeprecated(
+    "on-deprecated", llvm::cl::init(Warn),
+    llvm::cl::desc("Action to perform on deprecated def"),
+    llvm::cl::values(clEnumValN(DeprecatedAction::None, "none", "No action"),
+                     clEnumValN(DeprecatedAction::Warn, "warn", "Warn on use"),
+                     clEnumValN(DeprecatedAction::Error, "error",
+                                "Error on use")));
+
 static llvm::ManagedStatic<std::vector<GenInfo>> generatorRegistry;
 
 mlir::GenRegistration::GenRegistration(StringRef arg, StringRef description,
                                        const GenFunction &function) {
   generatorRegistry->emplace_back(arg, description, function);
 }
 
 GenNameParser::GenNameParser(llvm::cl::Option &opt)
GenRegistration printRecords("print-records", "Print all records to stdout",
                              [](const RecordKeeper &records, raw_ostream &os) {
                                os << records;
                                return false;
                              });
 
 // Generator to invoke.
 const mlir::GenInfo *generator;
 
+// Returns if there is a use of `init` in `record`.
+bool findUse(Record &record, Init *init,
+             llvm::DenseMap<Record *, bool> &known) {
+  auto it = known.find(&record);
+  if (it != known.end())
+    return it->second;
+
+  auto memoize = [&](bool val) {
+    known[&record] = val;
+    return val;
+  };
+
+  for (const RecordVal &val : record.getValues()) {
+    Init *valInit = val.getValue();
+    if (valInit == init)
+      return true;
+    if (auto *di = dyn_cast<DefInit>(valInit)) {
+      if (findUse(*di->getDef(), init, known))
+        return memoize(true);
+    } else if (auto *di = dyn_cast<DagInit>(valInit)) {
+      for (Init *arg : di->getArgs())
+        if (auto *di = dyn_cast<DefInit>(arg))
+          if (findUse(*di->getDef(), init, known))
+            return memoize(true);
+    } else if (ListInit *li = dyn_cast<ListInit>(valInit)) {
+      for (Init *jt : li->getValues())
+        if (jt == init)
+          return memoize(true);
+    }
+  }
+  return memoize(false);
+}
+
+void warnOfDeprecatedUses(RecordKeeper &records) {
+  // This performs a direct check for any def marked as deprecated and then
+  // finds all uses of deprecated def. Deprecated defs are not expected to be
+  // either numerous or long lived.
+  bool deprecatedDefsFounds = false;
+  for (auto &it : records.getDefs()) {
+    const RecordVal *r = it.second->getValue("odsDeprecated");
+    if (!r || !r->getValue())
+      continue;
+
+    llvm::DenseMap<Record *, bool> hasUse;
+    if (auto *si = dyn_cast<StringInit>(r->getValue())) {
+      for (auto &jt : records.getDefs()) {
+        // Skip anonymous defs.
+        if (jt.second->isAnonymous())
+          continue;
+        // Skip all outside main file to avoid flagging redundantly.
+        unsigned buf =
+            SrcMgr.FindBufferContainingLoc(jt.second->getLoc().front());
+        if (buf != SrcMgr.getMainFileID())
+          continue;
+
+        if (findUse(*jt.second, it.second->getDefInit(), hasUse)) {
+          PrintWarning(jt.second->getLoc(),
+                       "Using deprecated def `" + it.first + "`");
+          PrintNote(si->getAsUnquotedString());
+          deprecatedDefsFounds = true;
+        }
+      }
+    }
+  }
+  if (deprecatedDefsFounds && actionOnDeprecated == DeprecatedAction::Error)
+    PrintFatalNote("Error'ing out due to deprecated defs");
+}
+
 // TableGenMain requires a function pointer so this function is passed in which
 // simply wraps the call to the generator.
 static bool mlirTableGenMain(raw_ostream &os, RecordKeeper &records) {
+  if (actionOnDeprecated != DeprecatedAction::None)
+    warnOfDeprecatedUses(records);
+
   if (!generator) {
     os << records;
     return false;
   }
   return generator->invoke(records, os);
 }
 
 int main(int argc, char **argv) {
   llvm::InitLLVM y(argc, argv);
   llvm::cl::opt<const mlir::GenInfo *, false, mlir::GenNameParser> generator(
       "", llvm::cl::desc("Generator to run"));
   cl::ParseCommandLineOptions(argc, argv);
   ::generator = generator.getValue();
 
   return TableGenMain(argv[0], &mlirTableGenMain);
 }