Document __builtin_extend_pointer

Message ID 1519147981.6296.18.camel@cavium.com
State New
Headers show
Series
  • Document __builtin_extend_pointer
Related show

Commit Message

Steve Ellcey Feb. 20, 2018, 5:33 p.m.
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.

Comments

Jeff Law Feb. 22, 2018, 5:04 a.m. | #1
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.
Tom de Vries March 20, 2018, 12:08 p.m. | #2
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
Jeff Law March 20, 2018, 8:57 p.m. | #3
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

Patch

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