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

[Matthieu Longo]

On 10/11/2025 06:27, Jan Beulich wrote:
> 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.
> 

I duplicated the description of the directives between c-aarch64.texi 
and as.texi. I also removed the link toward the AArch64 one.
See the final result in the next revision.

>>> 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

A recent question of yours required a change in the specification not 
later than today -> 
https://github.com/ARM-software/abi-aa/pull/230/commits/226364b3f3db6a9091a9cecab38cce668c09433d 


Pinning it down whereas you are still reviewing the patch series, does 
not seem to work. I don't have any objection to add a stable link to the 
documentation later when this last will be published. In the mean time, 
a reference by name should be ok. In the unlikelihood that someone 
searches the document name on Google, he/she can still find the PR by 
following the link from the mailing list. Otherwise, the last option is 
to update the doc before committing when the patch series will be approved.

Now, regarding the link stability, I will repeat myself. Arm does not 
guarantee the long-term stability of the result. In other words, the 
document could be moved in 10 years (even if it is unlikely). I don't 
know what is the solution for this. As far as I can tell, there is no 
link at all to the Object Attribute v1 specification, so I don't have a 
precedent case to refer to.

Richard Earnshaw, please could you advise on this ?

Matthieu