[llvm-commits] CVS: llvm/docs/LangRef.html
Chris Lattner
lattner at cs.uiuc.edu
Sun Nov 6 00:03:09 PST 2005
Changes in directory llvm/docs:
LangRef.html updated: 1.113 -> 1.114
---
Log message:
document alignment on globals, functions, and allocation instructions.
---
Diffs of the changes: (+103 -30)
LangRef.html | 133 +++++++++++++++++++++++++++++++++++++++++++++--------------
1 files changed, 103 insertions(+), 30 deletions(-)
Index: llvm/docs/LangRef.html
diff -u llvm/docs/LangRef.html:1.113 llvm/docs/LangRef.html:1.114
--- llvm/docs/LangRef.html:1.113 Mon Oct 24 11:17:18 2005
+++ llvm/docs/LangRef.html Sun Nov 6 02:02:57 2005
@@ -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>
+<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>
@@ -3314,7 +3387,7 @@
<a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
<a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
- Last modified: $Date: 2005/10/24 16:17:18 $
+ Last modified: $Date: 2005/11/06 08:02:57 $
</address>
</body>
</html>
More information about the llvm-commits
mailing list