# Changeset View

# Standalone View

# docs/LangRef.rst

- This file is larger than 256 KB, so syntax highlighting is disabled by default.

Show First 20 Lines • Show All 12018 Lines • ▼ Show 20 Line(s) | |||||

12019 | the pointer to the memory for which the ``invariant.group`` no longer holds. | 12019 | the pointer to the memory for which the ``invariant.group`` no longer holds. | ||

12020 | 12020 | | |||

12021 | Semantics: | 12021 | Semantics: | ||

12022 | """""""""" | 12022 | """""""""" | ||

12023 | 12023 | | |||

12024 | Returns another pointer that aliases its argument but which is considered different | 12024 | Returns another pointer that aliases its argument but which is considered different | ||

12025 | for the purposes of ``load``/``store`` ``invariant.group`` metadata. | 12025 | for the purposes of ``load``/``store`` ``invariant.group`` metadata. | ||

12026 | 12026 | | |||

12027 | Constrained Floating Point Intrinsics | ||||

12028 | ------------------------------------- | ||||

12029 | | ||||

12030 | These intrinsics are used to provide special handling of floating point | ||||

12031 | operations when specific rounding mode or floating point exception behavior is | ||||

12032 | required. By default, LLVM optimization passes assume that the rounding mode is | ||||

12033 | round-to-nearest and that floating point exceptions will not be monitored. | ||||

12034 | Constrained FP intrinsics are used to support non-default rounding modes and | ||||

12035 | accurately preserve exception behavior without compromising LLVM's ability to | ||||

12036 | optimize FP code when the default behavior is used. | ||||

12037 | | ||||

12038 | Each of these intrinsics corresponds to a normal floating point operation. The | ||||

12039 | first two arguments and the return value are the same as the corresponding FP | ||||

12040 | operation. | ||||

12041 | | ||||

12042 | The third argument is a metadata argument specifying the rounding mode to be | ||||

12043 | assumed. This argument must be one of the following strings: | ||||

12044 | | ||||

12045 | :: | ||||

12046 | "round.dynamic" | ||||

hfinkel: To engage in some bikeshedding, I really don't like this naming convention which reminds me of… | |||||

12047 | "round.tonearest" | ||||

12048 | "round.downward" | ||||

12049 | "round.upward" | ||||

12050 | "round.towardzero" | ||||

12051 | | ||||

12052 | If this argument is "round.dynamic" optimization passes must assume that the | ||||

12053 | rounding mode is unknown and may change at runtime. No transformations that | ||||

12054 | depend on rounding mode may be performed in this case. | ||||

12055 | | ||||

12056 | The other possible values for the rounding mode argument correspond to the | ||||

12057 | similarly named IEEE rounding modes. If the argument is any of these values | ||||

12058 | optimization passes may perform transformations as long as they are consistent | ||||

12059 | with the specified rounding mode. | ||||

12060 | | ||||

12061 | For example, 'x-0'->'x' is not a valid transformation if the rounding mode is | ||||

12062 | "round.downward" or "round.dynamic" because if the value of 'x' is +0 then | ||||

12063 | 'x-0' should evaluate to '-0' when rounding downward. However, this | ||||

12064 | transformation is legal for all other rounding modes. | ||||

12065 | | ||||

12066 | For values other than "round.dynamic" optimization passes may assume that the | ||||

12067 | actual runtime rounding mode (as defined in a target-specific manner) matches | ||||

12068 | the specified rounding mode, but this is not guaranteed. Using a specific | ||||

12069 | non-dynamic rounding mode which does not match the actual rounding mode at | ||||

12070 | runtime results in undefined behavior. | ||||

12071 | | ||||

12072 | The fourth argument to the constrained floating point intrinsics specifies the | ||||

12073 | required exception behavior. This argument must be one of the following | ||||

12074 | strings: | ||||

12075 | | ||||

12076 | :: | ||||

12077 | "fpexcept.ignore" | ||||

12078 | "fpexcept.maytrap" | ||||

12079 | "fpexcept.strict" | ||||

12080 | | ||||

12081 | If this argument is "fpexcept.ignore" optimization passes may assume that the | ||||

12082 | exception status flags will not be read and that floating point exceptions will | ||||

