[Patch] Document __builtin_extend_pointer

[Patch] Document __builtin_extend_pointer

[Steve Ellcey]

While working on PR 83335 I proposed a change to a test case that
used __builtin_extend_pointer and Richared Earnshaw pointed out
that this builtin is not documented.  Since I could not find any
other (reasonable) way to generate an extended address in inline
assembly other than this builtin I would like to document it for
use.

Here is a proposed patch, the one problem I found was the return
type of the builtin.  I don't know how to describe it other than
Pmode, but that is not a user visible type.

See https://gcc.gnu.org/ml/gcc-patches/2018-02/msg01051.html
for my PR 83335 patch and follow up comments.

Should I go ahead and add this documentation?


2018-02-20  Steve Ellcey  <sellcey@cavium.com>

	* doc/extend.texi (__builtin_extend_pointer): Document builtin.


diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index d38840e..94e47aa 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -11042,6 +11042,7 @@ the built-in function returns -1.
 @findex __builtin_alloca_with_align
 @findex __builtin_alloca_with_align_and_max
 @findex __builtin_call_with_static_chain
+@findex __builtin_extend_pointer
 @findex __builtin_fpclassify
 @findex __builtin_isfinite
 @findex __builtin_isnormal
@@ -12419,6 +12420,15 @@ Similar to @code{__builtin_bswap32}, except the argument and return types
 are 64 bit.
 @end deftypefn
 
+@deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x)
+On targets where the user visible pointer size is different than the size
+of an actual hardware address this function returns the extended user
+pointer.  Targets where this is true included ILP32 mode on x86_64 or
+Aarch64.  This function is mainly useful when writing inline assembly
+code.
+@var{addr}
+@end deftypefn
+
 @node Target Builtins
 @section Built-in Functions Specific to Particular Target Machines
 

Re: [Patch] Document __builtin_extend_pointer

[Jeff Law]

On 02/20/2018 10:33 AM, Steve Ellcey wrote:
> While working on PR 83335 I proposed a change to a test case that
> used __builtin_extend_pointer and Richared Earnshaw pointed out
> that this builtin is not documented.  Since I could not find any
> other (reasonable) way to generate an extended address in inline
> assembly other than this builtin I would like to document it for
> use.
> 
> Here is a proposed patch, the one problem I found was the return
> type of the builtin.  I don't know how to describe it other than
> Pmode, but that is not a user visible type.
> 
> See https://gcc.gnu.org/ml/gcc-patches/2018-02/msg01051.html
> for my PR 83335 patch and follow up comments.
> 
> Should I go ahead and add this documentation?
> 
> 
> 2018-02-20  Steve Ellcey  <sellcey@cavium.com>
> 
> 	* doc/extend.texi (__builtin_extend_pointer): Document builtin.
I'd change "is different than" to "is smaller than".  It's kind of
implied in the name, but I think it's slightly clearer.

With that.  OK.

jeff

ps.  You might ping Richard Sandiford on the actual patch that fixes
83335.  It looks like it's been waiting for over a month.

Re: [Patch] Document __builtin_extend_pointer

[Tom de Vries]

On 02/20/2018 06:33 PM, Steve Ellcey wrote:
> +@deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x)
> +On targets where the user visible pointer size is different than the size
> +of an actual hardware address this function returns the extended user
> +pointer.  Targets where this is true included ILP32 mode on x86_64 or
> +Aarch64.  This function is mainly useful when writing inline assembly
> +code.
> +@var{addr}
> +@end deftypefn

Hi,

I think the "@var{addr}" bit is a pasto.

Thanks,
- Tom

Re: [Patch] Document __builtin_extend_pointer

[Jeff Law]

On 03/20/2018 06:08 AM, Tom de Vries wrote:
> On 02/20/2018 06:33 PM, Steve Ellcey wrote:
>> +@deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x)
>> +On targets where the user visible pointer size is different than the
>> size
>> +of an actual hardware address this function returns the extended user
>> +pointer.  Targets where this is true included ILP32 mode on x86_64 or
>> +Aarch64.  This function is mainly useful when writing inline assembly
>> +code.
>> +@var{addr}
>> +@end deftypefn
> 
> Hi,
> 
> I think the "@var{addr}" bit is a pasto.
Agreed. And a patch to remove the pasto is pre-approved.

jeff