/usr/share/doc/llvm-3.5-doc/html/InAlloca.html is in llvm-3.5-doc 1:3.5~svn201651-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Design and Usage of the InAlloca Attribute — LLVM 3.4 documentation</title>
<link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '3.4',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="LLVM 3.4 documentation" href="index.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head>
<body>
<div class="logo">
<a href="index.html">
<img src="_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></a>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li><a href="http://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="body">
<div class="section" id="design-and-usage-of-the-inalloca-attribute">
<h1>Design and Usage of the InAlloca Attribute<a class="headerlink" href="#design-and-usage-of-the-inalloca-attribute" title="Permalink to this headline">¶</a></h1>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This feature is unstable and not fully implemented.</p>
</div>
<p>The <a class="reference internal" href="LangRef.html#attr-inalloca"><em>inalloca</em></a> attribute is designed to allow
taking the address of an aggregate argument that is being passed by
value through memory. Primarily, this feature is required for
compatibility with the Microsoft C++ ABI. Under that ABI, class
instances that are passed by value are constructed directly into
argument stack memory. Prior to the addition of inalloca, calls in LLVM
were indivisible instructions. There was no way to perform intermediate
work, such as object construction, between the first stack adjustment
and the final control transfer. With inalloca, all arguments passed in
memory are modelled as a single alloca, which can be stored to prior to
the call. Unfortunately, this complicated feature comes with a large
set of restrictions designed to bound the lifetime of the argument
memory around the call.</p>
<p>For now, it is recommended that frontends and optimizers avoid producing
this construct, primarily because it forces the use of a base pointer.
This feature may grow in the future to allow general mid-level
optimization, but for now, it should be regarded as less efficient than
passing by value with a copy.</p>
</div>
<div class="section" id="intended-usage">
<h2>Intended Usage<a class="headerlink" href="#intended-usage" title="Permalink to this headline">¶</a></h2>
<p>The example below is the intended LLVM IR lowering for some C++ code
that passes a default-constructed <tt class="docutils literal"><span class="pre">Foo</span></tt> object to <tt class="docutils literal"><span class="pre">g</span></tt> in the 32-bit
Microsoft C++ ABI.</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Foo is non-trivial.</span>
<span class="k">struct</span> <span class="n">Foo</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">;</span> <span class="n">Foo</span><span class="p">();</span> <span class="o">~</span><span class="n">Foo</span><span class="p">();</span> <span class="n">Foo</span><span class="p">(</span><span class="k">const</span> <span class="o">&</span><span class="n">Foo</span><span class="p">);</span> <span class="p">};</span>
<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="n">Foo</span> <span class="n">a</span><span class="p">,</span> <span class="n">Foo</span> <span class="n">b</span><span class="p">);</span>
<span class="kt">void</span> <span class="nf">f</span><span class="p">()</span> <span class="p">{</span>
<span class="n">f</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">Foo</span><span class="p">(),</span> <span class="mi">3</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="highlight-llvm"><div class="highlight"><pre>%struct.Foo = type { i32, i32 }
%callframe.f = type { %struct.Foo, %struct.Foo }
declare void @Foo_ctor(%Foo* %this)
declare void @Foo_dtor(%Foo* %this)
declare void @g(%Foo* inalloca %memargs)
define void @f() {
entry:
%base = call i8* @llvm.stacksave()
%memargs = alloca %callframe.f
%b = getelementptr %callframe.f*, i32 0
%a = getelementptr %callframe.f*, i32 1
call void @Foo_ctor(%struct.Foo* %b)
; If a's ctor throws, we must destruct b.
invoke void @Foo_ctor(%struct.Foo* %arg1)
to label %invoke.cont unwind %invoke.unwind
invoke.cont:
store i32 1, i32* %arg0
call void @g(%callframe.f* inalloca %memargs)
call void @llvm.stackrestore(i8* %base)
...
invoke.unwind:
call void @Foo_dtor(%struct.Foo* %b)
call void @llvm.stackrestore(i8* %base)
...
}
</pre></div>
</div>
<p>To avoid stack leaks, the frontend saves the current stack pointer with
a call to <a class="reference internal" href="LangRef.html#int-stacksave"><em>llvm.stacksave</em></a>. Then, it allocates the
argument stack space with alloca and calls the default constructor. The
default constructor could throw an exception, so the frontend has to
create a landing pad. The frontend has to destroy the already
constructed argument <tt class="docutils literal"><span class="pre">b</span></tt> before restoring the stack pointer. If the
constructor does not unwind, <tt class="docutils literal"><span class="pre">g</span></tt> is called. In the Microsoft C++ ABI,
<tt class="docutils literal"><span class="pre">g</span></tt> will destroy its arguments, and then the stack is restored in
<tt class="docutils literal"><span class="pre">f</span></tt>.</p>
</div>
<div class="section" id="design-considerations">
<h2>Design Considerations<a class="headerlink" href="#design-considerations" title="Permalink to this headline">¶</a></h2>
<div class="section" id="lifetime">
<h3>Lifetime<a class="headerlink" href="#lifetime" title="Permalink to this headline">¶</a></h3>
<p>The biggest design consideration for this feature is object lifetime.
We cannot model the arguments as static allocas in the entry block,
because all calls need to use the memory at the top of the stack to pass
arguments. We cannot vend pointers to that memory at function entry
because after code generation they will alias.</p>
<p>The rule against allocas between argument allocations and the call site
avoids this problem, but it creates a cleanup problem. Cleanup and
lifetime is handled explicitly with stack save and restore calls. In
the future, we may want to introduce a new construct such as <tt class="docutils literal"><span class="pre">freea</span></tt>
or <tt class="docutils literal"><span class="pre">afree</span></tt> to make it clear that this stack adjusting cleanup is less
powerful than a full stack save and restore.</p>
</div>
<div class="section" id="nested-calls-and-copy-elision">
<h3>Nested Calls and Copy Elision<a class="headerlink" href="#nested-calls-and-copy-elision" title="Permalink to this headline">¶</a></h3>
<p>We also want to be able to support copy elision into these argument
slots. This means we have to support multiple live argument
allocations.</p>
<p>Consider the evaluation of:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Foo is non-trivial.</span>
<span class="k">struct</span> <span class="n">Foo</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">a</span><span class="p">;</span> <span class="n">Foo</span><span class="p">();</span> <span class="n">Foo</span><span class="p">(</span><span class="k">const</span> <span class="o">&</span><span class="n">Foo</span><span class="p">);</span> <span class="o">~</span><span class="n">Foo</span><span class="p">();</span> <span class="p">};</span>
<span class="n">Foo</span> <span class="nf">bar</span><span class="p">(</span><span class="n">Foo</span> <span class="n">b</span><span class="p">);</span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
<span class="n">bar</span><span class="p">(</span><span class="n">bar</span><span class="p">(</span><span class="n">Foo</span><span class="p">()));</span>
<span class="p">}</span>
</pre></div>
</div>
<p>In this case, we want to be able to elide copies into <tt class="docutils literal"><span class="pre">bar</span></tt>‘s argument
slots. That means we need to have more than one set of argument frames
active at the same time. First, we need to allocate the frame for the
outer call so we can pass it in as the hidden struct return pointer to
the middle call. Then we do the same for the middle call, allocating a
frame and passing its address to <tt class="docutils literal"><span class="pre">Foo</span></tt>‘s default constructor. By
wrapping the evaluation of the inner <tt class="docutils literal"><span class="pre">bar</span></tt> with stack save and
restore, we can have multiple overlapping active call frames.</p>
</div>
<div class="section" id="callee-cleanup-calling-conventions">
<h3>Callee-cleanup Calling Conventions<a class="headerlink" href="#callee-cleanup-calling-conventions" title="Permalink to this headline">¶</a></h3>
<p>Another wrinkle is the existence of callee-cleanup conventions. On
Windows, all methods and many other functions adjust the stack to clear
the memory used to pass their arguments. In some sense, this means that
the allocas are automatically cleared by the call. However, LLVM
instead models this as a write of undef to all of the inalloca values
passed to the call instead of a stack adjustment. Frontends should
still restore the stack pointer to avoid a stack leak.</p>
</div>
<div class="section" id="exceptions">
<h3>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3>
<p>There is also the possibility of an exception. If argument evaluation
or copy construction throws an exception, the landing pad must do
cleanup, which includes adjusting the stack pointer to avoid a stack
leak. This means the cleanup of the stack memory cannot be tied to the
call itself. There needs to be a separate IR-level instruction that can
perform independent cleanup of arguments.</p>
</div>
<div class="section" id="efficiency">
<h3>Efficiency<a class="headerlink" href="#efficiency" title="Permalink to this headline">¶</a></h3>
<p>Eventually, it should be possible to generate efficient code for this
construct. In particular, using inalloca should not require a base
pointer. If the backend can prove that all points in the CFG only have
one possible stack level, then it can address the stack directly from
the stack pointer. While this is not yet implemented, the plan is that
the inalloca attribute should not change much, but the frontend IR
generation recommendations may change.</p>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li><a href="http://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
</ul>
</div>
<div class="footer">
© Copyright 2003-2014, LLVM Project.
Last updated on 2014-03-23.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
|