From 26fe25f6517238fd113f280863ffe0fbe237dd7c Mon Sep 17 00:00:00 2001 From: Benjamin Kramer Date: Tue, 13 Jul 2010 12:26:09 +0000 Subject: HTML cleanup and validation. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@108239 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/LangRef.html | 150 ++++++++++++++---------------------------------------- 1 file changed, 39 insertions(+), 111 deletions(-) (limited to 'docs/LangRef.html') diff --git a/docs/LangRef.html b/docs/LangRef.html index 80bf1c8b34..0eee86e8c0 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -370,11 +370,9 @@ what is considered 'well formed'. For example, the following instruction is syntactically okay, but not well formed:

-
-
+
 %x = add i32 1, %x
 

-

because the definition of %x does not dominate all of its uses. The LLVM infrastructure provides a verification pass that may be used to verify @@ -437,29 +435,23 @@

The easy way:

-
-
+
 %result = mul i32 %X, 8
 

-

After strength reduction:

-
-
+
 %result = shl i32 %X, i8 3
 

-

And the hard way:

-
-
+
 %0 = add i32 %X, %X           ; yields {i32}:%0
 %1 = add i32 %0, %0           ; yields {i32}:%1
 %result = add i32 %1, %1
 

-

This last way of multiplying %X by 8 illustrates several important lexical features of LLVM:

@@ -498,8 +490,7 @@ forward declarations, and merges symbol table entries. Here is an example of the "hello world" module:

-
-
+
 ; Declare the string constant as a global constant.
 @.LC0 = internal constant [13 x i8] c"hello world\0A\00"    ; [13 x i8]*
 
