docs/InAlloca.rst

   1 ==========================================
   2 Design and Usage of the InAlloca Attribute
   3 ==========================================
   4
   5 Introduction
   6 ============
   7
   8 .. Warning:: This feature is unstable and not fully implemented.
   9
  10 The :ref:`inalloca <attr_inalloca>` attribute is designed to allow
  11 taking the address of an aggregate argument that is being passed by
  12 value through memory.  Primarily, this feature is required for
  13 compatibility with the Microsoft C++ ABI.  Under that ABI, class
  14 instances that are passed by value are constructed directly into
  15 argument stack memory.  Prior to the addition of inalloca, calls in LLVM
  16 were indivisible instructions.  There was no way to perform intermediate
  17 work, such as object construction, between the first stack adjustment
  18 and the final control transfer.  With inalloca, all arguments passed in
  19 memory are modelled as a single alloca, which can be stored to prior to
  20 the call.  Unfortunately, this complicated feature comes with a large
  21 set of restrictions designed to bound the lifetime of the argument
  22 memory around the call.
  23
  24 For now, it is recommended that frontends and optimizers avoid producing
  25 this construct, primarily because it forces the use of a base pointer.
  26 This feature may grow in the future to allow general mid-level
  27 optimization, but for now, it should be regarded as less efficient than
  28 passing by value with a copy.
  29
  30 Intended Usage
  31 ==============
  32
  33 The example below is the intended LLVM IR lowering for some C++ code
  34 that passes a default-constructed ``Foo`` object to ``g`` in the 32-bit
  35 Microsoft C++ ABI.
  36
  37 .. code-block:: c++
  38
  39     // Foo is non-trivial.
  40     struct Foo { int a, b; Foo(); ~Foo(); Foo(const &Foo); };
  41     void g(Foo a, Foo b);
  42     void f() {
  43       f(1, Foo(), 3);
  44     }
  45
  46 .. code-block:: llvm
  47
  48     %struct.Foo = type { i32, i32 }
  49     %callframe.f = type { %struct.Foo, %struct.Foo }
  50     declare void @Foo_ctor(%Foo* %this)
  51     declare void @Foo_dtor(%Foo* %this)
  52     declare void @g(%Foo* inalloca %memargs)
  53
  54     define void @f() {
  55     entry:
  56       %base = call i8* @llvm.stacksave()
  57       %memargs = alloca %callframe.f
  58       %b = getelementptr %callframe.f*, i32 0
  59       %a = getelementptr %callframe.f*, i32 1
  60       call void @Foo_ctor(%struct.Foo* %b)
  61
  62       ; If a's ctor throws, we must destruct b.
  63       invoke void @Foo_ctor(%struct.Foo* %arg1)
  64           to label %invoke.cont unwind %invoke.unwind
  65
  66     invoke.cont:
  67       store i32 1, i32* %arg0
  68       call void @g(%callframe.f* inalloca %memargs)
  69       call void @llvm.stackrestore(i8* %base)
  70       ...
  71
  72     invoke.unwind:
  73       call void @Foo_dtor(%struct.Foo* %b)
  74       call void @llvm.stackrestore(i8* %base)
  75       ...
  76     }
  77
  78 To avoid stack leaks, the frontend saves the current stack pointer with
  79 a call to :ref:`llvm.stacksave <int_stacksave>`.  Then, it allocates the
  80 argument stack space with alloca and calls the default constructor.  The
  81 default constructor could throw an exception, so the frontend has to
  82 create a landing pad.  The frontend has to destroy the already
  83 constructed argument ``b`` before restoring the stack pointer.  If the
  84 constructor does not unwind, ``g`` is called.  In the Microsoft C++ ABI,
  85 ``g`` will destroy its arguments, and then the stack is restored in
  86 ``f``.
  87
  88 Design Considerations
  89 =====================
  90
  91 Lifetime
  92 --------
  93
  94 The biggest design consideration for this feature is object lifetime.
  95 We cannot model the arguments as static allocas in the entry block,
  96 because all calls need to use the memory at the top of the stack to pass
  97 arguments.  We cannot vend pointers to that memory at function entry
  98 because after code generation they will alias.
  99
 100 The rule against allocas between argument allocations and the call site
 101 avoids this problem, but it creates a cleanup problem.  Cleanup and
 102 lifetime is handled explicitly with stack save and restore calls.  In
 103 the future, we may want to introduce a new construct such as ``freea``
 104 or ``afree`` to make it clear that this stack adjusting cleanup is less
 105 powerful than a full stack save and restore.
 106
 107 Nested Calls and Copy Elision
 108 -----------------------------
 109
 110 We also want to be able to support copy elision into these argument
 111 slots.  This means we have to support multiple live argument
 112 allocations.
 113
 114 Consider the evaluation of:
 115
 116 .. code-block:: c++
 117
 118     // Foo is non-trivial.
 119     struct Foo { int a; Foo(); Foo(const &Foo); ~Foo(); };
 120     Foo bar(Foo b);
 121     int main() {
 122       bar(bar(Foo()));
 123     }
 124
 125 In this case, we want to be able to elide copies into ``bar``'s argument
 126 slots.  That means we need to have more than one set of argument frames
 127 active at the same time.  First, we need to allocate the frame for the
 128 outer call so we can pass it in as the hidden struct return pointer to
 129 the middle call.  Then we do the same for the middle call, allocating a
 130 frame and passing its address to ``Foo``'s default constructor.  By
 131 wrapping the evaluation of the inner ``bar`` with stack save and
 132 restore, we can have multiple overlapping active call frames.
 133
 134 Callee-cleanup Calling Conventions
 135 ----------------------------------
 136
 137 Another wrinkle is the existence of callee-cleanup conventions.  On
 138 Windows, all methods and many other functions adjust the stack to clear
 139 the memory used to pass their arguments.  In some sense, this means that
 140 the allocas are automatically cleared by the call.  However, LLVM
 141 instead models this as a write of undef to all of the inalloca values
 142 passed to the call instead of a stack adjustment.  Frontends should
 143 still restore the stack pointer to avoid a stack leak.
 144
 145 Exceptions
 146 ----------
 147
 148 There is also the possibility of an exception.  If argument evaluation
 149 or copy construction throws an exception, the landing pad must do
 150 cleanup, which includes adjusting the stack pointer to avoid a stack
 151 leak.  This means the cleanup of the stack memory cannot be tied to the
 152 call itself.  There needs to be a separate IR-level instruction that can
 153 perform independent cleanup of arguments.
 154
 155 Efficiency
 156 ----------
 157
 158 Eventually, it should be possible to generate efficient code for this
 159 construct.  In particular, using inalloca should not require a base
 160 pointer.  If the backend can prove that all points in the CFG only have
 161 one possible stack level, then it can address the stack directly from
 162 the stack pointer.  While this is not yet implemented, the plan is that
 163 the inalloca attribute should not change much, but the frontend IR
 164 generation recommendations may change.