12083 | be masked. This allows transformations to be performed that may change the | ||||

Not Done Reply"not be unmasked" is a double negative. How about just saying will be masked? Or will not be enabled? hfinkel: "not be unmasked" is a double negative. How about just saying will be masked? Or will not be… | |||||

12084 | exception semantics of the original code. For example, FP operations may be | ||||

12085 | speculatively executed in this case whereas they must not be for either of the | ||||

12086 | other possible values of this argument. | ||||

12087 | | ||||

12088 | If the exception behavior argument is "fpexcept.maytrap" optimization passes | ||||

12089 | must avoid transformations that may raise exceptions that would not have been | ||||

12090 | raised by the original code (such as speculatively executing FP operations), but | ||||

12091 | passes are not required to preserve all exceptions that are implied by the | ||||

12092 | original code. For example, exceptions may be potentially hidden by constant | ||||

12093 | folding. | ||||

12094 | | ||||

12095 | If the exception behavior argument is "fpexcept.strict" all transformations must | ||||

12096 | strictly preserve the floating point exception semantics of the original code. | ||||

12097 | Any FP exception that would have been raised by the original code must be raised | ||||

12098 | by the transformed code, and the transformed code must not raise any FP | ||||

12099 | exceptions that would not have been raised by the original code. This is the | ||||

12100 | exception behavior argument that will be used if the code being compiled reads | ||||

12101 | the FP exception status flags, but this mode can also be used with code that | ||||

12102 | unmasks FP exceptions. | ||||

12103 | | ||||

12104 | The number and order of floating point exceptions is NOT guaranteed. For | ||||

12105 | example, a series of FP operations that each may raise exceptions may be | ||||

12106 | vectorized into a single instruction that raises each unique exception a single | ||||

12107 | time. | ||||

12108 | | ||||

12109 | | ||||

12110 | '``llvm.experimental.constrained.fadd``' Intrinsic | ||||

12111 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||||

12112 | | ||||

12113 | Syntax: | ||||

12114 | """"""" | ||||

12115 | | ||||

12116 | :: | ||||

12117 | | ||||

12118 | declare <type> | ||||

12119 | @llvm.experimental.constrained.fadd(<type> <op1>, <type> <op2>, | ||||

12120 | metadata <rounding mode>, | ||||

12121 | metadata <exception behavior>) | ||||

12122 | | ||||

12123 | Overview: | ||||

12124 | """"""""" | ||||

12125 | | ||||

12126 | The '``llvm.experimental.constrained.fadd``' intrinsic returns the sum of its | ||||

Not Done ReplyTypo: lllvm (seems repeated a number of times) arsenm: Typo: lllvm (seems repeated a number of times) | |||||

12127 | two operands. | ||||

12128 | | ||||

12129 | | ||||

12130 | Arguments: | ||||

12131 | """""""""" | ||||

12132 | | ||||

12133 | The first two arguments to the '``llvm.experimental.constrained.fadd``' | ||||

