diff options
Diffstat (limited to 'docs/LangRef.rst')
| -rw-r--r-- | docs/LangRef.rst | 202 |
1 files changed, 66 insertions, 136 deletions
diff --git a/docs/LangRef.rst b/docs/LangRef.rst index 2c55d333a6..935732a032 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -127,8 +127,7 @@ lexical features of LLVM: #. Comments are delimited with a '``;``' and go until the end of line. #. Unnamed temporaries are created when the result of a computation is not assigned to a named value. -#. Unnamed temporaries are numbered sequentially (using a per-function - incrementing counter, starting with 0). +#. Unnamed temporaries are numbered sequentially It also shows a convention that we follow in this document. When demonstrating instructions, we will follow an instruction with a comment @@ -387,8 +386,6 @@ More calling conventions can be added/defined on an as-needed basis, to support Pascal conventions or any other well-known target-independent convention. -.. _visibilitystyles: - Visibility Styles ----------------- @@ -414,8 +411,6 @@ styles: defining module will bind to the local symbol. That is, the symbol cannot be overridden by another module. -.. _namedtypes: - Named Types ----------- @@ -568,11 +563,7 @@ A function definition contains a list of basic blocks, forming the CFG start with a label (giving the basic block a symbol table entry), contains a list of instructions, and ends with a :ref:`terminator <terminators>` instruction (such as a branch or function -return). If explicit label is not provided, a block is assigned an -implicit numbered label, using a next value from the same counter as used -for unnamed temporaries (:ref:`see above<identifiers>`). For example, if a -function entry block does not have explicit label, it will be assigned -label "%0", then first unnamed temporary in that block will be "%1", etc. +return). The first basic block in a function is special in two ways: it is immediately executed on entrance to the function, and it is not allowed @@ -600,8 +591,6 @@ Syntax:: [fn Attrs] [section "name"] [align N] [gc] { ... } -.. _langref_aliases: - Aliases ------- @@ -703,7 +692,7 @@ Currently, only the following parameter attributes are defined: the first parameter. This is not a valid attribute for return values. ``noalias`` - This indicates that pointer values :ref:`based <pointeraliasing>` on + This indicates that pointer values `*based* <pointeraliasing>` on the argument or return value do not alias pointer values which are not *based* on it, ignoring certain "irrelevant" dependencies. For a call to the parent function, dependencies between memory references @@ -818,11 +807,6 @@ example: This attribute indicates that the inliner should attempt to inline this function into callers whenever possible, ignoring any active inlining size threshold for this caller. -``cold`` - This attribute indicates that this function is rarely called. When - computing edge weights, basic blocks post-dominated by a cold - function call are also considered to be cold; and, thus, given low - weight. ``nonlazybind`` This attribute suppresses lazy symbol binding for the function. This may make calls to the function faster, at the cost of extra program @@ -976,8 +960,6 @@ two digit hex code for the number. The inline asm code is simply printed to the machine code .s file when assembly code is generated. -.. _langref_datalayout: - Data Layout ----------- @@ -1367,8 +1349,6 @@ 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: - Type Classifications -------------------- @@ -1882,8 +1862,6 @@ followed by 4 hexadecimal digits. All hexadecimal formats are big-endian There are no constants of type x86mmx. -.. _complexconstants: - Complex Constants ----------------- @@ -2205,8 +2183,6 @@ instruction. Finally, some targets may provide defined semantics when using the value as the operand to an inline assembly, but that is target specific. -.. _constantexprs: - Constant Expressions -------------------- @@ -2311,8 +2287,6 @@ The following is the syntax for constant expressions: Other Values ============ -.. _inlineasmexprs: - Inline Assembler Expressions ---------------------------- @@ -2570,8 +2544,8 @@ Examples: It is sometimes useful to attach information to loop constructs. Currently, loop metadata is implemented as metadata attached to the branch instruction in the loop latch block. This type of metadata refer to a metadata node that is -guaranteed to be separate for each loop. The loop identifier metadata is -specified with the name ``llvm.loop``. +guaranteed to be separate for each loop. The loop-level metadata is prefixed +with ``llvm.loop``. The loop identifier metadata is implemented using a metadata that refers to itself to avoid merging it with any other identifier metadata, e.g., @@ -2585,17 +2559,32 @@ constructs: !0 = metadata !{ metadata !0 } !1 = metadata !{ metadata !1 } -The loop identifier metadata can be used to specify additional per-loop -metadata. Any operands after the first operand can be treated as user-defined -metadata. For example the ``llvm.vectorizer.unroll`` metadata is understood -by the loop vectorizer to indicate how many times to unroll the loop: -.. code-block:: llvm +'``llvm.loop.parallel``' Metadata +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0 - ... - !0 = metadata !{ metadata !0, metadata !1 } - !1 = metadata !{ metadata !"llvm.vectorizer.unroll", i32 2 } +This loop metadata can be used to communicate that a loop should be considered +a parallel loop. The semantics of parallel loops in this case is the one +with the strongest cross-iteration instruction ordering freedom: the +iterations in the loop can be considered completely independent of each +other (also known as embarrassingly parallel loops). + +This metadata can originate from a programming language with parallel loop +constructs. In such a case it is completely the programmer's responsibility +to ensure the instructions from the different iterations of the loop can be +executed in an arbitrary order, in parallel, or intertwined. No loop-carried +dependency checking at all must be expected from the compiler. + +In order to fulfill the LLVM requirement for metadata to be safely ignored, +it is important to ensure that a parallel loop is converted to +a sequential loop in case an optimization (agnostic of the parallel loop +semantics) converts the loop back to such. This happens when new memory +accesses that do not fulfill the requirement of free ordering across iterations +are added to the loop. Therefore, this metadata is required, but not +sufficient, to consider the loop at hand a parallel loop. For a loop +to be parallel, all its memory accessing instructions need to be +marked with the ``llvm.mem.parallel_loop_access`` metadata that refer +to the same loop identifier metadata that identify the loop at hand. '``llvm.mem``' ^^^^^^^^^^^^^^^ @@ -2607,28 +2596,29 @@ for optimizations are prefixed with ``llvm.mem``. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For a loop to be parallel, in addition to using -the ``llvm.loop`` metadata to mark the loop latch branch instruction, +the ``llvm.loop.parallel`` metadata to mark the loop latch branch instruction, also all of the memory accessing instructions in the loop body need to be marked with the ``llvm.mem.parallel_loop_access`` metadata. If there is at least one memory accessing instruction not marked with the metadata, -the loop must be considered a sequential loop. This causes parallel loops to be +the loop, despite it possibly using the ``llvm.loop.parallel`` metadata, +must be considered a sequential loop. This causes parallel loops to be converted to sequential loops due to optimization passes that are unaware of the parallel semantics and that insert new memory instructions to the loop body. Example of a loop that is considered parallel due to its correct use of -both ``llvm.loop`` and ``llvm.mem.parallel_loop_access`` +both ``llvm.loop.parallel`` and ``llvm.mem.parallel_loop_access`` metadata types that refer to the same loop identifier metadata. .. code-block:: llvm for.body: - ... - %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0 - ... - store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0 - ... - br i1 %exitcond, label %for.end, label %for.body, !llvm.loop !0 + ... + %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0 + ... + store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0 + ... + br i1 %exitcond, label %for.end, label %for.body, !llvm.loop.parallel !0 for.end: ... @@ -2644,75 +2634,27 @@ the loop identifier metadata node directly: ... inner.for.body: - ... - %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0 - ... - store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0 - ... - br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop !1 + ... + %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0 + ... + store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0 + ... + br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop.parallel !1 inner.for.end: - ... - %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0 - ... - store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0 - ... - br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2 + ... + %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0 + ... + store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0 + ... + br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop.parallel !2 outer.for.end: ; preds = %for.body ... - !0 = metadata !{ metadata !1, metadata !2 } ; a list of loop identifiers - !1 = metadata !{ metadata !1 } ; an identifier for the inner loop - !2 = metadata !{ metadata !2 } ; an identifier for the outer loop - -'``llvm.vectorizer``' -^^^^^^^^^^^^^^^^^^^^^ - -Metadata prefixed with ``llvm.vectorizer`` is used to control per-loop -vectorization parameters such as vectorization factor and unroll factor. + !0 = metadata !{ metadata !1, metadata !2 } ; a list of parallel loop identifiers + !1 = metadata !{ metadata !1 } ; an identifier for the inner parallel loop + !2 = metadata !{ metadata !2 } ; an identifier for the outer parallel loop -``llvm.vectorizer`` metadata should be used in conjunction with ``llvm.loop`` -loop identification metadata. - -'``llvm.vectorizer.unroll``' Metadata -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This metadata instructs the loop vectorizer to unroll the specified -loop exactly ``N`` times. - -The first operand is the string ``llvm.vectorizer.unroll`` and the second -operand is an integer specifying the unroll factor. For example: - -.. code-block:: llvm - - !0 = metadata !{ metadata !"llvm.vectorizer.unroll", i32 4 } - -Note that setting ``llvm.vectorizer.unroll`` to 1 disables unrolling of the -loop. - -If ``llvm.vectorizer.unroll`` is set to 0 then the amount of unrolling will be -determined automatically. - -'``llvm.vectorizer.width``' Metadata -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This metadata sets the target width of the vectorizer to ``N``. Without -this metadata, the vectorizer will choose a width automatically. -Regardless of this metadata, the vectorizer will only vectorize loops if -it believes it is valid to do so. - -The first operand is the string ``llvm.vectorizer.width`` and the second -operand is an integer specifying the width. For example: - -.. code-block:: llvm - - !0 = metadata !{ metadata !"llvm.vectorizer.width", i32 4 } - -Note that setting ``llvm.vectorizer.width`` to 1 disables vectorization of the -loop. - -If ``llvm.vectorizer.width`` is set to 0 then the width will be determined -automatically. Module Flags Metadata ===================== @@ -2914,8 +2856,6 @@ Each individual option is required to be either a valid option for the target's linker, or an option that is reserved by the target specific assembly writer or object file emitter. No other aspect of these options is defined by the IR. -.. _intrinsicglobalvariables: - Intrinsic Global Variables ========================== @@ -2925,15 +2865,13 @@ All globals of this sort should have a section specified as "``llvm.metadata``". This section and all globals that start with "``llvm.``" are reserved for use by LLVM. -.. _gv_llvmused: - The '``llvm.used``' Global Variable ----------------------------------- -The ``@llvm.used`` global is an array which has +The ``@llvm.used`` global is an array with i8\* element type which has :ref:`appending linkage <linkage_appending>`. This array contains a list of -pointers to named global variables, functions and aliases which may optionally -have a pointer cast formed of bitcast or getelementptr. For example, a legal +pointers to global variables and functions which may optionally have a +pointer cast formed of bitcast or getelementptr. For example, a legal use of it is: .. code-block:: llvm @@ -2946,20 +2884,18 @@ use of it is: i8* bitcast (i32* @Y to i8*) ], section "llvm.metadata" -If a symbol appears in the ``@llvm.used`` list, then the compiler, assembler, -and linker are required to treat the symbol as if there is a reference to the -symbol that it cannot see (which is why they have to be named). For example, if -a variable has internal linkage and no references other than that from the -``@llvm.used`` list, it cannot be deleted. This is commonly used to represent -references from inline asms and other things the compiler cannot "see", and -corresponds to "``attribute((used))``" in GNU C. +If a global variable appears in the ``@llvm.used`` list, then the +compiler, assembler, and linker are required to treat the symbol as if +there is a reference to the global that it cannot see. For example, if a +variable has internal linkage and no references other than that from the +``@llvm.used`` list, it cannot be deleted. This is commonly used to +represent references from inline asms and other things the compiler +cannot "see", and corresponds to "``attribute((used))``" in GNU C. On some targets, the code generator must emit a directive to the assembler or object file to prevent the assembler and linker from molesting the symbol. -.. _gv_llvmcompilerused: - The '``llvm.compiler.used``' Global Variable -------------------------------------------- @@ -2972,8 +2908,6 @@ by ``@llvm.used``. This is a rare construct that should only be used in rare circumstances, and should not be exposed to source languages. -.. _gv_llvmglobalctors: - The '``llvm.global_ctors``' Global Variable ------------------------------------------- @@ -2988,8 +2922,6 @@ array will be called in ascending order of priority (i.e. lowest first) when the module is loaded. The order of functions with the same priority is not defined. -.. _llvmglobaldtors: - The '``llvm.global_dtors``' Global Variable ------------------------------------------- @@ -4076,7 +4008,7 @@ Example: <result> = lshr i32 4, 1 ; yields {i32}:result = 2 <result> = lshr i32 4, 2 ; yields {i32}:result = 1 <result> = lshr i8 4, 3 ; yields {i8}:result = 0 - <result> = lshr i8 -2, 1 ; yields {i8}:result = 0x7F + <result> = lshr i8 -2, 1 ; yields {i8}:result = 0x7FFFFFFF <result> = lshr i32 1, 32 ; undefined <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1> @@ -6726,9 +6658,6 @@ memory. Implementations are allowed to either return a application specific value or a system wide value. On backends without support, this is lowered to a constant 0. -Note that runtime support may be conditional on the privilege-level code is -running at and the host platform. - Standard C Library Intrinsics ----------------------------- @@ -8685,3 +8614,4 @@ Semantics: This intrinsic does nothing, and it's removed by optimizers and ignored by codegen. +S
\ No newline at end of file |