<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=iso-2022-jp">
<meta name="Generator" content="Microsoft Word 14 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Tms Rmn";
panose-1:2 2 6 3 4 5 5 2 3 4;}
@font-face
{font-family:Helv;
panose-1:2 11 6 4 2 2 2 3 2 4;}
@font-face
{font-family:"MS Mincho";
panose-1:2 2 6 9 4 2 5 8 3 4;}
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 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">As some of you know, we at Sony Computer Entertainment America have been working on various aspects of LLVM, including Clang and its toolchain. As part of our work, we have created documentation for our customers about using Clang, and
we would like to share the fruits of our work with the Clang and LLVM communities.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">As our first documentation submission, we plan to provide our *CPU Intrinsics Guide*, which documents the Clang intrinsics for x86intrin.h, along with several builtin and sync types. I've included a sample of what we document for one of
the intrinsics below.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Our question for the community is: what documentation format is most helpful and desired for this information? We currently have two main possibilities in mind (with three variants for the first option):<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">1) Add the documentation for each intrinsic to the header file:<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">- 1a) Using Doxygen tagging. One benefit of this approach is that the documentation is available for the developer within a code-development/editing system. One potential difficulty with this approach is that the intrinsics header file
becomes much larger, which could increase compile times.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">- 1b) Using Microsoft's annotation grammar. We might be able to contain this annotation grammar within Doxygen tagging that deviates somewhat from the LLVM Doxygen style. This approach allows us to generate XML output for the Microsoft
Visual Studio Tooltip class. The benefit of this approach is that the documentation is available for the developer within Visual Studio, without his or her having to open the specific header file. Like option (1a), one potential difficulty with this approach
is that the intrinsics header file becomes much larger, which could increase compile times.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">- 1c) Using TblGen to maintain both the intrinsics definitions and their documentation, from which we generate the header file with both. With this approach, we could implement either option (1a), (1b), or both, and have a single point
of maintenance. This option has the same benefits and drawbacks as (1a) and (1b).<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">2) Add the documentation in reST and Sphynx format (to match existing Clang and LLVM documentation) to the Clang Web site. The main benefit of this approach is that the documentation is available to anyone on the Web.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Thus, we come to you today to ask your opinion on which approach we should take. We're open to providing one or more of the formats, as desired, or considering a different option that one of you might make.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Sample intrinsic documentation (ASCII formatted for forum viewing)<o:p></o:p></p>
<p class="MsoNormal">-------------------------------<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">_mm256_round_ps<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">SYNOPSIS<o:p></o:p></p>
<p class="MsoNormal">#include <x86intrin.h><o:p></o:p></p>
<p class="MsoNormal">__m256 _mm256_round_ps(__m256 v, const int m);<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">INSTRUCTION<o:p></o:p></p>
<p class="MsoNormal">VROUNDPS<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">DESCRIPTION<o:p></o:p></p>
<p class="MsoNormal">Rounds the values stored in a packed 256-bit vector [8 x float] as specified by the byte operand. The source values are rounded to integer values and returned as floating point values.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">PARAMETERS<o:p></o:p></p>
<p class="MsoNormal">v A 256-bit vector of [8 x float] values.<o:p></o:p></p>
<p class="MsoNormal">m An immediate byte operand specifying how the rounding is to be performed.<o:p></o:p></p>
<p class="MsoNormal"> Bits [7:4] are reserved.<o:p></o:p></p>
<p class="MsoNormal"> Bit [3] is a precision exception value:<o:p></o:p></p>
<p class="MsoNormal"> 0: A normal PE exception is used<o:p></o:p></p>
<p class="MsoNormal"> 1: The PE field is not updated<o:p></o:p></p>
<p class="MsoNormal"> Bit [2] is a rounding control source:<o:p></o:p></p>
<p class="MsoNormal"> 0: MXCSR:RC<o:p></o:p></p>
<p class="MsoNormal"> 1: Use the RC field value<o:p></o:p></p>
<p class="MsoNormal"> Bit [1:0] contain the rounding control definition:<o:p></o:p></p>
<p class="MsoNormal"> 00: Nearest<o:p></o:p></p>
<p class="MsoNormal"> 01: Downward (toward negative infinity)<o:p></o:p></p>
<p class="MsoNormal"> 10: Upward (toward positive infinity)<o:p></o:p></p>
<p class="MsoNormal"> 11: Truncated<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">RETURNS<o:p></o:p></p>
<p class="MsoNormal">A 256-bit vector of [8 x float] containing the rounded values.<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" style="text-autospace:none"><span style="font-size:10.0pt;font-family:"Helv","sans-serif";color:purple">Cheers,<o:p></o:p></span></p>
<p class="MsoNormal" style="text-autospace:none"><span style="font-size:10.0pt;font-family:"Helv","sans-serif";color:purple">Michael<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:14.0pt;font-family:"Cambria Math","serif";color:black">$B"$(B</span><span style="font-size:14.0pt;font-family:"Arial","sans-serif";color:black">$B!{(B</span><span style="font-size:14.0pt;font-family:"Helv","sans-serif";color:black">$B!_(B</span><span style="font-size:14.0pt;font-family:"Arial","sans-serif";color:black">$B""(B</span><span style="font-size:14.0pt;font-family:"Tms Rmn","serif";color:black">
</span><span style="font-size:12.0pt;font-family:"Tms Rmn","serif";color:black"> </span><span style="font-size:12.0pt;font-family:"MS Mincho";color:black">$B$*Hh$lMM$G$9(B</span><o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
</body>
</html>