diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Benchmarking.rst | 87 | ||||
| -rw-r--r-- | docs/GettingStartedVS.rst | 4 | ||||
| -rw-r--r-- | docs/LangRef.rst | 471 | ||||
| -rw-r--r-- | docs/Vectorizers.rst | 4 | ||||
| -rw-r--r-- | docs/index.rst | 1 |
5 files changed, 555 insertions, 12 deletions
diff --git a/docs/Benchmarking.rst b/docs/Benchmarking.rst new file mode 100644 index 000000000000..0f88db745a68 --- /dev/null +++ b/docs/Benchmarking.rst @@ -0,0 +1,87 @@ +================================== +Benchmarking tips +================================== + + +Introduction +============ + +For benchmarking a patch we want to reduce all possible sources of +noise as much as possible. How to do that is very OS dependent. + +Note that low noise is required, but not sufficient. It does not +exclude measurement bias. See +https://www.cis.upenn.edu/~cis501/papers/producing-wrong-data.pdf for +example. + +General +================================ + +* Use a high resolution timer, e.g. perf under linux. + +* Run the benchmark multiple times to be able to recognize noise. + +* Disable as many processes or services as possible on the target system. + +* Disable frequency scaling, turbo boost and address space + randomization (see OS specific section). + +* Static link if the OS supports it. That avoids any variation that + might be introduced by loading dynamic libraries. This can be done + by passing ``-DLLVM_BUILD_STATIC=ON`` to cmake. + +* Try to avoid storage. On some systems you can use tmpfs. Putting the + program, inputs and outputs on tmpfs avoids touching a real storage + system, which can have a pretty big variability. + + To mount it (on linux and freebsd at least):: + + mount -t tmpfs -o size=<XX>g none dir_to_mount + +Linux +===== + +* Disable address space randomization:: + + echo 0 > /proc/sys/kernel/randomize_va_space + +* Set scaling_governor to performance:: + + for i in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor + do + echo performance > /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor + done + +* Use https://github.com/lpechacek/cpuset to reserve cpus for just the + program you are benchmarking. If using perf, leave at least 2 cores + so that perf runs in one and your program in another:: + + cset shield -c N1,N2 -k on + + This will move all threads out of N1 and N2. The ``-k on`` means + that even kernel threads are moved out. + +* Disable the SMT pair of the cpus you will use for the benchmark. The + pair of cpu N can be found in + ``/sys/devices/system/cpu/cpuN/topology/thread_siblings_list`` and + disabled with:: + + echo 0 > /sys/devices/system/cpu/cpuX/online + + +* Run the program with:: + + cset shield --exec -- perf stat -r 10 <cmd> + + This will run the command after ``--`` in the isolated cpus. The + particular perf command runs the ``<cmd>`` 10 times and reports + statistics. + +With these in place you can expect perf variations of less than 0.1%. + +Linux Intel +----------- + +* Disable turbo mode:: + + echo 1 > /sys/devices/system/cpu/intel_pstate/no_turbo diff --git a/docs/GettingStartedVS.rst b/docs/GettingStartedVS.rst index 1e4676767939..50f7aa123c55 100644 --- a/docs/GettingStartedVS.rst +++ b/docs/GettingStartedVS.rst @@ -100,6 +100,10 @@ Here's the short story for getting up and running quickly with LLVM: * CMake generates project files for all build types. To select a specific build type, use the Configuration manager from the VS IDE or the ``/property:Configuration`` command line option when using MSBuild. + * By default, the Visual Studio project files generated by CMake use the + 32-bit toolset. If you are developing on a 64-bit version of Windows and + want to use the 64-bit toolset, pass the ``-Thost=x64`` flag when + generating the Visual Studio solution. This requires CMake 3.8.0 or later. 6. Start Visual Studio diff --git a/docs/LangRef.rst b/docs/LangRef.rst index b205cae9b118..2e339183ef11 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -4415,12 +4415,6 @@ The current supported vocabulary is limited: address space identifier. - ``DW_OP_stack_value`` marks a constant value. -DIExpression nodes that contain a ``DW_OP_stack_value`` operator are standalone -location descriptions that describe constant values. This form is used to -describe global constants that have been optimized away. All other expressions -are modifiers to another location: A debug intrinsic ties a location and a -DIExpression together. - DWARF specifies three kinds of simple location descriptions: Register, memory, and implicit location descriptions. Register and memory location descriptions describe the *location* of a source variable (in the sense that a debugger might @@ -12722,7 +12716,7 @@ Syntax: declare <type> @llvm.experimental.constrained.fadd(<type> <op1>, <type> <op2>, metadata <rounding mode>, - metadata <exception behavior>) + metadata <exception behavior>) Overview: """"""""" @@ -12759,7 +12753,7 @@ Syntax: declare <type> @llvm.experimental.constrained.fsub(<type> <op1>, <type> <op2>, metadata <rounding mode>, - metadata <exception behavior>) + metadata <exception behavior>) Overview: """"""""" @@ -12796,7 +12790,7 @@ Syntax: declare <type> @llvm.experimental.constrained.fmul(<type> <op1>, <type> <op2>, metadata <rounding mode>, - metadata <exception behavior>) + metadata <exception behavior>) Overview: """"""""" @@ -12833,7 +12827,7 @@ Syntax: declare <type> @llvm.experimental.constrained.fdiv(<type> <op1>, <type> <op2>, metadata <rounding mode>, - metadata <exception behavior>) + metadata <exception behavior>) Overview: """"""""" @@ -12870,7 +12864,7 @@ Syntax: declare <type> @llvm.experimental.constrained.frem(<type> <op1>, <type> <op2>, metadata <rounding mode>, - metadata <exception behavior>) + metadata <exception behavior>) Overview: """"""""" @@ -12899,6 +12893,461 @@ value operands and has the same type as the operands. The remainder has the same sign as the dividend. +Constrained libm-equivalent Intrinsics +-------------------------------------- + +In addition to the basic floating point operations for which constrained +intrinsics are described above, there are constrained versions of various +operations which provide equivalent behavior to a corresponding libm function. +These intrinsics allow the precise behavior of these operations with respect to +rounding mode and exception behavior to be controlled. + +As with the basic constrained floating point intrinsics, the rounding mode +and exception behavior arguments only control the behavior of the optimizer. +They do not change the runtime floating point environment. + + +'``llvm.experimental.constrained.sqrt``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.sqrt(<type> <op1>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.sqrt``' intrinsic returns the square root +of the specified value, returning the same value as the libm '``sqrt``' +functions would, but without setting ``errno``. + +Arguments: +"""""""""" + +The first argument and the return type are floating point numbers of the same +type. + +The second and third arguments specify the rounding mode and exception +behavior as described above. + +Semantics: +"""""""""" + +This function returns the nonnegative square root of the specified value. +If the value is less than negative zero, a floating point exception occurs +and the the return value is architecture specific. + + +'``llvm.experimental.constrained.pow``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.pow(<type> <op1>, <type> <op2>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.pow``' intrinsic returns the first operand +raised to the (positive or negative) power specified by the second operand. + +Arguments: +"""""""""" + +The first two arguments and the return value are floating point numbers of the +same type. The second argument specifies the power to which the first argument +should be raised. + +The third and fourth arguments specify the rounding mode and exception +behavior as described above. + +Semantics: +"""""""""" + +This function returns the first value raised to the second power, +returning the same values as the libm ``pow`` functions would, and +handles error conditions in the same way. + + +'``llvm.experimental.constrained.powi``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.powi(<type> <op1>, i32 <op2>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.powi``' intrinsic returns the first operand +raised to the (positive or negative) power specified by the second operand. The +order of evaluation of multiplications is not defined. When a vector of floating +point type is used, the second argument remains a scalar integer value. + + +Arguments: +"""""""""" + +The first argument and the return value are floating point numbers of the same +type. The second argument is a 32-bit signed integer specifying the power to +which the first argument should be raised. + +The third and fourth arguments specify the rounding mode and exception +behavior as described above. + +Semantics: +"""""""""" + +This function returns the first value raised to the second power with an +unspecified sequence of rounding operations. + + +'``llvm.experimental.constrained.sin``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.sin(<type> <op1>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.sin``' intrinsic returns the sine of the +first operand. + +Arguments: +"""""""""" + +The first argument and the return type are floating point numbers of the same +type. + +The second and third arguments specify the rounding mode and exception +behavior as described above. + +Semantics: +"""""""""" + +This function returns the sine of the specified operand, returning the +same values as the libm ``sin`` functions would, and handles error +conditions in the same way. + + +'``llvm.experimental.constrained.cos``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.cos(<type> <op1>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.cos``' intrinsic returns the cosine of the +first operand. + +Arguments: +"""""""""" + +The first argument and the return type are floating point numbers of the same +type. + +The second and third arguments specify the rounding mode and exception +behavior as described above. + +Semantics: +"""""""""" + +This function returns the cosine of the specified operand, returning the +same values as the libm ``cos`` functions would, and handles error +conditions in the same way. + + +'``llvm.experimental.constrained.exp``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.exp(<type> <op1>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.exp``' intrinsic computes the base-e +exponential of the specified value. + +Arguments: +"""""""""" + +The first argument and the return value are floating point numbers of the same +type. + +The second and third arguments specify the rounding mode and exception +behavior as described above. + +Semantics: +"""""""""" + +This function returns the same values as the libm ``exp`` functions +would, and handles error conditions in the same way. + + +'``llvm.experimental.constrained.exp2``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.exp2(<type> <op1>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.exp2``' intrinsic computes the base-2 +exponential of the specified value. + + +Arguments: +"""""""""" + +The first argument and the return value are floating point numbers of the same +type. + +The second and third arguments specify the rounding mode and exception +behavior as described above. + +Semantics: +"""""""""" + +This function returns the same values as the libm ``exp2`` functions +would, and handles error conditions in the same way. + + +'``llvm.experimental.constrained.log``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.log(<type> <op1>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.log``' intrinsic computes the base-e +logarithm of the specified value. + +Arguments: +"""""""""" + +The first argument and the return value are floating point numbers of the same +type. + +The second and third arguments specify the rounding mode and exception +behavior as described above. + + +Semantics: +"""""""""" + +This function returns the same values as the libm ``log`` functions +would, and handles error conditions in the same way. + + +'``llvm.experimental.constrained.log10``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.log10(<type> <op1>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.log10``' intrinsic computes the base-10 +logarithm of the specified value. + +Arguments: +"""""""""" + +The first argument and the return value are floating point numbers of the same +type. + +The second and third arguments specify the rounding mode and exception +behavior as described above. + +Semantics: +"""""""""" + +This function returns the same values as the libm ``log10`` functions +would, and handles error conditions in the same way. + + +'``llvm.experimental.constrained.log2``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.log2(<type> <op1>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.log2``' intrinsic computes the base-2 +logarithm of the specified value. + +Arguments: +"""""""""" + +The first argument and the return value are floating point numbers of the same +type. + +The second and third arguments specify the rounding mode and exception +behavior as described above. + +Semantics: +"""""""""" + +This function returns the same values as the libm ``log2`` functions +would, and handles error conditions in the same way. + + +'``llvm.experimental.constrained.rint``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.rint(<type> <op1>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.rint``' intrinsic returns the first +operand rounded to the nearest integer. It may raise an inexact floating point +exception if the operand is not an integer. + +Arguments: +"""""""""" + +The first argument and the return value are floating point numbers of the same +type. + +The second and third arguments specify the rounding mode and exception +behavior as described above. + +Semantics: +"""""""""" + +This function returns the same values as the libm ``rint`` functions +would, and handles error conditions in the same way. The rounding mode is +described, not determined, by the rounding mode argument. The actual rounding +mode is determined by the runtime floating point environment. The rounding +mode argument is only intended as information to the compiler. + + +'``llvm.experimental.constrained.nearbyint``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.nearbyint(<type> <op1>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.nearbyint``' intrinsic returns the first +operand rounded to the nearest integer. It will not raise an inexact floating +point exception if the operand is not an integer. + + +Arguments: +"""""""""" + +The first argument and the return value are floating point numbers of the same +type. + +The second and third arguments specify the rounding mode and exception +behavior as described above. + +Semantics: +"""""""""" + +This function returns the same values as the libm ``nearbyint`` functions +would, and handles error conditions in the same way. The rounding mode is +described, not determined, by the rounding mode argument. The actual rounding +mode is determined by the runtime floating point environment. The rounding +mode argument is only intended as information to the compiler. + + General Intrinsics ------------------ diff --git a/docs/Vectorizers.rst b/docs/Vectorizers.rst index 65c19aa2bc0c..a909d458c317 100644 --- a/docs/Vectorizers.rst +++ b/docs/Vectorizers.rst @@ -99,7 +99,9 @@ Optimization remarks are enabled using: indicates if vectorization was specified. ``-Rpass-analysis=loop-vectorize`` identifies the statements that caused -vectorization to fail. +vectorization to fail. If in addition ``-fsave-optimization-record`` is +provided, multiple causes of vectorization failure may be listed (this behavior +might change in the future). Consider the following loop: diff --git a/docs/index.rst b/docs/index.rst index fe47eb1bcb7f..becbe48e7ec7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -90,6 +90,7 @@ representation. CodeOfConduct CompileCudaWithLLVM ReportingGuide + Benchmarking :doc:`GettingStarted` Discusses how to get up and running quickly with the LLVM infrastructure. |