[PATCH 3/3] Extend -falign-FOO=N to N[,M[,N2[,M2]]]

[Sandra Loosemore]

On 04/17/2017 09:57 AM, Denys Vlasenko wrote:
> Index: gcc/doc/invoke.texi
> ===================================================================
> --- gcc/doc/invoke.texi	(revision 246948)
> +++ gcc/doc/invoke.texi	(working copy)
> @@ -351,9 +351,11 @@ Objective-C and Objective-C++ Dialects}.
>
>   @item Optimization Options
>   @xref{Optimize Options,,Options that Control Optimization}.
> -@gccoptlist{-faggressive-loop-optimizations  -falign-functions[=@var{n}] @gol
> --falign-jumps[=@var{n}] @gol
> --falign-labels[=@var{n}]  -falign-loops[=@var{n}] @gol
> +@gccoptlist{-faggressive-loop-optimizations @gol
> +-falign-functions[=@var{n}[,@var{m},[@var{n2}[,@var{m2}]]]] @gol
> +-falign-jumps[=@var{n}[,@var{m},[@var{n2}[,@var{m2}]]]] @gol
> +-falign-labels[=@var{n}[,@var{m},[@var{n2}[,@var{m2}]]]] @gol
> +-falign-loops[=@var{n}[,@var{m},[@var{n2}[,@var{m2}]]]] @gol
>   -fassociative-math  -fauto-profile  -fauto-profile[=@var{path}] @gol
>   -fauto-inc-dec  -fbranch-probabilities @gol
>   -fbranch-target-load-optimize  -fbranch-target-load-optimize2 @gol
> @@ -8672,19 +8674,36 @@ The @option{-fstrict-overflow} option is enabled a
>
>   @item -falign-functions
>   @itemx -falign-functions=@var{n}
> +@itemx -falign-functions=@var{n},@var{m}
> +@itemx -falign-functions=@var{n},@var{m},@var{n2}
> +@itemx -falign-functions=@var{n},@var{m},@var{n2},@var{m2}
>   @opindex falign-functions
>   Align the start of functions to the next power-of-two greater than
> -@var{n}, skipping up to @var{n} bytes.  For instance,
> -@option{-falign-functions=32} aligns functions to the next 32-byte
> -boundary, but @option{-falign-functions=24} aligns to the next
> -32-byte boundary only if this can be done by skipping 23 bytes or less.
> +@var{n}, skipping up to @var{m}-1 bytes.  Such alignment ensures that
> +after branch, at least @var{m} bytes can be fetched by the CPU
> +without crossing specified alignment boundary.

This last sentence doesn't make much sense to me.  How about something like

This ensures that at least the first @var{m} bytes of the function can 
be fetched by the CPU without crossing an @var{n}-byte alignment boundary.

> -@option{-fno-align-functions} and @option{-falign-functions=1} are
> -equivalent and mean that functions are not aligned.
> +If @var{m} is not specified, it defaults to @var{n}.
> +Same for @var{m2} and @var{n2}.

You haven't said what m2 and n2 are yet.  The last sentence should be 
moved to the end of this paragraph instead.

> +The second pair of @var{n2},@var{m2} values allows to have a secondary
> +alignment: @option{-falign-functions=64,7,32,3} aligns to the next
> +64-byte boundary if this can be done by skipping 6 bytes or less,
> +otherwise aligns to the next 32-byte boundary if this can be done
> +by skipping 2 bytes or less.

Also please
s/allows to have/allows you to specify/

> @@ -8697,12 +8716,13 @@ skip more bytes than the size of the function.
>
>   @item -falign-labels
>   @itemx -falign-labels=@var{n}
> +@itemx -falign-labels=@var{n},@var{m}
> +@itemx -falign-labels=@var{n},@var{m},@var{n2}
> +@itemx -falign-labels=@var{n},@var{m},@var{n2},@var{m2}
>   @opindex falign-labels
> -Align all branch targets to a power-of-two boundary, skipping up to
> -@var{n} bytes like @option{-falign-functions}.  This option can easily
> -make code slower, because it must insert dummy operations for when the
> -branch target is reached in the usual flow of the code.
> +Align all branch targets to a power-of-two boundary.
>
> +Parameters of this option are analogous to @option{-falign-functions} option.

s/to @option/to the @option/

Here and for -falign-loops and -falign-jumps too.

-Sandra