Lines Matching full:the
12 In this document we refer to the "runtime" collectively as all
13 components that serve as the LLVM client, including the LLVM IR
16 A stack map records the location of ``live values`` at a particular
17 instruction address. These ``live values`` do not refer to all the
18 LLVM values live across the stack map. Instead, they are only the
19 values that the runtime requires to be live at this point. For
20 example, they may be the values the runtime will need to resume
21 program execution at that point independent of the compiled function
22 containing the stack map.
24 LLVM emits stack map data into the object code within a designated
26 each stack map. The record stores the stack map's instruction address
34 generation, which allows the runtime to locate the patchpoint and
35 find the location of ``live values`` at that point.
41 in a variety of settings, the most obvious being a runtime (JIT)
42 compiler. Example applications of the patchpoint intrinsics are
44 optimizing the retrieval of properties in dynamically typed languages
47 The intrinsics documented here are currently used by the JavaScript
48 compiler within the open source WebKit project, see the `FTL JIT
50 used whenever stack maps or code patching are needed. Because the
54 The stack map functionality described in this document is separate
55 from the functionality described in
56 :ref:`stack-map`. `GCFunctionMetadata` provides the location of
57 pointers into a collected heap captured by the `GCRoot` intrinsic,
58 which can also be considered a "stack map". Unlike the stack maps
59 defined above, the `GCFunctionMetadata` stack map interface does not
61 an instruction address, nor does it specify a format for the resulting
62 stack map. The stack maps described here could potentially provide
69 The following two kinds of intrinsics can be used to implement stack
74 implicitly generates a stack map without the need for an additional
75 call to ``llvm.experimental.stackmap``). The choice of which to use
77 and whether any of the intrinsic arguments should be lowered according
79 reserve any space, nor does it expect any call arguments. If the
80 runtime patches code at the stack map's address, it will destructively
81 overwrite the program text. This is unlike
83 patching without overwriting surrounding code. The
89 in the :ref:`stackmap-section`. The record includes an ID, allowing
90 the runtime to uniquely identify the stack map, and the offset within
91 the code from the beginning of the enclosing function.
107 The '``llvm.experimental.stackmap``' intrinsic records the location of
108 specified values in the stack map without generating any code.
113 The first operand is an ID to be encoded within the stack map. The
114 second operand is the number of shadow bytes following the
116 be passed as variables. The variable number of operands that follow are
117 the ``live values`` for which locations will be recorded in the stack map.
120 support, the number of shadow bytes can be set to zero.
125 The stack map intrinsic generates no code in place, unless nops are
127 function entry is stored in the stack map. This is the relative
128 instruction address immediately following the instructions that
129 precede the stack map.
131 The stack map ID allows a runtime to locate the desired stack map
132 record. LLVM passes this ID through directly to the stack map
135 LLVM guarantees a shadow of instructions following the stack map's
136 instruction offset during which neither the end of the basic block nor
138 ``llvm.experimental.patchpoint`` may occur. This allows the runtime to
139 patch the code at this point in response to an event triggered from
140 outside the code. The code for instructions following the stack map
141 may be emitted in the stack map's shadow, and these instructions may
143 destructive patching could overwrite program text or data outside the
145 the runtime does not need to consider this corner case.
169 Now, if the runtime needs to invalidate the compiled code, it may
170 patch 8 bytes of code at the stack map's address at follows:
178 This way, after the normal call to the runtime returns, the code will
180 stack frame from the values located by the stack map.
200 The '``llvm.experimental.patchpoint.*``' intrinsics creates a function
201 call to the specified ``<target>`` and records the location of specified
202 values in the stack map.
207 The first operand is an ID, the second operand is the number of bytes
208 reserved for the patchable region, the third operand is the target
209 address of a function (optionally null), and the fourth operand
210 specifies how many of the following variable operands are considered
211 function call arguments. The remaining variable number of operands are
212 the ``live values`` for which locations will be recorded in the stack
218 The patch point intrinsic generates a stack map. It also emits a
219 function call to the address specified by ``<target>`` if the address
220 is not a constant null. The function call and its arguments are
221 lowered according to the calling convention specified at the
222 intrinsic's callsite. Variants of the intrinsic with non-void return
225 On PowerPC, note that ``<target>`` must be the ABI function pointer for the
226 intended target of the indirect call. Specifically, when compiling for the
227 ELF V1 ABI, ``<target>`` is the function-descriptor address normally used as
228 the C/C++ function-pointer representation.
232 ``llvm.experimental.stackmap.*``. The difference is that space will
236 The location of the arguments are not normally recorded in the stack
237 map because they are already fixed by the calling convention. The
241 which forces the arguments to be loaded into registers but allows
243 will have their register locations recorded in the stack map in
244 addition to the remaining ``live values``.
246 The patch point also emits nops to cover at least ``<numBytes>`` of
247 instruction encoding space. Hence, the client must ensure that
248 ``<numBytes>`` is enough to encode a call to the target address on the
249 supported targets. If the call target is constant null, then there is
253 The runtime may patch the code emitted for the patch point, including
254 the call sequence and nops. However, the runtime may not assume
255 anything about the code LLVM emits within the reserved space. Partial
256 patching is not allowed. The runtime must patch all reserved bytes,
282 Note that no stack map locations will be recorded. If the patched code
284 registers, then the ``anyregcc`` convention may be used:
292 The stack map now indicates the location of the %ptr argument and
299 The patch code sequence may now use the argument that happened to be
316 The existence of a stack map or patch point intrinsic within an LLVM
317 Module forces code emission to create a :ref:`stackmap-section`. The
362 The first byte of each location encodes a type that indicates how to
363 interpret the ``RegNum`` and ``Offset`` fields as follows:
375 In the common case, a value is available in a register, and the
376 ``Offset`` field will be zero. Values spilled to the stack are encoded
377 as ``Indirect`` locations. The runtime must load those values from a
378 stack address, typically in the form ``[BP + Offset]``. If an
380 LLVM may fold the frame index into the stack map as an optimization to
382 encoded as ``Direct`` locations in the form ``BP + Offset``. LLVM may
383 also optimize constants by emitting them directly in the stack map,
384 either in the ``Offset`` of a ``Constant`` location or in the constant
388 are the registers that are live across the stackmap and therefore must
389 be saved by the runtime. This is an important optimization when the
393 Each entry in the liveout register list contains a DWARF register
394 number and size in bytes. The stackmap format deliberately omits
395 specific subregister information. Instead the runtime must interpret
396 this information conservatively. For example, if the stackmap reports
397 one byte at ``%rax``, then the value may be in either ``%al`` or
398 ``%ah``. It doesn't matter in practice, because the runtime will
399 simply save ``%rax``. However, if the stackmap reports 16 bytes at
400 ``%ymm0``, then the runtime can safely optimize by saving only
403 The stack map format is a contract between an LLVM SVN revision and
404 the runtime. It is currently experimental and may change in the short
405 term, but minimizing the need to update the runtime is
406 important. Consequently, the stack map design is motivated by
407 simplicity and extensibility. Compactness of the representation is
408 secondary because the runtime is expected to parse the data
409 immediately after compiling a module and encode the information in its
410 own format. Since the runtime controls the allocation of sections, it
411 can reuse the same stack map space for multiple modules.
414 platforms. However, a 32-bit implementation should be able to use the
423 memory manager via the LLVM C API
424 ``LLVMCreateSimpleMCJITMemoryManager()``. When creating the memory
425 manager, the JIT provides a callback:
427 this section, it invokes the callback and passes the section name. The
428 JIT can record the in-memory address of the section at this time and
429 later parse it to recover the stack map data.
431 For MachO (e.g. on Darwin), the stack map section name is
432 "__llvm_stackmaps". The segment name is "__LLVM_STACKMAPS".
434 For ELF (e.g. on Linux), the stack map section name is
435 ".llvm_stackmaps". The segment name is "__LLVM_STACKMAPS".
440 The stack map support described in this document can be used to
441 precisely determine the location of values at a specific position in
442 the code. LLVM does not maintain any mapping between those values and
443 any higher-level entity. The runtime must be able to interpret the
444 stack map record given only the ID, offset, and the order of the
447 Note that this is quite different from the goal of debug information,
448 which is a best-effort attempt to track the location of named
453 associated with a stack map. The runtime must be able to rebuild a
454 stack frame and resume program execution using the information
455 provided by the stack map. For example, execution may resume in an
456 interpreter or a recompiled version of the same function.
460 conservatively. If the load may trigger an exception, hoisting it
461 above a stack map could be invalid. For example, the runtime may
463 the current state of the type system. If the type system changes while
464 some activation of the load's function exists on the stack, the load
465 becomes unsafe. The runtime can prevent subsequent execution of that
467 the current call site and the load (typically, the runtime would
468 simply patch all stack map locations to invalidate the function). If
469 the compiler had hoisted the load above the stack map, then the
470 program could crash before the runtime could take back control.
475 avoided by marking the call site as "readonly". In the future we may
476 also allow meta-data to be added to the intrinsic call to express
484 records the address of frame index. This address is itself the value
485 that the runtime requested. This differs from Indirect locations,
486 which refer to a stack locations from which the requested values must
487 be loaded. Direct locations can communicate the address if an alloca,
498 The runtime can determine this alloca's relative location on the
500 differs from Register and Indirect locations, because the runtime can
501 only read the values in those locations when execution reaches the
502 instruction address of the stack map.
506 the same requirement imposed by the llvm.gcroot intrinsic.) LLVM
507 transformations must not substitute the alloca with any intervening
508 value. This can be verified by the runtime simply by checking that the
515 Support for StackMap generation and the related intrinsics requires
517 are supported. The currently supported architectures are X86_64,