Document number: IHI 0057C, current through AArch64 ABI release 2019Q4
Date of Issue: 30th January 2020
This document describes the use of the DWARF debug table format in the Application Binary Interface (ABI) for the Arm 64-bit architecture.
DWARF, DWARF 3.0, use of DWARF format
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.
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).
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 ©  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
- DWARF for the Arm® 64-bit Architecture (AArch64)
- About this document
- Arm-specific DWARF definitions
The following support level definitions are used by the Arm ABI specifications:
- 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.
- 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.
- The content of this specification is a draft, and Arm considers the likelihood of future incompatible changes to be significant.
Content relating to SVE and Pointer Authentication should be considered as having a Beta support level. This includes:
- DWARF register names marked as Beta in DWARF register names
- Call frame instructions (Call frame instructions (Beta))
- DWARF expression operations (DWARF expression operations (Beta))
All other content in this document is at the Release quality level.
|00bet3||16th December 2010||MGD||Beta release.|
|1.0||22nd May 2013||RE||First public release.|
|2018Q4||31st December 2018||OS||Add SVE and pointer authentication support.|
|2019Q4||30th January 2020||TS||Minor layout changes.|
This document refers to, or is referred to by, the following documents.
|Ref||External reference or URL||Title|
|AADWARF||DWARF for the Arm 64-bit Architecture (AArch64).|
|GDWARF||http://dwarfstd.org/Dwarf3Std.php||DWARF 3.0, the generic debug table format.|
The ABI for the Arm 64-bit Architecture uses the following terms and abbreviations.
- The instruction set named Arm in the Armv7 architecture; A32 uses 32-bit fixed-length instructions.
- The instruction set available when in AArch64 state.
- Procedure Call Standard for the Arm 64-bit Architecture (AArch64).
- The 32-bit general-purpose register width state of the Armv8 architecture, broadly compatible with the Armv7-A architecture.
- The 64-bit general-purpose register width state of the Armv8 architecture.
Application Binary Interface:
- 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.
- A 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, ELF for the Arm Architecture, …
- … based on the Arm architecture …
- Floating point
- Depending on context floating point means or qualifies: (a) floating-point arithmetic conforming to IEEE 754 2008; (b) the Armv8 floating point instruction set; (c) the register set shared by (b) and the Armv8 SIMD instruction set.
- 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.
- Pointer Authentication Code.
- Pointer Authentication Extension.
- Single Instruction Multiple Data – A term denoting or qualifying: (a) processing several data items in parallel under the control of one instruction; (b) the Arm v8 SIMD instruction set: (c) the register set shared by (b) and the Armv8 floating point instruction set.
- SIMD and floating point
- The Arm architecture’s SIMD and Floating Point architecture comprising the floating point instruction set, the SIMD instruction set and the register set shared by them.
- Scalable Vector Extension.
- The instruction set named Thumb in the Armv7 architecture; T32 uses 16-bit and 32-bit instructions.
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.
- 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.
- 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.
- 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)
The ABI for the Arm 64-bit architecture specifies the use of DWARF 3.0 format debugging data. For details of the base standard see GDWARF.
The ABI for the Arm 64-bit architecture gives additional rules for how DWARF 3.0 should be used, and how it is extended in ways specific to the Arm 64-bit architecture. The following topics are covered in detail:
- The enumeration of DWARF register numbers for using in
.debug_infosections (DWARF register names).
- The definition of Canonical Frame Address (CFA) used by this ABI (Canonical frame address).
- The definition of Common Information Entries (CIE) used by this ABI (Common information entries).
- The definition of Call Frame Instructions (CFI) used by this ABI (Call frame instructions (Beta)).
- The definition of DWARF Expression Operations used by this ABI (DWARF expression operations (Beta)).
GDWARF, §2.6.1, Register Name Operators, suggests that the mapping from a DWARF register name to a target register number should be defined by the ABI for the target architecture. DWARF register names are encoded as unsigned LEB128 integers.
|DWARF register number||AArch64 register name||Description|
|0–30||X0–X30||64-bit general registers (Note 1)|
|31||SP||64-bit stack pointer|
|33||ELR_mode||The current mode exception link register|
|34||RA_SIGN_STATE (Beta)||Return address signed state pseudo-register (Note 8)|
|46||VG (Beta)||64-bit SVE vector granule pseudo-register (Note 2, Note 3)|
|47||FFR (Beta)||VG×8-bit SVE first fault register (Note 4)|
|48-63||P0-P15 (Beta)||VG×8-bit SVE predicate registers (Note 4)|
|64-95||V0-V31||128-bit FP/Advanced SIMD registers (Note 5, Note 7)|
|96-127||Z0-Z31 (Beta)||VG×64-bit SVE vector registers (Note 6, Note 7)|
- The size of a general register is to be taken from context. For instance in a
.debug_infosection if the
DW_AT_locationattribute of a variable is
DW_OP_reg0then the number of significant bits in the register is determined by the variable’s
DW_AT_typeattribute. If no context is available (for example in
.eh_framesections) then the register number refers to a 64-bit register.
- The value of the SVE vector granule pseudo-register is an even integer in the range 2 to 32. The value of the register is the available size in bits of the SVE vector registers in the current call frame divided by 64.
- The SVE vector granule pseudo-register enables the construction of DWARF
expressions that require the use of the current vector length, such as the
location of saved SVE predicate and vector registers on the stack using the
DWARF stack frame operator
- The available size of a SVE predicate register and the first fault register is VG×8-bits.
- In a similar manner to the general register file the size of an FP/Advanced SIMD register is taken from some external context to the register number. If no context is available then only the least significant 64 bits of the register are referenced. In particular this means that the most significant part of a SIMD register is unrecoverable by frame unwinding.
- The available size of the SVE vector registers is VG×64-bits.
The architecture defines that the FP/Advanced SIMD registers (V registers) overlap with the SVE vector registers (Z registers). A given V register is mapped to the low 128-bits of the corresponding Z register.
The DWARF call frame instructions do not explicitly specify the size of a register; this is implicit in the definition of the register. As a consequence the V registers and Z registers have been allocated separate DWARF register number ranges which have their own definition for the size of these registers.
When searching the call frame information table for either a V register or a Z register a consumer must take into account the aliasing between the V and Z registers.
- The RA_SIGN_STATE pseudo-register records whether the return address has been signed with a PAC. This information can be used when unwinding. It is an unsigned integer with the same size as a general register. Only bit is meaningful and is initialized to zero. A value of 0 indicates the return address has not been signed. A value of 1 indicates the return address has been signed.
The term Canonical Frame Address (CFA) is defined in GDWARF, §6.4, Call Frame Information.
This ABI adopts the typical definition of CFA given there:
The DWARF virtual unwinding model is based, conceptually, on a tabular structure
with one column for each target register (GDWARF, §6.4.1, Structure of Call
Frame Information). A
.debug_frame Common Information Entry (CIE) specifies
the initial values (on entry to an associated function) of each register.
The variability of execution environments conforming to the Arm architecture creates a problem for this model. A producer cannot reliably enumerate all the registers in the target. For example, an integer-only function might be included in one executable file for use in execution environments with floating-point and another for use in environments without. In effect, it must be acceptable for a producer not to initialize, in a CIE, registers it does not know about. In turn this generates an obligation on consuming debuggers to default missing initial values.
This generates the following obligations on producers and consumers of CIEs:
Consumers must default the CIE initial value of any target register not mentioned explicitly in the CIE.
Callee-saved registers (and registers intentionally unused by the program, for example as a consequence of the procedure call standard) should be initialized as if by
DW_CFA_same_value, other registers as if by
A debugger can use built-in knowledge of the procedure call standard or can deduce which registers are callee-saved by scanning all CIEs.
The VG pseudo-register should be initialized as if by
RA_SIGN_STATEpseudo-register should be initialized as described in Section 3.3.
To allow consumers to reliably default the initial values of missing entries by scanning a program’s CIEs, without recourse to built-in knowledge, producers must identify registers not preserved by callees, as follows:
- If a function uses any register from a particular hardware register class
(e.g. Arm core registers), its associated CIE must initialize all the
registers of that class that are not callee-saved to
- If a function uses a callee-saved register R, its associated CIE must
initialize R using one of the defined value methods (not
(As an optimization, a producer need not initialize registers it can prove cannot be used by any associated functions and their descendants. Although these are not callee-saved, they are not callee-used either.)
- If a function uses any register from a particular hardware register class (e.g. Arm core registers), its associated CIE must initialize all the registers of that class that are not callee-saved to
This ABI defines a single CIE augmentation character that may appear as part of a CIE augmentation string. This is the character ‘B’, when present this indicates associated frames are using the B key for return address signing.
This ABI defines one vendor call frame instruction
|Instruction||High 2 bits||Low 6 bits||Operand 1||Operand 2|
DW_CFA_AARCH64_negate_ra_state operation negates bit of the
RA_SIGN_STATE pseudo-register. It does not take any operands.
This ABI defines one vendor DWARF expression operation
DW_OP_AARCH64_operation takes one mandatory operand encoded
as an unsigned LEB128. Bits[6:0] of this value specify an AArch64
DWARF Expression sub-operation. The remaining operands and the
action performed are as specified by the sub-operation. The
DW_OP_AARCH64_operation allows this ABI to define operations
specific to the Arm 64-bit architecture outside the encoding space
of DWARF expression operations.
DW_SUB_OP_AARCH64_sign sub-operation takes a single operand
encoded as an unsigned LEB128 operand. This value specifies a pointer
key signing operation given in AArch64 DWARF pointer signing operations. The top
two stack stack entries are popped, the first is treated as an 8-byte
address value to be signed and the second is treated as an 8-byte salt.
The key signing operation is performed on the address value using the
salt, and the result is pushed to the stack.