[llvm][doc] Update comments and documentation of custom stackmap formats in GC

[zero9178]

Summary

Since https://reviews.llvm.org/D53892 it is possible to emit a custom stackmap by overwriting the emitStackMaps method of GCMetadataPrinter. That way even AOT compilers can generate a more efficient and more suitable format for their needs.

This patch updates documentation and stale comments in source code. In particular it removes the issue from the issue list in the Statepoints documentation and adjusts comments in GCStrategy.

llvm/docs/Statepoints.rst

 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Relocations along exceptional paths are currently broken in ToT.  In
 particular, there is current no way to represent a rethrow on a path which
 also has relocations.  See `this llvm-dev discussion
 <https://groups.google.com/forum/#!topic/llvm-dev/AE417XjgxvI>`_ for more
 detail.
 
-Support for alternate stackmap formats
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-For some use cases, it is
-desirable to directly encode a final memory efficient stackmap format for
-use by the runtime.  This is particularly relevant for ahead of time
-compilers which wish to directly link object files without the need for
-post processing of each individual object file.  While not implemented
-today for statepoints, there is precedent for a GCStrategy to be able to
-select a customer GCMetataPrinter for this purpose.  Patches to enable
-this functionality upstream are welcome.
-
 Bugs and Enhancements
 =====================
 
 Currently known bugs and enhancements under consideration can be
 tracked by performing a `bugzilla search
 <https://bugs.llvm.org/buglist.cgi?cmdtype=runnamed&namedcmd=Statepoint%20Bugs&list_id=64342>`_
 for [Statepoint] in the summary field. When filing new bugs, please
 use this tag so that interested parties see the newly filed bug.  As
 with most LLVM features, design discussions take place on `llvm-dev
 <http://lists.llvm.org/mailman/listinfo/llvm-dev>`_, and patches
 should be sent to `llvm-commits
 <http://lists.llvm.org/mailman/listinfo/llvm-commits>`_ for review.

llvm/include/llvm/IR/GCStrategy.h

 //   stored in an alloca registered with llvm.gcoot.
 //
 // This information can used to emit the metadata tables which are required by
 // the target garbage collector runtime.
 //
 // When used with gc.statepoint, information about safepoint and roots can be
 // found in the binary StackMap section after code generation.  Safepoint
 // placement is currently the responsibility of the frontend, though late
-// insertion support is planned.  gc.statepoint does not currently support
-// custom stack map formats; such can be generated by parsing the standard
-// stack map section if desired.
+// insertion support is planned.
 //
 // The read and write barrier support can be used with either implementation.
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_IR_GCSTRATEGY_H
 #define LLVM_IR_GCSTRATEGY_H
 
public:
   /// pointers to GC managed locations and false for pointers to non-GC
   /// managed locations.  Note a GCStrategy can always return 'None' (i.e. an
   /// empty optional indicating it can't reliably distinguish.
   virtual Optional<bool> isGCManagedPointer(const Type *Ty) const {
     return None;
   }
   ///@}
 
+  /// If set, appropriate metadata tables must be emitted by the back-end
+  /// (assembler, JIT, or otherwise). The default stackmap information can be
+  /// found in the StackMap section as described in the documentation.
+  bool usesMetadata() const { return UsesMetadata; }
+
   /** @name GCRoot Specific Properties
    * These properties and overrides only apply to collector strategies using
    * GCRoot.
    */
   ///@{
 
   /// True if safe points need to be inferred on call sites
   bool needsSafePoints() const { return NeededSafePoints; }
 
-  /// If set, appropriate metadata tables must be emitted by the back-end
-  /// (assembler, JIT, or otherwise). For statepoint, this method is
-  /// currently unsupported.  The stackmap information can be found in the
-  /// StackMap section as described in the documentation.
-  bool usesMetadata() const { return UsesMetadata; }
-
   ///@}
 };
 
 /// Subclasses of GCStrategy are made available for use during compilation by
 /// adding them to the global GCRegistry.  This can done either within the
 /// LLVM source tree or via a loadable plugin.  An example registeration
 /// would be:
 /// static GCRegistry::Add<CustomGC> X("custom-name",
 ///        "my custom supper fancy gc strategy");
 ///
-/// Note that to use a custom GCMetadataPrinter w/gc.roots, you must also
+/// Note that to use a custom GCMetadataPrinter, you must also
 /// register your GCMetadataPrinter subclass with the
 /// GCMetadataPrinterRegistery as well.
 using GCRegistry = Registry<GCStrategy>;
 
 /// Lookup the GCStrategy object associated with the given gc name.
 std::unique_ptr<GCStrategy> getGCStrategy(const StringRef Name);
 
 } // end namespace llvm
 
 #endif // LLVM_IR_GCSTRATEGY_H