[PATCH v4 22/22] gas doc: update the documentation for OAv1 and OAv2

[Jan Beulich]

On 03.07.2025 18:27, Matthieu Longo wrote:
> - amend the existing documentation on OAv1.
> - add a new section for OAv2 in the Object Attributes chapter.
> - add entries for the new directives.

This shouldn't come as a separate patch imo; at least the parts about new directives
would better be folded into wherever they're introduced.

Jan

> --- a/gas/doc/as.texi
> +++ b/gas/doc/as.texi
> @@ -4563,6 +4563,7 @@ Some machine configurations provide additional directives.
>  * Func::                        @code{.func}
>  * Global::                      @code{.global @var{symbol}}, @code{.globl @var{symbol}}
>  @ifset ELF
> +* Gnu_subsection::              @code{.gnu_subsection @var{name}, @var{comprehension}, @var{encoding}}
>  * Gnu_attribute::               @code{.gnu_attribute @var{tag},@var{value}}
>  * Hidden::                      @code{.hidden @var{names}}
>  @end ifset
> @@ -5702,6 +5703,10 @@ partial programs.  You may need the HPPA-only @code{.EXPORT} directive as well.
>  @end ifset
>  
>  @ifset ELF
> +@node Gnu_subsection
> +@section @code{.gnu_subsection @var{name}, @var{comprehension}, @var{encoding}}
> +Record a @sc{gnu} object attribute subsection for this file.  @xref{Object Attributes}
> +
>  @node Gnu_attribute
>  @section @code{.gnu_attribute @var{tag},@var{value}}
>  Record a @sc{gnu} object attribute for this file.  @xref{Object Attributes}.
> @@ -7911,6 +7916,25 @@ This information is useful during and after linking.  At link time,
>  time, tools like @command{gdb} can use it to process the linked file
>  correctly.
>  
> +Two versions of object attributes are currently in use:
> +@itemize @bullet{}
> +@item
> +Object Attributes version 1 (OAv1) used by: ARC, Arm, CSky, MIPS, msp430, m68k,
> +PowerPC, RISC-V, SPARC, S390, and TI C6X.
> +@item
> +Object Attributes version 2 (OAv2) used by: AArch64.
> +@end itemize
> +
> +@menu
> +* Object Attributes v1::                Object Attributes v1
> +* Object Attributes v2::                Object Attributes v2
> +* GNU Object Attributes::               @sc{gnu} Object Attributes
> +* Defining New Object Attributes::      Defining New Object Attributes
> +@end menu
> +
> +@node Object Attributes v1
> +@section Object Attributes v1
> +
>  Compatibility information is recorded as a series of object attributes.  Each
>  attribute has a @dfn{vendor}, @dfn{tag}, and @dfn{value}.  The vendor is a
>  string, and indicates who sets the meaning of the tag.  The tag is an integer,
> @@ -7918,13 +7942,51 @@ and indicates what property the attribute describes.  The value may be a string
>  or an integer, and indicates how the property affects this object.  Missing
>  attributes are the same as attributes with a zero value or empty string value.
>  
> -Object attributes were developed as part of the ABI for the ARM Architecture.
> -The file format is documented in @cite{ELF for the ARM Architecture}.
> +Object Attributes v1 (OAv1) were developed as part of the ABI for the ARM
> +Architecture.
> +The file format is documented in @cite{Addenda to, and Errata in, the ABI for
> +the Arm® Architecture}.
>  
> -@menu
> -* GNU Object Attributes::               @sc{gnu} Object Attributes
> -* Defining New Object Attributes::      Defining New Object Attributes
> -@end menu
> +@node Object Attributes v2
> +@section Object Attributes v2
> +
> +Object Attributes v2 (OAv2) is the successor of OAv1. OAv1's complexity makes
> +parsing and skipping subsections or attributes challenging, especially for the
> +main consumers, the linkers, which are responsible to merge them, and enforce
> +compatibility.
> +
> +To address these limitations, a new specification for object attributes was
> +proposed. Key design goals of OAv2 include:
> +@itemize @bullet{}
> +@item
> +Retaining successful aspects of OAv1.
> +@item
> +Defining the relationship between build attributes and the existing GNU program
> +properties.
> +@item
> +Separating architectural requirements from software ABI requirements.
> +@item
> +Simplifying the format to allow consumers to skip a subsection or attribute
> +that it does not understand without giving a warning message.
> +@end itemize
> +
> +OAv2 share common concepts of @dfn{vendor}, @dfn{tag} and @dfn{value} with OAv1,
> +and also introduce the new ones like @dfn{subsection} and @dfn{scope}.
> +Attributes with common properties are grouped into subsections.  All the
> +attributes in a subsection share the same encoding, comprehension, and scope.
> +A subsection starting with the vendor name is considered public.  The value of
> +an attribute may be a string or an integer depending on the encoding set on its
> +subsection.
> +
> +The @code{.gnu_subsection} directive creates a new subsection or switch to the
> +subsection if it has already been declared.  The @code{.gnu_attribute} directive
> +records an object attribute in the current subsection.
> +Those directives are valid on all the architectures that support OAv2.
> +
> +Object attributes v2 were developed as part of the ABI for the AArch64
> +architecture.
> +The file format is documented in @cite{Build Attributes for the Arm® 64-bit
> +Architecture (AArch64)}
>  
>  @node GNU Object Attributes
>  @section @sc{gnu} Object Attributes
> @@ -7940,7 +8002,7 @@ architecture-dependent ones.
>  
>  @subsection Common @sc{gnu} attributes
>  
> -These attributes are valid on all architectures.
> +These attributes are valid on all the architectures that support OAv1.
>  
>  @table @r
>  @item Tag_compatibility (32)
> diff --git a/gas/doc/c-aarch64.texi b/gas/doc/c-aarch64.texi
> index d7e9c95111d..d88fcdf2da7 100644
> --- a/gas/doc/c-aarch64.texi
> +++ b/gas/doc/c-aarch64.texi
> @@ -460,6 +460,29 @@ The AArch64 architecture uses @sc{ieee} floating-point numbers.
>  
>  @c AAAAAAAAAAAAAAAAAAAAAAAAA
>  
> +@cindex @code{.aeabi_subsection} directive, AArch64
> +@item .aeabi_subsection @var{name}, @var{comprehension}, @var{encoding}
> +Create or switch the current object attributes subsection to @var{name}.  Valid
> +values for @var{name} are following the pattern @code{[a-zA-Z0-9_-]+}.
> +
> +@var{comprehension} determines whether the subsection is @code{required} or
> +@code{optional}. An optional subsection can be skipped if it is not known by the
> +customer tool, unknown @code{required} subsection should generate an error and
> +stop the processing.
> +
> +@var{encoding} specifies the expected encoding of the attributes recorded in the
> +subsection. Currently supported values are @code{ULEB128} and @code{NTBS}
> +(null-terminated byte string).
> +
> +@cindex @code{.aeabi_attribute} @var{tag}, @var{value}
> +@item .aeabi_attribute @var{tag}, @var{value}
> +Create an attribute with the pair @var{tag}, @var{value} in the current
> +subsection.  @var{tag} can either be an integer value, or a known named key.
> +@var{value} can either be an integer or a string.
> +
> +The exhaustive list of subsections and tags supported on AArch64 is documented
> +in @cite{Build Attributes for the Arm® 64-bit Architecture (AArch64)}.
> +
>  @cindex @code{.arch} directive, AArch64
>  @item .arch @var{name}
>  Select the target architecture.  Valid values for @var{name} are the same as