-
Notifications
You must be signed in to change notification settings - Fork 10.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Headers][X86] Add rounding and exception notes to conversions #83447
Conversation
Consistently describe rounding/truncating on convert intrinsics. Add notes where an out-of-range result can raise an exception.
FYI @cflores |
@llvm/pr-subscribers-backend-x86 @llvm/pr-subscribers-clang Author: Paul T Robinson (pogo59) ChangesConsistently 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:
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]
|
clang/lib/Headers/avxintrin.h
Outdated
/// 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we don't need to mention it. This is the default behavior if not mentioned otherwise.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Discussed this internally and agreed that it is not necessary.
clang/lib/Headers/avxintrin.h
Outdated
/// 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, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not only larger than, considering the negative number.
Rephrase the conversion note to apply to both positive and negative overflow.
clang/lib/Headers/emmintrin.h
Outdated
@@ -1405,11 +1413,12 @@ 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]. | |||
/// returned in the lower 64 bits of a 128-bit vector of [4 x i32], | |||
/// truncating inexact results. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The last sentence is not necessary and has ambiguity in truncating the fractional part or truncating higher bits to 32-bit.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Truncation is what distinguishes this from _mm_cvtpd_epi32
so I think it is necessary? That information used to be in the second paragraph, I shortened it and moved it up to the first paragraph, to make that difference more obvious.
Behavior on overflow was added to the second paragraph.
Do you have a different suggestion for how to organize this information?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, I took that simply as wrong infromation.
Do you have a different suggestion for how to organize this information?
Not ideal, something like
/// Converts the two double-precision floating-point elements of a
/// 128-bit vector of [2 x double] into two signed truncated
/// (rounded towards zero) 32-bit integer values,returned in the
/// most negative integer.
Test from "craig.flores@sony.com". |
Reworded the parts about truncating results. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks great, thanks!
…83447) Consistently describe rounding/truncating on convert intrinsics. Add notes where an out-of-range result can raise an exception.
Consistently describe rounding/truncating on convert intrinsics. Add notes where an out-of-range result can raise an exception.