From c3f5976112c2785f192c4ef95404627020d33ec3 Mon Sep 17 00:00:00 2001 From: Chris Lattner Date: Thu, 9 Dec 2004 17:30:23 +0000 Subject: Fully document the LLVM constants. This should go into LLVM 1.4 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@18701 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/LangRef.html | 228 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 213 insertions(+), 15 deletions(-) (limited to 'docs/LangRef.html') diff --git a/docs/LangRef.html b/docs/LangRef.html index 42767e6..77c20c1 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -44,6 +44,13 @@
  • Constants +
      +
    1. Simple Constants +
    2. Aggregate Constants +
    3. Global Variable and Function Addresses +
    4. Undefined Values +
    5. Constant Expressions +
  • Instruction Reference
      @@ -221,9 +228,6 @@ the parser.

      purposes:

        -
      1. Numeric constants are represented as you would expect: 12, -3 123.421, - etc. Floating point constants have an optional hexadecimal notation.
        2. -
      2. Named values are represented as a string of characters with a '%' prefix. For example, %foo, %DivisionByZero, %a.really.long.identifier. The actual regular expression used is '%[a-zA-Z$._][a-zA-Z$._0-9]*'. @@ -234,6 +238,8 @@ purposes:

      3. Unnamed values are represented as an unsigned numeric value with a '%' prefix. For example, %12, %2, %44.
        4. +
      4. Constants, which are described in section about + constants

      LLVM requires that values start with a '%' sign for two reasons: Compilers @@ -293,16 +299,6 @@ demonstrating instructions, we will follow an instruction with a comment that defines the type and name of value produced. Comments are shown in italic text.

      -

      The one non-intuitive notation for constants is the optional hexidecimal form -of floating point constants. For example, the form 'double -0x432ff973cafa8000' is equivalent to (but harder to read than) 'double -4.5e+15' which is also supported by the parser. The only time hexadecimal -floating point constants are useful (and the only time that they are generated -by the disassembler) is when an FP constant has to be emitted that is not -representable as a decimal floating point number exactly. For example, NaN's, -infinities, and other special cases are represented in their IEEE hexadecimal -format so that assembly and disassembly do not cause any bits to change in the -constants.

      @@ -577,25 +573,39 @@ produced by instructions, passed as arguments, or used as operands to instructions. This means that all structures and arrays must be manipulated either by pointer or by component.

      +
      Derived Types
      +
      +

      The real power in LLVM comes from the derived types in the system. This is what allows a programmer to represent arrays, functions, pointers, and other useful types. Note that these derived types may be recursive: For example, it is possible to have a two dimensional array.

      +
      +
      Array Type
      +
      +
      Overview:
      +

      The array type is a very simple derived type that arranges elements sequentially in memory. The array type requires a size (number of elements) and an underlying data type.

      +
      Syntax:
      -
        [<# elements> x <elementtype>]
      + +
      +  [<# elements> x <elementtype>]
+
      +

      The number of elements is a constant integer value, elementtype may be any type with a size.

      +
      Examples:
      @@ -756,34 +766,220 @@ be any integral or floating point type.

      + +
      Constants
      + + +
      + +

      LLVM has several different basic types of constants. This section describes +them all and their syntax.

      + +
      + + +
      Simple Constants +
      + +
      + +
      +
      Boolean constants
      + +
      The two strings 'true' and 'false' are both valid + constants of the bool type. +
      + +
      Integer constants
      + +
      Standard integers (such as '4') are constants of integer type. Negative numbers may be used with signed + integer types. +
      + +
      Floating point constants
      + +
      Floating point constants use standard decimal notation (e.g. 123.421), + exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal + notation. etc. Floating point constants have an optional hexadecimal + notation (see below). Floating point constants must have a floating point type.
      + +
      Null pointer constants
      + +
      The identifier 'null' is recognized as a null pointer constant, + and must be of pointer type.
      + +
      + +

      The one non-intuitive notation for constants is the optional hexidecimal form +of floating point constants. For example, the form 'double +0x432ff973cafa8000' is equivalent to (but harder to read than) 'double +4.5e+15'. The only time hexadecimal floating point constants are required +(and the only time that they are generated by the disassembler) is when an FP +constant has to be emitted that is not representable as a decimal floating point +number exactly. For example, NaN's, infinities, and other special cases are +represented in their IEEE hexadecimal format so that assembly and disassembly do +not cause any bits to change in the constants.

      + +
      + + +
      Aggregate Constants +
      + +
      + +
      +
      Structure constants
      + +
      Structure constants are represented with notation similar to structure + type definitions (a comma separated list of elements, surrounded by braces + ({}). For example: "{ int 4, float 17.0 }". Structure + constants must have structure type, and the number and + types of elements must match those specified by the type. +
      + +
      Array constants
      + +
      Array constants are represented with notation similar to array type + definitions (a comma separated list of elements, surrounded by square brackets + ([]). For example: "[ int 42, int 11, int 74 ]". Array + constants must have array type, and the number and + types of elements must match those specified by the type. +
      + +
      Packed constants
      + +
      Packed constants are represented with notation similar to packed type + definitions (a comma separated list of elements, surrounded by + less-than/greater-than's (<>). For example: "< int 42, + int 11, int 74, int 100 >". Packed constants must have packed type, and the number and types of elements must + match those specified by the type. +
      + +
      Zero initialization
      + +
      The string 'zeroinitializer' can be used to zero initialize a + value to zero of any type, including scalar and aggregate types. + This is often used to avoid having to print large zero initializers (e.g. for + large arrays), and is always exactly equivalent to using explicit zero + initializers. +
      +
      + +
      + + +
      + Global Variable and Function Addresses +
      + +
      + +

      The addresses of global variables and functions are always implicitly valid (link-time) +constants. These constants explicitly referenced when the identifier for the global is used, and always have pointer type. For example, the following is a legal LLVM +file:

      + +
      +  %X = global int 17
+  %Y = global int 42
+  %Z = global [2 x int*] [ int* %X, int* %Y ]
+
      + +
      + + +
      Undefined Values +
      + +
      + +

      The string 'undef' is recognized as a filler that has no specified +value. Undefined values may be of any type, and be used anywhere a constant +is.

      + +

      Undefined values are used to indicate the compiler that the program is well +defined no matter what value is used, giving it more freedom.

      + +
      + + +
      Constant Expressions +
      + +
      + +

      Constant expressions are used to allow expressions involving other constants +to be used as constants. Constant expressions may be of any first class type, and may involve any LLVM operation +that does not have side effects (e.g. load and call are not supported). The +following is the syntax for constant expressions:

      + +
      +
      cast ( CST to TYPE )
      + +
      Cast a constant to another type.
      + +
      getelementptr ( CSTPTR, IDX0, IDX1, ... )
      + +
      Perform the getelementptr operation on + constants. As with the getelementptr + instruction, the index list may have zero or more indexes, which are required + to make sense for the type of "CSTPTR".
      + +
      OPCODE ( LHS, RHS )
      + +
      Perform the specied operation of the LHS and RHS constants. OPCODE may be + any of the binary or bitwise + binary operations. The constraints on operands are the same as those for + the corresponding instruction (e.g. no bitwise operations on floating point + are allowed).
      + +
      + +
      Instruction Reference
      +
      +

      The LLVM instruction set consists of several different classifications of instructions: terminator instructions, binary instructions, memory instructions, and other instructions.

      +
      +
      Terminator Instructions
      +
      +

      As mentioned previously, every basic block in a program ends with a "Terminator" instruction, which indicates which block should be executed after the current block is finished. These terminator instructions typically yield a 'void' value: they produce control flow, not values (the one exception being the 'invoke' instruction).

      +

      There are five different terminator instructions: the 'ret' instruction, the 'br' instruction, the 'switch' instruction, the 'invoke' instruction, the 'unwind' instruction, and the 'unreachable' instruction.

      +
      +
      'ret' Instruction
      @@ -2361,7 +2557,9 @@ unsigned 16 bit value, and the return value must be 8, 16, or 32 bits.
      Syntax:
      -  call void (<integer type>, <integer type>)* %llvm.writeport (<integer type> <value>, <integer type> <address>)
+  call void (<integer type>, <integer type>)*
+            %llvm.writeport (<integer type> <value>,
+                             <integer type> <address>)
      Overview:
      -- cgit v1.1