12134 | intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector <t_vector>` | ||||

12135 | of floating point values. Both arguments must have identical types. | ||||

12136 | | ||||

12137 | The third and fourth arguments specify the rounding mode and exception | ||||

12138 | behavior as described above. | ||||

12139 | | ||||

12140 | Semantics: | ||||

12141 | """""""""" | ||||

12142 | | ||||

12143 | The value produced is the floating point sum of the two value operands and has | ||||

12144 | the same type as the operands. | ||||

12145 | | ||||

12146 | | ||||

12147 | '``llvm.experimental.constrained.fsub``' Intrinsic | ||||

DavidKreitzerUnsubmitted Not Done ReplyThis question might be beyond the scope of this initial change set, but here goes. FP negation is currently handled using fsub -0, X. Is that sufficient in a constrained context? If we allow X to be a signaling NaN, -0-X should raise Invalid while -X should not, at least according to IEEE-754. DavidKreitzer: This question might be beyond the scope of this initial change set, but here goes.
FP negation… | |||||

scanonUnsubmitted Not Done ReplyProbably more importantly, -X has a defined signbit (the negation of whatever the signbit of X was), but -0-X does not [assuming the obvious binding of -X to the IEEE 754 negate operation and -0-X to the subtract operation]. scanon: Probably more importantly, -X has a defined signbit (the negation of whatever the signbit of X… | |||||

DavidKreitzerUnsubmitted Not Done ReplySteve, are you referring to the fact that the sign of -0-X is unspecified when X is NaN or something else? I am trying to understand the implications of your comment - whether they are specific to the new constrained FP intrinsics or whether something needs to be done for normal FP LLVM IR. Another problem worth mentioning with implementing -X as -0-X in a constrained context is that -0-X will produce -0 when X is -0 and the rounding mode is toward -inf. DavidKreitzer: Steve, are you referring to the fact that the sign of -0-X is unspecified when X is NaN or… | |||||

12148 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||||

12149 | | ||||

12150 | Syntax: | ||||

12151 | """"""" | ||||

12152 | | ||||

12153 | :: | ||||

12154 | | ||||

12155 | declare <type> | ||||

12156 | @llvm.experimental.constrained.fsub(<type> <op1>, <type> <op2>, | ||||

12157 | metadata <rounding mode>, | ||||

12158 | metadata <exception behavior>) | ||||

12159 | | ||||

12160 | Overview: | ||||

12161 | """"""""" | ||||

12162 | | ||||

12163 | The '``llvm.experimental.constrained.fsub``' intrinsic returns the difference | ||||

12164 | of its two operands. | ||||

12165 | | ||||

12166 | | ||||

12167 | Arguments: | ||||

12168 | """""""""" | ||||

12169 | | ||||

12170 | The first two arguments to the '``llvm.experimental.constrained.fsub``' | ||||

12171 | intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector <t_vector>` | ||||

12172 | of floating point values. Both arguments must have identical types. | ||||

12173 | | ||||

12174 | The third and fourth arguments specify the rounding mode and exception | ||||

12175 | behavior as described above. | ||||

12176 | | ||||

12177 | Semantics: | ||||

12178 | """""""""" | ||||

12179 | | ||||

12180 | The value produced is the floating point difference of the two value operands | ||||

12181 | and has the same type as the operands. | ||||

12182 | | ||||

12183 | | ||||

12184 | '``llvm.experimental.constrained.fmul``' Intrinsic | ||||

12185 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||||

12186 | | ||||

12187 | Syntax: | ||||

12188 | """"""" | ||||

12189 | | ||||

12190 | :: | ||||

12191 | | ||||

12192 | declare <type> | ||||

12193 | @llvm.experimental.constrained.fmul(<type> <op1>, <type> <op2>, | ||||

12194 | metadata <rounding mode>, | ||||

12195 | metadata <exception behavior>) | ||||

12196 | | ||||

12197 | Overview: | ||||

12198 | """"""""" | ||||

12199 | | ||||

12200 | The '``llvm.experimental.constrained.fmul``' intrinsic returns the product of | ||||

12201 | its two operands. | ||||

12202 | | ||||

12203 | | ||||

12204 | Arguments: | ||||

12205 | """""""""" | ||||

12206 | | ||||

12207 | The first two arguments to the '``llvm.experimental.constrained.fmul``' | ||||

12208 | intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector <t_vector>` | ||||

12209 | of floating point values. Both arguments must have identical types. | ||||

12210 | | ||||

12211 | The third and fourth arguments specify the rounding mode and exception | ||||

12212 | behavior as described above. | ||||

12213 | | ||||

12214 | Semantics: | ||||

12215 | """""""""" | ||||

12216 | | ||||

12217 | The value produced is the floating point product of the two value operands and | ||||

12218 | has the same type as the operands. | ||||

12219 | | ||||

12220 | | ||||

12221 | '``llvm.experimental.constrained.fdiv``' Intrinsic | ||||

12222 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||||

12223 | | ||||

12224 | Syntax: | ||||

12225 | """"""" | ||||

12226 | | ||||

12227 | :: | ||||

12228 | | ||||

12229 | declare <type> | ||||

12230 | @llvm.experimental.constrained.fdiv(<type> <op1>, <type> <op2>, | ||||

12231 | metadata <rounding mode>, | ||||

12232 | metadata <exception behavior>) | ||||

12233 | | ||||

12234 | Overview: | ||||

