[wwwdocs] Document Runtime CPU detection builtins

[wwwdocs] Document Runtime CPU detection builtins

[Sriraman Tallam]

[-- Attachment #1: Type: text/plain, Size: 181 bytes --]

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.

[-- Attachment #2: changes_html_patch.txt --]
[-- Type: text/plain, Size: 3097 bytes --]

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>

Re: [wwwdocs] Document Runtime CPU detection builtins

[Sriraman Tallam]

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.

Re: [wwwdocs] Document Runtime CPU detection builtins

[Sriraman Tallam]

+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.

Re: [wwwdocs] Document Runtime CPU detection builtins

[Sriraman Tallam]

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.

Re: [wwwdocs] Document Runtime CPU detection builtins

[Diego Novillo]

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.

Re: [wwwdocs] Document Runtime CPU detection builtins

[Gerald Pfeifer]

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

Re: [wwwdocs] Document Runtime CPU detection builtins

[Sriraman Tallam]

[-- Attachment #1: Type: text/plain, Size: 3530 bytes --]

Hi Gerald / Diego,

    I have made all the mentioned changes.  I also shortened the
description like Diego mentioned by removing all the strings but kept
the caveats. I have not added a reference to the documentation because
i do not know what link to reference. The builtins are completely
documented in extend.texi.

   I have attached the patch. If there are no further comments I will
submit this tomorrow.

Thanks,
-Sri.


On Mon, Aug 20, 2012 at 1:31 PM, Gerald Pfeifer <gerald@pfeifer.com> wrote:
> 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

[-- Attachment #2: changes_html_patch.txt --]
[-- Type: text/plain, Size: 2331 bytes --]

Index: changes.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/gcc-4.8/changes.html,v
retrieving revision 1.10
diff -u -r1.10 changes.html
--- changes.html	10 Aug 2012 16:25:46 -0000	1.10
+++ changes.html	21 Aug 2012 02:38:40 -0000
@@ -92,6 +92,38 @@
     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 built-in functions to detect run-time CPU type and ISA:
+    <ul>
+      <li>A built-in function <code>__builtin_cpu_is</code> has been added to
+      detect if the run-time CPU is of a particular type.  It returns a
+      positive integer on a match and zero otherwise.  It accepts one string
+      literal argument, the CPU name.  For example,
+      <code>__builtin_cpu_is("westmere")</code> returns a positive integer if
+      the run-time CPU is an Intel Core i7 Westmere processor.  Please refer
+      to the documentation for the list of valid CPU names recognized.</li>
+      <li>A built-in function <code>__builtin_cpu_supports</code> has been
+      added to detect if the run-time CPU supports a particular ISA feature.
+      It returns a positive integer on a match and zero otherwise.  It 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.  Please refer to the
+      documentation for the list of valid ISA names recognized.</li>
+    </ul>
+    <p>Caveat: If these built-in functions are called before any static
+    constructors are invoked, like during IFUNC initialization, then the CPU
+    detection initialization must be explicity run using this newly provided
+    built-in function,  <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>
+    <pre>
+    static void (*some_ifunc_resolver(void))(void)
+    {
+      __builtin_cpu_init();
+      if (__builtin_cpu_is("amdfam10h") ...
+      if (__builtin_cpu_supports("popcnt") ...
+    }
+    </pre>
+    </li>
   </ul>
 
 <h3 id="mips">MIPS</h3>

Re: [wwwdocs] Document Runtime CPU detection builtins

[Diego Novillo]

On 2012-08-20 22:41 , Sriraman Tallam wrote:
> Hi Gerald / Diego,
>
>      I have made all the mentioned changes.  I also shortened the
> description like Diego mentioned by removing all the strings but kept
> the caveats. I have not added a reference to the documentation because
> i do not know what link to reference. The builtins are completely
> documented in extend.texi.

Referring to the user's manual is OK, I think.

> +    <p>Caveat: If these built-in functions are called before any static
> +    constructors are invoked, like during IFUNC initialization, then the CPU
> +    detection initialization must be explicity run using this newly provided

s/explicity/explicitly/

Other than that, it looks fine to me.


Diego.

Re: [wwwdocs] Document Runtime CPU detection builtins

[Sriraman Tallam]

Committed after making the changes.

One small problem, I am not sure how to fix this:

The hyper link I referenced is :
http://gcc.gnu.org/onlinedocs/gcc/X86-Built_002din-Functions.html#X86-Built_002din-Functions

whereas the committed changes.html is pointing to:
http://gcc.gnu.org/onlinedocs/gcc/X86-Built-in-Functions.html#X86-Built-in-Functions

Please note that the "_002din" is missing. This makes the link broken,
did I miss anything? I verified that I submitted the right link.

Thanks,
-Sri.

On Tue, Aug 21, 2012 at 5:41 AM, Diego Novillo <dnovillo@google.com> wrote:
> On 2012-08-20 22:41 , Sriraman Tallam wrote:
>>
>> Hi Gerald / Diego,
>>
>>      I have made all the mentioned changes.  I also shortened the
>> description like Diego mentioned by removing all the strings but kept
>> the caveats. I have not added a reference to the documentation because
>> i do not know what link to reference. The builtins are completely
>> documented in extend.texi.
>
>
> Referring to the user's manual is OK, I think.
>
>> +    <p>Caveat: If these built-in functions are called before any static
>> +    constructors are invoked, like during IFUNC initialization, then the
>> CPU
>> +    detection initialization must be explicity run using this newly
>> provided
>
>
> s/explicity/explicitly/
>
> Other than that, it looks fine to me.
>
>
> Diego.

Re: [wwwdocs] Document Runtime CPU detection builtins

[Gerald Pfeifer]

On Tue, 21 Aug 2012, Sriraman Tallam wrote:
> Committed after making the changes.
> 
> One small problem, I am not sure how to fix this:
> 
> The hyper link I referenced is :
> http://gcc.gnu.org/onlinedocs/gcc/X86-Built_002din-Functions.html#X86-Built_002din-Functions
> 
> whereas the committed changes.html is pointing to:
> http://gcc.gnu.org/onlinedocs/gcc/X86-Built-in-Functions.html#X86-Built-in-Functions
> 
> Please note that the "_002din" is missing. This makes the link broken,
> did I miss anything? I verified that I submitted the right link.

Based on changes I just committed and applied on gcc.gnu.org, finally
there won't be new files or anchors with "_002d" in their names, just
"-" instead.

The patch below, which I just committed, adjust the links.  All simpler
and nicer now. :-)

Gerald

Index: gcc-4.8/changes.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/gcc-4.8/changes.html,v
retrieving revision 1.124
diff -u -3 -p -r1.124 changes.html
--- gcc-4.8/changes.html	26 Nov 2013 03:21:07 -0000	1.124
+++ gcc-4.8/changes.html	2 Dec 2013 20:17:11 -0000
@@ -512,7 +512,7 @@ int i = A().f();  // error, f() requires
     added. For details, see the
     <a href="http://gcc.gnu.org/wiki/avr-gcc#Fixed-Point_Support">
       GCC wiki</a> and the
-    <a href="http://gcc.gnu.org/onlinedocs/gcc/Fixed_002dPoint.html">
+    <a href="http://gcc.gnu.org/onlinedocs/gcc/Fixed-Point.html">
       user manual</a>.  The support is not complete. 
   </li>
   <li>A new print modifier <code>%r</code> for register operands in inline
@@ -584,7 +584,7 @@ int i = A().f();  // error, f() requires
       <code>__builtin_cpu_is("westmere")</code> returns a positive integer if
       the run-time CPU is an Intel Core i7 Westmere processor.  Please refer
       to the <a
-      href="http://gcc.gnu.org/onlinedocs/gcc/X86-Built_002din-Functions.html#X86-Built_002din-Functions">
+      href="http://gcc.gnu.org/onlinedocs/gcc/X86-Built-in-Functions.html#X86-Built-in-Functions">
       user manual</a> for the list of valid CPU names recognized.</li>
       <li>A built-in function <code>__builtin_cpu_supports</code> has been
       added to detect if the run-time CPU supports a particular ISA feature.
@@ -592,7 +592,7 @@ int i = A().f();  // error, f() requires
       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.  Please refer to the <a
-      href="http://gcc.gnu.org/onlinedocs/gcc/X86-Built_002din-Functions.html#X86-Built_002din-Functions">
+      href="http://gcc.gnu.org/onlinedocs/gcc/X86-Built-in-Functions.html#X86-Built-in-Functions">
       user manual</a> for the list of valid ISA names recognized.</li>
     </ul>
     <p>Caveat: If these built-in functions are called before any static