@@ -519,7 +510,6 @@ define i32 @main() {                                        ; i32()* 
 !1 = metadata !{i32 41}
 !foo = !{!1, null}
 

-

This example is made up of a global variable named ".LC0", an external declaration of the "puts" function, @@ -793,11 +783,9 @@ define i32 @main() { ; i32()* it easier to read the IR and make the IR more condensed (particularly when recursive types are involved). An example of a name specification is:

-
-
+
 %mytype = type { %mytype*, i32 }
 

-

You may give a name to any type except "void". Type name aliases may be used anywhere a type @@ -869,11 +857,9 @@ define i32 @main() { ; i32()*

For example, the following defines a global in a numbered address space with an initializer, section, and alignment:

-
-
+
 @G = addrspace(5) constant float 1.0, section "foo", align 4
 

-
@@ -926,15 +912,13 @@ define i32 @main() { ; i32()* alignments must be a power of 2.

Syntax:
-
-
+
 define [linkage] [visibility]
        [cconv] [ret attrs]
        <ResultType> @<FunctionName> ([argument list])
        [fn Attrs] [section "name"] [align N]
        [gc] { ... }
 

-
@@ -951,11 +935,9 @@ define [linkage] [visibility] optional visibility style.

Syntax:
-
-
+
 @<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee>
 

-
@@ -971,12 +953,10 @@ define [linkage] [visibility] a named metadata.

Syntax:
-
-
+
 !1 = metadata !{metadata !"one"}
 !name = !{null, !1}
 

-
@@ -996,13 +976,11 @@ define [linkage] [visibility] multiple parameter attributes are needed, they are space separated. For example:

-
-
+
 declare i32 @printf(i8* noalias nocapture, ...)
 declare i32 @atoi(i8 zeroext)
 declare signext i8 @returns_signed_char()
 

-

Note that any attributes for the function result (nounwind, readonly) come immediately after the argument list.

@@ -1095,11 +1073,9 @@ declare signext i8 @returns_signed_char()

Each function may specify a garbage collector name, which is simply a string:

-
-
+
 define void @f() gc "name" { ... }
 

-

The compiler declares the supported values of name. Specifying a collector which will cause the compiler to alter its output in order to @@ -1122,14 +1098,12 @@ define void @f() gc "name" { ... }

Function attributes are simple keywords that follow the type specified. If multiple attributes are needed, they are space separated. For example:

-
-
+
 define void @f() noinline { ... }
 define void @f() alwaysinline { ... }
 define void @f() alwaysinline optsize { ... }
 define void @f() optsize { ... }
 

-
alignstack(<n>)
@@ -1236,12 +1210,10 @@ define void @f() optsize { ... } concatenated by LLVM and treated as a single unit, but may be separated in the .ll file if desired. The syntax is very simple:

-
-
+
 module asm "inline asm code goes here"
 module asm "more can go here"
 

-

The strings can contain any character by escaping non-printable characters. The escape sequence used is simply "\xx" where "xx" is the two digit hex code @@ -1263,11 +1235,9 @@ module asm "more can go here" data is to be laid out in memory. The syntax for the data layout is simply:

-
-
+
 target datalayout = "layout specification"
 

-

The layout specification consists of a list of specifications separated by the minus sign character ('-'). Each specification starts with @@ -1663,8 +1633,6 @@ Classifications - -

Array Type
@@ -2198,13 +2166,11 @@ Classifications have pointer type. For example, the following is a legal LLVM file:

-
-
+
 @X = global i32 17
 @Y = global i32 42
 @Z = global [2 x i32*] [ i32* @X, i32* @Y ]
 

-
@@ -2223,8 +2189,7 @@ Classifications surprising) transformations that are valid (in pseudo IR):

-
-
+
   %A = add %X, undef
   %B = sub %X, undef
   %C = xor %X, undef
@@ -2233,13 +2198,11 @@ Safe:
   %B = undef
   %C = undef
 

-

This is safe because all of the output bits are affected by the undef bits. Any output bit can have a zero or one depending on the input bits.

-
-
+
   %A = or %X, undef
   %B = and %X, undef
 Safe:
@@ -2249,7 +2212,6 @@ Unsafe:
   %A = undef
   %B = undef
 

-

These logical operations have bits that are not always affected by the input. For example, if "%X" has a zero bit, then the output of the 'and' operation will @@ -2260,8 +2222,7 @@ optimize the and to 0. Likewise, it is safe to assume that all the bits of the undef operand to the or could be set, allowing the or to be folded to -1.

-
-
+
   %A = select undef, %X, %Y
   %B = select undef, 42, %Y
   %C = select %X, %Y, undef
@@ -2274,7 +2235,6 @@ Unsafe:
   %B = undef
   %C = undef
 

-

This set of examples show that undefined select (and conditional branch) conditions can go "either way" but they have to come from one of the two @@ -2284,8 +2244,7 @@ the optimizer is allowed to assume that the undef operand could be the same as %Y, allowing the whole select to be eliminated.

-
-
+
   %A = xor undef, undef
 
   %B = undef
@@ -2303,7 +2262,6 @@ Safe:
   %E = undef
   %F = undef
 

-

This example points out that two undef operands are not necessarily the same. This can be surprising to people (and also matches C semantics) where they @@ -2316,15 +2274,13 @@ so the value is not necessarily consistent over time. In fact, %A and %C need to have the same semantics or the core LLVM "replace all uses with" concept would not hold.

-
-
+
   %A = fdiv undef, %X
   %B = fdiv %X, undef
 Safe:
   %A = undef
 b: unreachable
 

-

These examples show the crucial difference between an undefined value and undefined behavior. An undefined value (like undef) is @@ -2339,15 +2295,13 @@ it: since the undefined operation "can't happen", the optimizer can assume that it occurs in dead code.

-
-
+
 a:  store undef -> %X
 b:  store %X -> undef
 Safe:
 a: <deleted>
 b: unreachable
 

-

These examples reiterate the fdiv example: a store "of" an undefined value can be assumed to not have any effect: we can assume that the value is @@ -2373,7 +2327,6 @@ has undefined behavior.

Trap value behavior is defined in terms of value dependence:

-

-

Whenever a trap value is generated, all values which depend on it evaluate to trap. If they have side effects, the evoke their side effects as if each @@ -2426,8 +2378,7 @@ has undefined behavior.

Here are some examples:

-
-
+
 entry:
   %trap = sub nuw i32 0, 1           ; Results in a trap value.
   %still_trap = and i32 %trap, 0     ; Whereas (and i32 undef, 0) would return 0.
@@ -2462,7 +2413,6 @@ end:
                                      ; so this is defined (ignoring earlier
                                      ; undefined behavior in this example).
 

-
@@ -2644,31 +2594,25 @@ end: containing the asm needs to align its stack conservatively. An example inline assembler expression is:

-
-
+
 i32 (i32) asm "bswap $0", "=r,r"
 

-

Inline assembler expressions may only be used as the callee operand of a call instruction. Thus, typically we have:

-
-
+
 %X = call i32 asm "bswap $0", "=r,r"(i32 %Y)
 

-

Inline asms with side effects not visible in the constraint list must be marked as having side effects. This is done through the use of the 'sideeffect' keyword, like so:

-
-
+
 call void asm sideeffect "eieio", ""()
 

-

In some cases inline asms will contain code that will not work unless the stack is aligned in some way, such as calls or SSE instructions on x86, @@ -2677,11 +2621,9 @@ call void asm sideeffect "eieio", ""() contain and should generate its usual stack alignment code in the prologue if the 'alignstack' keyword is present:

-
-
+
 call void asm alignstack "eieio", ""()
 

-

If both keywords appear the 'sideeffect' keyword must come first.

@@ -2705,13 +2647,11 @@ call void asm alignstack "eieio", ""() front-end to correlate backend errors that occur with inline asm back to the source code that produced it. For example:

-
-
+
 call void asm sideeffect "something bad", ""(), !srcloc !42
 ...
 !42 = !{ i32 1234567 }
 

-

It is up to the front-end to make sense of the magic numbers it places in the IR.

@@ -2746,22 +2686,18 @@ call void asm sideeffect "something bad", ""(), !srcloc !42 example: "!foo = metadata !{!4, !3}".

Metadata can be used as function arguments. Here llvm.dbg.value - function is using two metadata arguments. + function is using two metadata arguments.

-
- 
+     
        call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
      

-

Metadata can be attached with an instruction. Here metadata !21 is - attached with add instruction using !dbg identifier. + attached with add instruction using !dbg identifier.

-
- 
+    
       %indvar.next = add i64 %indvar, 1, !dbg !21
     

-

@@ -4389,8 +4325,8 @@ Instruction
Syntax:
-  store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !]                   ; yields {void}
-  volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !]          ; yields {void}
+  store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]                   ; yields {void}
+  volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]          ; yields {void}
Overview:
@@ -4415,7 +4351,7 @@ Instruction produce less efficient code. An alignment of 1 is always safe.

