Skip to Main Content Skip to Footer Navigation

Sorry, your browser is not supported. We recommend upgrading your browser. We have done our best to make all the documentation and resources available on old versions of Internet Explorer, but vector image support and the layout may not be optimal. Technical documentation is available as a PDF Download.

You copied the Doc URL to your clipboard.

Addenda to, and Errata in, the ABI for the Arm® Architecture

Document number: IHI 0045F, current through ABI release 2018Q4

Date of Issue: 21st December 2018


Preamble

Abstract

This document describes late additions (addenda) to the ABI for the Arm Architecture version 2.0, and errors (errata) discovered in it after publication.

Keywords

Addenda to the ABI for the Arm Architecture, errata in the ABI for the Arm Architecture

How to find the latest release of this specification or report a defect in it

Please check the Arm Developer site (https://developer.arm.com/products/software-development-tools/specifications) for a later release if your copy is more than one year old.

Please report defects in this specification to arm dot eabi at arm dot com.

Licence

THE TERMS OF YOUR ROYALTY FREE LIMITED LICENCE TO USE THIS ABI SPECIFICATION ARE GIVEN IN Your licence to use this specification (Arm contract reference LEC-ELA-00081 V2.0). PLEASE READ THEM CAREFULLY.

BY DOWNLOADING OR OTHERWISE USING THIS SPECIFICATION, YOU AGREE TO BE BOUND BY ALL OF ITS TERMS. IF YOU DO NOT AGREE TO THIS, DO NOT DOWNLOAD OR USE THIS SPECIFICATION. THIS ABI SPECIFICATION IS PROVIDED "AS IS" WITH NO WARRANTIES (SEE Your licence to use this specification FOR DETAILS).

Non-Confidential Proprietary Notice

This document is protected by copyright and other related rights and the practice or implementation of the information contained in this document may be protected by one or more patents or pending patent applications. No part of this document may be reproduced in any form by any means without the express prior written permission of Arm. No license, express or implied, by estoppel or otherwise to any intellectual property rights is granted by this document unless specifically stated.

Your access to the information in this document is conditional upon your acceptance that you will not use or permit others to use the information for the purposes of determining whether implementations infringe any third party patents.

THIS DOCUMENT IS PROVIDED "AS IS". ARM PROVIDES NO REPRESENTATIONS AND NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY, SATISFACTORY QUALITY, NON-INFRINGEMENT OR FITNESS FOR A PARTICULAR PURPOSE WITH RESPECT TO THE DOCUMENT. For the avoidance of doubt, Arm makes no representation with respect to, and has undertaken no analysis to identify or understand the scope and content of, patents, copyrights, trade secrets, or other rights.

This document may include technical inaccuracies or typographical errors.

TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL ARM BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF ANY USE OF THIS DOCUMENT, EVEN IF ARM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

This document consists solely of commercial items. You shall be responsible for ensuring that any use, duplication or disclosure of this document complies fully with any relevant export laws and regulations to assure that this document or any portion thereof is not exported, directly or indirectly, in violation of such export laws. Use of the word "partner" in reference to Arm's customers is not intended to create or refer to any partnership relationship with any other company. Arm may make changes to this document at any time and without notice.

If any of the provisions contained in these terms conflict with any of the provisions of any click through or signed written agreement covering this document with Arm, then the click through or signed written agreement prevails over and supersedes the conflicting provisions of these terms. This document may be translated into other languages for convenience, and you agree that if there is any conflict between the English version of this document and any translation, the terms of the English version of the Agreement shall prevail.

The Arm corporate logo and words marked with ® or ™ are registered trademarks or trademarks of Arm Limited (or its subsidiaries) in the US and/or elsewhere. All rights reserved. Other brands and names mentioned in this document may be the trademarks of their respective owners. Please follow Arm's trademark usage guidelines at http://www.arm.com/company/policies/trademarks.

Copyright © [2018] Arm Limited (or its affiliates). All rights reserved.

Arm Limited. Company 02557590 registered in England. 110 Fulbourn Road, Cambridge, England CB1 9NJ. LES-PRE-20349

ABOUT THIS DOCUMENT

Change control

Current status and anticipated changes

The following support level definitions are used by the Arm ABI specifications:

Release
Arm considers this specification to have enough implementations, which have received sufficient testing, to verify that it is correct. The details of these criteria are dependent on the scale and complexity of the change over previous versions: small, simple changes might only require one implementation, but more complex changes require multiple independent implementations, which have been rigorously tested for cross-compatibility. Arm anticipates that future changes to this specification will be limited to typographical corrections, clarifications and compatible extensions.
Beta
Arm considers this specification to be complete, but existing implementations do not meet the requirements for confidence in its release quality. Arm may need to make incompatible changes if issues emerge from its implementation.
Alpha
The content of this specification is a draft, and Arm considers the likelihood of future incompatible changes to be significant.

All content in this document is at the "Release" quality level.

Change history

Issue   Date By Change
v1.0 r2.0 24th March 2005 LS First public release.
v1.01 r2.01 4th July 2005 LS Added new Coding extensibility and compatibility. Noted component errata and omissions (ELF for the Arm Architecture, Library ABI for the Arm Architecture, and C++ ABI for the Arm Architecture).
v1.02   7th October 2005 LS Added WMMX v2 architecture, TAG_CPU_unaligned_access (Public ("aeabi") attribute tags); changed R_ARM_PC24 to R_ARM_CALL (Linux for Arm general dynamic model); added list of reserved name-space prefixes (Reserved Names); noted errata and omissions (DWARF for the Arm Architecture, Procedure Call Standard for the Arm Architecture, Library ABI for the Arm Architecture, Exception Handling ABI for the Arm Architecture, and Run-time ABI for the Arm Architecture)
v1.03 r2.02 13th October 2005 LS Minor typographical fixes.
v1.04 r2.03 6th January 2006 LS Noted errata and omissions (Clarifications, Additions and omissions fixed, and Clarifications).
v1.05 r2.04 8th May 2006 LS Added missing Tag_FP_arch value for VFPv3 (Target-related attributes). Noted errata and omissions (Errors fixed, Additions and omissions fixed, Clarifications, Errors fixed, and Clarifications).
v1.06 r2.05 18th January 2007 LS Major clarification of, and some compatible extension to, ADDENDUM: Build Attributes.
v1.07 r2.06 23rd October 2007 LS Added: CPU_arch values for v6S-M and v6-M; and VFP_arch value for VFPv3-D16; added Tag_nodefaults, Tag_ABI_FP_16bit_format, and Tag_FP_HP_extension. Rewrote ADDENDUM: Build Attributes. Noted errata and omissions.
A   25th October 2007 LS Document renumbered (formerly GENC-005895 v1.07).
A   13th November 2007 LS Minor corrections to Errata and Minor Addenda
B r2.07 10th October 2008 LS Added architecture tags Tag_T2EE_use, Tag_Virtualization_use, and Tag_MPextension_use; clarified definitions of Tag_CPU_name and Tag_CPU_raw_name (The target-related attributes); clarified tag value inheritance and Tag_Nodefaults (Default values for public tags, Inheritance of public tag values, No defaults tag).
C r2.08 4th November 2009 LS (The target-related attributes): added Tag_CPU_arch enum value V7E-M =13; renamed Tag_VFP_arch to Tag_FP_arch, added values for VFPv4; renamed Tag_VFP_HP_extension to Tag_FP_HP_extension; added value to Tag_Advanced_SIMD_arch for Neon with fused MAC; added values to Tag_Virtualization_use describing use of the virtualization extensions; recoded Tag_MPextension use to catch potential user-mode faults; added Tag_DIV_use to describe use of UDIV/SDIV in code for v7A. (The procedure call-related attributes) clarified the role of R9 when used as a TLS (Tag_ABI_PCS_R9_use = 2). Renamed and extended Tag_ABI_align8_needed, Tag_ABI_align8_preserved to data with extended 2n-byte alignment (for n in 4-12).
D r2.09 30th November 2012 AC Made section and symbol attributes deprecated and optional (The scope of build attributes, Formal syntax of a public ("aeabi") attributes subsection, Inheritance of public tag values, No defaults tag). (Formal syntax of a public ("aeabi") attributes subsection) clarified section and symbol numbers are ULEB128. (The target-related attributes) added architecture v8 values to Tag_CPU_arch, Tag_FP_arch, Tag_Advanced_SIMD_arch; clarified use of existing Tag_Advanced_SIMD_arch and Tag_FP_HP_extension values; clarified the meaning of Tag_DIV_use; deprecated Tag_T2EE_use. (The procedure call-related attributes) fixed typo in Tag_ABI_FP_exceptions; clarified use of Tag_ABI_HardFP_use values and removed pointless DP-only option; added enum value to Tag_ABI_VFP_args for code compatible with both the base and VFP variants. (Secondary compatibility tag clarified the format of Tag_also_compatible_with data. (Arm CPU names recognized by Arm Compiler 5.01 (armcc)) updated list of recognised CPU names.
E r2.10 24th November 2015 CR (The target-related attributes) added architecture v8.1 values to Tag_Advanced_SIMD_arch.
F 2018Q4 21st December 2018 OS

In The target-related attributes, deprecated values 1 and 2 of Tag_THUMB_ISA_use, added value 3.

In The target-related attributes, deprecated Tag_CPU_arch_profile for architecture version 8 onwards.

In The target-related attributes, defined build attributes for Armv8-M, Armv8-R, Armv8.1-A, Armv8.2-A and Armv8.3-A.

References

This document refers to the following documents.

Ref Status / External URL Title
AAELF   ELF for the Arm Architecture
AAPCS   Procedure Call Standard for the Arm Architecture
BSABI   ABI for the Arm Architecture (Base Standard).
EHABI   Exception Handling ABI for the Arm Architecture
RTABI   Run-time ABI for the Arm Architecture
ARMARM

https://developer.arm.com/docs/ddi0406/c/arm-architecture-reference-manual-armv7-a-and-armv7-r-edition

https://developer.arm.com/products/architecture/m-profile/docs/ddi0403/e/armv7-m-architecture-reference-manual

Arm DDI 0406: Arm Architecture Reference Manual Arm v7-A and Arm v7-R edition

Arm DDI 0403C: Armv7-M Architecture Reference Manual

ACLE IHI 0053A Arm C Language Extensions
GDWARF http://dwarfstd.org/Dwarf3Std.php DWARF 3.0, the generic debug table format.
GELF http://www.sco.com/developers/gabi/ Generic ELF, 17th December 2003 draft.

Terms and abbreviations

The ABI for the Arm Architecture uses the following terms and abbreviations.

AAPCS
Procedure Call Standard for the Arm Architecture
ABI

Application Binary Interface:

  1. The specifications to which an executable must conform in order to execute in a specific execution environment. For example, the Linux ABI for the Arm Architecture.
  2. particular aspect of the specifications to which independently produced relocatable files must conform in order to be statically linkable and executable. For example, the C++ ABI for the Arm Architecture, the Run-time ABI for the Arm Architecture, the Library ABI for the Arm Architecture.
AEABI
(Embedded) ABI for the Arm architecture (this ABI…)
Arm-based
… based on the Arm architecture …
core registers
The general purpose registers visible in the Arm architecture's programmer's model, typically r0-r12, SP, LR, PC, and CPSR.
EABI
An ABI suited to the needs of embedded, and deeply embedded (sometimes called free standing), applications.
Q-o-I
Quality of Implementation - a quality, behavior, functionality, or mechanism not required by this standard, but which might be provided by systems conforming to it. Q-o-I is often used to describe the tool-chain-specific means by which a standard requirement is met.
VFP
The Arm architecture's Floating Point architecture and instruction set. In this ABI, this abbreviation includes all floating point variants regardless of whether or not vector (V) mode is supported.

Your licence to use this specification

IMPORTANT: THIS IS A LEGAL AGREEMENT ("LICENCE") BETWEEN YOU (AN INDIVIDUAL OR SINGLE ENTITY WHO IS RECEIVING THIS DOCUMENT DIRECTLY FROM ARM LIMITED) ("LICENSEE") AND ARM LIMITED ("ARM") FOR THE SPECIFICATION DEFINED IMMEDIATELY BELOW. BY DOWNLOADING OR OTHERWISE USING IT, YOU AGREE TO BE BOUND BY ALL OF THE TERMS OF THIS LICENCE. IF YOU DO NOT AGREE TO THIS, DO NOT DOWNLOAD OR USE THIS SPECIFICATION.

"Specification" means, and is limited to, the version of the specification for the Applications Binary Interface for the Arm Architecture comprised in this document. Notwithstanding the foregoing, "Specification" shall not include (i) the implementation of other published specifications referenced in this Specification; (ii) any enabling technologies that may be necessary to make or use any product or portion thereof that complies with this Specification, but are not themselves expressly set forth in this Specification (e.g. compiler front ends, code generators, back ends, libraries or other compiler, assembler or linker technologies; validation or debug software or hardware; applications, operating system or driver software; RISC architecture; processor microarchitecture); (iii) maskworks and physical layouts of integrated circuit designs; or (iv) RTL or other high level representations of integrated circuit designs.

Use, copying or disclosure by the US Government is subject to the restrictions set out in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software - Restricted Rights at 48 C.F.R. 52.227-19, as applicable.

This Specification is owned by Arm or its licensors and is protected by copyright laws and international copyright treaties as well as other intellectual property laws and treaties. The Specification is licensed not sold.

  1. Subject to the provisions of Clauses 2 and 3, Arm hereby grants to LICENSEE, under any intellectual property that is (i) owned or freely licensable by Arm without payment to unaffiliated third parties and (ii) either embodied in the Specification or Necessary to copy or implement an applications binary interface compliant with this Specification, a perpetual, non-exclusive, non-transferable, fully paid, worldwide limited licence (without the right to sublicense) to use and copy this Specification solely for the purpose of developing, having developed, manufacturing, having manufactured, offering to sell, selling, supplying or otherwise distributing products which comply with the Specification.
  2. THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO WARRANTIES EXPRESS, IMPLIED OR STATUTORY, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OF SATISFACTORY QUALITY, MERCHANTABILITY, NONINFRINGEMENT OR FITNESS FOR A PARTICULAR PURPOSE. THE SPECIFICATION MAY INCLUDE ERRORS. Arm RESERVES THE RIGHT TO INCORPORATE MODIFICATIONS TO THE SPECIFICATION IN LATER REVISIONS OF IT, AND TO MAKE IMPROVEMENTS OR CHANGES IN THE SPECIFICATION OR THE PRODUCTS OR TECHNOLOGIES DESCRIBED THEREIN AT ANY TIME.
  3. This Licence shall immediately terminate and shall be unavailable to LICENSEE if LICENSEE or any party affiliated to LICENSEE asserts any patents against Arm, Arm affiliates, third parties who have a valid licence from Arm for the Specification, or any customers or distributors of any of them based upon a claim that a LICENSEE (or LICENSEE affiliate) patent is Necessary to implement the Specification. In this Licence; (i) "affiliate" means any entity controlling, controlled by or under common control with a party (in fact or in law, via voting securities, management control or otherwise) and "affiliated" shall be construed accordingly; (ii) "assert" means to allege infringement in legal or administrative proceedings, or proceedings before any other competent trade, arbitral or international authority; (iii) "Necessary" means with respect to any claims of any patent, those claims which, without the appropriate permission of the patent owner, will be infringed when implementing the Specification because no alternative, commercially reasonable, non-infringing way of implementing the Specification is known; and (iv) English law and the jurisdiction of the English courts shall apply to all aspects of this Licence, its interpretation and enforcement. The total liability of Arm and any of its suppliers and licensors under or in relation to this Licence shall be limited to the greater of the amount actually paid by LICENSEE for the Specification or US$10.00. The limitations, exclusions and disclaimers in this Licence shall apply to the maximum extent allowed by applicable law.

Arm Contract reference LEC-ELA-00081 V2.0 AB/LS (9 March 2005)

ADDENDUM: Build Attributes

Introduction to build attributes

About build attributes and compatibility

Build attributes record data that a linker needs to reason mechanically about the compatibility, or incompatibility, of a set of relocatable files. Other tools that consume relocatable files may find the data useful.

Build attributes are designed to have long-term invariant meaning. They record choices to which there is long term public commitment through the Arm Architecture Reference Manual [ARMARM], the ABI for the Arm Architecture (of which this document is a component), vendor data sheets, and similar long lived publications.

Build attributes approximate the intentions the user of a compiler or assembler has for the compatibility of the relocatable file produced by the compiler or assembler (Attribute values are based on user intentions).

Software development flows supported by build attributes, below, depicts the software development flows in which build attributes are important.

addenda32-toolflow.png

Software development flows supported by build attributes

In this depiction there are two principal uses of build attributes.

  • Within a tool chain, build attributes generate rich opportunities for a linker to diagnose incompatibility, enforce compatibility, and select library members intelligently according to its compatibility model.
  • Between tool chains, build attributes describe the intended compatibility of a relocatable file and the entities it defines in terms independent of either tool chain, promoting safe exchange of portable code in binary form.
Attribute values are based on user intentions

We base attribute values on user intentions to avoid the values being an unpredictable (effectively random) function of a compiler's code generation algorithms and to support using attributes with assembly language without overburdening programmers. Where attributes support exchanging portable relocatable files among tool chains, predictability is worth more than precision.

Capturing a user's compile-time intentions about compatibility is also important at link time. For example:

  • user might permit a compiler to use both the Arm ISA and the Thumb ISA.

    (The user intends the code to be usable on any processor that has both the Arm ISA and the Thumb ISA).

  • The compiler might choose to use only the Thumb ISA in a specific build of a source file.

    Nonetheless, the relocatable file should be tagged as having been permitted to use the Arm ISA so that a linker can later link it with Arm-state library code and generate Arm-state intra-call veneers if that gives benefit to the executable file.

On the other hand, if the user intends code to be executed by both Arm7TDMI and Cortex-M3, the compiler must be constrained to generate only Thumb v1 instructions and the relocatable file should be tagged as not permitted to use the Arm ISA.

Capturing user intentions about compatibility

This standard does not specify how a tool should capture and approximate the intentions of its users.

As far as possible, ABI-defined compatibility tags (Public ("aeabi") attribute tags) model the long-term compatibility commitments implicit in architectural specifications, product data sheets, and the ABI for the Arm Architecture.

In general, tools have invocation options - command-line options and GUI configuration options - that present choices similar to those revealed in such documentation and modeled by ABI-defined compatibility tags.

The challenge for a tool that generates relocatable files is to select the set of build attributes - giving a value to each compatibility tag - that best approximates the user's intentions implicit in its invocation options.

This part of the problem of managing compatibility does not have a perfect solution. A user's intentions are imperfectly approximated by invocation options that are then sometimes imperfectly mapped to build attributes.

No standard compatibility model

This specification standardizes the meaning of build attributes, not the compatibility models within which they will be interpreted.

For the majority of build attributes there is only one reasonable interpretation of compatibility among their values, and it is an obvious one.

For a minority - mostly associated with procedure-call compatibility between functions - this is not the case and it is reasonable for different tool chains to take different positions according to the markets they serve.

Thus it is entirely reasonable that a relocatable file produced by tool chain A and accepted by tool chain B's linker might be rejected by tool chain C's linker when targeting exactly the same environment as tool chain B.

Our hope and intention for attributes is that they might prevent C's linker from accepting the output of A and silently generating a non functioning executable file or failing in a mysterious and difficult to explain manner.

The kinds of compatibility modeled by build attributes

Build attributes primarily model two kinds of compatibility.

  • The compatibility of binary code with target hardware conforming to a revision of the Arm Architecture.
  • The procedure-call compatibility between functions conforming to variants of this ABI.

The intuitive notion of compatibility can be given a mathematically precise definition using sets of demands placed on an execution environment.

For example, a program could be defined to be compatible with a processor if (and only if) the set of instructions the program might try to execute is a subset of the set of instructions implemented by the processor.

Target-related attributes (Target-related attributes) describe the hardware-related demands a relocatable file will place on an execution environment through being included in an executable file for that environment.

For example, target-related attributes record whether use of the Thumb ISA is permitted, and at what architectural revision use is permitted. A pair of values for these attributes describes the set of Thumb instructions that code is permitted to execute and that the target processor must implement.

Procedure call-related attributes (Procedure call-related attributes) describe features of the ABI contract that the ABI allows to vary, such as whether floating point parameters are passed in floating point registers, the size of wchar_t, whether enumerated values are containerized according to their size, and so on.

We can also understand procedure call-related compatibility in terms of sets of demands placed on an execution environment, but the modeling is more difficult. In this case the environment is less obvious, more abstract, and elements of it can depend on an operating system or the tool chain itself.

Mathematically, A compatible with B can be understood as: {demands made by A} \subseteq {demands made by B}.

Making this concrete sometimes requires combining information from several tags. Writing {T16@v4T} to denote the set of 16-bit Thumb instructions a processor must execute to conform to architecture version v4T, we can understand T16@v4T compatible with T16@v5TE as {T16@v4T} \subset {T16@v5TE}.

The scope of build attributes

Unless #pragma or other mechanisms specific to a tool chain are used, it is usual for all parts of a relocatable file to be built the same way with the same compatibility intentions. So, usually, build attributes are given file scope and apply to all entities defined in the file to which they can apply. For example:

  • File-scope attributes that model the compatibility of binary instructions with processors naturally apply to each instruction in every code-containing section in the file.

    (They obviously do not apply to sections that contain no code, nor to the data - such as literal pools - embedded in code sections).

  • Attributes that describe the procedure call-compatibility of functions naturally apply to every function symbol defined in the code sections contained within the file.

Build attributes can be given to individual entities defined in a relocatable file.

  • To an individual ELF section.

    These attributes also apply to every (relevant) symbol defined in the section.

  • To an individual function or data object identified by an ELF symbol definition.

For the public build attributes defined by this ABI (Public ("aeabi") attribute tags) a compiler for C/C++ can only need to use section and symbol attributes in the presence of #pragmas, language extensions, or other mechanisms that affect the compatibility of individual entities within a binary file.

Linkers that support relocatable file merging - termed partial linking by RealView linkers - will, in general, need to transfer the file scope attributes of an input file to the individual sections that file contributes to the output file.

This standard places no requirements on the presence or absence of build attributes in executable files.

Note

From the 2.09 release, section and symbol attributes are deprecated and optional. Primary object producers are discouraged from generating them and consumers are permitted to ignore them.

Build attributes and conformance to the ABI

In revision 2.05 and later revisions of this ABI specification, the presence of a build attributes section containing an "aeabi" subsection containing a conformance tag (Conformance tag) denotes an explicit claim by the producer that the relocatable file conforms to:

  • The version of the ABI described by tag's string parameter.
  • The variant of that version described by the public ("aeabi") build attributes.

claim to conform to ABI version "0" denotes that no unconditional claim to conform is being made. Generic compatibility tags (Generic compatibility tag) may then describe limited or conditional claims to conform.

In revisions of this specification before r2.05 any claim to conform to this ABI was implicit, and the version to which conformance was (possibly) claimed was implicitly "2".

Combining attribute values

Suppose E1 and E2 are entities (for example, relocatable files) with attribute values a1 and a2 for an attribute tag T. This section discusses how to generate the correct value of T for the entity formed by combining E1 and E2 (for example, the executable file formed by linking E1 with E2)

In each case, the values of a tag can be partially ordered according to the sets of demands they represent. We shall write a1 \le a2 if an entity tagged with <T, a1> makes no more demands on its environment than an entity tagged with <T, a2>.

Writing {T:a1} to denote the set of demands made by an entity tagged with <T, a1>, we can define a1 \le a2 if {T:a1} \subseteq {T:a2}. (A set of demands might be the set of instructions a processor must execute, for example).

Informally we say that a1 is compatible with a2 or a1 is more compatible than a2 when a1 \le a2.

Using Tag_CPU_arch (The target-related attributes) as an example, v4T \le v5TE, because the set of instructions conforming to architecture v4T is a subset of the set conforming to architecture v5TE. Stated more precisely, for both the Arm ISA and the 16-bit Thumb ISA, it is the case that {ISA@v4T} \subseteq {ISA@v5TE}.

This partial order often differs from the arithmetic order of the enumerated values though in many cases it

Note that the appropriate partial order to use can evolve over time as the underlying specifications evolve.

Combining two values of the same tag

We shall write a1 <> a2 if a1 and a2 are unordered in the partial order of demands/compatibility and a1 + a2 to denote the combination of a1 and a2. There are the following combination rules.

  • If a1 \le a2, a1 + a2 = a2. Similarly, if a2 \le a1, a1 + a2 = a1. ('+' behaves like the maximum function).

  • If a1 <> a2 there are two mutually exclusive sub-cases.

    • There is a least a3 such that a1 \le a3 and a2 \le a3. Then a1 + a2 = a3.

      Example: Tag_CPU_arch when a1 = v6KZ, a2 = v6T2, and a3 = v7.

    • There is no such a3, so a1 + a2 denotes the attempted combination of incompatible values.

      Example: Tag_ABI_PCS_wchar_t when a1 = 2 and a2 = 4.

In this second sub-case it is a matter of notational taste whether a1 + a2 is defined to have a value such as error or Top, or defined to have no value. Either way, in practice we expect an attempted combination to fail in a way specific to a tool chain's compatibility model (for example by provoking a link-time diagnostic).

Representing build attributes in ELF files

Encoding

Encoding build attributes needs more than a few bits, so we encode them in an vendor-specific section of type SHT_ARM_ATTRIBUTES and name .ARM.attributes (for further details see [AAELF]).

An attribute is encoded in a <tag, value> pair.

Both tags and numerical values are encoded using unsigned LEB128 encoding (ULEB128), DWARF-3 style (for details see [GDWARF]).

The public tags and values specified by this version of the ABI encode identically as ULEB128 numbers and single byte numbers (all values are in the range 0-127).

String values are encoded using NUL-terminated byte strings (NTBS).

Structure of an ELF attributes section

An attributes section contains a sequence of subsections. Each one is either

  • Defined by this ABI and public to all tools that process the file.
  • Private to a tool vendor's tools.

The type of each subsection is given by a short textual (NTBS) name.

This ABI requires a vendor to register a short vendor name to use as a prefix to the names of private helper functions (for details see [RTABI] or [AAELF]). The same vendor name identifies attribute subsections private to that vendor's tools.

public attributes subsection is named aeabi. Names beginning Anon and anon are reserved to unregistered private use.

Formal syntax of an ELF attributes section

The syntactic structure of an attributes section is:

<format-version: 'A'>
[ <uint32: subsection-length> NTBS: vendor-name
  <bytes: vendor-data>
]*

Format-version describes the format of the following data. It is a single byte. This is version 'A' (0x41). This field exists to allow future changes in format. We do not intend that there will be many versions.

Subsection-length is a 4-byte integer in the byte order of the ELF file. It encodes the length of the subsection, including the length field itself, the vendor name string and its terminating NUL byte, and the following vendor data. It gives the offset from the start of this subsection to the start of the next one.

Vendor-name is a NUL-terminated byte string (NTBS) like a C-language literal string.

No requirements are placed on the format of private vendor data. The format of a public attributes subsection ("aeabi" pseudo-vendor data) is described in Formal syntax of a public ("aeabi") attributes subsection.

We expect a dot-ARM-dot-attributes section in a relocatable file will most typically contain one vendor subsection from the "aeabi" pseudo-vendor and possibly one from the generating tool chain (e.g. "ARM", "gnu", "WRS", etc).

Formally, there are no constraints on the order or number of vendor subsections. A consumer can collect the public ("aeabi") attributes in a single pass over the section, then all of its private data in a second pass.

Formal syntax of a public ("aeabi") attributes subsection

The syntactic structure of a public attributes subsection is:

[   Tag_File    (=1) <uint32: byte-size> <attribute>*
  | Tag_Section (=2) <uint32: byte-size> <section number>* 0 <attribute>*
  | Tag_Symbol  (=3) <unit32: byte-size> <symbol number>*  0 <attribute>*
]+

public subsection contains any number of sub-subsections. Each records attributes relating to:

  • The whole relocatable file.

    These sub-subsections contain just a list of attributes. They are identified by a leading Tag_File (=1) byte.

  • A set of sections within the relocatable file.

    These sub-subsections contain a list of ULEB128 section numbers followed by a list of attributes. They are identified by a leading Tag_Section (=2) byte.

  • A set of (defined) symbols in the relocatable file.

    These sub-subsections contain a list of ULEB128 symbol numbers followed by a list of attributes. They are identified by a leading Tag_Symbol (=3) byte.

In each case, byte-size is a 4-byte unsigned integer in the byte order of the ELF file. Byte-size includes the initial tag byte, the size field itself, and the sub-subsection content. That is, it is the byte offset from the start of this sub-subsection to the start of the next sub-subsection.

Both section indexes and defined symbol indexes are non-zero, so a NUL byte ends a string and a list of indexes without ambiguity.

There are no constraints on the order or number of sub-subsections in a public attributes subsection (but see remarks in Conformance tag concerning Tag_conformance and No defaults tag concerning Tag_nodefaults).

consumer that needs the data in scope nesting order can obtain the file attributes, the section-related attributes, and the symbol-related attributes, by making three passes over the subsection.

Note

From the 2.09 release, section and symbol attributes are deprecated and optional. Primary object producers are discouraged from generating them and consumers are permitted to ignore them.

Conformance constraints

This ABI requires the following of files that claim to conform (Build attributes and conformance to the ABI) to the ABI.

  • Attributes that record data about the compatibility of this file with other files must be recorded in a public "aeabi" subsection.
  • Attributes meaningful only to the producer must be recorded in a private vendor subsection. These must not affect compatibility between relocatable files.

When a producer does not explicitly claim compatibility to the ABI, it may nonetheless publicly describe the effect on compatibility of its private attributes by using generic compatibility tags (Generic compatibility tag). These must record a safe approximation. The producer can record precise information that only its own tool chain comprehends in a private vendor subsection.

  • We intend that another tool chain should not mistakenly link incompatible files. The price of safety is that a tool chain might sometimes diagnose incompatibility between files that could be safely linked, because their compatibility has been approximated.
  • We do not expect that a tool chain should be able to comprehend the private data of a different tool chain (other than through private agreement among tool chains).

Coding extensibility and compatibility

As a specification like this evolves, legacy binary files and the tools that process them get out of step. This will cause difficulties when a tool must consume a public attributes subsection containing tags it does not comprehend (that is, when the tool follows an earlier version of the specification than the binary file).

The attributes defined in Public ("aeabi") attribute tags, below, carry a mix of information that consumers can safely ignore and information about incompatibility that must not be ignored. In the absence of further conventions, the only safe course for a tool to take on encountering an unknown tag would be to stop processing.

To support more graceful behavior in the face of an evolving set of public tags, we adopt these conventions.

  • Tags 0-63 convey information that a consuming tool must comprehend. This includes all the tags (1-32) defined by the first release (v1.0) of this addendum. A tool encountering an unknown tag in this range should stop processing or take similar defensive action (Q-o-I).
  • Tags 64-127 convey information a consumer can ignore safely (though maybe with degraded functionality).
  • For N \ge 128, tag N has the same properties as tag N modulo 128.

To allow an ignored tag and its parameter value to be skipped easily, we adopt this convention.

  • For N > 32, even numbered tags have a ULEB128 parameter and odd numbered ones have a null-terminated byte string (NTBS) parameter.
  • consumer must comprehend tags 1-32 individually.

Public ("aeabi") attribute tags

About public tags

A consumer must recognize the tags described in this section (Public ("aeabi") attribute tags) in vendor subsections named "aeabi".

Other vendor sections may re-use these tags, define their own tags, or use a completely different encoding of their private attribute data. In each case the meaning of the data is private to the defining vendor.

While public tags and their numerical parameters are specified as ULEB128-encoded, the values defined by this version, and all earlier versions, of the ABI encode identically as ULEB128 numbers and single byte numbers.

Default values for public tags

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.

producer must consider what value it intends to give to each public tag. In the absence of Tag_nodefaults (No defaults tag) a consumer should conclude that the producer intended to give the value 0 to each omitted public tag.

Inheritance of public tag values

An attribute can be given to a symbol, a section, or a relocatable file. Normally, each section in a file inherits the attributes defined at file level and each symbol defined in a section inherits the attributes of that section.

tag value given explicitly in a scope overrides a value that would otherwise be inherited. If Tag_nodefaults (No defaults tag) appears in a scope, enclosed empty scopes have undefined attribute values value rather than default zero values.

Semi formally we define the value of a public tag T in a scope S (one of Symbol, Section, or File) as follows.

value(T, S) \equiv S.empty() & S.parent.has(Tag_nodefaults) ? undefined :
              S.has(T) ? T.value :
              value(T, S.parent)
value(T, File.parent) \equiv 0

Where S.empty() \equiv not (S.has(T) for some T \ne Tag_nodefaults)
      S.has(T)  \equiv T and its value are given explicitly in scope S
      Symbol.parent \equiv Section; Section.parent \equiv File

In any scope it is erroneous to give two different values to the same attribute, though the same value may be given more than once.

Note

From the 2.09 release, section and symbol attributes are deprecated and optional. Primary object producers are discouraged from generating them and consumers are permitted to ignore them.

How this specification describes public attributes

In the following sections we describe each attribute in a uniform style, as follows.

Tag_tag_name (=tag value), parameter type (=uleb128 or NTBS)
   value  Comment
   value  Comment
   ...

Block commentary about the tag and its possible values.

Tag value gives the numerical representation of the tag. It is a small integer less than 128.

Parameter type gives the type of the parameter that immediately follows the tag in the attributes section. It is either a ULEB128-encoded integer or a NUL-terminated byte string (NTBS).

Following lines enumerate the currently defined parameter values, giving a short comment about each one.

block of explanatory text follows in some cases.

Miscellaneous attributes

Optimization attributes

The final pair of ABI-related tags record optimization goals. These are not required for reasoning about incompatibility, but assist with selecting appropriate variants of library members.

Tag_ABI_optimization_goals, (=30), uleb128
    0  No particular optimization goals, or no information recorded
    1  Optimized for speed, but small size and good debug illusion preserved
    2  Optimized aggressively for speed, small size and debug illusion sacrificed
    3  Optimized for small size, but speed and debugging illusion preserved
    4  Optimized aggressively for small size, speed and debug illusion sacrificed
    5  Optimized for good debugging, but speed and small size preserved
    6  Optimized for best debugging illusion, speed and small size sacrificed

With Tag_ABI_optimization_goals we capture one of three potentially conflicting intentions - high performance, small size, and easy debugging - at one of two levels.

At the first level the goal is unambiguous, but pursuit of it is constrained. The conflicting goals still matter, but less than the primary goal.

At the second level, the conflicting goals are insignificant in comparison to the primary goal. It is difficult to capture optimization intentions precisely, but to a significant degree what matters to a tool chain is the user's goal (speed, small size, or debug-ability), and whether or not the user is willing to sacrifice all other considerations to achieving that goal.

Tag_ABI_FP_optimization_goals, (=31), uleb128
    0  No particular FP optimization goals, or no information recorded
    1  Optimized for speed, but small size and good accuracy preserved
    2  Optimized aggressively for speed, small size and accuracy sacrificed
    3  Optimized for small size, but speed and accuracy preserved
    4  Optimized aggressively for small size, speed and accuracy sacrificed
    5  Optimized for accuracy, but speed and small size preserved
    6  Optimized for best accuracy, speed and small size sacrificed

With Tag_ABI_FP_optimization_goals we also capture one of three potentially conflicting goals at one of the same two levels as Tag_ABI_optimization_goals captures.

Some accuracy sacrificed is intended to allow, for example, re-association of expressions in generated code. In library code it is intended to permit the assumption that value ranges will be reasonable. In particular, binary to decimal and decimal to binary conversion may meet only the minimum standards specified by IEEE 754, and range reduction for trigonometric functions should be assumed to be naive.

Generic compatibility tag

The generic compatibility tag describes the limited compatibility this file might offer when no strong claim to conform to the ABI (Build attributes and conformance to the ABI) has been made using Tag_conformance (Conformance tag).

Tag_compatibility (=32), uleb128: flag, NTBS: vendor-name

An omitted tag implies flag = 0, vendor-name = "". An explicit flag value is not 0 and can be considered to be the first byte(s) of the vendor name for the purpose of skipping the entry. The default value of 0 describes the implicit claim made by files generated prior to v1.06 of this specification.

The defined flag values and their meanings are as follows.

  The tagged entity has no tool chain-specific requirements (and no vendor tag hides an ABI incompatibility)
1   This entity can conform to the ABI if processed by the named tool chain. The ABI variant to which it conforms is described solely by public "aeabi" tags
>1  The tagged entity does not conform to the ABI but it can be processed by other tools under a private arrangement described by flag and vendor-name

A flag value >1 identifies an arrangement, beyond the scope of the ABI, defined by the named vendor. A tool chain that recognizes the arrangement might successfully process this file. Note that a producer must use the name of the vendor defining the arrangement, not the name of the producing tool chain.

(Versions of this specification through v1.05 stated:

>1 The tagged entity is compatible only with identically tagged entities, and entities not tagged by this tool chain

The underlined part of that definition was a mistake that makes the definition useless. With the underlined part removed, the old definition is effectively compatible with, but more restrictive than, the new one).

Secondary compatibility tag

Tag_CPU_arch conceals a difficulty in relation to the 16-bit Thumb ISA: there is no way to tag an entity as compatible with both Arm7TDMI (architecture v4T) and Cortex-M1 (architecture v6-M variant).The set of instructions compatible with both targets excludes the 16-bit Thumb SVC (formerly SWI) instruction. In effect we need a pseudo architecture v4T-no-SVC to describe such code, but no such architecture exists so it cannot simply be added to the Tag_CPU_arch enumeration.

We have chosen to deal with this problem describing such code as v4T also compatible with v6-M (or as v6-M also compatible with v4T) using the following safely ignorable (Coding extensibility and compatibility) tag.

Tag_also_compatible_with (=65), NTBS: data

The data string must be further interpreted as a ULEB128-encoded tag followed by a value of that tag. If that value is numerical (i.e. ULEB128), there is an additional NUL byte following it. Thus, the data string value of the Tag_also_compatible_with tag must be in one of the following two formats:

  • ULEB128: tag, ULEB128: value, 0.
  • ULEB128: tag, NBTS: data.

The following byte sequence records the intention to also be compatible with architecture version v6-M.

Tag_also_compatible_with (=65) Tag_CPU_arch (=6) v6-M (=11) 0

At this release of the ABI (2018Q4) there are only two defined uses of Tag_also_compatible_with:

  • To express v4T also compatible with v6-M and v6-M also compatible with v4T.
  • To express v8-A also compatible with v8-R and v8-R also compatible with v8-A.

All other uses are RESERVED to the ABI. Future releases of the ABI may relax this constraint.

Conformance tag

The conformance tag describes the version of the ABI to which conformity is claimed by an entity.

Tag_conformance (=67), string: ABI-version

This version of the ABI is "2018Q4". The minor version (dot-xy) is for information and does not affect the claim. Version "0" denotes no claim to conform and is the default if the tag is omitted.

To simplify recognition by consumers in the common case of claiming conformity for the whole file, this tag should be emitted first in a file-scope sub-subsection of the first public subsection of the attributes section.

In this case, the dot-ARM-dot-attributes section would begin "A~~~~aeabi01~~~~C2018Q4", where '~' denotes an unknown byte value.

No defaults tag

The occurrence of a no defaults tag in an attributes sub-subsection indicates that the tag values inherited (Default values for public tags, Inheritance of public tag values) by entities in enclosed scopes with no explicitly given tags are UNDEFINED rather than 0.

Tag_nodefaults (=64), uleb128: ignored (write as 0)

consuming tool may take IMPLEMENTATION DEFINED action if any tag has an UNDEFINED value after a dot-ARM-dot-attributes section has been fully processed.

Consumers that do not recognize this tag will default UNDEFINED values to 0.

To make processing easy for consumers, this tag should be emitted before any other tag in an attributes sub-subsection other than the conformance tag (Conformance tag).

We expect the no defaults tag to be used only by linkers that merge attributed and un-attributed (legacy) relocatable files.

Note

From the 2.09 release, section and symbol attributes are deprecated and optional. Primary object producers are discouraged from generating them and consumers are permitted to ignore them. Hence from the 2.09 release use of this tag is deprecated.

Arm CPU names recognized by Arm Compiler 5.01 (armcc)

Arm Compiler 5.01 armcc recognizes the following Arm processor product names.

  • ARM7EJ-S
  • ARM7TM
  • ARM7TDM
  • ARM7TDMI
  • ARM710T
  • ARM720T
  • ARM740T
  • ARM7TM-S
  • ARM7TDMI-S
  • ARM810
  • ARM9TDMI
  • ARM920T
  • ARM922T
  • ARM940T
  • ARM9E-S
  • ARM9EJ-S
  • ARM926EJ-S
  • ARM946E-S
  • ARM966E-S
  • ARM968E-S
  • ARM1020E
  • ARM1022E
  • ARM1026EJ-S
  • ARM1136J-S
  • ARM1136JF-S
  • ARM1156T2-S
  • ARM1156T2F-S
  • ARM1176JZ-S
  • ARM1176JZF-S
  • MPCore
  • Cortex-M0
  • Cortex-M0plus
  • Cortex-M1
  • Cortex-M3
  • Cortex-M4
  • SC000
  • SC300
  • Cortex-R4
  • Cortex-R4F
  • Cortex-R5
  • Cortex-R7
  • Cortex-A5
  • Cortex-A7
  • Cortex-A8
  • Cortex-A9
  • Cortex-A15

(Many of these names are trademarks of Arm Limited. For details see http://www.arm.com/legal.html).

The following pseudo processor names are recognized as architecture version names.

  • 4
  • 4T
  • 5T
  • 5TE
  • 5TEJ
  • 6
  • 6K
  • 6T2
  • 6Z
  • 6-M
  • 6S-M
  • 7
  • 7-A
  • 7-R
  • 7-M
  • 7E-M

(Other Arm product version names and non-Arm product names are also recognized).

Attributes summary and history

Table 1, Summary and history of individual attributes lists the public attribute tag names and for each tag its numerical value, its parameter type, the ABI revision in which it was introduced, and the revisions in which its parameter values or meaning were amended.

program claiming conformance to revision r2.x of this ABI must comprehend tags with values less than 64 (Coding extensibility and compatibility) defined in revisions r2.x and earlier, and all parameter values defined for those tags by those revisions.

Table 2, History of attributes in ABI revisions and ABI-Addenda document versions summarizes amendments to the specification of build attributes ABI revision by ABI revision.

Table 1, Summary and history of individual attributes
Tag Value Parameter type ABI revision Amendments
Tag_File 1 uint32 r2.0  
Tag_Section 2 uint32 r2.0 r2.09: Use deprecated.
Tag_Symbol 3 uint32 r2.0 r2.09: Use deprecated.
Tag_CPU_raw_name 4 NTBS r2.0  
Tag_CPU_name 5 NTBS r2.0  
Tag_CPU_arch 6 uleb128 r2.0 r2.06: Added enum values for v6-M, v6S-M;
r2.08: Added enum value for v7E-M.
r2.09: Added enum value for v8.
Tag_CPU_arch_profile 7 uleb128 r2.0 r2.05: Added 'S' denoting 'A' or 'R' (don't care)
Tag_ARM_ISA_use 8 uleb128 r2.0  
Tag_THUMB_ISA_use 9 uleb128 r2.0  

Tag_FP_arch

(formerly Tag_VFP_arch)

10 uleb128 r2.0 r2.04: Added enum value for VFPv3
r2.06: Added enum value for VFPv3 restricted to D0-D15
r2.08: Renamed; added enum value for VFPv4 (adds fused MAC + 16-bit FP data in memory).
r2.09: Added enum value for v8-A FP
Tag_WMMX_arch 11 uleb128 r2.0 r2.02: Added enum value for wireless MMX v2.
Tag_Advanced_SIMD_arch 12 uleb128 r2.0 r2.08: Added enum value for Neon with fused MAC
r2.09: Clarified existing usages and added enum value for v8-A ASIMD
Tag_PCS_config 13 uleb128 r2.0  
Tag_ABI_PCS_R9_use 14 uleb128 r2.0 r2.08: Clarified that value = 2 denotes using R9 to emulate one of the architecturally defined thread ID registers in CP15 c13.
Tag_ABI_PCS_RW_data 15 uleb128 r2.0  
Tag_ABI_PCS_RO_data 16 uleb128 r2.0  
Tag_ABI_PCS_GOT_use 17 uleb128 r2.0  
Tag_ABI_PCS_wchar_t 18 uleb128 r2.0  
Tag_ABI_FP_rounding 19 uleb128 r2.0  
Tag_ABI_FP_denormal 20 uleb128 r2.0  
Tag_ABI_FP_exceptions 21 uleb128 r2.0 r2.09: fixed typo (missing 'permitted')
Tag_ABI_FP_user_exceptions 22 uleb128 r2.0  
Tag_ABI_FP_number_model 23 uleb128 r2.0  

Tag_ABI_align_needed

(formerly …_align8_needed)

24 uleb128 r2.0 r2.08: Generalized to extended alignment of 2n bytes for n in 4..12

Tag_ABI_align8_preserved

(formerly ..align8_preserved)

25 uleb128 r2.0 r2.08: Generalized to extended alignment of 2n bytes for n in 4..12
Tag_ABI_enum_size 26 uleb128 r2.0  
Tag_ABI_HardFP_use 27 uleb128 r2.0 r2.09: Clarified use of existing values and removed DP-only option
Tag_ABI_VFP_args 28 uleb128 r2.0 r2.09: Added enum value for code compatible with both the base and VFP variants
Tag_ABI_WMMX_args 29 uleb128 r2.0  
Tag_ABI_optimization_goals 30 uleb128 r2.0  
Tag_ABI_FP_optimization_goals 31 uleb128 r2.0  
Tag_compatibility 32 NTBS r2.0 r2.05: Revised the ineffective definition. The new one is compatible with the old one if a nonsensical clause in the old one is ignored.
Tag_CPU_unaligned_access 34 uleb128 r2.02  

Tag_FP_HP_extension

(was Tag_VFP_HP_extension)

36 uleb128 r2.06 r2.08: Renamed (VFP → FP)
r2.09: Clarified use of existing values.
Tag_ABI_FP_16bit_format 38 uleb128 r2.06  
Tag_MPextension_use 42 uleb128 r2.08  
Tag_DIV_use 44 uleb128 r2.08 r2.09: Changed wording to clarify meaning.
Tag_nodefaults 64 uleb128 r2.06 r2.07: Re-specified tag value inheritance more precisely (Inheritance of public tag values and No defaults tag). In the absence of Tag_nodefaults the specification reduces to that used before its introduction. We believe that only Arm tools are affected.
r2.09: Use deprecated as Tag_Section and Tag_Symbol are deprecated.
Tag_also_compatible_with 65 NTBS r2.05 r2.06: Restricted usage as noted in Secondary compatibility tag.
r2.09: Clarified data format.
Tag_conformance 67 NTBS r2.05  
Tag_T2EE_use 66 uleb128 r2.07 r2.09: Deprecated as not useful
Tag_Virtualization_use 68 uleb128 r2.07 r2.08: Added two enumeration values to support the 2009 virtualization extensions.
Tag_MPextension_use 70 uleb128 r2.07 r2.08: Recoded to 42 (must be recognized by tool chains). PLDW is a user-mode instruction, undefined in architecture v7 w/o MP extensions.
Table 2, History of attributes in ABI revisions and ABI-Addenda document versions
ABI Revision Doc vsn Date Amendments
r2.0 v1.0 March 2005 Initial release of the build attributes specification.
r2.01 v1.01 5th July 2005 Added extensibility and compatibility rules (now Coding extensibility and compatibility).
r2.02 v1.03 13th October 2005

Added wMMX v2 to Tag_WMMX_arch enumeration.

Added Tag_CPU_unaligned_access.

r2.03 v1.04 6th January 2006 No changes to the specification of build attributes.
r2.04 v1.05 8th May 2006 Added VFPv3 to Tag_FP_arch enumeration.
r2.05 v1.06 25th January 2007

Added introductory Introduction to build attributes.

Clarified that all current uleb128 values are also plain byte values.

Clarified inheritance of default values through nested scopes.

Clarified the definitionof conformance.

Added 'S' to the Tag_CPU_arch_profile enumeration.

Corrected the previously useless definition of Tag_compatibility.

Added Tag_also_compatible_with and Tag_conformance.

Added Procedure call-related attributes about combining attribute values.

Many minor editorial improvements.

r2.06 A October 2007

Major re-write of material with emphasis on clear presentation.

Added v6-M and v6S-M to Tag_CPU_arch enumeration.

Added VFPv3 restricted to D0-D15 to Tag_FP_arch enumeration.

Added Tag_FP_HP_extension, Tag_ABI_FP_16bit_format, and

Tag_nodefaults. Restricted the use of Tag_also_compatible_with in the face of persistent difficulties with its formal definition.

r2.07 B October 2008 Added Tag_T2EE_use, Tag_Virtualization_use and Tag_MPextension_use. Clarified tag value inheritance and the use of Tag_Nodefaults; clarified the meaning of Tag_CPU_name and Tag_CPU_raw_name.
r2.08 C October 2009 Added Tag_CPU_arch enum value V7E-M =13; renamed Tag_VFP_arch to Tag_FP_arch, added values for VFPv4; renamed Tag_VFP_HP_extension to Tag_FP_HP_extension; added value to Tag_Advanced_SIMD_arch for Neon with fused MAC; added values to Tag_Virtualization_use describing use of the virtualization extensions; recoded Tag_MPextension use to catch potential user-mode faults; added Tag_DIV_use to describe use of UDIV/SDIV in code for v7A. Clarified the role of R9 when used as a TLS (Tag_ABI_PCS_R9_use = 2). Renamed Tag_ABI_align8_needed, Tag_ABI_align8_preserved and extended them to extended 2n-byte alignment (for n in 4-12).
r2.09 D November 2012 Changed Tag_DIV_use wording to clarify meaning. Clarified Tag_also_compatible_with data format. Deprecated Tag_Section, Tag_Symbol and Tag_nodefaults. Added architecture v8 values to Tag_CPU_arch, Tag_FP_arch, Tag_Advanced_SIMD_arch. Clarified use of existing Tag_Advanced_SIMD_arch and Tag_FP_HP_extension values. Deprecated Tag_T2EE_use. Clarified use of Tag_ABI_HardFP_use values and removed DP-only option. Fixed typo (missing 'permitted') in Tag_ABI_FP_exceptions. Added enum value to Tag_ABI_VFP_args for code compatible with both the base and VFP variants.

ADDENDUM: Thread Local Storage

Introduction to thread local storage

Thread Local Storage (TLS) is a class of own data (static storage) that - like the stack - is instanced once for each thread of execution. It fits into the abstract storage hierarchy as follows.

  • (Most global) Program-own data (static and extern variables, instanced once per program/process).
  • Thread local storage (variables instanced once per thread, shared between all accessing function activations).
  • (Most local) Automatic data (stack variables, instanced once per function activation, per thread).

Thread local storage generates a number of issues at a number of levels, not all of which affect an ABI.

  • How to denote TLS in source programs.

    Gcc uses __tls T t…; Microsoft use __declspec(thread) T t…; this is Q-o-I.

  • How to represent the initializing images of TLS in object files, and how to define symbols in TLS.

    The rules for ELF are well established (see SHF_TLS, STT_TLS in [GELF])

  • How a loader or run-time system creates instances of TLS per-thread at execution time.

    This is part of ABI for the platform or execution environment.

  • How to relocate, statically and dynamically, with respect to symbols defined in TLS (for details of relocations relevant to Arm Linux see [AAELF]).

  • How code must address variables allocated in TLS (the subject of the notes below).

It is the last two bullet points that are the subject of this ABI.

Introduction to TLS addressing

In the most general form supported by Linux, Windows, and similar platforms, a program is constructed dynamically from an application and a number of shared libraries (called, respectively, DSOs or DLLs). Each component (application or shared library) can be mapped into multiple processes. Additionally, a DSO or DLL can be loaded dynamically by a program, rather than being part of the initial process image constructed when the program is first loaded.

For the purpose of addressing TLS, both Linux and Windows identify the components of an application using indexes. On both platforms, indexes are allocated dynamically when a process is created, or when a DSO or DLL is loaded dynamically. The details of how indexes are allocated are specific to a platform and differ significantly between Linux and Windows.

component can have a different TLS index in two different processes, so its thread index must be part of its program-own state (or be queried dynamically). The run-time system is responsible for maintaining a per-thread vector of pointers to allocated TLS regions indexed by these component indexes. Under both Linux and the Win32 API, access to the vector is hidden behind run-time functions.

There is a system resource (such as a dedicated register) called the thread pointer that, typically, points to a control block for the currently executing thread which, in turn, points to the TLS vector for that thread.

At this stage, the details of TLS addressing become quite platform specific. In the next subsection we describe the concepts appropriate to Linux for Arm, which is all that this revision of the ABI supports.

Linux for Arm TLS addressing

Linux for Arm TLS addressing architecture depicts the fundamental components of the TLS addressing architecture used by Linux for Arm.

addenda32-linux-tls.png

Linux for Arm TLS addressing architecture

In the most general case, the location of an imported thread local datum - or an exported datum that might be pre-empted - is represented by a pair of GOT entries that give:

  • The index in the dynamic thread vector of the pointer to the TLS block containing the datum (the application itself has index 1 and index 0 is reserved to the run-time system).
  • The offset of the datum in the pointed-to TLS block.

In the most general case the expression to address a thread local symbol S is:

(tp[0])[GOTS[0]] + GOTS[1]

Linux for Arm general dynamic model

In the general dynamic model, the addressing expression is packaged by a call to __tls_get_addr that takes a single parameter, the address of GOTS. The code sequence and required relocations are shown in Table 3, General dynamic model (time optimized), below.

space-optimized version of the general dynamic model that calls ___tls_get_addr (triple-underscore) is shown in Table 4, General dynamic model (space optimized), below. The parameter passed to ___tls_get_addr is the offset of GOTS from lr.

The Linux for Arm TLS model has two local dynamic variants. These are used to address component-local thread-local variables more efficiently, but it can still be used in a dynamically loaded DSO. (A variable is local if its symbol S has STB_LOCAL binding or non-STV_DEFAULT visibility). In these variants the offset of variable in the component's TLS segment in known at link time and only the component index must be loaded from the GOT. Specimen code sequences and relocations are given in Table 5, Local dynamic models, below. This model is advantageous whenever a function accesses more than one variable (the address of the TLS block can be a common sub-expression).

Table 3, General dynamic model (time optimized)
Location General dynamic model code sequence
.text
     ldr r0, .Lt0
.L1  add r0, pc, r0
     bl  __tls_get_addr              ; R_ARM_CALL(__tls_get_addr)
     ldr rS, [r0]                    ; Load S...
literal_pool
.Lt0 .word S(tlsgd) + [. - .L1 - 8]  ; R_ARM_TLS_GD32(S)
GOT[S]
.word                           ;  R_ARM_TLS_DTPMOD32(S)
.word                           ;  R_ARM_TLS_DTPOFF32(S)
Table 4, General dynamic model (space optimized)
Location General dynamic model (space optimized)
.text
     ldr r0, .Lt0
.L1  bl  __tls_get_addr                 ; R_ARM_CALL(__tls_get_addr)
     ldr rS, [r0]                       ; Load S...
literal pool
.Lt0 .word S(tlsgd) + [. - .L1 - 4]     ; R_ARM_TLS_GD32(S)
GOT[S]
.word                              ; R_ARM_TLS_DTPMOD32(S)
.word                              ; R_ARM_TLS_DTPOFF32(S)
Table 5, Local dynamic models
Location Local dynamic model Relocation Symbol
.text
     ldr r0, .Lt0
.L1  add r0, pc, r0
     bl  __tls_get_addr                     ; R_ARM_CALL(__tls_get_addr)

      ... r0 points to my TLS, a CSE ...

     ldr r1, .Lt1
     ldr rX, [r0, r1] ; long offset to X

     ...       ; but a short offset to Y

     ldr rY, [r0, #Y(tlsldo)]               ; R_ARM_TLS_LDO12(Y)
literal pool
.Lt0 .word X(tlsldm) + [. - .L1 - 8]        ; R_ARM_TLS_LDM32(X)
.Lt1 .word Y(tlsldo)                        ; R_ARM_TLS_LDO32(Y)
GOT[X]
.word                                  ; R_ARM_TLS_DTPMOD32(X)
.word 0

R_ARM_TLS_LDM32 sets the first element of the GOT pair to the symbol's dynamic TLS vector index, as does R_ARM_TLS_GD32, but sets the second element to 0 (as shown in Table 5, Local dynamic models, above).

TLS-related relocations for Linux for Arm are described further in [AAELF].

Linux for Arm static (initial exec) model

If DSOs need not be loaded dynamically, more efficient addressing modes can be constructed if the run-time system allocates TLS at process creation time. As depicted in Figure 3 1, the offset from the thread pointer tp to a component's TLS is then known at process creation time (dynamic link time), so a component can address its thread local variables relative to tp, without indexing the dynamic thread vector.

Below, $tp denotes a general purpose register containing the result of reading tp.

Table 6, General initial exec model, below, shows the general model. It works for DSOs and the root application, in Arm and Thumb state.

Table 7, Initial exec model, DSO with GOT pointer and small FPIC addressing (DSO only), below, shows an optimized model for DSOs If the compiler uses a GOT pointer (denoted by $gp) and small PIC (12-bit PC-relative) addressing. This model works only in Arm state.

Finally, Table 8, Initial exec model, access to an application's local thread-local variables shows the code to access an application's local thread-local variables. Because an application's TLS is allocated first in the initial TLS vector for the process, the offsets of its variables from tp are known at static link time and do not need to be read from the GOT. The 12-bit model works only in Arm state.

Table 6, General initial exec model
Location Initial exec model code sequence
.text
     ldr r0, .Lt0
.L1  ldr r0, [pc, r0]
     ...
     ldr rS, [$tp, r0] ; Load S...
literal pool
.Lt0 .word S(tpoff) + [. - .L1 - 8]    ; R_ARM_TLS_IE32(S)
GOT[S]
.word                             ; R_ARM_TLS_TPOFF32(S)
Table 7, Initial exec model, DSO with GOT pointer and small FPIC addressing (DSO only)
Location Initial exec model code sequence
.text
ldr r0, [$gp, #S(gottpoff)]       ; R_ARM_TLS_IE12GP(S)
...
ldr rS, [$tp, r0]  ; Load S...
GOT[S]
.word                             ; R_ARM_TLS_TPOFF32(S)
Table 8, Initial exec model, access to an application's local thread-local variables
Location Initial exec model code sequence
.text
ldr r0, .Lt0
...
ldr rX, [$tp, r0]        ; Load X
...
ldr rY, [$tp, #Y(tpoff)] ; Load Y     ; R_ARM_TLS_LE12(Y)
literal pool
.Lt0 .word S(tpoff)                        ; R_ARM_TLS_LE32(X)

TLS-related relocations for Linux for Arm are described further in [AAELF].

Reserved Names

For external symbols defined/required by the C++ ABI there are already agreed names - either the standard mangling of C++ names or names like __cxa_acquire_guard.

The ABI for the Arm Architecture also needs a space of global symbol names private to each compiler vendor - external names guaranteed not to clash with other vendors - and a C++ name space private to each vendor.

Many of these names have C or assembly language linkage, so we propose to reserve names of the form __vendor-name_name, for example:

  • __ARM_foo
  • __gnu_foobar
  • __cxa_foobaz

In each case, namespace __vendor-name[vn] is also reserved in C++, for example:

namespace __ARM {...}                namespace __ARMv2 {...}
namespace __gnuv1 {...}              namespace __aeabi {...}

We also reserve the corresponding upper case vendor name with a single leading underscore to use by the vendor for C macro names, for example:

#if _AEABI_... != 0
#if _ARM_... == 2

Prefix names themselves must not contain underscore ('_') or dollar ('$'). The following prefixes are registered.

Registered Vendors
Name Vendor
ADI Analog Devices
acle Reserved for use by Arm C Language Extensions.
aeabi Reserved to the ABI for the Arm Architecture (EABI pseudo-vendor)
AnonXyz anonXyz Reserved to private experiments by the Xyz vendor. Guaranteed not to clash with any registered vendor name.
ARM Arm Ltd (Note: the company, not the processor).
cxa C++ ABI pseudo-vendor
FSL Freescale Semiconductor Inc.
GHS Green Hills Systems
gnu GNU compilers and tools (Free Software Foundation)
iar IAR Systems
icc ImageCraft Creations Inc (ImageCraft C Compiler)
intel Intel Corporation
ixs Intel Xscale
llvm The LLVM/Clang projects
PSI PalmSource Inc.
RAL Rowley Associates Ltd
SEGGER SEGGER Microcontroller GmbH
somn SOMNIUM Technologies Limited.
TASKING Altium Ltd.
TI TI Inc.
tls Reserved for use in thread-local storage routines.
WRS Wind River Systems.

To register a vendor prefix with Arm, please E-mail your request to arm.eabi at arm.com.

Errata and Minor Addenda

This section details errors found in the ABI for the Arm Architecture after publication of version 2.0 and minor additions made since then.

DWARF for the Arm Architecture

Clarifications

(v2.01, r2.02) The ABI-v2.0 DWARF register numbering scheme for VFP registers (S0-S31 → 64-95) has been declared obsolescent. It will become obsolete in the next major release of the ABI for the Arm Architecture.

(B, r2.09) Common information entries: Clarify CIE descriptions of registers that are unused by intention of the user, for example as a consequence of the chosen procedure call standard.

Errors fixed

(v2.02, r2.04) Describing other endian data, suggested that DW_AT_endianness, coded as 0x5b, might be approved by the DWARF3.0 standardization committee. In fact, 0x5b was used for another purpose and DW_AT_endianity, coded as 0x65, has been approved. The parametric values of this attribute have also changed their names and encodings.

Additions and omissions fixed

(v2.01, r2.02) VFP-v3 and Neon register descriptions, specifies how to describe the VFP-v3/Neon SIMD register file. There is a new range of DWARF register numbers allocated to D0-D31 and new schemes for describing Neon Q registers and VFP S registers. The new numbering should also be used for VFP-v2.

ELF for the Arm Architecture

Clarifications

(v1.02, r2.03) ELF Header: Corrected the wording of the description of e_entry.

(v1.03, r2.04) ELF Header: Clarified that bit[0] of [e_entry] controls the instruction set selection on entry.

(v1.02, r2.03) Symbol names: Clarified the necessary restrictions on local symbol removal in relocatable files.

(v1.04, r2.05) Relocation types: Clarified that 'Pa' is the adjusted address of the place being relocated, with the Thumb-bit stripped (defined as P & 0xFFFFFFFE), for Thumb state LDR- and ADR-type relocations.

(v1.04, r2.05) Static Arm relocations: Clarified that R_ARM_LDR_PC_G0 applies equally to LDRB, STRB.

(v1.04, r2.05) Static Thumb32 relocations: Added this section explicitly tabulating the relocations specific to 32-bit Thumb instructions.

(v1.05, r2.06) Registered Vendor Names:: Inserted the complete table of registered vendor names, now shared among AAELF, CLIBABI, and RTABI.

(vC, r2.07) Introduction, Program Loading: Added small remarks to previously empty sections to remove any doubt that the sections might be accidentally empty.

(vC, r2.07) Static Arm relocations, subsection Call and Jump relocations: Listed R_ARM_PC24, R_ARM_CALL, R_ARM_JUMP24, R_ARM_THM_CALL, R_ARM_THM_JUMP24, and R_ARM_THM_JUMP19 as the only relocations that might cause an intra procedure call veneer to be generated.

(vC, r2.07) Static miscellaneous relocations: Clarified the definition of the R_ARM_V4BX relocation and use of the null symbol (index 0) by it.

(vC, r2.07) Dynamic relocations: Added additional text to table 4-16 for R_ARM_TLS_DTPMOD32 and R_ARM_TLS_TPOFF32 clarifying the meaning of relocating with respect to the null symbol (index = 0).

(vD, r2.08) References: Updated references to the Arm ARM to refer to the latest version published on http://infocenter.arm.com.

(vD, r2.08) Static Thumb32 relocations: Referenced the text in Static Arm relocations (under the subheading Call and Jump relocations) that describes the conditions under which a relocation is permitted to generate an ip-corrupting intra-call or long jump veneer.

(vE, r2.09) Static Thumb32 relocations: Clarified/extended note on what the Static Arm relocations text deals with.

(vE, r2.09) Relocation: Standardized instruction descriptions to use Arm ARM terminology.

(vE, r2.09) Addends and PC-bias compensation: Clarified initial addend formulation for MOVW/MOVT and R_ARM_THM_PC8.

(vE, r2.09) Dynamic relocations: In Table 4-16, Proxy generating relocations, clarified the wording for R_ARM_RELATIVE.

(vF, r2.10) Relocation types: Clarified relocation expression values are computed mod 2^32.

Errors fixed

(v1.01, r2.01) Section Types, Table 4-4, Processor specific section types: The definition of SHT_ARM_ATTRIBUTES was given the value 0x70000002, already allocated to SHT_ARM_PREEMPTMAP (used by RVCT 2.2 and others). The correct value of SHT_ARM_ATTRIBUTES is 0x70000003.

(v1.04, r2.05) Relocation types: Corrected the relocation formulae for the R_ARM_ALU_{PC|SB}_GN_NC relocations so that they uniformly include the obligation to set the T bit when this is required.

(v1.05, r2.06) Relocation types: Corrected the definition of Pa (introduced in r2.05) which had the wrong mask.

(v1.05, r2.06) Relocations for thread-local storage: Corrected the text following Table 4-15 Thumb relocation actions by instruction type, which misspelled R_ARM_TLS_LE32 (relocation #108) and R_ARM_TLS_LE12 (relocation #110).

(vB, r2.06) Static Thumb32 relocations: Corrected an error in Table 4-13, Static Thumb-16 Relocations where the instructions to which R_ARM_THM_PC12 and R_ARM_THM_ALU_PREL_11_0 apply had been transposed.

(vE, r2.09) Static Arm relocations: Changed the behaviour of jump relocations to unresolved weak references to be implementation-defined rather than undefined.

(vE, r2.09) Static Thumb32 relocations, Table 4-13, Static Thumb-16 Relocations: Corrected Result Mask for R_ARM_THM_PC12.

(vE, r2.09) Platform architecture compatibility data (ABI format): Corrected off-by-one error in size of array.

(vF, r2.10) Relocation types: Table 4-9, Relocation codes: Renumbered R_ARM_IRELATIVE from 140 to 160 (the number agreed with stakeholders; publication as 140 was incorrect). Table 4-11, Static Arm instruction relocations: Removed incorrect overflow check on R_ARM_MOVT_ABS, R_ARM_MOVT_PREL and R_ARM_MOVT_BREL.

Additions and omissions fixed

(v1.01, r2.01) Section Types, Table 4-4, Processor specific section types: The definition of SHT_ARM_PREEMPTMAP was omitted. The correct value is 0x70000002.

(v1.03, r2.04) Merging of objects in sections with SHF_MERGE, Merging of objects in sections with SHF_MERGE: Rules governing SHF_MERGE optimizations are needed to support inter-operation between tool chains (omitted from release 1.02 and earlier).

(v1.01, r2.01) Special Sections, Table 4-5, Processor specific section attribute flags: The definition and explanation of .ARM.preemptmap were omitted.

(v1.03, r2.04) Addends and PC-bias compensation, Addends and PC-bias compensation: Release 1.03 makes explicit the rules describing the required initial addends for REL-type relocations.

(v1.04, r2.05) Relocation types: Added additional relocations to support a new, experimental Linux TLS addressing model described in Relocations for thread-local storage, Relocations for thread-local storage.

(v1.02, r2.03) Relocations for thread-local storage: Added a definition of R_ARM_RELATIVE when S = 0; described the new, experimental, Linux TLS addressing model.

(v1.02, r2.03) Platform architecture compatibility data: Added a specification of architecture compatibility information for executable files.

(vC, r2.07) Section Types: Added SHT_ARM_DEBUGOVERLAY and SHT_ARM_OVERLAYSECTION to Table 4-4, Processor specific section types. These are new section types to support debugging overlaid programs.

(vC, r2.07) Special Sections: Added .ARM.debug_overlay and .ARM.overlay_table to Table 4-5, Processor specific section attribute flags. These are new special section names to support debugging overlaid programs.

(vD, r2.08) Static Thumb16 relocations, Table 4-12, Arm relocation actions by instruction type: extended the range of R_ARM_THM_PC8 to ADR as well as LDR(literal) instructions.

(vD, r2.08) Platform architecture compatibility data: Updated and tidied the text and added Platform architecture compatibility data (ABI format), as an informative proposal for recording executable file attributes.

(vE, r2.09) Sections: Added e_flags EF_ARM_ABI_FLOAT_HARD and EF_ARM_ABI_FLOAT_SOFT to indicate floating point PCS conformance, and EF_ARM_GCCMASK as a mask for legacy bits.

(vE, r2.09) Relocation types, Static Thumb32 relocations, Proxy generating relocations: added R_ARM_THM_GOT_BREL12.

(vE, r2.09) Relocation types, Table 4-9, Relocation codes: Reserved relocation 140 for a specific future use.

(vE, r2.09) Static Arm relocations, Table 4-12, Arm relocation actions by instruction type: Added entries for MOVW and MOVT.

(vE, r2.09) Static Thumb16 relocations, Table 4-13, Static Thumb-16 Relocations: Added Overflow column.

(vE, r2.09) Static Thumb32 relocations: Added Table 4-15 Thumb relocation actions by instruction type.

(vF, r2.10) Relocation types, Table 4-9, Relocation codes: Changed the subdivisions within the reserved/unallocated relocation space.

(vF, r2.10) Relocation, Table 4-9, Relocation codes, Table 4-13, Static Thumb-16 Relocations, Table 4-15 Thumb relocation actions by instruction type: Added R_ARM_THM_ALU_ABS_Gn[_NC] relocations.

(vF, r2.10) Section Attribute Flags, Table 4-5, Processor specific section attribute flags: Added SHF_ARM_NOREAD processor specific section attribute flag.

Procedure Call Standard for the Arm Architecture

Clarifications

(v2.05, r2.04) Added Machine Registers, clarifying the roles of core registers and co-processor registers in the AAPCS.

(v2.03, r2.02) Parameter Passing, clarified that a callee may overwrite an incoming parameter area on the stack.

(v2.03, r2.02) Handling values larger than 32 bits, described how VFP-v3 d16-d31 are used.

(v2.04, r2.04) Use of IP by the linker, clarified when linking may insert intra-call veneers that may corrupt r12 and the condition flags.

(v2.01, r2.01) Enumerated Types, following Table 5, Additional data types: Clarified that if a platform chooses that all container types should be word sized, the type of the container is int unless the upper bound of the enumerator exceeds 2147483647.

(vB, r2.07) VFP co-processor register candidates: Simplified duplicated text and clarified that homogeneous aggregates of containerized vectors are limited to four members.

(vC, r2.07) Homogeneous Aggregates: Minor clarifications and improvements to the terminology. Added a remark that source language access control does not affect the test for homogeneity.

(vC, r2.07) Parameter passing: Added a remark clarifying the requirement to 'back fill' unused coprocessor register candidates when passing floating-point parameters using the VFP variant of AAPCS.

(vD, r2.08) Enumerated Types: Re-wrote the specification to better reflect the intentions for enumerated types in ABI-complying interfaces.

(vE, r2.09) APPENDIX Support for Advanced SIMD Extensions: Re-written to clarify requirements on Advanced SIMD types.

Errors fixed

(v2.03, r2.02) Bit-fields, retracted the requirement that the type of a plain bit-field be unsigned by default.

(vF, r2.10) Advanced SIMD data types, corrected the element counts of poly16x4_t and poly16x8_t.

Additions and omissions fixed

(v2.05, r2.05) Handling values larger than 32 bits, added in support of the Advanced SIMD Architecture.

(v2.05, r2.05) VFP register usage conventions (VFP v2, v3 and the Advanced SIMD Extension), extended in support of the Advanced SIMD Architecture.

(v2.05, r2.05) Result Return, extended in support of the Advanced SIMD Architecture.

(v2.05, r2.05) Mapping between registers and memory format, added in support of the Advanced SIMD Architecture.

(v2.05, r2.05) VFP co-processor register candidates and Result return, extended in support of the Advanced SIMD Architecture.

(v2.05, r2.05) APPENDIX Support for Advanced SIMD Extensions, added in support of the Advanced SIMD Architecture.

(v2.06, r2.06) Fundamental Data Types: Added half-precision floating point to the data type table.

(v2.06, r2.06) Added Half-precision Floating Point.

(v2.06, r2.06) Result Return, VFP co-processor register candidates: Extended the rules to half-precision floating point.

(v2.06, r2.06) Added Half-precision Format Compatibility.

(v2.06, r2.06) Arithmetic Types: Added __f16 (as an Arm extension) to Table 3, Mapping of C & C++ built-in data types.

(v2.06, r2.06) Advanced SIMD data types: Added float16x4_t to Table 7: Advanced SIMD data types using 128-bit containerized vectors.

(vC, r2.07) Arithmetic Types: Specified in Table 3, Mapping of C & C++ built-in data types that the only values of _Bool/bool are 0 and 1.

(vC, r2.07) Enumerated Types: Specified container types for enumerated values larger than 32 bits.

(vC, r2.07) Additional Types: Clarified that in C++ __va_list is in namespace std.

(vE, r2.09) Result Return: Clarified that memory passed for a function result may be modified at any point during the function call.

(vE, r2.09) Arithmetic Types: Changed the illustrative source name of the half-precision float type from __f16 to __fp16 to match [ACLE].

(vF, r2.10) Advanced SIMD data types, added [u]int64x1_t, [u]int64x2_t, poly64x2_t. Result Return, Parameter Passing, Mapping between registers and memory format, VFP co-processor register candidates: Allow half-precision floating point types as function parameter and return types, by specifying how half-precision floating point types are passed and returned in registers.

(vF, r2.10) Composite Types: Added definitions of member alignment and natural alignment.

(vF, r2.10) Parameter Passing: Added parameter passing rules for over-aligned types.

Base Platform ABI for the Arm Architecture

Clarifications

(vC, r2.09) Adding export and import tables (if required): Clarify STB_WEAK definitions are treated as equivalent to STB_GLOBAL when generating a Windows-style export table.

(vC, r2.09) Post linking for DLL-like linkage: Give more details on export rules.

Errors fixed

(vB, r2.07) The DLL model and indirect addressing of imported entities: Made a minor correction to the dllimport example (does not affect the specification).

(vB, r2.07) Obligations on static linkers generating pre-emption maps: (In the final bullet point of the section) Changed depth-first traversal to the intended breadth-first traversal.

Library ABI for the Arm Architecture

Clarifications

(v2.01, r2.01) General: When a library function is added to a header (e.g. following additions to the C standard), any inline (e.g. macro-implemented) version should be hidden when _AEABI_PORTABILITY_LEVEL != 0.

(v2.01, r2.01) Encoding of ctype table entries and macros (_AEABI_PORTABILITY_LEVEL != 0): Names of macros (__A, __X, etc) are for illustration only and are not mandated by the specification.

(v2.04, r2.06) Private names for private and AEABI-specific helper functions: Inserted the complete table of registered vendor names, now shared among AAELF, CLIBABI, and RTABI.

(v2.04, r2.06) Naming issues in C++ header files: Added C++ names of C library functions, explaining why, when generating portable binary from C++, standard library functions should be used via extern "C" linkage.

(vC, r2.09) assert.h: Clarified the intended method of customizing assert().

Errors fixed

(v2.01, r2.01) locale.h, struct __aeabi_lconv: struct lconv should be struct __aeabi_lconv.

(v2.01, r2.01) setjmp.h, setjmp.h definitions: The text "((__aeabi_JMP_BUF_SIZE))" at the end of the table is left over from a previous version and should be deleted.

(v2.02, r2.02) Encoding of ctype table entries and macros (_AEABI_PORTABILITY_LEVEL != 0): The C99 isblank() function cannot be implemented as a macro within this framework because __B is required to exclude tab when used by the C89 function isprint() and to include it when used by isblank(). To fix this, we define isblank() out of line, but allow compilers to inline the obvious implementation that is excluded from being a macro because it evaluates its parameter twice.

(v2.03, r2.04) signal.h: Corrected misinformation suggesting that it might be possible to access 8-byte types using LDRD/STRD and LDM/STM.

(vC, r2.09) setjmp.h: Corrected calculation of minimum jmp_buf size (previously given as 24 double-words).

Additions and omissions fixed

(v2.01, r2.01) Library overview, library headers: The C99 header stdbool.h is missing. There are no portability implications of providing it. A new 5.14, describes stdbool.h, and Table 19, Summary of conformance requirements when _AEABI_PORTABILITY_LEVEL != 0 in 6 has a new entry for stdbool.h.

(v2.01, r2.01) ctype.h when _AEABI_PORTABILITY_LEVEL != 0 and isxxxxx inline: The same character translations and locale bindings should be used for the implementations of the toxxxx macros and functions as are used for the isxxxx macros and functions.

(vD, r2.10) wchar.h: Permit wint_t to be unsigned int.

C++ ABI for the Arm Architecture

Clarifications

(v2.02, r2.03) Inter-DLL visibility rules for C++ ABI-defined symbols: Clarify that entities defined in unnamed namespaces must not be exported (because unnamed namespaces do not have globally defined names).

(v2.03, r2.04) In Library helper functions, Code example for __aeabi_atexit, Static object destruction: Clarified the use of __aeabi_atexit for registering atexit functions.

(v2.04, r2.06) In References, Updated the base standard for C++ to ISO/IEC 14882:2003.

(vD, r2.09) Summary of differences from and additions to the generic C++ ABI: Clarified handling of empty classes.

(vE, r2.10) Summary of differences from and additions to the generic C++ ABI: Again clarified handling of empty classes.

Errors fixed

(v2.01, r2.01) Static object construction and destruction: The global constructor vector section (.init_array) of ELF type SHT_INITARRAY, was erroneously specified to be read-only. The generic ELF specification requires these sections to have the SHF_WRITE flag set. The C++ ABI for the Arm Architecture requires producers to generate these sections as if they were read-only. (Some execution environments require .init_array sections to be read-only and linkers targeting these environments may drop the SHF_WRITE flag. Doing so must not cause run-time failures).

(vB, r2.07) In Summary of differences from and additions to the generic C++ ABI, removed the Arm-specified mangling of the 16-bit FP type name added in r2.06 (Dh has been specified by the generic C++ ABI). Noted the mangling of std::va_list now that [AAPCS] affirms that __va_list is in namespace std.

(vC, r2.08) In Library helper functions: corrected typos in and the wording of the justification for defining __aeabi_vec_delete3 but not __aeabi_vec_delete2.

(vC, r2.08) Library helper functions: In the definition of __aeabi_vec_ctor_nocookie_nodtor, corrected the order of size and count parameters to __aeabi_vec_ctor_cookie_nodtor().

(vC, r2.08) In Inter-DLL visibility rules for C++ ABI-defined symbols: corrected broken class export syntax and corrected comments about entities declared in unnamed namespaces and those derived from them.

Additions and omissions fixed

(v2.04, r2.06) In Summary of differences from and additions to the generic C++ ABI, specified the name mangling (GC++ABI 5.1.5) for the 16-bit FP type added to [AAPCS].

(v2.04, r2.06) In ELF binding of static data guard variable symbols, added an Arm-specific rule for the ELF binding of guard variable symbols.

Exception Handling ABI for the Arm Architecture

Clarifications

(v2.04, r2.05) In paragraph 5 in Phase 2 unwinding, clarified that an unwinder must in general restore all the machine registers listed in the VRS.

(v2.02, r2.02) In Implications for implementations, and Compiler helper functions, we clarify that _Unwind_Complete may overwrite UCB fields specific to the exception propagation that has just completed, and make clear the consequences of this. In Compiler helper functions we are less prescriptive about which of__cxa_allocate_exception and __cxa_throw initialize the UCB and LEO fields.

(vB, r2.10) Throughout, use UAL instruction mnemonics where possible.

Errors fixed

(v2.02, r2.02) In Compiler helper functions, we have added the specification of __cxa_get_exception_ptr. Adding this function and having compilers generate calls to it, corrects a non-conformance with the C++ Standard. This function was recently added to the Itanium ABI, from which the Arm EHABI is derived. There are consequential changes to Data structures, bullet 1 to mandate that barrier_cache.bitpattern[0] is valid on catch handler entry and to Compiler helper functions in the definition of __cxa_begin_catch, regarding initialisation of barrier_cache.bitpattern[0]. Handlers and landing pads adds an example of using __cxa_get_exception_ptr in a handler entry sequence.

Detailed rationale: The C++ Standard states that std::uncaught_exception() should return true after completing evaluation of the object to be thrown until completing the initialization of the exception-declaration in the matching catch handler. Thus for example:

 try {
   // .......
   throw S();
   // ........
 } catch (S s) {
   // ......
}

uncaught_exception() should return true between the end of the S() call and the end of the initialization of s. This has not been the case in several implementations, such as g++ and RVCT 2.2, where uncaught_exception() was incorrectly false during any copy construction of s. Version 2.0 of the EHABI cannot handle this case correctly.

The original Itanium spec declared void __cxa_begin_catch(void *exceptionObject) and required it be called on entry to a catch handler, and in some other circumstances, to perform some housekeeping including updating the uncaught_exception count. The void *exceptionObject is really intended to be a pointer to (IA_64 terminology) an _Unwind_Exception object, the language-independent sub-object within a propagated exception object. The handler code itself (as Arm understands it) was supposed to obtain a pointer to the matched C++ object by being passed such a pointer in a machine register, or by some other unspecified means. In EHABI terminology, _Unwind_Exception is _Unwind_Control_Block.

The g++ community, HP, and Arm all changed __cxa_begin_catch to return the pointer to the matched C++ object, thus avoiding the need to save the register containing the matched object pointer over the call to __cxa_begin_catch. On return from __cxa_begin_catch, initialization of the catch parameter then proceeds. In other words, the code sequence is BL __cxa_begin_catch, initialize catch parameter if there is one.

Unfortunately, because __cxa_begin_catch has updated the uncaught_exception count, uncaught_exception() will return the wrong value if it is called during the initialization - as is possible if the catch parameter is a class type with non-trivial copy constructor. This is corrected by using the new routine, when the code sequence for catches with a parameter of class type with a non-trivial copy constructor becomes:

save r0 somewhere
BL __cxa_get_exception_ptr
initialize catch parameter
recover r0
BL __cxa_begin_catch

The wording change in Compiler helper functions precludes the unlikely (and undesirable) possibility that handler code received the matched object pointer in some other place, then copied it to barrier_cache.bitpattern[0], without overly constraining the implementation.

Additions and omissions fixed

(v2.02, r2.02) In Language-independent unwinding types and functions, we have added _Unwind_DeleteException whose behaviour is described in Cross-language support, and object deletion. This function is present in the Itanium ABI and is a convenience function with no cost if not used by an implementation. Some vendors have requested Arm add this to remove a need for conditional compilation when targeting the Arm ABI verses other ABIs. The Arm definition is compatible with the Itanium requirements.

(v2.02, r2.02) In Assignment to VRS registers, Reading from VRS registers, Moving from stack to VRS, and Frame unwinding instructions, we have added support for VFPv3. The Arm VFP v3 adds 16 double precision registers, D16-D31. It should be possible to restore these during unwinding but because the registers are intended for scratch use, this is expected to be uncommon. Specifically:

  • In Assignment to VRS registers, we extend the register range for _UVRSC_VFP/_UVRSD_DOUBLE to 0-31.
  • In Reading from VRS registers, we extend the register range for _UVRSC_VFP/_UVRSD_DOUBLE to 0-31.
  • In Moving from stack to VRS, we clarify that _UVRSC_VFP/_UVRSD_DOUBLE undoes the effect or one or more FSTMD instructions.
  • In Frame unwinding instructions we allocate unwinding instruction "11001000 sssscccc" to popping D[16+ssss]-D[16+ssss+cccc], to permit recovery of a range of the new registers (including any range containing just one register).
  • In Frame unwinding instructions Update the remarks (split remark d and add extra words) to clarify the limitations of VFP unwinding instructions (No incompatible change)

Run-time ABI for the Arm Architecture

Clarifications

(v2.03, r2.06) Private names for private and AEABI-specific helper functions: Inserted the complete table of registered vendor names, now shared among AAELF, CLIBABI, and RTABI.

(v2.03, r2.06) Integer (32/32 → 32) division functions: Clarified the meaning of signed integer division when the result cannot be represented (MIN_INT/-1).

(vB, r2.07) Helper functions defined by the C++ ABI for the Arm Architecture: Add return value comments to each of the __aeabi_* helper functions.

(vC, r2.08) Introduction: added __hardfp_ name mangling, to explain legacy, deprecated __hardfp_ name mangling implemented by some compilers, notably armcc.

(vC, r2.08) The floating-point helper functions: improved text specifying the registers maybe affected by a call to an FP helper.

Errors fixed and features withdrawn or deprecated

(v2.02, r2.05) The floating-point helper functions, deprecated use of fneg and dneg because inlining these functions is always more efficient, even with the Thumb-1 ISA. Conforming library implementations must still provide implementations.

(vC, r2.08) The floating-point helper functions: declared fneg/dneg obsolete (withdrawn).

Additions and omissions fixed

(v2.01, r2.02) In (new) Thread-local storage (new in v2.01), we define __aeabi_read_tp() that returns the thread pointer denoted by $tp in Linux for Arm static (initial exec) model, of this specification.

(v2.01, r2.02) In Exception-handling support, brought the list of __cxa_ functions up to date and in line with [EHABI].

(vC, r2.08) The floating-point helper functions: added to Standard conversions between floating types, conversion helpers between VFPv3 half-precision memory format and float.

(vD, r2.09) The floating-point helper functions: added to Standard conversions between floating types, conversion helpers from double to VFPv3 half-precision memory format.

ABI for the Arm Architecture - The Base Standard

Clarifications

(vB, r2.07) note about ar format, A note about ar format: Fixed one minor typographical error and added a newly found Wikipedia reference to ar format.

Was this page helpful? Yes No