Patchwork [wwwdocs] Document Runtime CPU detection builtins

login
register
mail settings
Submitter Sriraman Tallam
Date Aug. 11, 2012, 2:20 a.m.
Message ID <CAAs8HmwO=jycJSgMS2LOfBNJrdUxyDDNDxWDX=kcABCZQEEMnw@mail.gmail.com>
Download mbox | patch
Permalink /patch/176656/
State New
Headers show

Comments

Sriraman Tallam - Aug. 11, 2012, 2:20 a.m.
Hi,

   I have added a release note for x86 builtins __builtin_cpu_is and
__builtin_cpu_supports. They were checked in to trunk in rev. 186789.
Is this ok to submit?

Thanks,
-Sri.
Sriraman Tallam - Aug. 14, 2012, 5:51 p.m.
Hi Gerald,

   Is this release note alright?

Thanks,
-Sri.

On Fri, Aug 10, 2012 at 7:20 PM, Sriraman Tallam <tmsriram@google.com> wrote:
> Hi,
>
>    I have added a release note for x86 builtins __builtin_cpu_is and
> __builtin_cpu_supports. They were checked in to trunk in rev. 186789.
> Is this ok to submit?
>
> Thanks,
> -Sri.
Sriraman Tallam - Aug. 14, 2012, 6:02 p.m.
+gerald@pfiefer.com

On Tue, Aug 14, 2012 at 10:51 AM, Sriraman Tallam <tmsriram@google.com> wrote:
> Hi Gerald,
>
>    Is this release note alright?
>
> Thanks,
> -Sri.
>
> On Fri, Aug 10, 2012 at 7:20 PM, Sriraman Tallam <tmsriram@google.com> wrote:
>> Hi,
>>
>>    I have added a release note for x86 builtins __builtin_cpu_is and
>> __builtin_cpu_supports. They were checked in to trunk in rev. 186789.
>> Is this ok to submit?
>>
>> Thanks,
>> -Sri.
Sriraman Tallam - Aug. 20, 2012, 6:04 p.m.
Ping.



On Tue, Aug 14, 2012 at 11:02 AM, Sriraman Tallam <tmsriram@google.com> wrote:
> +gerald@pfiefer.com
>
> On Tue, Aug 14, 2012 at 10:51 AM, Sriraman Tallam <tmsriram@google.com> wrote:
>> Hi Gerald,
>>
>>    Is this release note alright?
>>
>> Thanks,
>> -Sri.
>>
>> On Fri, Aug 10, 2012 at 7:20 PM, Sriraman Tallam <tmsriram@google.com> wrote:
>>> Hi,
>>>
>>>    I have added a release note for x86 builtins __builtin_cpu_is and
>>> __builtin_cpu_supports. They were checked in to trunk in rev. 186789.
>>> Is this ok to submit?
>>>
>>> Thanks,
>>> -Sri.
Diego Novillo - Aug. 20, 2012, 6:16 p.m.
On Fri, Aug 10, 2012 at 10:20 PM, Sriraman Tallam <tmsriram@google.com> wrote:
> Hi,
>
>    I have added a release note for x86 builtins __builtin_cpu_is and
> __builtin_cpu_supports. They were checked in to trunk in rev. 186789.
> Is this ok to submit?

I would not include such detailed documentation in changes.html.  I
assume that all this documentation, including caveats and limitations
is documented in the manual itself?  If that's the case, then simply
mention the builtins, an overview description of about a paragraph and
pointers to the user documentation for limitations and caveats.


Diego.
Gerald Pfeifer - Aug. 20, 2012, 8:31 p.m.
Hi Sriraman,

On Fri, 10 Aug 2012, Sriraman Tallam wrote:
> I have added a release note for x86 builtins __builtin_cpu_is and
> __builtin_cpu_supports. They were checked in to trunk in rev. 186789.

I had hoped one of the x86 maintainers would review this from his
perspective given that they have more background.  For the lack of
that, let me give it a try.

Index: changes.html
===================================================================
+    <li> New builtin functions to detect run-time CPU type and ISA:<br>

"built-in", cf. http://gcc.gnu.org/codingconventions.html; here and
in the following.

No <br> here; <ul> should just do that.

+    <ul>
+      <li>Builtin <code>__builtin_cpu_is</code> has been added to detect if
+      the run-time CPU is of a particular type. The builtin returns a postive
+      integer on a match and zero otherwise. The builtin accepts one string
+      literal argument, the CPU name. For example,

"A built-in function..."

"positive"

"It accepts one string" (to make this shorter)

+      <code>__builtin_cpu_is("westmere")</code> returns a postive integer if

"positive"

+      the run-time CPU is an Intel Corei7 Westmere processor.  The following

I don't work for Intel, but should there be a space before "i7"?

+      are the CPU names recognized by <code>__builtin_cpu_is:</code>

