Szabolcs Nagy <szabolcs.n...@arm.com> writes:
> The expected semantics and valid usage of __builtin_return_address is
> not clear since it exposes implementation internals that are normally
> not meaningful to portable c code.
>
> This documentation change tries to clarify the semantics in case the
> return address is stored in a mangled form. This affects AArch64 when
> pointer authentication is used for the return address signing (i.e.
> -mbranch-protection=pac-ret).
>
> gcc/ChangeLog:
>
> 2020-06-04  Szabolcs Nagy  <szabolcs.n...@arm.com>
>
>       * doc/extend.texi: Update the text for  __builtin_return_address.
LGTM apart from minor nits:

> ---
>  gcc/doc/extend.texi | 16 ++++++++++++++--
>  1 file changed, 14 insertions(+), 2 deletions(-)
>
> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index cced19d2018..0fd32a22599 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -11151,18 +11151,30 @@ The @var{level} argument must be a constant integer.
>  
>  On some machines it may be impossible to determine the return address of
>  any function other than the current one; in such cases, or when the top
> -of the stack has been reached, this function returns @code{0} or a
> -random value.  In addition, @code{__builtin_frame_address} may be used
> +of the stack has been reached, this function returns an unspecified
> +value.  In addition, @code{__builtin_frame_address} may be used
>  to determine if the top of the stack has been reached.
>  
>  Additional post-processing of the returned value may be needed, see
>  @code{__builtin_extract_return_addr}.
>  
> +The stored representation of the return address in memory may be different
> +from the address returned by @code{__builtin_return_address}.  For example

IMO reads better with a comma after “For example”.

> +on AArch64 the stored address may be mangled with return address signing.

Maybe add “whereas the address returned by @code{__builtin_return_address}
is not“.

> +
>  Calling this function with a nonzero argument can have unpredictable
>  effects, including crashing the calling program.  As a result, calls
>  that are considered unsafe are diagnosed when the @option{-Wframe-address}
>  option is in effect.  Such calls should only be made in debugging
>  situations.
> +
> +On targets where code addresses are representable as @code{void *},
> +@smallexample
> +void *addr = __builtin_extract_return_addr (__builtin_return_address (0))

Might as well add the ”;” too

> +@end smallexample
> +gives the code address where the current function would return.  For example

Same comment about the comma.

> +such address may be used with @code{dladdr} or other interfaces that work

“such an address”

> +with code addresses.
>  @end deftypefn
>  
>  @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void 
> *@var{addr})

OK for trunk and branches with those changes.

Thanks,
Richard

Reply via email to