From d7923910c58ea252033e102e83ae576de9eed8f2 Mon Sep 17 00:00:00 2001 From: Chris Lattner Date: Sun, 23 May 2004 21:06:01 +0000 Subject: [PATCH] Describe the new garbage collector intrinsics git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@13672 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/LangRef.html | 189 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 176 insertions(+), 13 deletions(-) diff --git a/docs/LangRef.html b/docs/LangRef.html index 26b709e9a01..07bb686698b 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -5,7 +5,9 @@ LLVM Assembly Language Reference Manual + +
LLVM Language Reference Manual
  1. Abstract
    2. @@ -97,6 +99,13 @@
  2. 'llvm.va_copy' Intrinsic
+
  • Accurate Garbage Collection Intrinsics +
      +
    1. 'llvm.gcroot' Intrinsic
      2. +
    2. 'llvm.gcread' Intrinsic
      3. +
    3. 'llvm.gcwrite' Intrinsic
      4. +
    +
  • Code Generator Intrinsics
    1. 'llvm.returnaddress' Intrinsic
      2. @@ -117,18 +126,20 @@
    2. 'llvm.memset' Intrinsic
    • -
  • Debugger intrinsics +
  • Debugger intrinsics
    • -
    -

    Written by Chris Lattner -and Vikram Adve

    -

    + +
    +

    Written by Chris Lattner + and Vikram Adve

    +
    Abstract
    +

    This document is a reference manual for the LLVM assembly language. LLVM is an SSA based representation that provides type safety, @@ -137,10 +148,13 @@ low-level operations, flexibility, and the capability of representing representation used throughout all phases of the LLVM compilation strategy.

    +
    Introduction
    +
    +

    The LLVM code representation is designed to be used in three different forms: as an in-memory compiler IR, as an on-disk bytecode representation (suitable for fast loading by a Just-In-Time compiler), @@ -150,6 +164,7 @@ compiler transformations and analysis, while providing a natural means to debug and visualize the transformations. The three different forms of LLVM are all equivalent. This document describes the human readable representation and notation.

    +

    The LLVM representation aims to be a light-weight and low-level while being expressive, typed, and extensible at the same time. It aims to be a "universal IR" of sorts, by being at a low enough level @@ -160,15 +175,23 @@ the target of optimizations: for example, through pointer analysis, it can be proven that a C automatic variable is never accessed outside of the current function... allowing it to be promoted to a simple SSA value instead of a memory location.

    +
    +
    Well-Formedness
    +
    +

    It is important to note that this document describes 'well formed' LLVM assembly language. There is a difference between what the parser accepts and what is considered 'well formed'. For example, the following instruction is syntactically okay, but not well formed:

    -
      %x = add int 1, %x
    + +
    +  %x = add int 1, %x