How about making this "The following are the CPU names recognized for
now", which avoids another reference to the name of the built-in and
makes it clear that this is subject to change.

+      <li>Builtin <code>__builtin_cpu_supports</code> has been added to detect

"A built-in function..."

+      returns a postive integer on a match and zero otherwise. The builtin

"positive"

+      following are the ISA features recognized by
+      <code>__builtin_cpu_supports:</code>

Same is above?

+    <p>Caveat: If the above builtins are called before any constructors are
+    invoked, like during IFUNC initialization, then the CPU detection
+    initialization must be explicity run using this newly provided
+    builtin,  <code>__builtin_cpu_init</code>.

"...using the new built-in function <code>__builtin_cpu_init</code>."

What is a constructor in this context, by the way?  Will this be clear
to all the users?

+    <code>
+    static void (*some_ifunc_resolver(void))(void)<br>
+    {<br>
+    &nbsp&nbsp __builtin_cpu_init();<br>
+    &nbsp&nbsp if (__builtin_cpu_is("amdfam10h") ...<br>
+    &nbsp&nbsp if (__builtin_cpu_supports("popcnt") ...<br>
+    }
+    </code>

How about using <pre> here? That avoids the <br/>s which will cause
problems with the web page validator, by the way.


Nice job for documenting this so well.  Thanks for taking the time
and your patience!

The patch is fine modulo the changes I pointed out (though some of
them are more suggestions and you do not need to slavishly follow
those).

Gerald

Patch

Index: changes.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/gcc-4.8/changes.html,v
retrieving revision 1.10
diff -u -u -p -r1.10 changes.html
--- changes.html	10 Aug 2012 16:25:46 -0000	1.10
+++ changes.html	11 Aug 2012 02:14:13 -0000
@@ -92,6 +92,69 @@  by this change.</p>
     wrong results.  You must build all
     modules with <code>-mpreferred-stack-boundary=3</code>, including any
     libraries.  This includes the system libraries and startup modules.</li>
+    <li> New builtin functions to detect run-time CPU type and ISA:<br>
+    <ul>
+      <li>Builtin <code>__builtin_cpu_is</code> has been added to detect if
+      the run-time CPU is of a particular type. The builtin returns a postive
+      integer on a match and zero otherwise. The builtin accepts one string
+      literal argument, the CPU name. For example,
+      <code>__builtin_cpu_is("westmere")</code> returns a postive integer if
+      the run-time CPU is an Intel Corei7 Westmere processor.  The following
+      are the CPU names recognized by <code>__builtin_cpu_is:</code>
+      <ul>
+        <li>amd</li>
+        <li>intel</li>
+        <li>atom</li>
+        <li>core2</li>
+        <li>corei7</li>
+        <li>nehalem</li>
+        <li>westmere</li>
+        <li>sandybridge</li>
+        <li>amdfam10h</li>
+        <li>barcelona</li>
+        <li>shanghai</li>
+        <li>istanbul</li>
+        <li>bdver1</li>
+        <li>bdver2</li>
+        <li>btver2</li>
+      </ul></li>
+      <li>Builtin <code>__builtin_cpu_supports</code> has been added to detect
+      if the run-time CPU supports a particular ISA feature.  The builtin
+      returns a postive integer on a match and zero otherwise. The builtin
+      accepts one string literal argument, the ISA feature.
+      For example,  <code>__builtin_cpu_supports("ssse3")</code> returns a
+      positive integer if the run-time CPU supports SSSE3 instructions. The
+      following are the ISA features recognized by
+      <code>__builtin_cpu_supports:</code>
+      <ul>
+        <li>cmov</li>
+        <li>mmx</li>
+        <li>popcnt</li>
+        <li>sse</li>
+        <li>sse2</li>
+        <li>sse3</li>
+        <li>ssse3</li>
+        <li>sse4.1</li>
+        <li>sse4.2</li>
+        <li>avx</li>
+        <li>avx2</li>
+      </ul></li>
+    </ul>
+    <p>Caveat: If the above builtins are called before any constructors are
+    invoked, like during IFUNC initialization, then the CPU detection
+    initialization must be explicity run using this newly provided
+    builtin,  <code>__builtin_cpu_init</code>.  The initialization needs to
+    be done only once.  For example, this is how the invocation would look
+    like inside an IFUNC initializer:</p>
+    <code>
+    static void (*some_ifunc_resolver(void))(void)<br>
+    {<br>
+    &nbsp&nbsp __builtin_cpu_init();<br>
+    &nbsp&nbsp if (__builtin_cpu_is("amdfam10h") ...<br>
+    &nbsp&nbsp if (__builtin_cpu_supports("popcnt") ...<br>
+    }
+    </code>
+    </li>
   </ul>
 
 <h3 id="mips">MIPS</h3>