6502/llvm-6502
1
0
Fork 0
mirror of https://github.com/c64scene-ar/llvm-6502.git synced 2024-07-22 09:29:31 +00:00
Code Issues Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Philip Reames 2015-02-25 00:18:04 +00:00
parent 7c5314a076
commit b0991ba014
2 changed files with 31 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
docs/GarbageCollection.rst
View File

@ -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

4
docs/Statepoints.rst
View File

@ -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.