AArch64 build attributes specification #230
Conversation
|
I don't think the PDF creation is to do with this pull-request as I didn't add the directory to the generate-pdfs script and the same attribute error happens in other documents. Looks like we may need to upgrade rst2pdf to 0.101 for python 3.12 compatibility. |
smithp35
force-pushed
the
build-attributes
branch
from
986daf3
to
5e6ee79
Compare
| Formal Syntax of aeabi prefixed subsections | ||
| ------------------------------------------- | ||
|
|
||
| <uint8: optional> <uint8: parameter type> |
There was a problem hiding this comment.
The design doc mentions "optimized for size". If we optimize for size, "optional" and "parameter type" can be merged into one byte. In contrast, the current design using two bytes is cleaner. I wonder whether there are additional thoughts into the current choice.
There was a problem hiding this comment.
That is true. In this particular case I'm not expecting too many different subsections, currently we only define one so my instinct is to keep it simple for now.
| *0* the values are ULEB128 encoded. | ||
|
|
||
| *1* the values are NTBS. | ||
|
|
There was a problem hiding this comment.
Looks good. This can be extended in the future if addenda32-style Tag_compatibility is needed.
| The effect of omitting a public tag in file scope is identical to | ||
| including it with a value of 0 or “”, depending on its parameter type. | ||
|
|
||
| Formal Syntax of aeabi prefixed subsections |
| * There is a least a3 such that a1 ≤ a3 and a2 ≤ a3. | ||
| Then a1 + a2 = a3. | ||
|
|
||
| Example: ``Tag_CPU_arch`` from (ADDENDA32_) when a1 = v6KZ, a2 = v6T2, and a3 = v7. |
There was a problem hiding this comment.
I assume that this AArch32-specific example can be replaced when an AArch64 tag with the right semantics arises.
There was a problem hiding this comment.
Yes. I'm somewhat limited with the examples right now.
buildattr64/buildattr64.rst
Outdated
|
|
||
| GNU Program Properties as defined by [LINUX_ABI_] are a similar | ||
| concept to Build Attributes. Program properties are encoded in | ||
| .note.gnu.property sections. A static linker combines the program |
There was a problem hiding this comment.
Should .note.gnu.property be placed in backquotes?
buildattr64/buildattr64.rst
Outdated
|
|
||
| The parameter type is ULEB128. | ||
|
|
||
| The lattice value is custom. Two entities are compabitible if both |
There was a problem hiding this comment.
perhaps semilattice. Since we support just the "join" operation, not "meet".
There was a problem hiding this comment.
Looking it up, it seems like join-semilattice is the formal term. What I'll do for now is explain that it is a join-semilattice but we'll use lattice for brevity.
There was a problem hiding this comment.
I ended up using partial order to remove the use of lattice. While build attributes are modelled on a lattice, the addenda32 only mentions it once.
| An executable or shared library. Also known as loadable-unit in | ||
| this document. | ||
|
|
||
| Loadable-unit |
There was a problem hiding this comment.
The existing docs don't use the term "loadable-unit". "link unit" has been used in several docs. Is there a rationale to introduce this alias?
There was a problem hiding this comment.
In some internal feedback some of my colleagues didn't like link-unit :-) . Loadable unit was felt to be more inituitively understandable than link-unit.
I'm confortable with link-unit, but that's many years of familiarity.
|
|
||
| The major differences between build attributes and GNU properties are: | ||
|
|
||
| - Build attributes are relocatable object only and have an encoding |
There was a problem hiding this comment.
This sentence appears to contradict with "Encoding of meta data in a loadable-unit" in buildattr64.rst. If the recommended practice is for loaders not to inspect the platform-specific build attributes, mention it in buildattr64.rst?
There was a problem hiding this comment.
In buildattr64.rst there is:
Encoding of meta data in a loadable-unit
----------------------------------------
Build attributes are only defined for relocatable objects. The
encoding of metadata in a loadable-unit (executable or shared-library)
is platform specific. For example a platform may choose to use GNU
program properties as defined in (LINUX_ABI_). This document specifies
the meaning of build attributes for relocatable objects only. The
presence of ``.ARM.attributes`` sections in a loadable-unit is
permitted, but the interpretation of the contents of the section is
outside the scope of this document.
I think that is consistent with Build Attributes are relocatable only.
Arm has traditionally taken the approach that the executable and shared-library are mostly "owned" by the platform holder, be that Android or the Linux community and the AArch64 ABI. I've written #229 which is a rationale for using GNU properties in sysvabi64.rst files which we equate to Linux/BSD.
Hope that makes sense. Any suggestions for improvement are welcome though.
| - All candidate libraries with build attributes ≤ selection build | ||
| attributes are compatible. | ||
|
|
||
| - For each compatible candidate library L with best candidate B then |
There was a problem hiding this comment.
I am puzzled by this sentence. Perhaps clarify it?
There was a problem hiding this comment.
OK, I'll try and rewrite it.
| a bit vector and use the binary ``or`` or ``and`` operator to do the | ||
| join. | ||
|
|
||
| Alternative one .aeabi_attributes section |
There was a problem hiding this comment.
Add a colon after "Alternative" to clarify that "alternative one" is not a phrase?
Introduce a new specification document for AArch64 build attributes. The 32-bit ABI makes extensive use of the build attributes defined in addenda32. These attributes defined for relocatable objects are used for a number of purposes including: * Checking ABI compatibility. * Checking required processor feature compatibility. * Automatic static library selection. With AArch64's focus on software platforms, there has not been a strong requirement to introduce extra metadata to denote the requirements and optional processor features used by a relocatable object. Programs are expected to do runtime testing to check if processor features are available. With the advent of security features like PAuthABI, BTI and GCS we need a way to record additional metadata that a static linker can use to set metadata like GNU properties in a loadable-unit (executable or shared-library). A brief summary: * Made a generic "aeabi" prefix for Arm subsections. Including a header that states optionality and encoding. All ULEB or all NTBS. * Describes a single subsection that maps directly to the existing .note.gnu.properties and uses language similar to AAELF64. This includes the existing BTI and PAC properties. * Is accompanied by a design rationale with a suggestion for tool syntax.
Commmit will be squashed prior to commit. - Fixed references to GNU properties which have moved to sysvabi64.rst - Mention in buildattr64.rst that SysVr4 platforms are recommended to use GNU properties in loadable units. - Change lattice to partial order. - Be more consistent with relocatable object file, rather than relocatable file, relocatable object or relocatable object file. - Rewrite example of library selection to be clearer.
smithp35
force-pushed
the
build-attributes
branch
from
5e6ee79
to
7c35e21
Compare
This was unfortunately missed out in the initial commit.
|
Thanks for starting https://discourse.llvm.org/t/rfc-aarch64-build-attributes-for-elf-relocatable-objects/75161 and I came here while reading that post. I have done a lot of object file format/assembler/linker work in llvm-project and I am in favor of AArch64 Build Attributes. I haven't studied much about PAuth, but if loaders don't need to know the relevant build attributes, using build attributes should be good.
In |
buildattr64/README.md
Outdated
|
|
||
| ## About this document | ||
|
|
||
| The [Build Attributes for the Arm 64-bit Architecture](buildattr64.rst) describes the |
There was a problem hiding this comment.
missing words after "the"?
buildattr64/buildattr64.rst
Outdated
| ------------------- | ||
|
|
||
| The tool interface for private subsections is implementation defined. | ||
|
|
There was a problem hiding this comment.
delete trailing blank line
| multiple feature bits with forcing functions. A concrete example is | ||
| ``FEAT_LSE2`` which can only exist if ``FEAT_LSE`` exists. | ||
|
|
||
| - require more then one attribute to describe. For example the |
|
|
||
| - Textual formats are slower to parse and take up more space. | ||
|
|
||
|
|
There was a problem hiding this comment.
delete trailing blank lines?
Make further corrections, these were all non-functional in nature. This commit will be squashed prior to merging.
|
Uploaded new version, thanks for the additional comments. |
| The syntactic structure of an attributes section is:: | ||
|
|
||
| <format-version: <version-letter>> | ||
| [ <uint32: subsection-length> NTBS: vendor-name |
There was a problem hiding this comment.
The first byte will be followed by 0 or more subsections.
[ <uint32: subsection-length> NTBS: vendor-name
<bytes: vendor-data>
]
Is the equivalent of a single .aeabi_subsection in the assembly.
for each .aeabi_subsection there must be single
[ <uint32: subsection-length> NTBS: vendor-name
<bytes: vendor-data>
]
In the ELF.
Each unique .aeabi_subsection vendor-name will result in a single subsection. That permits an assembler to allow .aeabi_subsection to appear multiple times in the same file with the same vendor name, like a .section directive. Therefore it is possible to change subsections, but be able to return to the previous one. I don't think this is likely in practice, but it is often how "stateful" directives are implemented in assembler.
For example:
// switch to subsection aeabi-feature-and-bits
.aeabi_subsection aeabi-feature-and-bits , 0, 0
.aeabi_attribute Tag_Feature_BTI, 1
// switch to subsection aeabi-pauthabi
.aeabi_subsection aeabi-pauthabi, 1, 0
.aeabi_attribute Tag_PAuth_Platform, 1
.aeabi_attribute Tag_PAuth_Schema, 1
// switch back to subsection aeabi-feature-and-bits
// Note this doesn't create a new subsection.
.aeabi_subsection aeabi-feature-and-bits , 0, 0
.aeabi_attribute Tag_Feature_GCS, 1
There will be two subsections in the ELF file aeabi-feature-and-bits and aeabi-pauthabi.
|
|
||
| The syntactic structure of an attributes section is:: | ||
|
|
||
| <format-version: <version-letter>> |
There was a problem hiding this comment.
The <format-version: > (double '<, >' also around 'version-letter') and <uint32: subsection-length> (single '<, >', not around 'subsection-length') does not indicated a different between the cases.
| type ``SHT_AARCH64_ATTRIBUTES`` and name ``.ARM.attributes`` (for | ||
| further details see [AAELF64_]). | ||
|
|
||
| An attribute is encoded in a <tag, value> pair. |
There was a problem hiding this comment.
A tag with the same name in a different .aeabi_subsections is considered a different tag.
| construct "aeabi" prefixed subsections. | ||
|
|
||
| :: | ||
| .aeabi_subsection name [optional] [, parameter type] |
There was a problem hiding this comment.
The syntax is not final. There are consideration around whether the values should be optional and with what exact syntax.
Options:
- as it is now, and to denote optional arguments:
.aeabi_subsection MySectionA 0 -> 'optional'
.aeabi_subsection MySectionA, 0 -> 'parameter type' - The syntax might be .aeabi_subsection name [, optional] [, parameter type]
and to denote optional arguments:
.aeabi_subsection MySectionA, 0, or:
.aeabi_subsection MySectionA, ,0 - Having both the arguments being mandatory
- Make encoding and parameter type either both present or absent
| Public aeabi prefixed subsections | ||
| ================================= | ||
|
|
||
| About public tags |
There was a problem hiding this comment.
Edit: reading it again I realize that this part describe the ELF while I thought that it describes the assembly. Therefore some of the comments are irrelevant, but some still makes sense so I figure I better leave them.
If details like vendor name has to be be encoded in the ELF, does it mean that they must also appear in the assembly?
Might it be a good idea to have a clear section regarding assembly, or some related document? even though strictly speaking the ABI is only the binary specification for the ELF file.
Here is a suggestion for this paragraph that reflect my understanding of public subsections: (Edit: in the assembly, maybe this can serve for another document that specify the assembly)
| About public tags | |
| Public subsections | |
| Subsections are denoted with the tag: `.aeabi_subsection <name>` | |
| Public subsections are subsections with <name> starting with a prefix of "aeabi". | |
| Public subsections have a header that indicates whether the subsection is mandatory or not, and what is the type of the value for all the subsection's attributes. | |
| A consumer must be able to parse the header of all the mandatory public subsections. A consumer may skip an optional subsection. |
Several points:
- The header does not indicates only optionality, but also the attribute's values type.
Edit: irrelevant to ELF, only to assembly. - The part about the subsection that do not need to be read is confusing. My understanding of the essence is: If subsection is mandatory, it has to be read, not being able to read it is an error. If it is optional, it can be skipped, from any reason (e.g. not being able to recognize the full vendor-name or any other reason, it is not clear what is special about the vendor-name)
Edit: This part seems relevant also for ELF. - Remove the mention of "vendor name" since in actuality sections names does not contained a vendor name.
Edit: not true to ELF, still, since this data is not in the assembly, how do we know what to put it in the ELF?
| Default values for public tags | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| The effect of omitting a public tag in file scope is identical to |
There was a problem hiding this comment.
It is unclear to me whether this is true only for optional subsections, only for mandatory subsections, or for both, optional and mandatory and subsections.
| have a prefix of "aeabi". If the header is optional then a consumer | ||
| may skip the subsection if they do not recognize the full vendor-name. | ||
|
|
||
| Default values for public tags |
There was a problem hiding this comment.
Might it be a good idea to call 'tags' -> subsections and therefore 'public tags' -> public subsections?
"Tags" might mean quite a few things.
| Encoding | ||
| -------- | ||
|
|
||
| Encoding build attributes are encoded in a vendor-specific section of |
There was a problem hiding this comment.
| Encoding build attributes are encoded in a vendor-specific section of | |
| Build attributes are encoded ... |
|
Thanks for all the comments. I'll aim to get a response tomorrow and I'll post an update to the spec and rationale this week. |
Introduce a new specification document for AArch64 build attributes.
The 32-bit ABI makes extensive use of the build attributes defined in addenda32. These attributes defined for relocatable objects are used for a number of purposes including:
Checking ABI compatibility.
Checking required processor feature compatibility.
Automatic static library selection.
With AArch64's focus on software platforms, there has not been a strong requirement to introduce extra metadata to denote the requirements and optional processor features used by a relocatable object. Programs are expected to do runtime testing to check if processor features are available.
With the advent of security features like PAuthABI, BTI and GCS we need a way to record additional metadata that a static linker can use to set metadata like GNU properties in a loadable-unit (executable or shared-library).
A brief summary:
Made a generic "aeabi" prefix for Arm subsections. Including a header that states optionality and encoding. All ULEB or all NTBS.
Describes a single subsection that maps directly to the existing .note.gnu.properties and uses language similar to AAELF64. This includes the existing BTI and PAC properties.
Is accompanied by a design rationale with a suggestion for tool syntax.