<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="Generator" content="Microsoft Word 14 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:Helvetica;
panose-1:2 11 6 4 2 2 2 2 2 4;}
@font-face
{font-family:"MS Mincho";
panose-1:2 2 6 9 4 2 5 8 3 4;}
@font-face
{font-family:"MS Mincho";
panose-1:2 2 6 9 4 2 5 8 3 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
{font-family:"\@MS Mincho";
panose-1:2 2 6 9 4 2 5 8 3 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:11.0pt;
font-family:"Calibri","sans-serif";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
span.EmailStyle17
{mso-style-type:personal-compose;
font-family:"Calibri","sans-serif";
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-family:"Calibri","sans-serif";}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang="EN-US" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">Hi all,<o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black"><o:p> </o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">I'd like to propose adding doxygen comments for intrinsics. I'm also proposing a specific format for these comments, although I welcome
any opinions on how it could be improved.<o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black"><o:p> </o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">There are several benefits to adding doxygen comments to the intrinsics headers:<o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">(1) Both MS tooltips and XCode will be able to display intrinsics documentation.<o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">(2) Online documentation for LLVM intrinsics headers can be easily generated and browsed in
<a href="http://llvm.org/doxygen">http://llvm.org/doxygen</a></span><b><i><span style="color:#1F497D"><o:p></o:p></span></i></b></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">(3) It is possible to convert doxygen comments to other formats such as pdf or chm. This is an important benefit for companies that
need to deliver update-to-date intrinsics documents in printable formats. It also helps to reduce documentation support cost.<o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">(4) Maintaining intrinsic documentation and code in one place makes it easier for developers to keep them in sync.<o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black"><o:p> </o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">Our documentation used to be kept in a closed format (CHM) and we decided to convert it into doxygen with the intention to keep it
in the doxygen-annotated header files exclusively moving forward, as it would be much easier to maintain.<o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">Converting hundreds of documented intrinsics manually would have been tedious and error prone, so I have created a hack of a tool (DCG) that inserts doxygen
comments into LLVM intrinsics header files. With the help of this tool we have added corresponding intrinsic comments (describing many of the SSE4a, AVX, BMI, SSE2, F16C, MMX, SSE3, POPCNT, PREFETCHW, SSE4.1, SSSE3, SSE intrinsics) to the LLVM header files.
DCG takes a CHM file containing PS4 internal documentation as input, processes it, and matches the intrinsics from LLVM headers with the intrinsics from the documentation. The tool does all the necessary formatting to create the doxygen comments that comply
with LLVM coding style and then inserts each generated comment in front of the corresponding intrinsic definition. Again, DCG was written as a one-time use tool.
</span>It’s large, I’m not clear what the long term value or use of it would be, and it would require much work to get it ready to open source.<o:p></o:p></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black"><o:p> </o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">Below are the format examples of two main kinds of doxygen comments I'm proposing (Intrinsics are taken from ammintrin.h):<o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black"><o:p> </o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">* The first example contains a regular intrinsics definition.<o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">* The second example contains an intrinsic that is described via macro definition.<o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black"><o:p> </o:p></span></p>
<p class="MsoNormal">/// \brief Extracts the specified bits from the lower 64 bits of the 128-bit<o:p></o:p></p>
<p class="MsoNormal">/// integer vector operand.<o:p></o:p></p>
<p class="MsoNormal">///<o:p></o:p></p>
<p class="MsoNormal">/// \headerfile <x86intrin.h><o:p></o:p></p>
<p class="MsoNormal">///<o:p></o:p></p>
<p class="MsoNormal">/// \code <o:p></o:p></p>
<p class="MsoNormal">/// This intrinsic corresponds to the \c EXTRQ instruction.<o:p></o:p></p>
<p class="MsoNormal">/// \endcode <o:p></o:p></p>
<p class="MsoNormal">///<o:p></o:p></p>
<p class="MsoNormal">/// \param __x<o:p></o:p></p>
<p class="MsoNormal">/// The value from which bits are extracted.<o:p></o:p></p>
<p class="MsoNormal">/// \param __y<o:p></o:p></p>
<p class="MsoNormal">/// Specifies the index of the least significant bit at [13:8],<o:p></o:p></p>
<p class="MsoNormal">/// and the length at [5:0].<o:p></o:p></p>
<p class="MsoNormal">/// \returns A 128-bit vector whose lower 64 bits contain the bits extracted
<o:p></o:p></p>
<p class="MsoNormal">/// from the operand.<o:p></o:p></p>
<p class="MsoNormal">static __inline__ __m128i __attribute__((__always_inline__, __nodebug__))<o:p></o:p></p>
<p class="MsoNormal">_mm_extract_si64(__m128i __x, __m128i __y)<o:p></o:p></p>
<p class="MsoNormal">{<o:p></o:p></p>
<p class="MsoNormal"> return (__m128i)__builtin_ia32_extrq((__v2di)__x, (__v16qi)__y);<o:p></o:p></p>
<p class="MsoNormal">}<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal"> <o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">/// \brief Extracts the specified bits from the lower 64 bits of the 128-bit<o:p></o:p></p>
<p class="MsoNormal">/// operand, using the length and bit index specified in the immediate<o:p></o:p></p>
<p class="MsoNormal">/// bytes.<o:p></o:p></p>
<p class="MsoNormal">///<o:p></o:p></p>
<p class="MsoNormal">/// \headerfile <x86intrin.h><o:p></o:p></p>
<p class="MsoNormal">///<o:p></o:p></p>
<p class="MsoNormal">/// \code <o:p></o:p></p>
<p class="MsoNormal">/// __m128i _mm_extracti_si64(__m128i x, const int len, const int idx);<o:p></o:p></p>
<p class="MsoNormal">/// \endcode <o:p></o:p></p>
<p class="MsoNormal">///<o:p></o:p></p>
<p class="MsoNormal">/// \code <o:p></o:p></p>
<p class="MsoNormal">/// This intrinsic corresponds to the \c EXTRQ instruction.<o:p></o:p></p>
<p class="MsoNormal">/// \endcode <o:p></o:p></p>
<p class="MsoNormal">///<o:p></o:p></p>
<p class="MsoNormal">/// \param x<o:p></o:p></p>
<p class="MsoNormal">/// The value from which bits are extracted.<o:p></o:p></p>
<p class="MsoNormal">/// \param len<o:p></o:p></p>
<p class="MsoNormal">/// Specifies the length at [5:0].<o:p></o:p></p>
<p class="MsoNormal">/// \param idx<o:p></o:p></p>
<p class="MsoNormal">/// Specifies the index of the least significant bit at [5:0].<o:p></o:p></p>
<p class="MsoNormal">/// \returns The bits extracted from the operand.<o:p></o:p></p>
<p class="MsoNormal"><span lang="ES-MX">#define _mm_extracti_si64(x, len, idx) \<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="ES-MX"> </span>((__m128i)__builtin_ia32_extrqi((__v2di)(__m128i)(x), \<o:p></o:p></p>
<p class="MsoNormal"> (char)(len), (char)(idx)))<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black"><o:p> </o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black"><o:p> </o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">The format is slightly different for these two cases. The second example contains an additional \code section describing the equivalent
function prototype for the macro. Even though the intrinsics is implemented as a macro, it does have expectations on the parameter types and the return type, and if left undocumented, such information is not always obvious to the user. Please review the proposed
format and comments' examples below.<o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black"><o:p> </o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">Thanks,<o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="font-size:10.0pt;font-family:"Helvetica","sans-serif";color:black">Katya<o:p></o:p></span></p>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
</body>
</html>