From 10147bdba7a5646e9706f37aa133b7a3291fb50e Mon Sep 17 00:00:00 2001 From: Douglas Yung Date: Tue, 2 Jan 2018 20:39:29 +0000 Subject: [PATCH] [DOXYGEN] Fix doxygen and content issues in emmintrin.h - Fixed innaccurate instruction mappings for various intrinsics. - Fixed description of NaN handling in comparison intrinsics. - Unify description of _mm_store_pd1 to match _mm_store1_pd. - Fix incorrect wording in various intrinsic descriptions. Previously the descriptions used "low-order" and "high-order" when the intended meaning was "even-indexed" and "odd-indexed". - Fix typos. - Add missing italics command (\a) for params and fixed some parameter spellings. This patch was made by Craig Flores Differential Revision: https://reviews.llvm.org/D41516 git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@321669 91177308-0d34-0410-b5e6-96231b3b80d8 --- lib/Headers/emmintrin.h | 111 +++++++++++++++++++++++----------------- 1 file changed, 63 insertions(+), 48 deletions(-) diff --git a/lib/Headers/emmintrin.h b/lib/Headers/emmintrin.h index 3372508a7f..b332eeec20 100644 --- a/lib/Headers/emmintrin.h +++ b/lib/Headers/emmintrin.h @@ -217,8 +217,8 @@ _mm_div_pd(__m128d __a, __m128d __b) /// \brief Calculates the square root of the lower double-precision value of /// the second operand and returns it in the lower 64 bits of the result. -/// The upper 64 bits of the result are copied from the upper double- -/// precision value of the first operand. +/// The upper 64 bits of the result are copied from the upper +/// double-precision value of the first operand. /// /// \headerfile /// @@ -260,8 +260,8 @@ _mm_sqrt_pd(__m128d __a) /// \brief Compares lower 64-bit double-precision values of both operands, and /// returns the lesser of the pair of values in the lower 64-bits of the -/// result. The upper 64 bits of the result are copied from the upper double- -/// precision value of the first operand. +/// result. The upper 64 bits of the result are copied from the upper +/// double-precision value of the first operand. /// /// \headerfile /// @@ -304,8 +304,8 @@ _mm_min_pd(__m128d __a, __m128d __b) /// \brief Compares lower 64-bit double-precision values of both operands, and /// returns the greater of the pair of values in the lower 64-bits of the -/// result. The upper 64 bits of the result are copied from the upper double- -/// precision value of the first operand. +/// result. The upper 64 bits of the result are copied from the upper +/// double-precision value of the first operand. /// /// \headerfile /// @@ -983,8 +983,10 @@ _mm_cmpnge_sd(__m128d __a, __m128d __b) } /// \brief Compares the lower double-precision floating-point values in each of -/// the two 128-bit floating-point vectors of [2 x double] for equality. The -/// comparison yields 0 for false, 1 for true. +/// the two 128-bit floating-point vectors of [2 x double] for equality. +/// +/// The comparison yields 0 for false, 1 for true. If either of the two +/// lower double-precision values is NaN, 0 is returned. /// /// \headerfile /// @@ -996,7 +998,8 @@ _mm_cmpnge_sd(__m128d __a, __m128d __b) /// \param __b /// A 128-bit vector of [2 x double]. The lower double-precision value is /// compared to the lower double-precision value of \a __a. -/// \returns An integer containing the comparison results. +/// \returns An integer containing the comparison results. If either of the two +/// lower double-precision values is NaN, 0 is returned. static __inline__ int __DEFAULT_FN_ATTRS _mm_comieq_sd(__m128d __a, __m128d __b) { @@ -1008,7 +1011,8 @@ _mm_comieq_sd(__m128d __a, __m128d __b) /// the value in the first parameter is less than the corresponding value in /// the second parameter. /// -/// The comparison yields 0 for false, 1 for true. +/// The comparison yields 0 for false, 1 for true. If either of the two +/// lower double-precision values is NaN, 0 is returned. /// /// \headerfile /// @@ -1020,7 +1024,8 @@ _mm_comieq_sd(__m128d __a, __m128d __b) /// \param __b /// A 128-bit vector of [2 x double]. The lower double-precision value is /// compared to the lower double-precision value of \a __a. -/// \returns An integer containing the comparison results. +/// \returns An integer containing the comparison results. If either of the two +/// lower double-precision values is NaN, 0 is returned. static __inline__ int __DEFAULT_FN_ATTRS _mm_comilt_sd(__m128d __a, __m128d __b) { @@ -1032,7 +1037,8 @@ _mm_comilt_sd(__m128d __a, __m128d __b) /// the value in the first parameter is less than or equal to the /// corresponding value in the second parameter. /// -/// The comparison yields 0 for false, 1 for true. +/// The comparison yields 0 for false, 1 for true. If either of the two +/// lower double-precision values is NaN, 0 is returned. /// /// \headerfile /// @@ -1044,7 +1050,8 @@ _mm_comilt_sd(__m128d __a, __m128d __b) /// \param __b /// A 128-bit vector of [2 x double]. The lower double-precision value is /// compared to the lower double-precision value of \a __a. -/// \returns An integer containing the comparison results. +/// \returns An integer containing the comparison results. If either of the two +/// lower double-precision values is NaN, 0 is returned. static __inline__ int __DEFAULT_FN_ATTRS _mm_comile_sd(__m128d __a, __m128d __b) { @@ -1056,7 +1063,8 @@ _mm_comile_sd(__m128d __a, __m128d __b) /// the value in the first parameter is greater than the corresponding value /// in the second parameter. /// -/// The comparison yields 0 for false, 1 for true. +/// The comparison yields 0 for false, 1 for true. If either of the two +/// lower double-precision values is NaN, 0 is returned. /// /// \headerfile /// @@ -1068,7 +1076,8 @@ _mm_comile_sd(__m128d __a, __m128d __b) /// \param __b /// A 128-bit vector of [2 x double]. The lower double-precision value is /// compared to the lower double-precision value of \a __a. -/// \returns An integer containing the comparison results. +/// \returns An integer containing the comparison results. If either of the two +/// lower double-precision values is NaN, 0 is returned. static __inline__ int __DEFAULT_FN_ATTRS _mm_comigt_sd(__m128d __a, __m128d __b) { @@ -1080,7 +1089,8 @@ _mm_comigt_sd(__m128d __a, __m128d __b) /// the value in the first parameter is greater than or equal to the /// corresponding value in the second parameter. /// -/// The comparison yields 0 for false, 1 for true. +/// The comparison yields 0 for false, 1 for true. If either of the two +/// lower double-precision values is NaN, 0 is returned. /// /// \headerfile /// @@ -1092,7 +1102,8 @@ _mm_comigt_sd(__m128d __a, __m128d __b) /// \param __b /// A 128-bit vector of [2 x double]. The lower double-precision value is /// compared to the lower double-precision value of \a __a. -/// \returns An integer containing the comparison results. +/// \returns An integer containing the comparison results. If either of the two +/// lower double-precision values is NaN, 0 is returned. static __inline__ int __DEFAULT_FN_ATTRS _mm_comige_sd(__m128d __a, __m128d __b) { @@ -1104,7 +1115,8 @@ _mm_comige_sd(__m128d __a, __m128d __b) /// the value in the first parameter is unequal to the corresponding value in /// the second parameter. /// -/// The comparison yields 0 for false, 1 for true. +/// The comparison yields 0 for false, 1 for true. If either of the two +/// lower double-precision values is NaN, 1 is returned. /// /// \headerfile /// @@ -1116,7 +1128,8 @@ _mm_comige_sd(__m128d __a, __m128d __b) /// \param __b /// A 128-bit vector of [2 x double]. The lower double-precision value is /// compared to the lower double-precision value of \a __a. -/// \returns An integer containing the comparison results. +/// \returns An integer containing the comparison results. If either of the two +/// lower double-precision values is NaN, 1 is returned. static __inline__ int __DEFAULT_FN_ATTRS _mm_comineq_sd(__m128d __a, __m128d __b) { @@ -1127,7 +1140,7 @@ _mm_comineq_sd(__m128d __a, __m128d __b) /// the two 128-bit floating-point vectors of [2 x double] for equality. The /// comparison yields 0 for false, 1 for true. /// -/// If either of the two lower double-precision values is NaN, 1 is returned. +/// If either of the two lower double-precision values is NaN, 0 is returned. /// /// \headerfile /// @@ -1140,7 +1153,7 @@ _mm_comineq_sd(__m128d __a, __m128d __b) /// A 128-bit vector of [2 x double]. The lower double-precision value is /// compared to the lower double-precision value of \a __a. /// \returns An integer containing the comparison results. If either of the two -/// lower double-precision values is NaN, 1 is returned. +/// lower double-precision values is NaN, 0 is returned. static __inline__ int __DEFAULT_FN_ATTRS _mm_ucomieq_sd(__m128d __a, __m128d __b) { @@ -1153,7 +1166,7 @@ _mm_ucomieq_sd(__m128d __a, __m128d __b) /// the second parameter. /// /// The comparison yields 0 for false, 1 for true. If either of the two lower -/// double-precision values is NaN, 1 is returned. +/// double-precision values is NaN, 0 is returned. /// /// \headerfile /// @@ -1166,7 +1179,7 @@ _mm_ucomieq_sd(__m128d __a, __m128d __b) /// A 128-bit vector of [2 x double]. The lower double-precision value is /// compared to the lower double-precision value of \a __a. /// \returns An integer containing the comparison results. If either of the two -/// lower double-precision values is NaN, 1 is returned. +/// lower double-precision values is NaN, 0 is returned. static __inline__ int __DEFAULT_FN_ATTRS _mm_ucomilt_sd(__m128d __a, __m128d __b) { @@ -1179,7 +1192,7 @@ _mm_ucomilt_sd(__m128d __a, __m128d __b) /// corresponding value in the second parameter. /// /// The comparison yields 0 for false, 1 for true. If either of the two lower -/// double-precision values is NaN, 1 is returned. +/// double-precision values is NaN, 0 is returned. /// /// \headerfile /// @@ -1192,7 +1205,7 @@ _mm_ucomilt_sd(__m128d __a, __m128d __b) /// A 128-bit vector of [2 x double]. The lower double-precision value is /// compared to the lower double-precision value of \a __a. /// \returns An integer containing the comparison results. If either of the two -/// lower double-precision values is NaN, 1 is returned. +/// lower double-precision values is NaN, 0 is returned. static __inline__ int __DEFAULT_FN_ATTRS _mm_ucomile_sd(__m128d __a, __m128d __b) { @@ -1257,7 +1270,7 @@ _mm_ucomige_sd(__m128d __a, __m128d __b) /// the second parameter. /// /// The comparison yields 0 for false, 1 for true. If either of the two lower -/// double-precision values is NaN, 0 is returned. +/// double-precision values is NaN, 1 is returned. /// /// \headerfile /// @@ -1270,7 +1283,7 @@ _mm_ucomige_sd(__m128d __a, __m128d __b) /// A 128-bit vector of [2 x double]. The lower double-precision value is /// compared to the lower double-precision value of \a __a. /// \returns An integer containing the comparison result. If either of the two -/// lower double-precision values is NaN, 0 is returned. +/// lower double-precision values is NaN, 1 is returned. static __inline__ int __DEFAULT_FN_ATTRS _mm_ucomineq_sd(__m128d __a, __m128d __b) { @@ -1935,14 +1948,15 @@ _mm_store_pd(double *__dp, __m128d __a) /// /// \headerfile /// -/// This intrinsic corresponds to the VMOVDDUP + VMOVAPD / MOVLHPS + MOVAPS instruction. +/// This intrinsic corresponds to the +/// VMOVDDUP + VMOVAPD / MOVLHPS + MOVAPS instruction. /// /// \param __dp /// A pointer to a memory location that can store two double-precision /// values. /// \param __a /// A 128-bit vector of [2 x double] whose lower 64 bits are copied to each -/// of the values in \a dp. +/// of the values in \a __dp. static __inline__ void __DEFAULT_FN_ATTRS _mm_store1_pd(double *__dp, __m128d __a) { @@ -1950,18 +1964,20 @@ _mm_store1_pd(double *__dp, __m128d __a) _mm_store_pd(__dp, __a); } -/// \brief Stores a 128-bit vector of [2 x double] into an aligned memory -/// location. +/// \brief Moves the lower 64 bits of a 128-bit vector of [2 x double] twice to +/// the upper and lower 64 bits of a memory location. /// /// \headerfile /// -/// This intrinsic corresponds to the VMOVAPD / MOVAPD instruction. +/// This intrinsic corresponds to the +/// VMOVDDUP + VMOVAPD / MOVLHPS + MOVAPS instruction. /// /// \param __dp -/// A pointer to a 128-bit memory location. The address of the memory -/// location has to be 16-byte aligned. +/// A pointer to a memory location that can store two double-precision +/// values. /// \param __a -/// A 128-bit vector of [2 x double] containing the values to be stored. +/// A 128-bit vector of [2 x double] whose lower 64 bits are copied to each +/// of the values in \a __dp. static __inline__ void __DEFAULT_FN_ATTRS _mm_store_pd1(double *__dp, __m128d __a) { @@ -3846,8 +3862,7 @@ _mm_set1_epi8(char __b) /// /// \headerfile /// -/// This intrinsic corresponds to the VPUNPCKLQDQ / PUNPCKLQDQ -/// instruction. +/// This intrinsic does not correspond to a specific instruction. /// /// \param __q0 /// A 64-bit integral value used to initialize the lower 64 bits of the @@ -4018,7 +4033,7 @@ _mm_storeu_si128(__m128i *__p, __m128i __b) /// specified unaligned memory location. When a mask bit is 1, the /// corresponding byte is written, otherwise it is not written. /// -/// To minimize caching, the date is flagged as non-temporal (unlikely to be +/// To minimize caching, the data is flagged as non-temporal (unlikely to be /// used again soon). Exception and trap behavior for elements not selected /// for storage to memory are implementation dependent. /// @@ -4532,8 +4547,8 @@ _mm_unpackhi_epi32(__m128i __a, __m128i __b) return (__m128i)__builtin_shufflevector((__v4si)__a, (__v4si)__b, 2, 4+2, 3, 4+3); } -/// \brief Unpacks the high-order (odd-indexed) values from two 128-bit vectors -/// of [2 x i64] and interleaves them into a 128-bit vector of [2 x i64]. +/// \brief Unpacks the high-order 64-bit elements from two 128-bit vectors of +/// [2 x i64] and interleaves them into a 128-bit vector of [2 x i64]. /// /// \headerfile /// @@ -4665,7 +4680,7 @@ _mm_unpacklo_epi64(__m128i __a, __m128i __b) /// /// \headerfile /// -/// This intrinsic has no corresponding instruction. +/// This intrinsic corresponds to the MOVDQ2Q instruction. /// /// \param __a /// A 128-bit integer vector operand. The lower 64 bits are moved to the @@ -4682,7 +4697,7 @@ _mm_movepi64_pi64(__m128i __a) /// /// \headerfile /// -/// This intrinsic corresponds to the VMOVQ / MOVQ / MOVD instruction. +/// This intrinsic corresponds to the MOVD+VMOVQ instruction. /// /// \param __a /// A 64-bit value. @@ -4712,8 +4727,8 @@ _mm_move_epi64(__m128i __a) return __builtin_shufflevector((__v2di)__a, (__m128i){ 0 }, 0, 2); } -/// \brief Unpacks the high-order (odd-indexed) values from two 128-bit vectors -/// of [2 x double] and interleaves them into a 128-bit vector of [2 x +/// \brief Unpacks the high-order 64-bit elements from two 128-bit vectors of +/// [2 x double] and interleaves them into a 128-bit vector of [2 x /// double]. /// /// \headerfile @@ -4733,7 +4748,7 @@ _mm_unpackhi_pd(__m128d __a, __m128d __b) return __builtin_shufflevector((__v2df)__a, (__v2df)__b, 1, 2+1); } -/// \brief Unpacks the low-order (even-indexed) values from two 128-bit vectors +/// \brief Unpacks the low-order 64-bit elements from two 128-bit vectors /// of [2 x double] and interleaves them into a 128-bit vector of [2 x /// double]. /// @@ -4792,9 +4807,9 @@ _mm_movemask_pd(__m128d __a) /// A 128-bit vector of [2 x double]. /// \param i /// An 8-bit immediate value. The least significant two bits specify which -/// elements to copy from a and b: \n -/// Bit[0] = 0: lower element of a copied to lower element of result. \n -/// Bit[0] = 1: upper element of a copied to lower element of result. \n +/// elements to copy from \a a and \a b: \n +/// Bit[0] = 0: lower element of \a a copied to lower element of result. \n +/// Bit[0] = 1: upper element of \a a copied to lower element of result. \n /// Bit[1] = 0: lower element of \a b copied to upper element of result. \n /// Bit[1] = 1: upper element of \a b copied to upper element of result. \n /// \returns A 128-bit vector of [2 x double] containing the shuffled values. -- 2.40.0