Document rounding for llvm.lround and llvm.lrint

[kpn]

Summary

The handling of rounding is not fully documented for the llvm.lround and llvm.lrint family of intrinsics.

This documentation was requested during the reviews of D64746.

[efriedma]

These intrinsics don't raise exceptions, semantically; they're readnone.

[kpn]

Drop the verbiage about exceptions. Update ticket description and title.

[craig.topper]

llvm/docs/LangRef.rst

12706–12711

Doesn't lrint use the current rounding mode?

[efriedma]

llvm/docs/LangRef.rst

12706–12711

Sort of? I mean, in this context, we assume the "current rounding mode" is round-to-nearest-even.

Probably worth clarifying what we mean by "nearest" here.

[kpn]

llvm/docs/LangRef.rst

12706–12711

We specify how rounding is done very rarely, and when we do we usually say "nearest integer" without mentioning the rounding mode.

Do we want to change all references to "nearest integer" to state that the current rounding mode is used? Do we want a mention somewhere else to cover all uses?

[efriedma]

llvm/docs/LangRef.rst

12706–12711

We only use "nearest integer" in connection to rint/round/etc. In that context, it's not obvious to a casual reader what this means in the context of IEEE arithmetic.

In other contexts, floating-point arithmetic uses the default floating-point rounding mode; this is stated explicitly at http://llvm.org/docs/LangRef.html#floating-point-environment .

[kpn]

llvm/docs/LangRef.rst

12706–12711

Looking more closely, the *lrint parts of this patch are just grammar changes. I could commit those tomorrow and this patch would be just *lround. The *lround part of the patch is explicit in stating the rounding. Does that seem reasonable?

[efriedma]

llvm/docs/LangRef.rst

12706–12711

Fine. In that case, LGTM

llvm/docs/LangRef.rst

::
       declare i64 @llvm.lround.i64.f64(double %Val)
       declare i64 @llvm.lround.i64.f80(float %Val)
       declare i64 @llvm.lround.i64.f128(double %Val)
       declare i64 @llvm.lround.i64.ppcf128(double %Val)
 
 Overview:
 """""""""
 
-The '``llvm.lround.*``' intrinsics returns the operand rounded to the
-nearest integer.
+The '``llvm.lround.*``' intrinsics return the operand rounded to the nearest
+integer with ties away from zero. It will raise an inexact floating-point
+exception if the operand is not an integer. An invalid exception is raised
+if the result is too large to fit into a supported integer type, and in
+this case the result is undefined.
+
 
 Arguments:
 """"""""""
 
-The argument is a floating-point number and return is an integer type.
+The argument is a floating-point number and the return value is an integer
+type.
 
 Semantics:
 """"""""""
 
 This function returns the same values as the libm ``lround``
 functions would, but without setting errno.
 
 '``llvm.llround.*``' Intrinsic
::
       declare i64 @llvm.lround.i64.f64(double %Val)
       declare i64 @llvm.lround.i64.f80(float %Val)
       declare i64 @llvm.lround.i64.f128(double %Val)
       declare i64 @llvm.lround.i64.ppcf128(double %Val)
 
 Overview:
 """""""""
 
-The '``llvm.llround.*``' intrinsics returns the operand rounded to the
-nearest integer.
+The '``llvm.llround.*``' intrinsics return the operand rounded to the nearest
+integer with ties away from zero. It will raise an inexact floating-point
+exception if the operand is not an integer. An invalid exception is raised
+if the result is too large to fit into a supported integer type, and in
+this case the result is undefined.
 
 Arguments:
 """"""""""
 
-The argument is a floating-point number and return is an integer type.
+The argument is a floating-point number and the return value is an integer
+type.
 
 Semantics:
 """"""""""
 
 This function returns the same values as the libm ``llround``
 functions would, but without setting errno.
 
 '``llvm.lrint.*``' Intrinsic
::
       declare i64 @llvm.lrint.i64.f64(double %Val)
       declare i64 @llvm.lrint.i64.f80(float %Val)
       declare i64 @llvm.lrint.i64.f128(double %Val)
       declare i64 @llvm.lrint.i64.ppcf128(double %Val)
 
 Overview:
 """""""""
 
-The '``llvm.lrint.*``' intrinsics returns the operand rounded to the
-nearest integer.
+The '``llvm.lrint.*``' intrinsics return the operand rounded to the nearest
+integer. An inexact floating-point exception will be raised if the operand
+is not an integer. An invalid exception is raised if the result is too
+large to fit into a supported integer type, and in this case the result
+is undefined.
+
 
 Arguments:
 """"""""""
 
-The argument is a floating-point number and return is an integer type.
+The argument is a floating-point number and the return value is an integer
+type.
 
 Semantics:
 """"""""""
 
 This function returns the same values as the libm ``lrint``
 functions would, but without setting errno.
 
 '``llvm.llrint.*``' Intrinsic
::
       declare i64 @llvm.llrint.i64.f64(double %Val)
       declare i64 @llvm.llrint.i64.f80(float %Val)
       declare i64 @llvm.llrint.i64.f128(double %Val)
       declare i64 @llvm.llrint.i64.ppcf128(double %Val)
 
 Overview:
 """""""""
 
-The '``llvm.llrint.*``' intrinsics returns the operand rounded to the
-nearest integer.
+The '``llvm.llrint.*``' intrinsics return the operand rounded to the nearest
+integer. An inexact floating-point exception will be raised if the operand
+is not an integer. An invalid exception is raised if the result is too
+large to fit into a supported integer type, and in this case the result
+is undefined.
 
 Arguments:
 """"""""""
 
-The argument is a floating-point number and return is an integer type.
+The argument is a floating-point number and the return value is an integer
+type.
 
 Semantics:
 """"""""""
 
 This function returns the same values as the libm ``llrint``
 functions would, but without setting errno.
 
 Bit Manipulation Intrinsics