+
    +

    ...because the definition of %x does not dominate all of its uses. The LLVM infrastructure provides a verification pass that may be used to verify that an LLVM module is well formed. This pass is @@ -176,13 +199,18 @@ automatically run by the parser after parsing input assembly, and by the optimizer before it outputs bytecode. The violations pointed out by the verifier pass indicate bugs in transformation passes or input to the parser.

    +
    +
    Identifiers
    +
    +

    LLVM uses three different forms of identifiers, for different purposes:

    +
    1. Numeric constants are represented as you would expect: 12, -3 123.421, etc. Floating point constants have an optional hexadecimal @@ -1803,18 +1831,22 @@ understand to raw LLVM instructions that they do.
    +

    Variable argument support is defined in LLVM with the vanext instruction and these three intrinsic functions. These functions are related to the similarly named macros defined in the <stdarg.h> header file.

    +

    All of these functions operate on arguments that use a target-specific value type "va_list". The LLVM assembly language reference manual does not define what this type is, so all transformations should be prepared to handle intrinsics with any type used.

    +

    This example shows how the vanext instruction and the variable argument handling intrinsic functions are used.

    + 
     int %test(int %X, ...) {
   ; Initialize variable argument processing
@@ -1888,21 +1920,152 @@ with calls to llvm.va_end.
    +
    Syntax:
    -
      call va_list (va_list)* %llvm.va_copy(va_list <destarglist>)
    + +
    +  call va_list (va_list)* %llvm.va_copy(va_list <destarglist>)
+
    +
    Overview:
    -

    The 'llvm.va_copy' intrinsic copies the current argument -position from the source argument list to the destination argument list.

    + +

    The 'llvm.va_copy' intrinsic copies the current argument position +from the source argument list to the destination argument list.

    +
    Arguments:
    +

    The argument is the va_list to copy.

    +
    Semantics:
    +

    The 'llvm.va_copy' intrinsic works just like the va_copy -macro available in C. In a target-dependent way, it copies the source va_list -element into the returned list. This intrinsic is necessary because the llvm.va_start intrinsic may be arbitrarily -complex and require memory allocation, for example.

    +macro available in C. In a target-dependent way, it copies the source +va_list element into the returned list. This intrinsic is necessary +because the llvm.va_start intrinsic may be +arbitrarily complex and require memory allocation, for example.

    +
    + +
    + Accurate Garbage Collection Intrinsics +
    + +
    + +

    +LLVM support for Accurate Garbage +Collection requires the implementation and generation of these intrinsics. +These intrinsics allow identification of GC roots on the +stack, as well as garbage collector implementations that require read and write barriers. +Front-ends for type-safe garbage collected languages should generate these +intrinsics to make use of the LLVM garbage collectors. For more details, see Accurate Garbage Collection with LLVM. +

    +
    + + +
    + 'llvm.gcroot' Intrinsic +
    + +
    + +
    Syntax:
    + +
    +  call void (<ty>**, <ty2>*)* %llvm.gcroot(<ty>** %ptrloc, <ty2>* %metadata)
+
    + +
    Overview:
    + +

    The 'llvm.gcroot' intrinsic declares the existance of a GC root to +the code generator, and allows some metadata to be associated with it.

    + +
    Arguments:
    + +

    The first argument specifies the address of a stack object that contains the +root pointer. The second pointer (which must be either a constant or a global +value address) contains the meta-data to be associated with the root.

    + +
    Semantics:
    + +

    At runtime, a call to this intrinsics stores a null pointer into the "ptrloc" +location. At compile-time, the code generator generates information to allow +the runtime to find the pointer at GC safe points. +

    + +
    + + + +
    + 'llvm.gcread' Intrinsic +
    + +
    + +
    Syntax:
    + +
    +  call sbyte* (sbyte**)* %llvm.gcread(sbyte** %Ptr)
+
    + +
    Overview:
    + +

    The 'llvm.gcread' intrinsic identifies reads of references from heap +locations, allowing garbage collector implementations that require read +barriers.

    + +
    Arguments:
    + +

    The argument is the address to read from, which should be an address +allocated from the garbage collector.

    + +
    Semantics:
    + +

    The 'llvm.gcread' intrinsic has the same semantics as a load +instruction, but may be replaced with substantially more complex code by the +garbage collector runtime, as needed.

    + +
    + + + +
    + 'llvm.gcwrite' Intrinsic +
    + +
    + +
    Syntax:
    + +
    +  call void (sbyte*, sbyte**)* %llvm.gcwrite(sbyte* %P1, sbyte** %P2)
+
    + +
    Overview:
    + +

    The 'llvm.gcwrite' intrinsic identifies writes of references to heap +locations, allowing garbage collector implementations that require write +barriers (such as generational or reference counting collectors).

    + +
    Arguments:
    + +

    The first argument is the reference to store, and the second is the heap +location to store to.

    + +
    Semantics:
    + +

    The 'llvm.gcwrite' intrinsic has the same semantics as a store +instruction, but may be replaced with substantially more complex code by the +garbage collector runtime, as needed.

    + +
    + + +
    Code Generator Intrinsics