From 2cbdc45f351aaccd63e612897cd57792a7f6360a Mon Sep 17 00:00:00 2001 From: Chris Lattner Date: Sun, 6 Nov 2005 08:02:57 +0000 Subject: [PATCH] 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 --- docs/LangRef.html | 133 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 103 insertions(+), 30 deletions(-) diff --git a/docs/LangRef.html b/docs/LangRef.html index 6b5bb962c6b..575f81ee071 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -494,7 +494,8 @@ convention.

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 never be modified (enabling better optimization, allowing the global data to be placed in the read-only section of @@ -516,6 +517,12 @@ variables always define a pointer to their "content" type because they describe a region of memory, and all memory objects in LLVM are accessed through pointers.

+

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.

+
@@ -528,11 +535,12 @@ accessed through pointers.

LLVM function definitions consist of an optional linkage type, an optional calling convention, 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 "declare" keyword, an optional calling convention, a return type, a function name, and -a possibly empty list of arguments.

+href="#callingconv">calling convention, a return type, a function name, +a possibly empty list of arguments, and an optional alignment.

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 @@ functions with the same name but different parameter lists or return values are considered different functions, and LLVM will resolve references to each appropriately.

+

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.

+ @@ -1761,98 +1775,157 @@ positions.

<result> = shr sbyte -2, ubyte 1 ; yields {sbyte}:result = -1 + -
Memory Access -Operations
+
+ Memory Access Operations +
+
+

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.

+
+ -
'malloc' -Instruction
+
+ 'malloc' Instruction +
+
+
Syntax:
-
  <result> = malloc <type>, uint <NumElements>     ; yields {type*}:result
-  <result> = malloc <type>                         ; yields {type*}:result
+
+
+  <result> = malloc <type>[, uint <NumElements>][, align <alignment>]     ; yields {type*}:result
 

+
 
Overview:

+
 
The 'malloc' instruction allocates memory from the system
 heap and returns a pointer to it.

+
 
Arguments:

-
The 'malloc' instruction allocates sizeof(<type>)*NumElements
+
+
The 'malloc' instruction allocates
+sizeof(<type>)*NumElements
 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.

+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.

+
 
'type' must be a sized type.

+
 
Semantics:

+
 
Memory is allocated using the system "malloc" function, and
 a pointer is returned.

-
Example:

-
  %array  = malloc [4 x ubyte ]                    ; yields {[%4 x ubyte]*}:array
 
-  %size   = add uint 2, 2                          ; yields {uint}:size = uint 4
+
Example:

+
+
+  %array  = malloc [4 x ubyte ]                    ; yields {[%4 x ubyte]*}:array
+
+  %size   = add uint 2, 2                          ; yields {uint}:size = uint 4
   %array1 = malloc ubyte, uint 4                   ; yields {ubyte*}:array1
   %array2 = malloc [12 x ubyte], uint %size        ; yields {[12 x ubyte]*}:array2
+  %array3 = malloc int, uint 4, align 1024         ; yields {int*}:array3
+  %array4 = malloc int, align 1024                 ; yields {int*}:array4
+ -
'free' -Instruction
+
+ 'free' Instruction +
+
+
Syntax:
-
  free <type> <value>                              ; yields {void}
+
+
+  free <type> <value>                              ; yields {void}
 

+
 
Overview:

+
 
The 'free' instruction returns memory back to the unused
 memory heap to be reallocated in the future.

-
 

+
 
Arguments:

+
 
'value' shall be a pointer value that points to a value
 that was allocated with the 'malloc'
 instruction.

+
 
Semantics:

+
 
Access to the memory pointed to by the pointer is no longer defined
 after this instruction executes.

+
 
Example:

-
  %array  = malloc [4 x ubyte]                    ; yields {[4 x ubyte]*}:array
+
+
+  %array  = malloc [4 x ubyte]                    ; yields {[4 x ubyte]*}:array
             free   [4 x ubyte]* %array
+ -
'alloca' -Instruction
+
+ 'alloca' Instruction +
+
+
Syntax:
-
  <result> = alloca <type>, uint <NumElements>  ; yields {type*}:result
-  <result> = alloca <type>                      ; yields {type*}:result
+
+
+  <result> = alloca <type>[, uint <NumElements>][, align <alignment>]     ; yields {type*}:result
 

+
 
Overview:

+
 
The 'alloca' instruction allocates memory on the current
 stack frame of the procedure that is live until the current function
 returns to its caller.

+
 
Arguments:

+
 
The 'alloca' instruction allocates sizeof(<type>)*NumElements
 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.

+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.

+
 
'type' may be any sized type.

+
 
Semantics:

+
 
Memory is allocated; a pointer is returned.  'alloca'd
 memory is automatically released when the function returns.  The 'alloca'
 instruction is commonly used to represent automatic variables that must
 have an address available.  When the function returns (either with the ret or unwind
 instructions), the memory is reclaimed.

+
 
Example:

-
  %ptr = alloca int                              ; yields {int*}:ptr
+
+
+  %ptr = alloca int                              ; yields {int*}:ptr
   %ptr = alloca int, uint 4                      ; yields {int*}:ptr
+  %ptr = alloca int, uint 4, align 1024          ; yields {int*}:ptr
+  %ptr = alloca int, align 1024                  ; yields {int*}:ptr
+
'load' Instruction