12235 | """"""""" | ||||

12236 | | ||||

12237 | The '``llvm.experimental.constrained.fdiv``' intrinsic returns the quotient of | ||||

12238 | its two operands. | ||||

12239 | | ||||

12240 | | ||||

12241 | Arguments: | ||||

12242 | """""""""" | ||||

12243 | | ||||

12244 | The first two arguments to the '``llvm.experimental.constrained.fdiv``' | ||||

12245 | intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector <t_vector>` | ||||

12246 | of floating point values. Both arguments must have identical types. | ||||

12247 | | ||||

12248 | The third and fourth arguments specify the rounding mode and exception | ||||

12249 | behavior as described above. | ||||

12250 | | ||||

12251 | Semantics: | ||||

12252 | """""""""" | ||||

12253 | | ||||

12254 | The value produced is the floating point quotient of the two value operands and | ||||

12255 | has the same type as the operands. | ||||

12256 | | ||||

12257 | | ||||

12258 | '``llvm.experimental.constrained.frem``' Intrinsic | ||||

12259 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||||

12260 | | ||||

12261 | Syntax: | ||||

12262 | """"""" | ||||

12263 | | ||||

12264 | :: | ||||

12265 | | ||||

12266 | declare <type> | ||||

12267 | @llvm.experimental.constrained.frem(<type> <op1>, <type> <op2>, | ||||

12268 | metadata <rounding mode>, | ||||

12269 | metadata <exception behavior>) | ||||

12270 | | ||||

12271 | Overview: | ||||

12272 | """"""""" | ||||

12273 | | ||||

12274 | The '``llvm.experimental.constrained.frem``' intrinsic returns the remainder | ||||

12275 | from the division of its two operands. | ||||

12276 | | ||||

12277 | | ||||

12278 | Arguments: | ||||

12279 | """""""""" | ||||

12280 | | ||||

12281 | The first two arguments to the '``llvm.experimental.constrained.frem``' | ||||

12282 | intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector <t_vector>` | ||||

12283 | of floating point values. Both arguments must have identical types. | ||||

12284 | | ||||

12285 | The third and fourth arguments specify the rounding mode and exception | ||||

12286 | behavior as described above. | ||||

12287 | | ||||

12288 | Semantics: | ||||

12289 | """""""""" | ||||

12290 | | ||||

12291 | The value produced is the floating point remainder from the division of the two | ||||

12292 | value operands and has the same type as the operands. The remainder has the | ||||

12293 | same sign as the dividend. | ||||

12294 | | ||||

12295 | | ||||

12027 | General Intrinsics | 12296 | General Intrinsics | ||

12028 | ------------------ | 12297 | ------------------ | ||

12029 | 12298 | | |||

12030 | This class of intrinsics is designed to be generic and has no specific | 12299 | This class of intrinsics is designed to be generic and has no specific | ||

12031 | purpose. | 12300 | purpose. | ||

12032 | 12301 | | |||

12033 | '``llvm.var.annotation``' Intrinsic | 12302 | '``llvm.var.annotation``' Intrinsic | ||

12034 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | 12303 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||

▲ Show 20 Lines • Show All 607 Lines • Show Last 20 Lines |

To engage in some bikeshedding, I really don't like this naming convention which reminds me of macro names. Not that we've been extremely consistent about the standardized metadata strings we already use, but this would be yet another choice; we should avoid that.

For controlling LLVM optimization passes, we use strings like this !"llvm.loop.vectorize.enable". We also use strings like !"function_entry_count" and !"branch_weights" for profiling info. We also have strings like !"ProfileFormat" and !"TotalCount" in other places. Of these choices, I prefer the one used by our basic profiling information (i.e. !"branch_weights"), and so I'd prefer these be named:

and similar for the fpexcept strings. We might also borrow the dot-based hierarchy scheme from our loop optimization metadata and use:

and similar for the fpexcept strings. I think that I like this slightly better than just using the underscore separators.

I specifically dislike having "llvm" in the name here, as it makes it seem as though the meaning of these things is somehow LLVM-specific. It is not (they come from IEEE if nothing else). Having "llvm" in the optimization metadata makes a bit more sense because those refer to specific LLVM optimization passes.