[PATCH] docs: update symver attribute description

[PATCH] docs: update symver attribute description

[Martin Liška]

This improves documentation as noticed by Jakub.

Ready for master?
Thanks,
Martin

gcc/ChangeLog:

	* doc/extend.texi: Be more precise in documentation
	of symver attribute.
---
 gcc/doc/extend.texi | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index e28e1860990..61d9a684b24 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -3848,7 +3848,8 @@ foo_v1 (void)
 Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
 output. 
 
-One can also define multiple version for a given symbol.
+One can also define multiple version for a given symbol
+(starting from binutils 2.35).
 
 @smallexample
 __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
@@ -3863,8 +3864,8 @@ int symver_bar_v1 (void)
 @}
 @end smallexample
 
-This example creates an alias of @code{foo_v1} with symbol name
-@code{symver_foo_v1} which will be version @code{VERS_2} of @code{foo}.
+This example creates a symbol name @code{symver_foo_v1}
+which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
 
 Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
 addition to creating a symbol version (as if
-- 
2.31.1

Re: [PATCH] docs: update symver attribute description

[Jakub Jelinek]

On Mon, Apr 12, 2021 at 01:44:54PM +0200, Martin Liška wrote:
> This improves documentation as noticed by Jakub.
> 
> Ready for master?
> Thanks,
> Martin
> 
> gcc/ChangeLog:
> 
> 	* doc/extend.texi: Be more precise in documentation
> 	of symver attribute.

Ok, but I'd prefer to see the old example with the old description in the
documentation too, so that people who don't have gcc configured against
binutils 2.35 or newer know what to do instead.

> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -3848,7 +3848,8 @@ foo_v1 (void)
>  Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
>  output. 
>  
> -One can also define multiple version for a given symbol.
> +One can also define multiple version for a given symbol
> +(starting from binutils 2.35).
>  
>  @smallexample
>  __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
> @@ -3863,8 +3864,8 @@ int symver_bar_v1 (void)
>  @}
>  @end smallexample
>  
> -This example creates an alias of @code{foo_v1} with symbol name
> -@code{symver_foo_v1} which will be version @code{VERS_2} of @code{foo}.
> +This example creates a symbol name @code{symver_foo_v1}
> +which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
>  
>  Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
>  addition to creating a symbol version (as if
> -- 
> 2.31.1

	Jakub

Re: [PATCH] docs: update symver attribute description

[Martin Liška]

On 4/12/21 1:50 PM, Jakub Jelinek wrote:
> On Mon, Apr 12, 2021 at 01:44:54PM +0200, Martin Liška wrote:
>> This improves documentation as noticed by Jakub.
>>
>> Ready for master?
>> Thanks,
>> Martin
>>
>> gcc/ChangeLog:
>>
>> 	* doc/extend.texi: Be more precise in documentation
>> 	of symver attribute.
> 
> Ok, but I'd prefer to see the old example with the old description in the
> documentation too

The old syntax with the alias is quite ugly..

> so that people who don't have gcc configured against
> binutils 2.35 or newer know what to do instead.

... and symver support for older binutils releases is fragile due to:

Changes in 2.35:

* Extend .symver directive to update visibility of the original symbol
  and assign one original symbol to different versioned symbols.

Martin

> 
>> --- a/gcc/doc/extend.texi
>> +++ b/gcc/doc/extend.texi
>> @@ -3848,7 +3848,8 @@ foo_v1 (void)
>>  Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
>>  output. 
>>  
>> -One can also define multiple version for a given symbol.
>> +One can also define multiple version for a given symbol
>> +(starting from binutils 2.35).
>>  
>>  @smallexample
>>  __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
>> @@ -3863,8 +3864,8 @@ int symver_bar_v1 (void)
>>  @}
>>  @end smallexample
>>  
>> -This example creates an alias of @code{foo_v1} with symbol name
>> -@code{symver_foo_v1} which will be version @code{VERS_2} of @code{foo}.
>> +This example creates a symbol name @code{symver_foo_v1}
>> +which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
>>  
>>  Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
>>  addition to creating a symbol version (as if
>> -- 
>> 2.31.1
> 
> 	Jakub
> 

Re: [PATCH] docs: update symver attribute description

[Jakub Jelinek]

On Mon, Apr 12, 2021 at 02:15:16PM +0200, Martin Liška wrote:
> The old syntax with the alias is quite ugly..

Not that much.  And users have no other option (besides inline asm
but that doesn't work with LTO well).

> > so that people who don't have gcc configured against
> > binutils 2.35 or newer know what to do instead.
> 
> ... and symver support for older binutils releases is fragile due to:
> 
> Changes in 2.35:
> 
> * Extend .symver directive to update visibility of the original symbol
>   and assign one original symbol to different versioned symbols.

That is a change that allows the new syntax.
The old syntax (on the as/ld side) have worked for the last 20+ years
just fine.

	Jakub

Re: [PATCH] docs: update symver attribute description

[Martin Liška]

[-- Attachment #1: Type: text/plain, Size: 825 bytes --]

On 4/12/21 2:18 PM, Jakub Jelinek wrote:
> On Mon, Apr 12, 2021 at 02:15:16PM +0200, Martin Liška wrote:
>> The old syntax with the alias is quite ugly..
> 
> Not that much.  And users have no other option (besides inline asm
> but that doesn't work with LTO well).
> 
>>> so that people who don't have gcc configured against
>>> binutils 2.35 or newer know what to do instead.
>>
>> ... and symver support for older binutils releases is fragile due to:
>>
>> Changes in 2.35:
>>
>> * Extend .symver directive to update visibility of the original symbol
>>   and assign one original symbol to different versioned symbols.
> 
> That is a change that allows the new syntax.
> The old syntax (on the as/ld side) have worked for the last 20+ years
> just fine.
> 
> 	Jakub
> 

All right, so something like this?

Thanks,
Martin

[-- Attachment #2: 0001-docs-update-symver-attribute-description.patch --]
[-- Type: text/x-patch, Size: 1730 bytes --]

From 750b715225d480fcb74e765623d54acc42ac25e3 Mon Sep 17 00:00:00 2001
From: Martin Liska <mliska@suse.cz>
Date: Mon, 12 Apr 2021 13:42:33 +0200
Subject: [PATCH] docs: update symver attribute description

gcc/ChangeLog:

	* doc/extend.texi: Be more precise in documentation
	of symver attribute.
---
 gcc/doc/extend.texi | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index e28e1860990..75e4a43a8c5 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -3848,23 +3848,27 @@ foo_v1 (void)
 Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
 output. 
 
-One can also define multiple version for a given symbol.
+One can also define multiple version for a given symbol
+(starting from binutils 2.35).
 
 @smallexample
 __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
 int symver_foo_v1 (void)
 @{
 @}
-
-__attribute__ ((__symver__ ("bar@@VERS_2")))
-__attribute__ ((__symver__ ("bar@@VERS_3")))
-int symver_bar_v1 (void)
-@{
-@}
 @end smallexample
 
-This example creates an alias of @code{foo_v1} with symbol name
-@code{symver_foo_v1} which will be version @code{VERS_2} of @code{foo}.
+This example creates a symbol name @code{symver_foo_v1}
+which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
+
+If you have an older release of binutils release, then symbol alias needs to
+be used:
+
+@smallexample
+__attribute__ ((__symver__ ("foo@@VERS_2")))
+__attribute__ ((alias ("foo_v1")))
+int symver_foo_v1 (void);
+@end smallexample
 
 Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
 addition to creating a symbol version (as if
-- 
2.31.1

Re: [PATCH] docs: update symver attribute description

[Jakub Jelinek]

On Mon, Apr 12, 2021 at 02:32:35PM +0200, Martin Liška wrote:
> +If you have an older release of binutils release, then symbol alias needs to

s/binutils release/binutils/

> +be used:
> +
> +@smallexample
> +__attribute__ ((__symver__ ("foo@@VERS_2")))
> +__attribute__ ((alias ("foo_v1")))
> +int symver_foo_v1 (void);
> +@end smallexample

The example should show two versions of foo rather than just one, otherwise
it will confuse users.  For symbol versions which just a single symbol they
don't need any aliases...

	Jakub

Re: [PATCH] docs: update symver attribute description

[Martin Liška]

[-- Attachment #1: Type: text/plain, Size: 663 bytes --]

On 4/12/21 2:45 PM, Jakub Jelinek wrote:
> On Mon, Apr 12, 2021 at 02:32:35PM +0200, Martin Liška wrote:
>> +If you have an older release of binutils release, then symbol alias needs to
> 
> s/binutils release/binutils/

Fixed.

> 
>> +be used:
>> +
>> +@smallexample
>> +__attribute__ ((__symver__ ("foo@@VERS_2")))
>> +__attribute__ ((alias ("foo_v1")))
>> +int symver_foo_v1 (void);
>> +@end smallexample
> 
> The example should show two versions of foo rather than just one, otherwise
> it will confuse users.  For symbol versions which just a single symbol they
> don't need any aliases...

Very good point! Is it fine now?

Thanks,
Martin

> 
> 	Jakub
> 


[-- Attachment #2: 0001-docs-update-symver-attribute-description.patch --]
[-- Type: text/x-patch, Size: 1813 bytes --]

From 6dda0ec10a1b0c60e6e9afe7fc45370d0132b5e3 Mon Sep 17 00:00:00 2001
From: Martin Liska <mliska@suse.cz>
Date: Mon, 12 Apr 2021 13:42:33 +0200
Subject: [PATCH] docs: update symver attribute description

gcc/ChangeLog:

	* doc/extend.texi: Be more precise in documentation
	of symver attribute.
---
 gcc/doc/extend.texi | 28 +++++++++++++++++++---------
 1 file changed, 19 insertions(+), 9 deletions(-)

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index e28e1860990..6542ada6583 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -3848,23 +3848,33 @@ foo_v1 (void)
 Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
 output. 
 
-One can also define multiple version for a given symbol.
+One can also define multiple version for a given symbol
+(starting from binutils 2.35).
 
 @smallexample
 __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
 int symver_foo_v1 (void)
 @{
 @}
-
-__attribute__ ((__symver__ ("bar@@VERS_2")))
-__attribute__ ((__symver__ ("bar@@VERS_3")))
-int symver_bar_v1 (void)
-@{
-@}
 @end smallexample
 
-This example creates an alias of @code{foo_v1} with symbol name
-@code{symver_foo_v1} which will be version @code{VERS_2} of @code{foo}.
+This example creates a symbol name @code{symver_foo_v1}
+which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
+
+If you have an older release of binutils, then symbol alias needs to
+be used:
+
+@smallexample
+__attribute__ ((__symver__ ("foo@@VERS_2")))
+int foo_v1 (void)
+{
+  return 0;
+}
+
+__attribute__ ((__symver__ ("foo@VERS_3")))
+__attribute__ ((alias ("foo_v1")))
+int symver_foo_v1 (void);
+@end smallexample
 
 Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
 addition to creating a symbol version (as if
-- 
2.31.1

Re: [PATCH] docs: update symver attribute description

[Jakub Jelinek]

On Mon, Apr 12, 2021 at 03:24:00PM +0200, Martin Liška wrote:
> On 4/12/21 2:45 PM, Jakub Jelinek wrote:
> > On Mon, Apr 12, 2021 at 02:32:35PM +0200, Martin Liška wrote:
> >> +If you have an older release of binutils release, then symbol alias needs to
> > 
> > s/binutils release/binutils/
> 
> Fixed.
> 
> > 
> >> +be used:
> >> +
> >> +@smallexample
> >> +__attribute__ ((__symver__ ("foo@@VERS_2")))
> >> +__attribute__ ((alias ("foo_v1")))
> >> +int symver_foo_v1 (void);
> >> +@end smallexample
> > 
> > The example should show two versions of foo rather than just one, otherwise
> > it will confuse users.  For symbol versions which just a single symbol they
> > don't need any aliases...
> 
> Very good point! Is it fine now?

Ok, thanks.

> >From 6dda0ec10a1b0c60e6e9afe7fc45370d0132b5e3 Mon Sep 17 00:00:00 2001
> From: Martin Liska <mliska@suse.cz>
> Date: Mon, 12 Apr 2021 13:42:33 +0200
> Subject: [PATCH] docs: update symver attribute description
> 
> gcc/ChangeLog:
> 
> 	* doc/extend.texi: Be more precise in documentation
> 	of symver attribute.
> ---
>  gcc/doc/extend.texi | 28 +++++++++++++++++++---------
>  1 file changed, 19 insertions(+), 9 deletions(-)
> 
> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index e28e1860990..6542ada6583 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -3848,23 +3848,33 @@ foo_v1 (void)
>  Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
>  output. 
>  
> -One can also define multiple version for a given symbol.
> +One can also define multiple version for a given symbol
> +(starting from binutils 2.35).
>  
>  @smallexample
>  __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
>  int symver_foo_v1 (void)
>  @{
>  @}
> -
> -__attribute__ ((__symver__ ("bar@@VERS_2")))
> -__attribute__ ((__symver__ ("bar@@VERS_3")))
> -int symver_bar_v1 (void)
> -@{
> -@}
>  @end smallexample
>  
> -This example creates an alias of @code{foo_v1} with symbol name
> -@code{symver_foo_v1} which will be version @code{VERS_2} of @code{foo}.
> +This example creates a symbol name @code{symver_foo_v1}
> +which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
> +
> +If you have an older release of binutils, then symbol alias needs to
> +be used:
> +
> +@smallexample
> +__attribute__ ((__symver__ ("foo@@VERS_2")))
> +int foo_v1 (void)
> +{
> +  return 0;
> +}
> +
> +__attribute__ ((__symver__ ("foo@VERS_3")))
> +__attribute__ ((alias ("foo_v1")))
> +int symver_foo_v1 (void);
> +@end smallexample
>  
>  Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
>  addition to creating a symbol version (as if
> -- 
> 2.31.1
> 


	Jakub

Re: [PATCH] docs: update symver attribute description

[H.J. Lu]

On Mon, Apr 12, 2021 at 5:54 AM Martin Liška <mliska@suse.cz> wrote:
>
> On 4/12/21 2:18 PM, Jakub Jelinek wrote:
> > On Mon, Apr 12, 2021 at 02:15:16PM +0200, Martin Liška wrote:
> >> The old syntax with the alias is quite ugly..
> >
> > Not that much.  And users have no other option (besides inline asm
> > but that doesn't work with LTO well).
> >
> >>> so that people who don't have gcc configured against
> >>> binutils 2.35 or newer know what to do instead.
> >>
> >> ... and symver support for older binutils releases is fragile due to:
> >>
> >> Changes in 2.35:
> >>
> >> * Extend .symver directive to update visibility of the original symbol
> >>   and assign one original symbol to different versioned symbols.
> >
> > That is a change that allows the new syntax.
> > The old syntax (on the as/ld side) have worked for the last 20+ years
> > just fine.
> >
> >       Jakub
> >
>
> All right, so something like this?
>
> Thanks,
> Martin

GCC failed to bootstrap:

/export/gnu/import/git/sources/gcc/gcc/doc/extend.texi:3870: misplaced {
/export/gnu/import/git/sources/gcc/gcc/doc/extend.texi:3872: misplaced }
/export/gnu/import/git/sources/gcc/gcc/doc/extend.texi:3874: unknown
command `VERS'
make[2]: *** [Makefile:3396: doc/gcc.info] Error 1


-- 
H.J.

Re: [PATCH] docs: update symver attribute description

[Martin Liška]

On 4/12/21 3:50 PM, H.J. Lu wrote:
> GCC failed to bootstrap:
> 
> /export/gnu/import/git/sources/gcc/gcc/doc/extend.texi:3870: misplaced {
> /export/gnu/import/git/sources/gcc/gcc/doc/extend.texi:3872: misplaced }
> /export/gnu/import/git/sources/gcc/gcc/doc/extend.texi:3874: unknown
> command `VERS'
> make[2]: *** [Makefile:3396: doc/gcc.info] Error 1

Whoops. Sorry for that, should be fixed now.

Martin