Differential D27028 Diff 80354 docs/LangRef.rst

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"
			hfinkelUnsubmitted Not Done Reply 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: "round_dynamic" "round_downward" ... and similar for the fpexcept strings. We might also borrow the dot-based hierarchy scheme from our loop optimization metadata and use: "round.dynamic" "round.downward" ... 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. 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
			hfinkelUnsubmitted 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
			arsenmUnsubmitted Not Done Reply Typo: 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 Reply This 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 Reply Probably 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 Reply Steve, 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