[clang] [Headers][X86] Add rounding and exception notes to conversions (PR #83447)
via cfe-commits
cfe-commits at lists.llvm.org
Thu Feb 29 09:03:15 PST 2024
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-clang
Author: Paul T Robinson (pogo59)
<details>
<summary>Changes</summary>
Consistently describe rounding/truncating on convert intrinsics. Add notes where an out-of-range result can raise an exception.
---
Patch is 23.00 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/83447.diff
3 Files Affected:
- (modified) clang/lib/Headers/avxintrin.h (+27-9)
- (modified) clang/lib/Headers/emmintrin.h (+66-25)
- (modified) clang/lib/Headers/xmmintrin.h (+89-36)
``````````diff
diff --git a/clang/lib/Headers/avxintrin.h b/clang/lib/Headers/avxintrin.h
index f116d8bc3a94c7..51c7d76e75ca1a 100644
--- a/clang/lib/Headers/avxintrin.h
+++ b/clang/lib/Headers/avxintrin.h
@@ -2180,7 +2180,8 @@ _mm256_cvtepi32_pd(__m128i __a)
return (__m256d)__builtin_convertvector((__v4si)__a, __v4df);
}
-/// Converts a vector of [8 x i32] into a vector of [8 x float].
+/// Converts a vector of [8 x i32] into a vector of [8 x float]. Rounds inexact
+/// results according to the rounding control bits in the MXCSR register.
///
/// \headerfile <x86intrin.h>
///
@@ -2196,7 +2197,8 @@ _mm256_cvtepi32_ps(__m256i __a)
}
/// Converts a 256-bit vector of [4 x double] into a 128-bit vector of
-/// [4 x float].
+/// [4 x float]. Rounds inexact results according to the rounding control
+/// bits in the MXCSR register.
///
/// \headerfile <x86intrin.h>
///
@@ -2211,7 +2213,12 @@ _mm256_cvtpd_ps(__m256d __a)
return (__m128)__builtin_ia32_cvtpd2ps256((__v4df) __a);
}
-/// Converts a vector of [8 x float] into a vector of [8 x i32].
+/// Converts a vector of [8 x float] into a vector of [8 x i32]. Rounds inexact
+/// results according to the rounding control bits in the MXCSR register.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -2243,8 +2250,11 @@ _mm256_cvtps_pd(__m128 __a)
}
/// Converts a 256-bit vector of [4 x double] into a 128-bit vector of [4
-/// x i32], truncating the result by rounding towards zero when it is
-/// inexact.
+/// x i32], truncating inexact results.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -2259,9 +2269,13 @@ _mm256_cvttpd_epi32(__m256d __a)
return (__m128i)__builtin_ia32_cvttpd2dq256((__v4df) __a);
}
-/// Converts a 256-bit vector of [4 x double] into a 128-bit vector of [4
-/// x i32]. When a conversion is inexact, the value returned is rounded
-/// according to the rounding control bits in the MXCSR register.
+/// Converts a 256-bit vector of [4 x double] into a 128-bit vector of
+/// [4 x i32]. Rounds inexact results according to the rounding control bits
+/// in the MXCSR register.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -2277,7 +2291,11 @@ _mm256_cvtpd_epi32(__m256d __a)
}
/// Converts a vector of [8 x float] into a vector of [8 x i32],
-/// truncating the result by rounding towards zero when it is inexact.
+/// truncating inexact results.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
diff --git a/clang/lib/Headers/emmintrin.h b/clang/lib/Headers/emmintrin.h
index 96e3ebdecbdf83..9ae7fe2c809ac6 100644
--- a/clang/lib/Headers/emmintrin.h
+++ b/clang/lib/Headers/emmintrin.h
@@ -1245,7 +1245,8 @@ static __inline__ int __DEFAULT_FN_ATTRS _mm_ucomineq_sd(__m128d __a,
/// Converts the two double-precision floating-point elements of a
/// 128-bit vector of [2 x double] into two single-precision floating-point
/// values, returned in the lower 64 bits of a 128-bit vector of [4 x float].
-/// The upper 64 bits of the result vector are set to zero.
+/// Rounds inexact results according to the rounding control bits in the
+/// MXCSR register. The upper 64 bits of the result vector are set to zero.
///
/// \headerfile <x86intrin.h>
///
@@ -1300,9 +1301,13 @@ static __inline__ __m128d __DEFAULT_FN_ATTRS _mm_cvtepi32_pd(__m128i __a) {
}
/// Converts the two double-precision floating-point elements of a
-/// 128-bit vector of [2 x double] into two signed 32-bit integer values,
-/// returned in the lower 64 bits of a 128-bit vector of [4 x i32]. The upper
-/// 64 bits of the result vector are set to zero.
+/// 128-bit vector of [2 x double] into two signed 32-bit integer values.
+/// Rounds inexact results according to the rounding control bits in the
+/// MXCSR register.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1317,7 +1322,12 @@ static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_cvtpd_epi32(__m128d __a) {
}
/// Converts the low-order element of a 128-bit vector of [2 x double]
-/// into a 32-bit signed integer value.
+/// into a 32-bit signed integer value. Rounds inexact results according to
+/// the rounding control bits in the MXCSR register.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1333,9 +1343,10 @@ static __inline__ int __DEFAULT_FN_ATTRS _mm_cvtsd_si32(__m128d __a) {
/// Converts the lower double-precision floating-point element of a
/// 128-bit vector of [2 x double], in the second parameter, into a
-/// single-precision floating-point value, returned in the lower 32 bits of a
-/// 128-bit vector of [4 x float]. The upper 96 bits of the result vector are
-/// copied from the upper 96 bits of the first parameter.
+/// single-precision floating-point value, returned in the lower 32 bits of
+/// a 128-bit vector of [4 x float]. Rounds inexact results according to the
+/// rounding control bits in the MXCSR register. The upper 96 bits of the
+/// result vector are copied from the upper 96 bits of the first parameter.
///
/// \headerfile <x86intrin.h>
///
@@ -1405,11 +1416,11 @@ static __inline__ __m128d __DEFAULT_FN_ATTRS _mm_cvtss_sd(__m128d __a,
/// Converts the two double-precision floating-point elements of a
/// 128-bit vector of [2 x double] into two signed 32-bit integer values,
-/// returned in the lower 64 bits of a 128-bit vector of [4 x i32].
+/// truncating inexact results.
///
-/// If the result of either conversion is inexact, the result is truncated
-/// (rounded towards zero) regardless of the current MXCSR setting. The upper
-/// 64 bits of the result vector are set to zero.
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1425,7 +1436,11 @@ static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_cvttpd_epi32(__m128d __a) {
}
/// Converts the low-order element of a [2 x double] vector into a 32-bit
-/// signed integer value, truncating the result when it is inexact.
+/// signed integer value, truncating inexact results.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1441,8 +1456,13 @@ static __inline__ int __DEFAULT_FN_ATTRS _mm_cvttsd_si32(__m128d __a) {
}
/// Converts the two double-precision floating-point elements of a
-/// 128-bit vector of [2 x double] into two signed 32-bit integer values,
-/// returned in a 64-bit vector of [2 x i32].
+/// 128-bit vector of [2 x double] into two signed 32-bit integer values.
+/// Rounds inexact results according to the rounding control bits in the
+/// MXCSR register.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1457,10 +1477,11 @@ static __inline__ __m64 __DEFAULT_FN_ATTRS_MMX _mm_cvtpd_pi32(__m128d __a) {
/// Converts the two double-precision floating-point elements of a
/// 128-bit vector of [2 x double] into two signed 32-bit integer values,
-/// returned in a 64-bit vector of [2 x i32].
+/// truncating inexact results.
///
-/// If the result of either conversion is inexact, the result is truncated
-/// (rounded towards zero) regardless of the current MXCSR setting.
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -3185,8 +3206,9 @@ static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_cmplt_epi32(__m128i __a,
#ifdef __x86_64__
/// Converts a 64-bit signed integer value from the second operand into a
/// double-precision value and returns it in the lower element of a [2 x
-/// double] vector; the upper element of the returned vector is copied from
-/// the upper element of the first operand.
+/// double] vector. Rounds inexact results according to the rounding control
+/// bits in the MXCSR register. The upper element of the returned vector is
+/// copied from the upper element of the first operand.
///
/// \headerfile <x86intrin.h>
///
@@ -3207,7 +3229,12 @@ static __inline__ __m128d __DEFAULT_FN_ATTRS _mm_cvtsi64_sd(__m128d __a,
}
/// Converts the first (lower) element of a vector of [2 x double] into a
-/// 64-bit signed integer value, according to the current rounding mode.
+/// 64-bit signed integer value. Rounds inexact results according to the
+/// rounding control bits in the MXCSR register.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -3222,7 +3249,11 @@ static __inline__ long long __DEFAULT_FN_ATTRS _mm_cvtsd_si64(__m128d __a) {
}
/// Converts the first (lower) element of a vector of [2 x double] into a
-/// 64-bit signed integer value, truncating the result when it is inexact.
+/// 64-bit signed integer value, truncating inexact results.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -3238,7 +3269,8 @@ static __inline__ long long __DEFAULT_FN_ATTRS _mm_cvttsd_si64(__m128d __a) {
}
#endif
-/// Converts a vector of [4 x i32] into a vector of [4 x float].
+/// Converts a vector of [4 x i32] into a vector of [4 x float]. Rounds inexact
+/// results according to the rounding control bits in the MXCSR register.
///
/// \headerfile <x86intrin.h>
///
@@ -3251,7 +3283,12 @@ static __inline__ __m128 __DEFAULT_FN_ATTRS _mm_cvtepi32_ps(__m128i __a) {
return (__m128) __builtin_convertvector((__v4si)__a, __v4sf);
}
-/// Converts a vector of [4 x float] into a vector of [4 x i32].
+/// Converts a vector of [4 x float] into a vector of [4 x i32]. Rounds inexact
+/// results according to the rounding control bits in the MXCSR register.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -3266,7 +3303,11 @@ static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_cvtps_epi32(__m128 __a) {
}
/// Converts a vector of [4 x float] into a vector of [4 x i32],
-/// truncating the result when it is inexact.
+/// truncating inexact results.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
diff --git a/clang/lib/Headers/xmmintrin.h b/clang/lib/Headers/xmmintrin.h
index 47368f3c23d2d6..0feee669e1e818 100644
--- a/clang/lib/Headers/xmmintrin.h
+++ b/clang/lib/Headers/xmmintrin.h
@@ -1295,7 +1295,12 @@ _mm_ucomineq_ss(__m128 __a, __m128 __b)
}
/// Converts a float value contained in the lower 32 bits of a vector of
-/// [4 x float] into a 32-bit integer.
+/// [4 x float] into a 32-bit integer. Rounds an inexact result according to
+/// the rounding control bits in the MXCSR register.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1313,7 +1318,12 @@ _mm_cvtss_si32(__m128 __a)
}
/// Converts a float value contained in the lower 32 bits of a vector of
-/// [4 x float] into a 32-bit integer.
+/// [4 x float] into a 32-bit integer. Rounds an inexact result according to
+/// the rounding control bits in the MXCSR register.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1333,7 +1343,12 @@ _mm_cvt_ss2si(__m128 __a)
#ifdef __x86_64__
/// Converts a float value contained in the lower 32 bits of a vector of
-/// [4 x float] into a 64-bit integer.
+/// [4 x float] into a 64-bit integer. Rounds an inexact result according to
+/// the rounding control bits in the MXCSR register.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1352,8 +1367,13 @@ _mm_cvtss_si64(__m128 __a)
#endif
-/// Converts two low-order float values in a 128-bit vector of
-/// [4 x float] into a 64-bit vector of [2 x i32].
+/// Converts two low-order float values in a 128-bit vector of [4 x float] into
+/// a 64-bit vector of [2 x i32]. Rounds inexact results according to the
+/// rounding control bits in the MXCSR register.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1368,8 +1388,13 @@ _mm_cvtps_pi32(__m128 __a)
return (__m64)__builtin_ia32_cvtps2pi((__v4sf)__a);
}
-/// Converts two low-order float values in a 128-bit vector of
-/// [4 x float] into a 64-bit vector of [2 x i32].
+/// Converts two low-order float values in a 128-bit vector of [4 x float] into
+/// a 64-bit vector of [2 x i32]. Rounds inexact results according to the
+/// rounding control bits in the MXCSR register.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1385,8 +1410,11 @@ _mm_cvt_ps2pi(__m128 __a)
}
/// Converts a float value contained in the lower 32 bits of a vector of
-/// [4 x float] into a 32-bit integer, truncating the result when it is
-/// inexact.
+/// [4 x float] into a 32-bit integer, truncating an inexact result.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1404,8 +1432,11 @@ _mm_cvttss_si32(__m128 __a)
}
/// Converts a float value contained in the lower 32 bits of a vector of
-/// [4 x float] into a 32-bit integer, truncating the result when it is
-/// inexact.
+/// [4 x float] into a 32-bit integer, truncating an inexact result.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1424,8 +1455,11 @@ _mm_cvtt_ss2si(__m128 __a)
#ifdef __x86_64__
/// Converts a float value contained in the lower 32 bits of a vector of
-/// [4 x float] into a 64-bit integer, truncating the result when it is
-/// inexact.
+/// [4 x float] into a 64-bit integer, truncating an inexact result.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1444,8 +1478,12 @@ _mm_cvttss_si64(__m128 __a)
#endif
/// Converts two low-order float values in a 128-bit vector of
-/// [4 x float] into a 64-bit vector of [2 x i32], truncating the result
-/// when it is inexact.
+/// [4 x float] into a 64-bit vector of [2 x i32], truncating inexact
+/// results.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1462,8 +1500,11 @@ _mm_cvttps_pi32(__m128 __a)
}
/// Converts two low-order float values in a 128-bit vector of [4 x
-/// float] into a 64-bit vector of [2 x i32], truncating the result when it
-/// is inexact.
+/// float] into a 64-bit vector of [2 x i32], truncating inexact results.
+///
+/// If a converted value is larger than the maximum possible result,
+/// raises a floating-point invalid exception. If the exception is
+/// masked, returns the most negative integer.
///
/// \headerfile <x86intrin.h>
///
@@ -1478,10 +1519,11 @@ _mm_cvtt_ps2pi(__m128 __a)
return _mm_cvttps_pi32(__a);
}
-/// Converts a 32-bit signed integer value into a floating point value
-/// and writes it to the lower 32 bits of the destination. The remaining
-/// higher order elements of the destination vector are copied from the
-/// corresponding elements in the first operand.
+/// Converts a 32-bit signed integer value into a floating point value and
+/// writes it to the lower 32 bits of the destination. Rounds an inexact
+/// result according to the rounding control bits in the MXCSR register.
+/// The remaining higher order elements of the destination vector are copied
+/// from the corresponding elements in the first operand.
///
/// \headerfile <x86intrin.h>
///
@@ -1501,10 +1543,11 @@ _mm_cvtsi32_ss(__m128 __a, int __b)
return __a;
}
-/// Converts a 32-bit signed integer value into a floating point value
-/// and writes it to the lower 32 bits of the destination. The remaining
-/// higher order elements of the destination are copied from the
-/// corresponding elements in the first operand.
+/// Converts a 32-bit signed integer value into a floating point value and
+/// writes it to the lower 32 bits of the destination. Rounds an inexact
+/// result according to the rounding control bits in the MXCSR register.
+/// The remaining higher order elements of the destination are copied from
+/// the corresponding elements in the first operand.
///
/// \headerfile <x86intrin.h>
///
@@ -1525,10 +1568,11 @@ _mm_cvt_si2ss(__m128 __a, int __b)
#ifdef __x86_64__
-/// Converts a 64-bit signed integer value into a floating point value
-/// and writes it to the lower 32 bits of the destination. The remaining
-/// higher order elements of the destination are copied from the
-/// corresponding elements in the first operand.
+/// Converts a 64-bit signed integer value into a floating point value and
+/// writes it to the lower 32 bits of the destination. Rounds an inexact
+/// result according to the rounding control bits in the MXCSR register.
+/// The remaining higher order elements of the destina...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/83447
More information about the cfe-commits
mailing list