Update the GC docs to explicitly mention both gcroot and gc.statepoint

Also, fix confusing bit of the gcroot documentation that bit me personally.



git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@230405 91177308-0d34-0410-b5e6-96231b3b80d8

docs/GarbageCollection.rst

@@ -222,8 +222,24 @@ programs that use different garbage collection algorithms (or none at all).
 
 .. _gcroot:
 
-Identifying GC roots on the stack: ``llvm.gcroot``
---------------------------------------------------
+Identifying GC roots on the stack
+----------------------------------
+
+LLVM currently supports two different mechanisms for describing references in
+compiled code at safepoints.  ``llvm.gcroot`` is the older mechanism; 
+``gc.statepoint`` has been added more recently.  At the moment, you can choose 
+either implementation (on a per :ref:`GC strategy <plugin>` basis).  Longer 
+term, we will probably either migrate away from ``llvm.gcroot`` entirely, or 
+substantially merge their implementations. Note that most new development 
+work is focused on ``gc.statepoint``.  
+
+Using ``gc.statepoint``
+^^^^^^^^^^^^^^^^^^^^^^^^
+:doc:`This page <Statepoints>` contains detailed documentation for 
+``gc.statepoint``. 
+
+Using ``llvm.gcwrite``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: llvm
 
@@ -235,20 +251,23 @@ The exact impact on generated code is specified by a :ref:`compiler plugin
 <plugin>`.  All calls to ``llvm.gcroot`` **must** reside inside the first basic
 block.
 
-A compiler which uses mem2reg to raise imperative code using ``alloca`` into SSA
-form need only add a call to ``@llvm.gcroot`` for those variables which a
-pointers into the GC heap.
+The first argument **must** be a value referring to an alloca instruction or a
+bitcast of an alloca.  The second contains a pointer to metadata that should be
+associated with the pointer, and **must** be a constant or global value
+address.  If your target collector uses tags, use a null pointer for metadata.
+
+A compiler which performs manual SSA construction **must** ensure that SSA 
+values representing GC references are stored in to the alloca passed to the
+respective ``gcroot`` before every call site and reloaded after every call.  
+A compiler which uses mem2reg to raise imperative code using ``alloca`` into 
+SSA form need only add a call to ``@llvm.gcroot`` for those variables which 
+are pointers into the GC heap.  
 
 It is also important to mark intermediate values with ``llvm.gcroot``.  For
 example, consider ``h(f(), g())``.  Beware leaking the result of ``f()`` in the
 case that ``g()`` triggers a collection.  Note, that stack variables must be
 initialized and marked with ``llvm.gcroot`` in function's prologue.
 
-The first argument **must** be a value referring to an alloca instruction or a
-bitcast of an alloca.  The second contains a pointer to metadata that should be
-associated with the pointer, and **must** be a constant or global value
-address.  If your target collector uses tags, use a null pointer for metadata.
-
 The ``%metadata`` argument can be used to avoid requiring heap objects to have
 'isa' pointers or tag bits. [Appel89_, Goldberg91_, Tolmach94_] If specified,
 its value will be tracked along with the location of the pointer in the stack

docs/Statepoints.rst

@@ -14,8 +14,8 @@ with caution.  Because the intrinsics have experimental status,
 compatibility across LLVM releases is not guaranteed.
 
 LLVM currently supports an alternate mechanism for conservative
-garbage collection support using the gc_root intrinsic.  The mechanism
-described here shares little in common with the alternate
+garbage collection support using the ``gcroot`` intrinsic.  The mechanism
+described here shares little in common with the alternate ``gcroot``
 implementation and it is hoped that this mechanism will eventually
 replace the gc_root mechanism.