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

12788

Doesn't lrint use the current rounding mode?

[efriedma]

llvm/docs/LangRef.rst

12788

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

12788

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

12788

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

12788

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

12788

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.
+
 
 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.
 
 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.
+
 
 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.
 
 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