[PATCH v9 16/19] gnu directives: add support for gnu_attribute and gnu_subsection in OAv2 context

[Jan Beulich]

On 07.11.2025 17:02, Matthieu Longo wrote:
> On 07/11/2025 09:00, Jan Beulich wrote:
>> On 06.11.2025 17:39, Matthieu Longo wrote:
>>> On 31/10/2025 12:48, Jan Beulich wrote:
>>>> On 01.09.2025 18:56, Matthieu Longo wrote:
>>>>> @@ -5745,6 +5746,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}
>>>>
>>>> Here you document the new directive, whereas ...
>>>>
>>>>> @@ -7954,32 +7959,62 @@ Many architectures support incompatible variations.  For instance, floating
>>>>>    point arguments might be passed in floating point registers if the object file
>>>>>    requires hardware floating point support---or floating point arguments might be
>>>>>    passed in integer registers if the object file supports processors with no
>>>>> -hardware floating point unit.  Or, if two objects are built for different
>>>>> -generations of the same architecture, the combination may require the
>>>>> -newer generation at run-time.
>>>>> -
>>>>> -This information is useful during and after linking.  At link time,
>>>>> -@command{@value{LD}} can warn about incompatible object files.  After link
>>>>> -time, tools like @command{gdb} can use it to process the linked file
>>>>> -correctly.
>>>>> +hardware floating point unit.  Another example might be when two object files
>>>>> +make use of different architectural extensions: the final image will require
>>>>> +both features to be supported at runtime; or if the features are mutually
>>>>> +exclusive, the linker can issue a diagnostic.
>>>>>    -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,
>>>>> -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.
>>>>> +@command{@value{AS}} currently supports two versions of object attributes:
>>>>> +@itemize @bullet{}
>>>>> +@item
>>>>> +Object Attributes version 1 (OAv1) used by: ARC, ARM, C-SKY, MIPS, MSP430, M68K,
>>>>> +PowerPC, RISC-V, SPARC, s390, and TIC6X.
>>>>> +@item
>>>>> +Object Attributes version 2 (OAv2) used by: AArch64.
>>>>> +@end itemize
>>>>>    -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 are only supported when generating ELF format.
>>>>>       @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
>>>>> +
>>>>> +In Object Attributes v1 (OAv1) Compatibility information is recorded as a series
>>>>> +of object attributes.  Each attribute has a @dfn{vendor}, @dfn{tag}, and
>>>>> +@dfn{value}.  The @dfn{vendor} is a string, and indicates who sets the meaning
>>>>> +of the tag.  The @dfn{tag} is an integer, and indicates what property the
>>>>> +attribute describes.  The @dfn{value} may be a string or an integer, and
>>>>> +indicates how the property affects this object.  Integer tags generally default
>>>>> +to 0, while string tags default to the empty string.  Tags are only recorded in
>>>>> +the file if they have a non-default value.
>>>>> +
>>>>> +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}.
>>>>> +
>>>>> +@node Object Attributes v2
>>>>> +@section Object Attributes v2
>>>>> +
>>>>> +Object Attributes v2 (OAv2) share common concepts of @dfn{vendor}, @dfn{tag}
>>>>> +and @dfn{value} with OAv1, but 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.
>>>>> +
>>>>> +OAv2 is only used by AArch64.  Directives are documented in @ref{AArch64
>>>>> +Directives}.  The file format is documented in @cite{Build Attributes for the
>>>>> +Arm 64-bit Architecture (AArch64)}.
>>>>
>>>> ... here you refer to something living elsewhere.
>>>
>>> I am not sure that I understand what your concern is with the current
>>> documentation.
>>> Do you mean that I should remove the reference "@xref{Object
>>> Attributes}" because the link between this directive, and the
>>> explanation of what OAv2 are is not clear, or at least not directly
>>> related ?
>>> Please could you elaborate ?
>>
>> "AArch64 Directives" lives in c-aarch64.texi. The patch doesn't alter that file
>> at all, hence why I can't help the impression that the @ref here points to the
>> wrong place.
> 
> @xref{AArch64 Directives} seems to be the right reference, i.e. the syntax of those directives. GNU or not GNU, they all follow the syntax of AArch64 ones.
> 
>> That said, I may be irritated by it being .gnu_subsection that you
>> document here, while at the same time inserting a reference to where
>> .aeabi_subsection and .aeabi_attribute are documented. Perhaps this reference
>> wants adding there already in patch 04?
>>
> 
> What about this phrasing ? Does it clarifies the situation from your perspective ?
> 
> OAv2 is only used by AArch64. OAv2 directives, GNU or non-GNU, have the same format as the AArch64 ones documented in @ref{AArch64 Directives}. The file format is documented in @cite{Build Attributes for the Arm 64-bit Architecture (AArch64)}, the original specification document that introduced OAv2.

Well, no. Saying "AArch64-only" is liable to go stale and doesn't scale (we don't
want to be enumerating all arch-es supporting it once a few more do). IOW my
request is to keep AArch64-specific doc to c-aarch64.texi, and keep additions to
as.texi as generic as possible.

>> It's further unclear to me where exactly the @cite points. Looking back through
>> the series, a similar @cite is added in patch 04. There it's also unclear what
>> it references. You don't expect people to search the internet for something by
>> that title, with unpredictable quality of results, do you? Surely there is a
>> stable URL you could supply?
> 
> Regarding this @cite, the specification document is still a pull request, and should be merged once this patch series is merged. Consequently, I cannot provide you today a stable URL. Also, when this PR is merged, Arm does not guarantee the long-term stability of the result. Adding such a cross-site link might become a maintenance burden in the future.

Hmm, no, the specification wants pinning down first. And clearly a specification
wants to live at a (reasonably) stable address. Else how would one go about
locating (unambiguously) it in a few years time?

Jan