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

[Matthieu Longo]

- amend the existing documentation on OAv1.
- add a new section for OAv2 in the Object Attributes chapter.
- add entries for the new directives.
---
 gas/doc/as.texi        | 76 ++++++++++++++++++++++++++++++++++++++----
 gas/doc/c-aarch64.texi | 23 +++++++++++++
 2 files changed, 92 insertions(+), 7 deletions(-)

diff --git a/gas/doc/as.texi b/gas/doc/as.texi
index 7d6cdcb0a73..4b690659b23 100644
--- 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
-- 
2.50.0