The optional !nontemporal metadata must reference a single metatadata - name corresponding to a metadata node with one i32 entry of + name <index> corresponding to a metadata node with one i32 entry of value 1. The existence of the !nontemporal metatadata on the instruction tells the optimizer and code generator that this load is not expected to be reused in the cache. The code generator may @@ -4482,8 +4418,7 @@ Instruction

For example, let's consider a C code fragment and how it gets compiled to LLVM:

-
-
+
 struct RT {
   char A;
   int B[10][20];
@@ -4499,12 +4434,10 @@ int *foo(struct ST *s) {
   return &s[1].Z.B[5][13];
 }
 

-

The LLVM code generated by the GCC frontend is:

-
-
+
 %RT = type { i8 , [10 x [20 x i32]], i8  }
 %ST = type { i32, double, %RT }
 
@@ -4514,7 +4447,6 @@ entry:
   ret i32* %reg
 }
 

-
Semantics:

In the example above, the first index is indexing into the '%ST*' @@ -5585,8 +5517,7 @@ freestanding environments and non-C-based languages.

instruction and the variable argument handling intrinsic functions are used.

-
-
+
 define i32 @test(i32 %X, ...) {
   ; Initialize variable argument processing
   %ap = alloca i8*
@@ -5611,7 +5542,6 @@ declare void @llvm.va_start(i8*)
 declare void @llvm.va_copy(i8*, i8*)
 declare void @llvm.va_end(i8*)
 

-
@@ -6977,14 +6907,12 @@ LLVM.

pointer has signature i32 (i32, i32)*. It can be created as follows:

-
-
+
   %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
   %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0
   %p = call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8* nest , i32, i32)* @f to i8*), i8* %nval)
   %fp = bitcast i8* %p to i32 (i32, i32)*
 

-

The call %val = call i32 %fp(i32 %x, i32 %y) is then equivalent to %val = call i32 %f(i8* %nval, i32 %x, i32 %y).

-- cgit v1.2.3