Re: [PATCH][RFC] middle-end/106811 - document GENERIC/GIMPLE undefined behavior

[Richard Sandiford <richard.sandiford@arm.com>]

Thanks for doing this.  Question below...

Richard Biener via Gcc-patches <gcc-patches@gcc.gnu.org> writes:
> The following attempts to provide a set of conditions GENERIC/GIMPLE
> considers invoking undefined behavior, leaning on the C standards
> Annex J, as to provide portability guidance to language frontend
> developers.
>
> I've both tried to remember cases we exploit undefined behavior
> and went over C2x Annex J to catch more stuff.  I'd be grateful
> if people could point out obvious omissions or cases where the
> wording isn't clear.  I plan to check/amend the individual operator
> documentations as well, but not everything fits there.
>
> I've put this into generic.texi because it applies to GENERIC as
> the frontend interface.  All constraints apply to GIMPLE as well.
> I plan to add a section to gimple.texi as to how to deal with
> undefined behavior.
>
> As said, every comment is welcome.
>
> For testing I've built doc and inspected the resulting pdf.
>
> 	PR middle-end/106811
> 	* doc/generic.texi: Add portability section with
> 	subsection on undefined behavior.
> ---
>  gcc/doc/generic.texi | 87 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 87 insertions(+)
>
> diff --git a/gcc/doc/generic.texi b/gcc/doc/generic.texi
> index 6534c354b7a..0969f881146 100644
> --- a/gcc/doc/generic.texi
> +++ b/gcc/doc/generic.texi
> @@ -43,6 +43,7 @@ seems inelegant.
>  * Functions::           	Function bodies, linkage, and other aspects.
>  * Language-dependent trees::    Topics and trees specific to language front ends.
>  * C and C++ Trees::     	Trees specific to C and C++.
> +* Portability issues::          Portability summary for languages.
>  @end menu
>  
>  @c ---------------------------------------------------------------------
> @@ -3733,3 +3734,89 @@ In either case, the expression is void.
>  
>  
>  @end table
> +
> +
> +@node Portability issues
> +@section Portability issues
> +
> +This section summarizes portability issues when translating source languages
> +to GENERIC.  Everything written here also applies to GIMPLE.  This section
> +heavily relies on interpretation according to the C standard.
> +
> +@menu
> +* Undefined behavior::          Undefined behavior.
> +@end menu
> +
> +@node Undefined behavior
> +@subsection Undefined behavior
> +
> +The following is a list of circumstances that invoke undefined behavior.
> +
> +@itemize @bullet
> +@item
> +When the result of negation, addition, subtraction or division of two signed
> +integers or signed integer vectors not subject to @option{-fwrapv} cannot be
> +represented in the type.

Couldn't tell: is the omission of multiplication deliberate?

Richard

> +
> +@item
> +The value of the second operand of any of the division or modulo operators
> +is zero.
> +
> +@item
> +When incrementing or decrementing a pointer not subject to
> +@option{-fwrapv-pointer} wraps around zero.
> +
> +@item
> +An expression is shifted by a negative number or by an amount greater
> +than or equal to the width of the shifted operand.
> +
> +@item
> +Pointers that do not point to the same object are compared using
> +relational operators.
> +
> +@item
> +An object which has been modified is accessed through a restrict-qualified
> +pointer and another pointer that are not both based on the same object.
> +
> +@item
> +The @} that terminates a function is reached, and the value of the function
> +call is used by the caller.
> +
> +@item
> +When program execution reaches __builtin_unreachable.
> +
> +@item
> +When an object has its stored value accessed by an lvalue that
> +does not have one of the following types:
> +@itemize @minus
> +@item
> +a (qualified) type compatible with the effective type of the object
> +@item
> +a type that is the (qualified) signed or unsigned type corresponding to
> +the effective type of the object
> +@item
> +a character type, a ref-all qualified type or a type subject to
> +@option{-fno-strict-aliasing}
> +@item
> +a pointer to void with the same level of indirection as the accessed
> +pointer object
> +@end itemize
> +
> +@item
> +Addition or subtraction of a pointer into, or just beyond, an object
> +and an integer type produces a result that does not point into, or just
> +beyond when not dereferenced, the same object.
> +
> +@item
> +Pointers that do not point into, or just beyond, the same object are
> +subtracted.
> +
> +@item
> +When a pointer not pointing to actual storage is dereferenced.
> +
> +@item
> +An array subscript is out of range, even if an object is apparently accessible
> +with the given subscript (as in the lvalue expression a[1][7] given the
> +declaration int a[4][5]).
> +
> +@end itemize