diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/LangRef.rst | 334 |
1 files changed, 140 insertions, 194 deletions
diff --git a/docs/LangRef.rst b/docs/LangRef.rst index 9adbea5e9e..7f719cb375 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -4,7 +4,7 @@ LLVM Language Reference Manual .. contents:: :local: - :depth: 3 + :depth: 4 Abstract ======== @@ -1476,80 +1476,94 @@ transformation. A strong type system makes it easier to read the generated code and enables novel analyses and transformations that are not feasible to perform on normal three address code representations. -.. _typeclassifications: +.. _t_void: -Type Classifications --------------------- +Void Type +--------- -The types fall into a few useful classifications: +Overview: +^^^^^^^^^ +The void type does not represent any value and has no size. -.. list-table:: - :header-rows: 1 +Syntax: +^^^^^^^ + +:: + + void - * - Classification - - Types - * - :ref:`integer <t_integer>` - - ``i1``, ``i2``, ``i3``, ... ``i8``, ... ``i16``, ... ``i32``, ... - ``i64``, ... +.. _t_function: - * - :ref:`floating point <t_floating>` - - ``half``, ``float``, ``double``, ``x86_fp80``, ``fp128``, - ``ppc_fp128`` +Function Type +------------- +Overview: +^^^^^^^^^ - * - first class +The function type can be thought of as a function signature. It consists of a +return type and a list of formal parameter types. The return type of a function +type is a void type or first class type --- except for :ref:`label <t_label>` +and :ref:`metadata <t_metadata>` types. - .. _t_firstclass: +Syntax: +^^^^^^^ - - :ref:`integer <t_integer>`, :ref:`floating point <t_floating>`, - :ref:`pointer <t_pointer>`, :ref:`vector <t_vector>`, - :ref:`structure <t_struct>`, :ref:`array <t_array>`, - :ref:`label <t_label>`, :ref:`metadata <t_metadata>`. +:: - * - :ref:`primitive <t_primitive>` - - :ref:`label <t_label>`, - :ref:`void <t_void>`, - :ref:`integer <t_integer>`, - :ref:`floating point <t_floating>`, - :ref:`x86mmx <t_x86mmx>`, - :ref:`metadata <t_metadata>`. + <returntype> (<parameter list>) - * - :ref:`derived <t_derived>` - - :ref:`array <t_array>`, - :ref:`function <t_function>`, - :ref:`pointer <t_pointer>`, - :ref:`structure <t_struct>`, - :ref:`vector <t_vector>`, - :ref:`opaque <t_opaque>`. +...where '``<parameter list>``' is a comma-separated list of type +specifiers. Optionally, the parameter list may include a type ``...``, which +indicates that the function takes a variable number of arguments. Variable +argument functions can access their arguments with the :ref:`variable argument +handling intrinsic <int_varargs>` functions. '``<returntype>``' is any type +except :ref:`label <t_label>` and :ref:`metadata <t_metadata>`. + +Examples: +^^^^^^^^^ + ++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` | ++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. | ++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``i32 (i8*, ...)`` | A vararg function that takes at least one :ref:`pointer <t_pointer>` to ``i8`` (char in C), which returns an integer. This is the signature for ``printf`` in LLVM. | ++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``{i32, i32} (i32)`` | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values | ++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. _t_firstclass: + +First Class Types +----------------- The :ref:`first class <t_firstclass>` types are perhaps the most important. Values of these types are the only ones which can be produced by instructions. -.. _t_primitive: +.. _t_single_value: -Primitive Types ---------------- +Single Value Types +^^^^^^^^^^^^^^^^^^ -The primitive types are the fundamental building blocks of the LLVM -system. +These are the types that are valid in registers from CodeGen's perspective. .. _t_integer: Integer Type -^^^^^^^^^^^^ +"""""""""""" Overview: -""""""""" +********* The integer type is a very simple type that simply specifies an arbitrary bit width for the integer type desired. Any bit width from 1 bit to 2\ :sup:`23`\ -1 (about 8 million) can be specified. Syntax: -""""""" +******* :: @@ -1559,7 +1573,7 @@ The number of bits the integer will occupy is specified by the ``N`` value. Examples: -""""""""" +********* +----------------+------------------------------------------------+ | ``i1`` | a single-bit integer. | @@ -1572,7 +1586,7 @@ Examples: .. _t_floating: Floating Point Types -^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""" .. list-table:: :header-rows: 1 @@ -1601,10 +1615,10 @@ Floating Point Types .. _t_x86mmx: X86mmx Type -^^^^^^^^^^^ +""""""""""" Overview: -""""""""" +********* The x86mmx type represents a value held in an MMX register on an x86 machine. The operations allowed on it are quite limited: parameters and @@ -1614,28 +1628,87 @@ and/or results of this type. There are no arrays, vectors or constants of this type. Syntax: -""""""" +******* :: x86mmx -.. _t_void: -Void Type -^^^^^^^^^ +.. _t_pointer: + +Pointer Type +"""""""""""" Overview: -""""""""" +********* -The void type does not represent any value and has no size. +The pointer type is used to specify memory locations. Pointers are +commonly used to reference objects in memory. + +Pointer types may have an optional address space attribute defining the +numbered address space where the pointed-to object resides. The default +address space is number zero. The semantics of non-zero address spaces +are target-specific. + +Note that LLVM does not permit pointers to void (``void*``) nor does it +permit pointers to labels (``label*``). Use ``i8*`` instead. Syntax: -""""""" +******* :: - void + <type> * + +Examples: +********* + ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| ``[4 x i32]*`` | A :ref:`pointer <t_pointer>` to :ref:`array <t_array>` of four ``i32`` values. | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| ``i32 (i32*) *`` | A :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32*``, returning an ``i32``. | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| ``i32 addrspace(5)*`` | A :ref:`pointer <t_pointer>` to an ``i32`` value that resides in address space #5. | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ + +.. _t_vector: + +Vector Type +""""""""""" + +Overview: +********* + +A vector type is a simple derived type that represents a vector of +elements. Vector types are used when multiple primitive data are +operated in parallel using a single instruction (SIMD). A vector type +requires a size (number of elements) and an underlying primitive data +type. Vector types are considered :ref:`first class <t_firstclass>`. + +Syntax: +******* + +:: + + < <# elements> x <elementtype> > + +The number of elements is a constant integer value larger than 0; +elementtype may be any integer or floating point type, or a pointer to +these types. Vectors of size zero are not allowed. + +Examples: +********* + ++-------------------+--------------------------------------------------+ +| ``<4 x i32>`` | Vector of 4 32-bit integer values. | ++-------------------+--------------------------------------------------+ +| ``<8 x float>`` | Vector of 8 32-bit floating-point values. | ++-------------------+--------------------------------------------------+ +| ``<2 x i64>`` | Vector of 2 64-bit integer values. | ++-------------------+--------------------------------------------------+ +| ``<4 x i64*>`` | Vector of 4 pointers to 64-bit integer values. | ++-------------------+--------------------------------------------------+ .. _t_label: @@ -1672,18 +1745,6 @@ Syntax: metadata -.. _t_derived: - -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. Each of these types contain one or more element -types which may be a primitive type, or another derived type. For -example, it is possible to have a two dimensional array, using an array -as the element type of another array. - .. _t_aggregate: Aggregate Types @@ -1697,17 +1758,17 @@ aggregate types. .. _t_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: -""""""" +******* :: @@ -1717,7 +1778,7 @@ The number of elements is a constant integer value; ``elementtype`` may be any type with a size. Examples: -""""""""" +********* +------------------+--------------------------------------+ | ``[40 x i32]`` | Array of 40 32-bit integer values. | @@ -1745,53 +1806,13 @@ LLVM with a zero length array type. An implementation of 'pascal style arrays' in LLVM could use the type "``{ i32, [0 x float]}``", for example. -.. _t_function: - -Function Type -^^^^^^^^^^^^^ - -Overview: -""""""""" - -The function type can be thought of as a function signature. It consists of a -return type and a list of formal parameter types. The return type of a function -type is a void type or first class type --- except for :ref:`label <t_label>` -and :ref:`metadata <t_metadata>` types. - -Syntax: -""""""" - -:: - - <returntype> (<parameter list>) - -...where '``<parameter list>``' is a comma-separated list of type -specifiers. Optionally, the parameter list may include a type ``...``, which -indicates that the function takes a variable number of arguments. Variable -argument functions can access their arguments with the :ref:`variable argument -handling intrinsic <int_varargs>` functions. '``<returntype>``' is any type -except :ref:`label <t_label>` and :ref:`metadata <t_metadata>`. - -Examples: -""""""""" - -+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` | -+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. | -+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``i32 (i8*, ...)`` | A vararg function that takes at least one :ref:`pointer <t_pointer>` to ``i8`` (char in C), which returns an integer. This is the signature for ``printf`` in LLVM. | -+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``{i32, i32} (i32)`` | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values | -+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - .. _t_struct: Structure Type -^^^^^^^^^^^^^^ +"""""""""""""" Overview: -""""""""" +********* The structure type is used to represent a collection of data members together in memory. The elements of a structure may be any type that has @@ -1816,7 +1837,7 @@ or opaque since there is no way to write one. Identified types can be recursive, can be opaqued, and are never uniqued. Syntax: -""""""" +******* :: @@ -1824,7 +1845,7 @@ Syntax: %T2 = type <{ <type list> }> ; Identified packed struct type Examples: -""""""""" +********* +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``{ i32, i32, i32 }`` | A triple of three ``i32`` values | @@ -1837,17 +1858,17 @@ Examples: .. _t_opaque: Opaque Structure Types -^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""" Overview: -""""""""" +********* Opaque structure types are used to represent named structure types that do not have a body specified. This corresponds (for example) to the C notion of a forward declared structure. Syntax: -""""""" +******* :: @@ -1855,87 +1876,12 @@ Syntax: %52 = type opaque Examples: -""""""""" +********* +--------------+-------------------+ | ``opaque`` | An opaque type. | +--------------+-------------------+ -.. _t_pointer: - -Pointer Type -^^^^^^^^^^^^ - -Overview: -""""""""" - -The pointer type is used to specify memory locations. Pointers are -commonly used to reference objects in memory. - -Pointer types may have an optional address space attribute defining the -numbered address space where the pointed-to object resides. The default -address space is number zero. The semantics of non-zero address spaces -are target-specific. - -Note that LLVM does not permit pointers to void (``void*``) nor does it -permit pointers to labels (``label*``). Use ``i8*`` instead. - -Syntax: -""""""" - -:: - - <type> * - -Examples: -""""""""" - -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| ``[4 x i32]*`` | A :ref:`pointer <t_pointer>` to :ref:`array <t_array>` of four ``i32`` values. | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| ``i32 (i32*) *`` | A :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32*``, returning an ``i32``. | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| ``i32 addrspace(5)*`` | A :ref:`pointer <t_pointer>` to an ``i32`` value that resides in address space #5. | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ - -.. _t_vector: - -Vector Type -^^^^^^^^^^^ - -Overview: -""""""""" - -A vector type is a simple derived type that represents a vector of -elements. Vector types are used when multiple primitive data are -operated in parallel using a single instruction (SIMD). A vector type -requires a size (number of elements) and an underlying primitive data -type. Vector types are considered :ref:`first class <t_firstclass>`. - -Syntax: -""""""" - -:: - - < <# elements> x <elementtype> > - -The number of elements is a constant integer value larger than 0; -elementtype may be any integer or floating point type, or a pointer to -these types. Vectors of size zero are not allowed. - -Examples: -""""""""" - -+-------------------+--------------------------------------------------+ -| ``<4 x i32>`` | Vector of 4 32-bit integer values. | -+-------------------+--------------------------------------------------+ -| ``<8 x float>`` | Vector of 8 32-bit floating-point values. | -+-------------------+--------------------------------------------------+ -| ``<2 x i64>`` | Vector of 2 64-bit integer values. | -+-------------------+--------------------------------------------------+ -| ``<4 x i64*>`` | Vector of 4 pointers to 64-bit integer values. | -+-------------------+--------------------------------------------------+ - Constants ========= |