Re: [PATCH] Update -ffunction/data-sections documentation

[Sandra Loosemore <sandra at codesourcery dot com>]

On 10/15/2017 11:59 PM, Sebastian Huber wrote:
> gcc/
> 	* invoke.texi (ffunction-sections and fdata-sections): Update.
> ---
>   gcc/doc/invoke.texi | 32 ++++++++++++++++++++------------
>   1 file changed, 20 insertions(+), 12 deletions(-)
>
> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index 4e7dfb33c31..7bc051a1fc5 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -9712,18 +9712,26 @@ file if the target supports arbitrary sections.  The name of the
>   function or the name of the data item determines the section's name
>   in the output file.
>
> -Use these options on systems where the linker can perform optimizations
> -to improve locality of reference in the instruction space.  Most systems
> -using the ELF object format and SPARC processors running Solaris 2 have
> -linkers with such optimizations.  AIX may have these optimizations in
> -the future.
> -
> -Only use these options when there are significant benefits from doing
> -so.  When you specify these options, the assembler and linker
> -create larger object and executable files and are also slower.
> -You cannot use @command{gprof} on all systems if you
> -specify this option, and you may have problems with debugging if
> -you specify both this option and @option{-g}.
> +Use these options on systems where the linker can perform optimizations to
> +improve locality of reference in the instruction space.  Most systems using the
> +ELF object format have linkers with such optimizations.  On AIX, the linker
> +rearranges sections (CSECTs) based on the call graph.  The performance impact
> +varies.
> +
> +Together with a linker garbage collection (linker @option{--gc-sections}
> +option) these options may lead to smaller statically linked executables (after

statically-linked

> +stripping).
> +
> +On ELF/DWARF systems these options do not degenerate the quality of the debug
> +information.  There could be issues with other object files/debug info formats.
> +
> +Only use these options when there are significant benefits from doing so.  When
> +you specify these options, the assembler and linker create larger object and
> +executable files and are also slower.  These options affect code generation.
> +They prevent optimzations by the compiler and assembler using relative

optimizations

> +locations inside a translation unit since the locations are unknown until
> +link-time.

link time

> +An examples for such an optimization is a call to short call
> +relaxation.

I'd rewrite the last sentence as

An example of such an optimization is relaxing calls to short call 
instructions.

I think the patch is OK with those nits fixed.

-Sandra