document alignment on globals, functions, and allocation instructions.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@24221 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/LangRef.html b/docs/LangRef.html
index 6b5bb96..575f81e 100644
--- a/docs/LangRef.html
+++ b/docs/LangRef.html
@@ -494,7 +494,8 @@
<div class="doc_text">
<p>Global variables define regions of memory allocated at compilation time
-instead of run-time. Global variables may optionally be initialized. A
+instead of run-time. Global variables may optionally be initialized, and may
+have an optional explicit alignment specified. A
variable may be defined as a global "constant," which indicates that the
contents of the variable will <b>never</b> be modified (enabling better
optimization, allowing the global data to be placed in the read-only section of
@@ -516,6 +517,12 @@
describe a region of memory, and all memory objects in LLVM are
accessed through pointers.</p>
+<p>An explicit alignment may be specified for a global. If not present, or if
+the alignment is set to zero, the alignment of the global is set by the target
+to whatever it feels convenient. If an explicit alignment is specified, the
+global is forced to have at least that much alignment. All alignments must be
+a power of 2.</p>
+
</div>
@@ -528,11 +535,12 @@
<p>LLVM function definitions consist of an optional <a href="#linkage">linkage
type</a>, an optional <a href="#callingconv">calling convention</a>, a return
-type, a function name, a (possibly empty) argument list, an opening curly brace,
+type, a function name, a (possibly empty) argument list, an optional alignment,
+an opening curly brace,
a list of basic blocks, and a closing curly brace. LLVM function declarations
are defined with the "<tt>declare</tt>" keyword, an optional <a
-href="#callingconv">calling convention</a>, a return type, a function name, and
-a possibly empty list of arguments.</p>
+href="#callingconv">calling convention</a>, a return type, a function name,
+a possibly empty list of arguments, and an optional alignment.</p>
<p>A function definition contains a list of basic blocks, forming the CFG for
the function. Each basic block may optionally start with a label (giving the
@@ -551,6 +559,12 @@
considered different functions, and LLVM will resolve references to each
appropriately.</p>
+<p>An explicit alignment may be specified for a function. If not present, or if
+the alignment is set to zero, the alignment of the function is set by the target
+to whatever it feels convenient. If an explicit alignment is specified, the
+function is forced to have at least that much alignment. All alignments must be
+a power of 2.</p>
+
</div>
@@ -1761,98 +1775,157 @@
<result> = shr sbyte -2, ubyte 1 <i>; yields {sbyte}:result = -1</i>
</pre>
</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection"> <a name="memoryops">Memory Access
-Operations</a></div>
+<div class="doc_subsection">
+ <a name="memoryops">Memory Access Operations</a>
+</div>
+
<div class="doc_text">
+
<p>A key design point of an SSA-based representation is how it
represents memory. In LLVM, no memory locations are in SSA form, which
makes things very simple. This section describes how to read, write,
allocate, and free memory in LLVM.</p>
+
</div>
+
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_malloc">'<tt>malloc</tt>'
-Instruction</a> </div>
+<div class="doc_subsubsection">
+ <a name="i_malloc">'<tt>malloc</tt>' Instruction</a>
+</div>
+
<div class="doc_text">
+
<h5>Syntax:</h5>
-<pre> <result> = malloc <type>, uint <NumElements> <i>; yields {type*}:result</i>
- <result> = malloc <type> <i>; yields {type*}:result</i>
+
+<pre>
+ <result> = malloc <type>[, uint <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
</pre>
+
<h5>Overview:</h5>
+
<p>The '<tt>malloc</tt>' instruction allocates memory from the system
heap and returns a pointer to it.</p>
+
<h5>Arguments:</h5>
-<p>The '<tt>malloc</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt>
+
+<p>The '<tt>malloc</tt>' instruction allocates
+<tt>sizeof(<type>)*NumElements</tt>
bytes of memory from the operating system and returns a pointer of the
-appropriate type to the program. The second form of the instruction is
-a shorter version of the first instruction that defaults to allocating
-one element.</p>
+appropriate type to the program. If "NumElements" is specified, it is the
+number of elements allocated. If an alignment is specified, the value result
+of the allocation is guaranteed to be aligned to at least that boundary. If
+not specified, or if zero, the target can choose to align the allocation on any
+convenient boundary.</p>
+
<p>'<tt>type</tt>' must be a sized type.</p>
+
<h5>Semantics:</h5>
+
<p>Memory is allocated using the system "<tt>malloc</tt>" function, and
a pointer is returned.</p>
-<h5>Example:</h5>
-<pre> %array = malloc [4 x ubyte ] <i>; yields {[%4 x ubyte]*}:array</i>
- %size = <a
- href="#i_add">add</a> uint 2, 2 <i>; yields {uint}:size = uint 4</i>
+<h5>Example:</h5>
+
+<pre>
+ %array = malloc [4 x ubyte ] <i>; yields {[%4 x ubyte]*}:array</i>
+
+ %size = <a href="#i_add">add</a> uint 2, 2 <i>; yields {uint}:size = uint 4</i>
%array1 = malloc ubyte, uint 4 <i>; yields {ubyte*}:array1</i>
%array2 = malloc [12 x ubyte], uint %size <i>; yields {[12 x ubyte]*}:array2</i>
+ %array3 = malloc int, uint 4, align 1024 <i>; yields {int*}:array3</i>
+ %array4 = malloc int, align 1024 <i>; yields {int*}:array4</i>
</pre>
</div>
+
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_free">'<tt>free</tt>'
-Instruction</a> </div>
+<div class="doc_subsubsection">
+ <a name="i_free">'<tt>free</tt>' Instruction</a>
+</div>
+
<div class="doc_text">
+
<h5>Syntax:</h5>
-<pre> free <type> <value> <i>; yields {void}</i>
+
+<pre>
+ free <type> <value> <i>; yields {void}</i>
</pre>
+
<h5>Overview:</h5>
+
<p>The '<tt>free</tt>' instruction returns memory back to the unused
memory heap to be reallocated in the future.</p>
-<p> </p>
+
<h5>Arguments:</h5>
+
<p>'<tt>value</tt>' shall be a pointer value that points to a value
that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>'
instruction.</p>
+
<h5>Semantics:</h5>
+
<p>Access to the memory pointed to by the pointer is no longer defined
after this instruction executes.</p>
+
<h5>Example:</h5>
-<pre> %array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
+
+<pre>
+ %array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
free [4 x ubyte]* %array
</pre>
</div>
+
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_alloca">'<tt>alloca</tt>'
-Instruction</a> </div>
+<div class="doc_subsubsection">
+ <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
+</div>
+
<div class="doc_text">
+
<h5>Syntax:</h5>
-<pre> <result> = alloca <type>, uint <NumElements> <i>; yields {type*}:result</i>
- <result> = alloca <type> <i>; yields {type*}:result</i>
+
+<pre>
+ <result> = alloca <type>[, uint <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
</pre>
+
<h5>Overview:</h5>
+
<p>The '<tt>alloca</tt>' instruction allocates memory on the current
stack frame of the procedure that is live until the current function
returns to its caller.</p>
+
<h5>Arguments:</h5>
+
<p>The '<tt>alloca</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt>
bytes of memory on the runtime stack, returning a pointer of the
-appropriate type to the program. The second form of the instruction is
-a shorter version of the first that defaults to allocating one element.</p>
+appropriate type to the program. If "NumElements" is specified, it is the
+number of elements allocated. If an alignment is specified, the value result
+of the allocation is guaranteed to be aligned to at least that boundary. If
+not specified, or if zero, the target can choose to align the allocation on any
+convenient boundary.</p>
+
<p>'<tt>type</tt>' may be any sized type.</p>
+
<h5>Semantics:</h5>
+
<p>Memory is allocated; a pointer is returned. '<tt>alloca</tt>'d
memory is automatically released when the function returns. The '<tt>alloca</tt>'
instruction is commonly used to represent automatic variables that must
have an address available. When the function returns (either with the <tt><a
href="#i_ret">ret</a></tt> or <tt><a href="#i_unwind">unwind</a></tt>
instructions), the memory is reclaimed.</p>
+
<h5>Example:</h5>
-<pre> %ptr = alloca int <i>; yields {int*}:ptr</i>
+
+<pre>
+ %ptr = alloca int <i>; yields {int*}:ptr</i>
%ptr = alloca int, uint 4 <i>; yields {int*}:ptr</i>
+ %ptr = alloca int, uint 4, align 1024 <i>; yields {int*}:ptr</i>
+ %ptr = alloca int, align 1024 <i>; yields {int*}:ptr</i>
</pre>
</div>
+
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>'
Instruction</a> </div>