[PATCH] Begin adding docs and IR-level support for the inalloca attribute

[Reid Kleckner]

================
Comment at: docs/LangRef.rst:702-728
@@ -701,1 +701,29 @@
 
+.. _attr_inalloca:
+
+``inalloca``
+
+    The ``inalloca`` argument attribute allows the caller to get the
+    address of an outgoing argument to a ``call`` or ``invoke`` before
+    it executes.  It is similar to ``byval`` in that it is used to pass
+    arguments by value, but it guarantees that the argument will not be
+    copied.
+
+    To be :ref:`well formed <wellformed>`, the caller must pass in an
+    alloca value into an ``inalloca`` parameter, and an alloca may be
+    used as an ``inalloca`` argument at most once.  The attribute can
+    only be applied to parameters that would be passed in memory and not
+    registers.  The ``inalloca`` attribute cannot be used in conjunction
+    with ``byval``, ``readonly``, ``inreg``, and others.
+
+    There are additional rules that must be followed at runtime to avoid
+    undefined behavior.  allocas passed with ``inalloca`` to a given
+    call must be in the opposite order of the parameter list, meaning
+    that the rightmost argument must be allocated first.  If a call has
+    inalloca arguments, no other allocas can occur between the first
+    alloca used by the call and the call site, unless they are are
+    cleared by calls to :ref:`llvm.stackrestore <int_stackrestore>`.
+
+    See :doc:`InAlloca` for more information on how to use this
+    attribute.
+
----------------
Sean Silva wrote:
> Now there is no indication that this feature is experimental.
> 
> Just as with Andy's stackmaps document, I suggest moving the *entire* description of this feature to the new document, and have LangRef only contain a link to it. For example, maybe you would say ##``alloca`` There is also the experimental inalloca attribute described at :doc:`InAlloca`. It is primarily designed for complying with the Microsoft C++ ABI.##.
> 
> That way, it clearly stands apart from the other non-experimental attributes.
> 
> Also, using a separate page "gives you space" to give the feature adequate and precise description (especially for a feature like this, which is kind of subtle), whereas trying to fit in a description into LangRef you necessarily are working under "space pressure" amidst the rest of the document, and are likely to give insufficient description and hence not actually produce proper reference documentation.
I think the hard and fast rules have to go in LangRef, and I hope to reach tentative agreement on them in this patch.  Intended usage and explanations can live in the other document.

================
Comment at: docs/LangRef.rst:719-720
@@ +718,4 @@
+
+    There are additional rules that must be followed at runtime to avoid
+    undefined behavior.  allocas passed with ``inalloca`` to a given
+    call must be in the opposite order of the parameter list, meaning
----------------
Sean Silva wrote:
> Does this paragraph list all such rules? Maybe just delete this introductory sentence?
I clarified that these rules are unchecked at the end of the paragraph and removed this sentence.


http://llvm-reviews.chandlerc.com/D2173