[PATCH v2 0/3] doc: -falign-functions improvements

[PATCH v2 0/3] doc: -falign-functions improvements

[Palmer Dabbelt]

There were some recent discussions about the desired behavior of
-falign-functions, which is behaving as desired.  This improves the
documentation to make that explicit.

Change since v1 <20221007134901.5078-1-palmer@rivosinc.com>:

* New patch 2 and 3

[PATCH v2 1/3] doc: -falign-functions doesn't override the __attribute__((align(N)))

[Palmer Dabbelt]

I found this when reading the documentation for Kito's recent patch.
From the discussion it sounds like this is the desired behavior, so
let's document it.

gcc/doc/ChangeLog

	* invoke.texi (-falign-functions): Mention __align__
---
 gcc/doc/invoke.texi | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 2a9ea3455f6..8326a60dcf1 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -13136,7 +13136,9 @@ effective only in combination with @option{-fstrict-aliasing}.
 Align the start of functions to the next power-of-two greater than or
 equal to @var{n}, skipping up to @var{m}-1 bytes.  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.
+without crossing an @var{n}-byte alignment boundary.  This does not override
+functions that otherwise specify their own alignment constraints, such as via
+an alignment attribute.
 
 If @var{m} is not specified, it defaults to @var{n}.
 
-- 
2.34.1

[PATCH v2 2/3] doc: -falign-functions is ignored under -Os

[Palmer Dabbelt]

This is implicitly mentioned in the docs, but there were some questions
in a recent patch.  This makes it more exlicit that -falign-functions is
meant to be ignored under -Os.

gcc/doc/ChangeLog

	* invoke.texi (-falign-functions): Mention -Os
---
 gcc/doc/invoke.texi | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 8326a60dcf1..a24798d5029 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -13164,7 +13164,8 @@ equivalent and mean that functions are not aligned.
 If @var{n} is not specified or is zero, use a machine-dependent default.
 The maximum allowed @var{n} option value is 65536.
 
-Enabled at levels @option{-O2}, @option{-O3}.
+Enabled at levels @option{-O2}, @option{-O3}.  This has no behavior under under
+@option{-Os}.
 
 @item -flimit-function-alignment
 If this option is enabled, the compiler tries to avoid unnecessarily
-- 
2.34.1

[PATCH v2 3/3] doc: -falign-functions is ignored for cold/size-optimized functions

[Palmer Dabbelt]

gcc/doc/ChangeLog

	* invoke.texi (-falign-functions): Mention cold/size-optimized
	functions.
---
 gcc/doc/invoke.texi | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index a24798d5029..6af18ae9bfd 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -13138,7 +13138,8 @@ equal to @var{n}, skipping up to @var{m}-1 bytes.  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.  This does not override
 functions that otherwise specify their own alignment constraints, such as via
-an alignment attribute.
+an alignment attribute.  Functions that are optimized for size, for example
+cold functions, are not aligned.
 
 If @var{m} is not specified, it defaults to @var{n}.
 
-- 
2.34.1

Re: [PATCH v2 2/3] doc: -falign-functions is ignored under -Os

[Eric Gallager]

On Tue, Oct 11, 2022 at 5:03 PM Palmer Dabbelt <palmer@rivosinc.com> wrote:
>
> This is implicitly mentioned in the docs, but there were some questions
> in a recent patch.  This makes it more exlicit that -falign-functions is
> meant to be ignored under -Os.
>
> gcc/doc/ChangeLog
>
>         * invoke.texi (-falign-functions): Mention -Os

Since there's -Oz now, too, should that be mentioned as well?

> ---
>  gcc/doc/invoke.texi | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index 8326a60dcf1..a24798d5029 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -13164,7 +13164,8 @@ equivalent and mean that functions are not aligned.
>  If @var{n} is not specified or is zero, use a machine-dependent default.
>  The maximum allowed @var{n} option value is 65536.
>
> -Enabled at levels @option{-O2}, @option{-O3}.
> +Enabled at levels @option{-O2}, @option{-O3}.  This has no behavior under under
> +@option{-Os}.
>
>  @item -flimit-function-alignment
>  If this option is enabled, the compiler tries to avoid unnecessarily
> --
> 2.34.1
>

Re: [PATCH v2 2/3] doc: -falign-functions is ignored under -Os

[Jan Hubicka]

> This is implicitly mentioned in the docs, but there were some questions
> in a recent patch.  This makes it more exlicit that -falign-functions is
> meant to be ignored under -Os.
> 
> gcc/doc/ChangeLog
> 
> 	* invoke.texi (-falign-functions): Mention -Os
> ---
>  gcc/doc/invoke.texi | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index 8326a60dcf1..a24798d5029 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -13164,7 +13164,8 @@ equivalent and mean that functions are not aligned.
>  If @var{n} is not specified or is zero, use a machine-dependent default.
>  The maximum allowed @var{n} option value is 65536.
>  
> -Enabled at levels @option{-O2}, @option{-O3}.
> +Enabled at levels @option{-O2}, @option{-O3}.  This has no behavior under under
> +@option{-Os}.

Maybe we could instead say that the function alignment is included for
functions optimized for size.

This can happen by -Os, -Oz, cold attribute
or because we auto-detect function as cold (i.e. it unavoidably leads to
abort or is only called on such paths)

It would be also nice to mention that for other alignment options (align
jumps, loops and labels are ignored when given jump, loop or label is
optimized for size).

Honza
>  
>  @item -flimit-function-alignment
>  If this option is enabled, the compiler tries to avoid unnecessarily
> -- 
> 2.34.1
> 

Re: [PATCH v2 1/3] doc: -falign-functions doesn't override the __attribute__((align(N)))

[Richard Biener]

On Tue, Oct 11, 2022 at 11:02 PM Palmer Dabbelt <palmer@rivosinc.com> wrote:
>
> I found this when reading the documentation for Kito's recent patch.
> From the discussion it sounds like this is the desired behavior, so
> let's document it.

OK.

> gcc/doc/ChangeLog
>
>         * invoke.texi (-falign-functions): Mention __align__
> ---
>  gcc/doc/invoke.texi | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index 2a9ea3455f6..8326a60dcf1 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -13136,7 +13136,9 @@ effective only in combination with @option{-fstrict-aliasing}.
>  Align the start of functions to the next power-of-two greater than or
>  equal to @var{n}, skipping up to @var{m}-1 bytes.  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.
> +without crossing an @var{n}-byte alignment boundary.  This does not override
> +functions that otherwise specify their own alignment constraints, such as via
> +an alignment attribute.
>
>  If @var{m} is not specified, it defaults to @var{n}.
>
> --
> 2.34.1
>

Re: [PATCH v2 3/3] doc: -falign-functions is ignored for cold/size-optimized functions

[Richard Biener]

On Tue, Oct 11, 2022 at 11:02 PM Palmer Dabbelt <palmer@rivosinc.com> wrote:
>
> gcc/doc/ChangeLog

OK.

>         * invoke.texi (-falign-functions): Mention cold/size-optimized
>         functions.
> ---
>  gcc/doc/invoke.texi | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index a24798d5029..6af18ae9bfd 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -13138,7 +13138,8 @@ equal to @var{n}, skipping up to @var{m}-1 bytes.  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.  This does not override
>  functions that otherwise specify their own alignment constraints, such as via
> -an alignment attribute.
> +an alignment attribute.  Functions that are optimized for size, for example
> +cold functions, are not aligned.
>
>  If @var{m} is not specified, it defaults to @var{n}.
>
> --
> 2.34.1
>