[TableGen] Deprecate old GI Combiner Emitter

[Pierre-vh]

Summary

Will be removed in a month or so.

[Pierre-vh]

Also fix docs while I'm at it. I was thinking of doing another patch but I think it's better to do it all at once.

I'm wondering if the deprecation warning is enough. a CI buildbot will probably ignore them, so downstream users could easily miss it unless they catch it by luck.
Should we add something like "legacy" to the older option? This would make it impossible to miss downstream. They'll have to fix the builds by adding the "legacy" prefix/suffix to the option.
This may be a bit aggressive though, not sure what others think?

[Pierre-vh]

ping

[aemerson]

LGTM. I'm thinking that we could perhaps put a link to this review/discourse thread in the warning as well.

llvm/docs/CommandGuide/tblgen.rst

.. option:: -optimize-match-table
   Make -gen-global-isel generate an optimized version of the match table.
 
 .. option:: -warn-on-skipped-patterns
 
   Make -gen-global-isel explain why a pattern was skipped for inclusion.
 
 .. option:: -gen-global-isel-combiner
 
-  Generate GlobalISel combiner.
+  (Deprecated, pending removal)
+  Generate legacy GlobalISel combiner.
+
+.. option:: -gen-global-isel-combiner-matchtable
+
+  Generate MatchTable-based GlobalISel combiner.
 
 .. option:: -combiners=list
 
-  Make -gen-global-isel-combiner emit the specified combiners.
+  Make -gen-global-isel-combiner and -gen-global-isel-combiner-matchtable
+  emit the specified combiners.
 
 .. option:: -gicombiner-show-expansions
 
   Make -gen-global-isel-combiner use C++ comments to indicate occurrences
   of code expansion.
 
 .. option:: -gicombiner-stop-after-build
 
   Make -gen-global-isel-combiner stop processing after building the match tree.
 
 .. option:: -gicombiner-stop-after-parse
 
-  Make -gen-global-isel-combiner stop processing after parsing rules
-  and dump state.
+  Make -gen-global-isel-combiner and -gen-global-isel-combiner-matchtable stop
+  processing after parsing rules and dump state.
 
 .. option:: -gen-instr-info
 
  Generate instruction descriptions.
 
 .. option:: -gen-instr-docs
 
  Generate instruction documentation.

llvm/utils/TableGen/GICombinerEmitter.cpp

OS << "\n  return false;\n"
      << "#endif // ifdef " << Name.upper() << "_GENCOMBINERHELPER_CPP\n";
 }
 
 } // end anonymous namespace
 
 //===----------------------------------------------------------------------===//
 
 static void EmitGICombiner(RecordKeeper &RK, raw_ostream &OS) {
+  PrintWarning(
+      "'-gen-global-isel-combiner' is deprecated and will be removed soon; "
+      "please use '-gen-global-isel-combiner-match-table' instead");
+  PrintNote(
+      "See "
+      "https://discourse.llvm.org/t/rfc-matchtable-based-globalisel-combiners");
+
   CodeGenTarget Target(RK);
   emitSourceFileHeader("Global Combiner", OS);
 
   if (SelectedCombiners.empty())
     PrintFatalError("No combiners selected with -combiners");
   for (const auto &Combiner : SelectedCombiners) {
     Record *CombinerDef = RK.getDef(Combiner);
     if (!CombinerDef)
       PrintFatalError("Could not find " + Combiner);
     GICombinerEmitter(RK, Target, Combiner, CombinerDef).run(OS);
   }
   NumPatternTotalStatistic = NumPatternTotal;
 }
 
 static TableGen::Emitter::Opt X("gen-global-isel-combiner", EmitGICombiner,
                                 "Generate GlobalISel combiner");