1 =====================================
2 Garbage Collection Safepoints in LLVM
3 =====================================
12 This document describes a set of experimental extensions to LLVM. Use
13 with caution. Because the intrinsics have experimental status,
14 compatibility across LLVM releases is not guaranteed.
16 LLVM currently supports an alternate mechanism for conservative
17 garbage collection support using the ``gcroot`` intrinsic. The mechanism
18 described here shares little in common with the alternate ``gcroot``
19 implementation and it is hoped that this mechanism will eventually
20 replace the gc_root mechanism.
25 To collect dead objects, garbage collectors must be able to identify
26 any references to objects contained within executing code, and,
27 depending on the collector, potentially update them. The collector
28 does not need this information at all points in code - that would make
29 the problem much harder - but only at well-defined points in the
30 execution known as 'safepoints' For most collectors, it is sufficient
31 to track at least one copy of each unique pointer value. However, for
32 a collector which wishes to relocate objects directly reachable from
33 running code, a higher standard is required.
35 One additional challenge is that the compiler may compute intermediate
36 results ("derived pointers") which point outside of the allocation or
37 even into the middle of another allocation. The eventual use of this
38 intermediate value must yield an address within the bounds of the
39 allocation, but such "exterior derived pointers" may be visible to the
40 collector. Given this, a garbage collector can not safely rely on the
41 runtime value of an address to indicate the object it is associated
42 with. If the garbage collector wishes to move any object, the
43 compiler must provide a mapping, for each pointer, to an indication of
46 To simplify the interaction between a collector and the compiled code,
47 most garbage collectors are organized in terms of three abstractions:
48 load barriers, store barriers, and safepoints.
50 #. A load barrier is a bit of code executed immediately after the
51 machine load instruction, but before any use of the value loaded.
52 Depending on the collector, such a barrier may be needed for all
53 loads, merely loads of a particular type (in the original source
54 language), or none at all.
56 #. Analogously, a store barrier is a code fragement that runs
57 immediately before the machine store instruction, but after the
58 computation of the value stored. The most common use of a store
59 barrier is to update a 'card table' in a generational garbage
62 #. A safepoint is a location at which pointers visible to the compiled
63 code (i.e. currently in registers or on the stack) are allowed to
64 change. After the safepoint completes, the actual pointer value
65 may differ, but the 'object' (as seen by the source language)
68 Note that the term 'safepoint' is somewhat overloaded. It refers to
69 both the location at which the machine state is parsable and the
70 coordination protocol involved in bring application threads to a
71 point at which the collector can safely use that information. The
72 term "statepoint" as used in this document refers exclusively to the
75 This document focuses on the last item - compiler support for
76 safepoints in generated code. We will assume that an outside
77 mechanism has decided where to place safepoints. From our
78 perspective, all safepoints will be function calls. To support
79 relocation of objects directly reachable from values in compiled code,
80 the collector must be able to:
82 #. identify every copy of a pointer (including copies introduced by
83 the compiler itself) at the safepoint,
84 #. identify which object each pointer relates to, and
85 #. potentially update each of those copies.
87 This document describes the mechanism by which an LLVM based compiler
88 can provide this information to a language runtime/collector, and
89 ensure that all pointers can be read and updated if desired. The
90 heart of the approach is to construct (or rewrite) the IR in a manner
91 where the possible updates performed by the garbage collector are
92 explicitly visible in the IR. Doing so requires that we:
94 #. create a new SSA value for each potentially relocated pointer, and
95 ensure that no uses of the original (non relocated) value is
96 reachable after the safepoint,
97 #. specify the relocation in a way which is opaque to the compiler to
98 ensure that the optimizer can not introduce new uses of an
99 unrelocated value after a statepoint. This prevents the optimizer
100 from performing unsound optimizations.
101 #. recording a mapping of live pointers (and the allocation they're
102 associated with) for each statepoint.
104 At the most abstract level, inserting a safepoint can be thought of as
105 replacing a call instruction with a call to a multiple return value
106 function which both calls the original target of the call, returns
107 it's result, and returns updated values for any live pointers to
108 garbage collected objects.
110 Note that the task of identifying all live pointers to garbage
111 collected values, transforming the IR to expose a pointer giving the
112 base object for every such live pointer, and inserting all the
113 intrinsics correctly is explicitly out of scope for this document.
114 The recommended approach is to use the :ref:`utility passes
115 <statepoint-utilities>` described below.
117 This abstract function call is concretely represented by a sequence of
118 intrinsic calls known collectively as a "statepoint relocation sequence".
120 Let's consider a simple call in LLVM IR:
124 define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
125 gc "statepoint-example" {
127 ret i8 addrspace(1)* %obj
130 Depending on our language we may need to allow a safepoint during the execution
131 of ``foo``. If so, we need to let the collector update local values in the
132 current frame. If we don't, we'll be accessing a potential invalid reference
133 once we eventually return from the call.
135 In this example, we need to relocate the SSA value ``%obj``. Since we can't
136 actually change the value in the SSA value ``%obj``, we need to introduce a new
137 SSA value ``%obj.relocated`` which represents the potentially changed value of
138 ``%obj`` after the safepoint and update any following uses appropriately. The
139 resulting relocation sequence is:
143 define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
144 gc "statepoint-example" {
145 %0 = call i32 (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 0, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 0, i8 addrspace(1)* %obj)
146 %obj.relocated = call coldcc i8 addrspace(1)* @llvm.experimental.gc.relocate.p1i8(i32 %0, i32 7, i32 7)
147 ret i8 addrspace(1)* %obj.relocated
150 Ideally, this sequence would have been represented as a M argument, N
151 return value function (where M is the number of values being
152 relocated + the original call arguments and N is the original return
153 value + each relocated value), but LLVM does not easily support such a
156 Instead, the statepoint intrinsic marks the actual site of the
157 safepoint or statepoint. The statepoint returns a token value (which
158 exists only at compile time). To get back the original return value
159 of the call, we use the ``gc.result`` intrinsic. To get the relocation
160 of each pointer in turn, we use the ``gc.relocate`` intrinsic with the
161 appropriate index. Note that both the ``gc.relocate`` and ``gc.result`` are
162 tied to the statepoint. The combination forms a "statepoint relocation
163 sequence" and represents the entitety of a parseable call or 'statepoint'.
165 When lowered, this example would generate the following x86 assembly:
174 movq (%rsp), %rax # This load is redundant (oops!)
178 Each of the potentially relocated values has been spilled to the
179 stack, and a record of that location has been recorded to the
180 :ref:`Stack Map section <stackmap-section>`. If the garbage collector
181 needs to update any of these pointers during the call, it knows
182 exactly what to change.
184 The relevant parts of the StackMap section for our example are:
188 # This describes the call site
189 # Stack Maps: callsite 2882400000
193 # .. 8 entries skipped ..
194 # This entry describes the spill slot which is directly addressable
195 # off RSP with offset 0. Given the value was spilled with a pushq,
197 # Stack Maps: Loc 8: Direct RSP [encoding: .byte 2, .byte 8, .short 7, .int 0]
203 This example was taken from the tests for the :ref:`RewriteStatepointsForGC` utility pass. As such, it's full StackMap can be easily examined with the following command.
207 opt -rewrite-statepoints-for-gc test/Transforms/RewriteStatepointsForGC/basics.ll -S | llc -debug-only=stackmaps
209 Base & Derived Pointers
210 ^^^^^^^^^^^^^^^^^^^^^^^
212 A base pointer is one which points to the base of an allocation (object). A
213 derived pointer is one which is offset from a base pointer by some amount.
214 When relocating objects, a garbage collector needs to be able to relocate each
215 derived pointer associated with an allocation to the same offset from the new
218 Derived pointers fall in to two categories:
219 * "Interior derived pointers" remain within the bounds of the allocation
220 they're associated with. As a result, the base object can be found at
221 runtime provided the bounds of allocations are known to the runtime system.
222 * "Exterior derived pointers" are outside the bounds of the associated object;
223 they may even fall within *another* allocations address range. As a result,
224 there is no way for a garbage collector to determine which allocation they
225 are associated with at runtime and compiler support is needed.
230 As a practical consideration, many garbage-collected systems allow code that is
231 collector-aware ("managed code") to call code that is not collector-aware
232 ("unmanaged code"). It is common that such calls must also be safepoints, since
233 it is desirable to allow the collector to run during the execution of
234 unmanaged code. Futhermore, it is common that coordinating the transition from
235 managed to unmanaged code requires extra code generation at the call site to
236 inform the collector of the transition. In order to support these needs, a
237 statepoint may be marked as a GC transition, and data that is necessary to
238 perform the transition (if any) may be provided as additional arguments to the
241 Note that although in many cases statepoints may be inferred to be GC
242 transitions based on the function symbols involved (e.g. a call from a
243 function with GC strategy "foo" to a function with GC strategy "bar"),
244 indirect calls that are also GC transitions must also be supported. This
245 requirement is the driving force behing the decision to require that GC
246 transitions are explicitly marked.
248 Let's revisit the sample given above, this time treating the call to ``@foo``
249 as a GC transition. Depending on our target, the transition code may need to
250 access some extra state in order to inform the collector of the transition.
251 Let's assume a hypothetical GC--somewhat unimaginatively named "hypothetical-gc"
252 --that requires that a TLS variable must be written to before and after a call
253 to unmanaged code. The resulting relocation sequence is:
257 @flag = thread_local global i32 0, align 4
259 define i8 addrspace(1)* @test1(i8 addrspace(1) *%obj)
260 gc "hypothetical-gc" {
262 %0 = call i32 (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 0, i32 0, void ()* @foo, i32 0, i32 1, i32* @Flag, i32 0, i8 addrspace(1)* %obj)
263 %obj.relocated = call coldcc i8 addrspace(1)* @llvm.experimental.gc.relocate.p1i8(i32 %0, i32 7, i32 7)
264 ret i8 addrspace(1)* %obj.relocated
267 During lowering, this will result in a instruction selection DAG that looks
274 GC_TRANSITION_START (lowered i32 *@Flag), SRCVALUE i32* Flag
276 GC_TRANSITION_END (lowered i32 *@Flag), SRCVALUE i32 *Flag
280 In order to generate the necessary transition code, the backend for each target
281 supported by "hypothetical-gc" must be modified to lower ``GC_TRANSITION_START``
282 and ``GC_TRANSITION_END`` nodes appropriately when the "hypothetical-gc"
283 strategy is in use for a particular function. Assuming that such lowering has
284 been added for X86, the generated assembly would be:
291 movl $1, %fs:Flag@TPOFF
293 movl $0, %fs:Flag@TPOFF
295 movq (%rsp), %rax # This load is redundant (oops!)
299 Note that the design as presented above is not fully implemented: in particular,
300 strategy-specific lowering is not present, and all GC transitions are emitted as
301 as single no-op before and after the call instruction. These no-ops are often
302 removed by the backend during dead machine instruction elimination.
308 'llvm.experimental.gc.statepoint' Intrinsic
309 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
317 @llvm.experimental.gc.statepoint(i64 <id>, i32 <num patch bytes>,
319 i64 <#call args>, i64 <flags>,
320 ... (call parameters),
321 i64 <# transition args>, ... (transition parameters),
322 i64 <# deopt args>, ... (deopt parameters),
328 The statepoint intrinsic represents a call which is parse-able by the
334 The 'id' operand is a constant integer that is reported as the ID
335 field in the generated stackmap. LLVM does not interpret this
336 parameter in any way and its meaning is up to the statepoint user to
337 decide. Note that LLVM is free to duplicate code containing
338 statepoint calls, and this may transform IR that had a unique 'id' per
339 lexical call to statepoint to IR that does not.
341 If 'num patch bytes' is non-zero then the call instruction
342 corresponding to the statepoint is not emitted and LLVM emits 'num
343 patch bytes' bytes of nops in its place. LLVM will emit code to
344 prepare the function arguments and retrieve the function return value
345 in accordance to the calling convention; the former before the nop
346 sequence and the latter after the nop sequence. It is expected that
347 the user will patch over the 'num patch bytes' bytes of nops with a
348 calling sequence specific to their runtime before executing the
349 generated machine code. There are no guarantees with respect to the
350 alignment of the nop sequence. Unlike :doc:`StackMaps` statepoints do
351 not have a concept of shadow bytes. Note that semantically the
352 statepoint still represents a call or invoke to 'target', and the nop
353 sequence after patching is expected to represent an operation
354 equivalent to a call or invoke to 'target'.
356 The 'target' operand is the function actually being called. The
357 target can be specified as either a symbolic LLVM function, or as an
358 arbitrary Value of appropriate function type. Note that the function
359 type must match the signature of the callee and the types of the 'call
360 parameters' arguments.
362 The '#call args' operand is the number of arguments to the actual
363 call. It must exactly match the number of arguments passed in the
364 'call parameters' variable length section.
366 The 'flags' operand is used to specify extra information about the
367 statepoint. This is currently only used to mark certain statepoints
368 as GC transitions. This operand is a 64-bit integer with the following
369 layout, where bit 0 is the least significant bit:
371 +-------+---------------------------------------------------+
373 +=======+===================================================+
374 | 0 | Set if the statepoint is a GC transition, cleared |
376 +-------+---------------------------------------------------+
377 | 1-63 | Reserved for future use; must be cleared. |
378 +-------+---------------------------------------------------+
380 The 'call parameters' arguments are simply the arguments which need to
381 be passed to the call target. They will be lowered according to the
382 specified calling convention and otherwise handled like a normal call
383 instruction. The number of arguments must exactly match what is
384 specified in '# call args'. The types must match the signature of
387 The 'transition parameters' arguments contain an arbitrary list of
388 Values which need to be passed to GC transition code. They will be
389 lowered and passed as operands to the appropriate GC_TRANSITION nodes
390 in the selection DAG. It is assumed that these arguments must be
391 available before and after (but not necessarily during) the execution
392 of the callee. The '# transition args' field indicates how many operands
393 are to be interpreted as 'transition parameters'.
395 The 'deopt parameters' arguments contain an arbitrary list of Values
396 which is meaningful to the runtime. The runtime may read any of these
397 values, but is assumed not to modify them. If the garbage collector
398 might need to modify one of these values, it must also be listed in
399 the 'gc pointer' argument list. The '# deopt args' field indicates
400 how many operands are to be interpreted as 'deopt parameters'.
402 The 'gc parameters' arguments contain every pointer to a garbage
403 collector object which potentially needs to be updated by the garbage
404 collector. Note that the argument list must explicitly contain a base
405 pointer for every derived pointer listed. The order of arguments is
406 unimportant. Unlike the other variable length parameter sets, this
407 list is not length prefixed.
412 A statepoint is assumed to read and write all memory. As a result,
413 memory operations can not be reordered past a statepoint. It is
414 illegal to mark a statepoint as being either 'readonly' or 'readnone'.
416 Note that legal IR can not perform any memory operation on a 'gc
417 pointer' argument of the statepoint in a location statically reachable
418 from the statepoint. Instead, the explicitly relocated value (from a
419 ``gc.relocate``) must be used.
421 'llvm.experimental.gc.result' Intrinsic
422 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
430 @llvm.experimental.gc.result(i32 %statepoint_token)
435 ``gc.result`` extracts the result of the original call instruction
436 which was replaced by the ``gc.statepoint``. The ``gc.result``
437 intrinsic is actually a family of three intrinsics due to an
438 implementation limitation. Other than the type of the return value,
439 the semantics are the same.
444 The first and only argument is the ``gc.statepoint`` which starts
445 the safepoint sequence of which this ``gc.result`` is a part.
446 Despite the typing of this as a generic i32, *only* the value defined
447 by a ``gc.statepoint`` is legal here.
452 The ``gc.result`` represents the return value of the call target of
453 the ``statepoint``. The type of the ``gc.result`` must exactly match
454 the type of the target. If the call target returns void, there will
457 A ``gc.result`` is modeled as a 'readnone' pure function. It has no
458 side effects since it is just a projection of the return value of the
459 previous call represented by the ``gc.statepoint``.
461 'llvm.experimental.gc.relocate' Intrinsic
462 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
469 declare <pointer type>
470 @llvm.experimental.gc.relocate(i32 %statepoint_token,
477 A ``gc.relocate`` returns the potentially relocated value of a pointer
483 The first argument is the ``gc.statepoint`` which starts the
484 safepoint sequence of which this ``gc.relocation`` is a part.
485 Despite the typing of this as a generic i32, *only* the value defined
486 by a ``gc.statepoint`` is legal here.
488 The second argument is an index into the statepoints list of arguments
489 which specifies the base pointer for the pointer being relocated.
490 This index must land within the 'gc parameter' section of the
491 statepoint's argument list.
493 The third argument is an index into the statepoint's list of arguments
494 which specify the (potentially) derived pointer being relocated. It
495 is legal for this index to be the same as the second argument
496 if-and-only-if a base pointer is being relocated. This index must land
497 within the 'gc parameter' section of the statepoint's argument list.
502 The return value of ``gc.relocate`` is the potentially relocated value
503 of the pointer specified by it's arguments. It is unspecified how the
504 value of the returned pointer relates to the argument to the
505 ``gc.statepoint`` other than that a) it points to the same source
506 language object with the same offset, and b) the 'based-on'
507 relationship of the newly relocated pointers is a projection of the
508 unrelocated pointers. In particular, the integer value of the pointer
509 returned is unspecified.
511 A ``gc.relocate`` is modeled as a ``readnone`` pure function. It has no
512 side effects since it is just a way to extract information about work
513 done during the actual call modeled by the ``gc.statepoint``.
515 .. _statepoint-stackmap-format:
520 Locations for each pointer value which may need read and/or updated by
521 the runtime or collector are provided via the :ref:`Stack Map format
522 <stackmap-format>` specified in the PatchPoint documentation.
524 Each statepoint generates the following Locations:
526 * Constant which describes the calling convention of the call target. This
527 constant is a valid :ref:`calling convention identifier <callingconv>` for
528 the version of LLVM used to generate the stackmap. No additional compatibility
529 guarantees are made for this constant over what LLVM provides elsewhere w.r.t.
531 * Constant which describes the flags passed to the statepoint intrinsic
532 * Constant which describes number of following deopt *Locations* (not
534 * Variable number of Locations, one for each deopt parameter listed in
535 the IR statepoint (same number as described by previous Constant)
536 * Variable number of Locations pairs, one pair for each unique pointer
537 which needs relocated. The first Location in each pair describes
538 the base pointer for the object. The second is the derived pointer
539 actually being relocated. It is guaranteed that the base pointer
540 must also appear explicitly as a relocation pair if used after the
541 statepoint. There may be fewer pairs then gc parameters in the IR
542 statepoint. Each *unique* pair will occur at least once; duplicates
545 Note that the Locations used in each section may describe the same
546 physical location. e.g. A stack slot may appear as a deopt location,
547 a gc base pointer, and a gc derived pointer.
549 The LiveOut section of the StkMapRecord will be empty for a statepoint
552 Safepoint Semantics & Verification
553 ==================================
555 The fundamental correctness property for the compiled code's
556 correctness w.r.t. the garbage collector is a dynamic one. It must be
557 the case that there is no dynamic trace such that a operation
558 involving a potentially relocated pointer is observably-after a
559 safepoint which could relocate it. 'observably-after' is this usage
560 means that an outside observer could observe this sequence of events
561 in a way which precludes the operation being performed before the
564 To understand why this 'observable-after' property is required,
565 consider a null comparison performed on the original copy of a
566 relocated pointer. Assuming that control flow follows the safepoint,
567 there is no way to observe externally whether the null comparison is
568 performed before or after the safepoint. (Remember, the original
569 Value is unmodified by the safepoint.) The compiler is free to make
570 either scheduling choice.
572 The actual correctness property implemented is slightly stronger than
573 this. We require that there be no *static path* on which a
574 potentially relocated pointer is 'observably-after' it may have been
575 relocated. This is slightly stronger than is strictly necessary (and
576 thus may disallow some otherwise valid programs), but greatly
577 simplifies reasoning about correctness of the compiled code.
579 By construction, this property will be upheld by the optimizer if
580 correctly established in the source IR. This is a key invariant of
583 The existing IR Verifier pass has been extended to check most of the
584 local restrictions on the intrinsics mentioned in their respective
585 documentation. The current implementation in LLVM does not check the
586 key relocation invariant, but this is ongoing work on developing such
587 a verifier. Please ask on llvm-dev if you're interested in
588 experimenting with the current version.
590 .. _statepoint-utilities:
592 Utility Passes for Safepoint Insertion
593 ======================================
595 .. _RewriteStatepointsForGC:
597 RewriteStatepointsForGC
598 ^^^^^^^^^^^^^^^^^^^^^^^^
600 The pass RewriteStatepointsForGC transforms a functions IR by replacing a
601 ``gc.statepoint`` (with an optional ``gc.result``) with a full relocation
602 sequence, including all required ``gc.relocates``. To function, the pass
603 requires that the GC strategy specified for the function be able to reliably
604 distinguish between GC references and non-GC references in IR it is given.
606 As an example, given this code:
610 define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
611 gc "statepoint-example" {
612 call i32 (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 2882400000, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 5, i32 0, i32 -1, i32 0, i32 0, i32 0)
613 ret i8 addrspace(1)* %obj
616 The pass would produce this IR:
620 define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
621 gc "statepoint-example" {
622 %0 = call i32 (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 2882400000, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 5, i32 0, i32 -1, i32 0, i32 0, i32 0, i8 addrspace(1)* %obj)
623 %obj.relocated = call coldcc i8 addrspace(1)* @llvm.experimental.gc.relocate.p1i8(i32 %0, i32 12, i32 12)
624 ret i8 addrspace(1)* %obj.relocated
627 In the above examples, the addrspace(1) marker on the pointers is the mechanism
628 that the ``statepoint-example`` GC strategy uses to distinguish references from
629 non references. Address space 1 is not globally reserved for this purpose.
631 This pass can be used an utility function by a language frontend that doesn't
632 want to manually reason about liveness, base pointers, or relocation when
633 constructing IR. As currently implemented, RewriteStatepointsForGC must be
634 run after SSA construction (i.e. mem2ref).
637 In practice, RewriteStatepointsForGC can be run much later in the pass
638 pipeline, after most optimization is already done. This helps to improve
639 the quality of the generated code when compiled with garbage collection support.
640 In the long run, this is the intended usage model. At this time, a few details
641 have yet to be worked out about the semantic model required to guarantee this
642 is always correct. As such, please use with caution and report bugs.
649 The pass PlaceSafepoints transforms a function's IR by replacing any call or
650 invoke instructions with appropriate ``gc.statepoint`` and ``gc.result`` pairs,
651 and inserting safepoint polls sufficient to ensure running code checks for a
652 safepoint request on a timely manner. This pass is expected to be run before
653 RewriteStatepointsForGC and thus does not produce full relocation sequences.
655 As an example, given input IR of the following:
659 define void @test() gc "statepoint-example" {
664 declare void @do_safepoint()
665 define void @gc.safepoint_poll() {
666 call void @do_safepoint()
671 This pass would produce the following IR:
675 define void @test() gc "statepoint-example" {
676 %safepoint_token = call i32 (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 2882400000, i32 0, void ()* @do_safepoint, i32 0, i32 0, i32 0, i32 0)
677 %safepoint_token1 = call i32 (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 2882400000, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 0)
681 In this case, we've added an (unconditional) entry safepoint poll and converted the call into a ``gc.statepoint``. Note that despite appearances, the entry poll is not necessarily redundant. We'd have to know that ``foo`` and ``test`` were not mutually recursive for the poll to be redundant. In practice, you'd probably want to your poll definition to contain a conditional branch of some form.
684 At the moment, PlaceSafepoints can insert safepoint polls at method entry and
685 loop backedges locations. Extending this to work with return polls would be
686 straight forward if desired.
688 PlaceSafepoints includes a number of optimizations to avoid placing safepoint
689 polls at particular sites unless needed to ensure timely execution of a poll
690 under normal conditions. PlaceSafepoints does not attempt to ensure timely
691 execution of a poll under worst case conditions such as heavy system paging.
693 The implementation of a safepoint poll action is specified by looking up a
694 function of the name ``gc.safepoint_poll`` in the containing Module. The body
695 of this function is inserted at each poll site desired. While calls or invokes
696 inside this method are transformed to a ``gc.statepoints``, recursive poll
697 insertion is not performed.
699 By default PlaceSafepoints passes in ``0xABCDEF00`` as the statepoint
700 ID and ``0`` as the number of patchable bytes to the newly constructed
701 ``gc.statepoint``. These values can be configured on a per-callsite
702 basis using the attributes ``"statepoint-id"`` and
703 ``"statepoint-num-patch-bytes"``. If a call site is marked with a
704 ``"statepoint-id"`` function attribute and its value is a positive
705 integer (represented as a string), then that value is used as the ID
706 of the newly constructed ``gc.statepoint``. If a call site is marked
707 with a ``"statepoint-num-patch-bytes"`` function attribute and its
708 value is a positive integer, then that value is used as the 'num patch
709 bytes' parameter of the newly constructed ``gc.statepoint``. The
710 ``"statepoint-id"`` and ``"statepoint-num-patch-bytes"`` attributes
711 are not propagated to the ``gc.statepoint`` call or invoke if they
712 could be successfully parsed.
714 If you are scheduling the RewriteStatepointsForGC pass late in the pass order,
715 you should probably schedule this pass immediately before it. The exception
716 would be if you need to preserve abstract frame information (e.g. for
717 deoptimization or introspection) at safepoints. In that case, ask on the
718 llvm-dev mailing list for suggestions.
721 Supported Architectures
722 =======================
724 Support for statepoint generation requires some code for each backend.
725 Today, only X86_64 is supported.
727 Bugs and Enhancements
728 =====================
730 Currently known bugs and enhancements under consideration can be
731 tracked by performing a `bugzilla search
732 <http://llvm.org/bugs/buglist.cgi?cmdtype=runnamed&namedcmd=Statepoint%20Bugs&list_id=64342>`_
733 for [Statepoint] in the summary field. When filing new bugs, please
734 use this tag so that interested parties see the newly filed bug. As
735 with most LLVM features, design discussions take place on `llvm-dev
736 <http://lists.llvm.org/mailman/listinfo/llvm-dev>`_, and patches
737 should be sent to `llvm-commits
738 <http://lists.llvm.org/mailman/listinfo/llvm-commits>`_ for review.