Adding doxygen comments to the LLVM intrinsics (part 5, f16cintrin.h)

[kromanova]

Summary

Eric Christopher told me that from now on it's OK to commit doxygen comments for x86 intrinsics without formal OK from the open source reviewers. Post-commit reviews could be done later if needed. It should speed up the process.

I still think it's worth posting a code review. At first, it's nice for bookkeeping. At second, I made one tiny non-comment related change by replacing the name of the parameter in one of the intrinsics. It's done for consistency purpose. It might be the only thing that needs to be briefly looked at during pre-commit review.

Here is the patch with the doxygen comments for the intrinsincs in the header file f16cintrin.h.
The doxygen comments are automatically generated based on SCE internal intrinsics document using DCG tool that I wrote.

I will submit more doxygen comments for the other intrinsic header files as soon as this patch is approved.

Here is the link to the general discussion about adding comments to x86 intrinsics headers.
http://permalink.gmane.org/gmane.comp.compilers.clang.devel/42032

Here are the links to the similar code reviews for the doxygen comments other header files.

http://reviews.llvm.org/D8762 (closed)
http://reviews.llvm.org/D15999 (closed)
http://reviews.llvm.org/D16562 (closed)
http://reviews.llvm.org/D16913 (closed)

[cfe-commits]

It's best not to commit things without approval once they've been sent for
review (the assumption being that if you asked for review it's because the
change needed review - time doesn't change that fact) - if approval was
given off-list (eg: on IRC) it's best to mention who gave it & where (&
ideally the person should provide it on-list just for record keeping)

• msg-537-31.txt159 BDownload

[kromanova]

My apologies…

From: David Blaikie [mailto:[e-mail]]
Sent: Tuesday, February 09, 2016 4:42 PM
To: [e-mail]; Romanova, Katya
Cc: Gao, Yunzhong; Robinson, Paul; Eric Christopher; Dmitri Gribenko; Craig Topper; Jonathan Roelofs; cfe-commits
Subject: Re: [PATCH] D17021: Adding doxygen comments to the LLVM intrinsics (part 5, f16cintrin.h)

It's best not to commit things without approval once they've been sent for review (the assumption being that if you asked for review it's because the change needed review - time doesn't change that fact) - if approval was given off-list (eg: on IRC) it's best to mention who gave it & where (& ideally the person should provide it on-list just for record keeping)

cfe/trunk/lib/Headers/f16cintrin.h

 #if !defined __X86INTRIN_H && !defined __EMMINTRIN_H && !defined __IMMINTRIN_H
 #error "Never use <f16cintrin.h> directly; include <emmintrin.h> instead."
 #endif
 
 #ifndef __F16CINTRIN_H
 #define __F16CINTRIN_H
 
 /* Define the default attributes for the functions in this file. */
-#define __DEFAULT_FN_ATTRS \ 
+#define __DEFAULT_FN_ATTRS \
   __attribute__((__always_inline__, __nodebug__, __target__("f16c")))
 
+/// \brief Converts a 16-bit half-precision float value into a 32-bit float
+///    value.
+///
+/// \headerfile <x86intrin.h>
+///
+/// This intrinsic corresponds to the \c VCVTPH2PS instruction.
+///
+/// \param a
+///    A 16-bit half-precision float value.
+/// \returns The converted 32-bit float value.
 static __inline float __DEFAULT_FN_ATTRS
 _cvtsh_ss(unsigned short a)
 {
   __v8hi v = {(short)a, 0, 0, 0, 0, 0, 0, 0};
   __v4sf r = __builtin_ia32_vcvtph2ps(v);
   return r[0];
 }
 
+/// \brief Converts a 32-bit single-precision float value to a 16-bit
+///    half-precision float value.
+///
+/// \headerfile <x86intrin.h>
+///
+/// \code
+/// unsigned short _cvtss_sh(float a, const int imm);
+/// \endcode
+///
+/// This intrinsic corresponds to the \c VCVTPS2PH instruction.
+///
+/// \param a
+///    A 32-bit single-precision float value to be converted to a 16-bit
+///    half-precision float value.
+/// \param imm
+///    An immediate value controlling rounding using bits [2:0]:
+///    000: Nearest
+///    001: Down
+///    010: Up
+///    011: Truncate
+///    1XX: Use MXCSR.RC for rounding
+/// \returns The converted 16-bit half-precision float value.
 #define _cvtss_sh(a, imm)  \
   ((unsigned short)(((__v8hi)__builtin_ia32_vcvtps2ph((__v4sf){a, 0, 0, 0}, \
                                                       (imm)))[0]))
 
+/// \brief Converts a 128-bit vector containing 32-bit float values into a
+///    128-bit vector containing 16-bit half-precision float values.
+///
+/// \headerfile <x86intrin.h>
+///
+/// \code
+/// __m128i _mm_cvtps_ph(__m128 a, const int imm);
+/// \endcode
+///
+/// This intrinsic corresponds to the \c VCVTPS2PH instruction.
+///
+/// \param a
+///    A 128-bit vector containing 32-bit float values.
+/// \param imm
+///    An immediate value controlling rounding using bits [2:0]:
+///    000: Nearest
+///    001: Down
+///    010: Up
+///    011: Truncate
+///    1XX: Use MXCSR.RC for rounding
+/// \returns A 128-bit vector containing converted 16-bit half-precision float
+///    values. The lower 64 bits are used to store the converted 16-bit
+///    half-precision floating-point values.
 #define _mm_cvtps_ph(a, imm) \
   ((__m128i)__builtin_ia32_vcvtps2ph((__v4sf)(__m128)(a), (imm)))
 
+/// \brief Converts a 128-bit vector containing 16-bit half-precision float
+///    values into a 128-bit vector containing 32-bit float values.
+///
+/// \headerfile <x86intrin.h>
+///
+/// This intrinsic corresponds to the \c VCVTPH2PS instruction.
+///
+/// \param a
+///    A 128-bit vector containing 16-bit half-precision float values. The lower
+///    64 bits are used in the conversion.
+/// \returns A 128-bit vector of [4 x float] containing converted float values.
 static __inline __m128 __DEFAULT_FN_ATTRS
-_mm_cvtph_ps(__m128i __a)
+_mm_cvtph_ps(__m128i a)
 {
-  return (__m128)__builtin_ia32_vcvtph2ps((__v8hi)__a);
+  return (__m128)__builtin_ia32_vcvtph2ps((__v8hi)a);
 }
 
 #undef __DEFAULT_FN_ATTRS
 
 #endif /* __F16CINTRIN_H */