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.

DWARF for the Arm ® Architecture

Document number: IHI 0040C, current through ABI release 2018Q4

Date of Issue: 21st December 2018


Preamble

Abstract

This document describes the use of the DWARF debug table format in the Application Binary Interface (ABI) for the Arm architecture.

Keywords

DWARF, DWARF 3.0, use of DWARF format

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
1.0 30th October 2003 LS First public release.
2.0 24th March 2005 LS Second public release.
2.01 6th October 2006 LS Added register numbers for VFP-v3 d0-d31 (DWARF register names).
2.02 5th May 2006 LS Minor corrections now that DWARF 3.0 is a standard; incompatible changes to the values of DW_AT_endianity (Describing other endian data) as a result.
A 25th October 2007 LS Document renumbered (formerly GENC-003533 v2.02).
B r2.09 30th November 2012 AC 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.
2018Q4 21st December 2018 OS Minor typographical fixes, updated links.

References

This document refers to, or is referred to by, the following documents.

Ref External reference or URL Title
AADWARF   DWARF for the Arm Architecture
BSABI   ABI for the Arm Architecture (Base Standard)
GDWARF http://dwarfstd.org/Dwarf3Std.php DWARF 3.0, the generic debug table format.

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

Acknowledgements

This specification has been developed with the active support of the following organizations. In alphabetical order: Arm, CodeSourcery, Intel, Metrowerks, Montavista, Nexus Electronics, PalmSource, Symbian, Texas Instruments, and Wind River.

Overview

The ABI for the Arm architecture specifies the use of DWARF 3.0-format debugging data. For details of the base standard see GDWARF.

The ABI for the Arm architecture gives additional rules for how DWARF 3.0 should be used, and how it is extended in ways specific to the Arm architecture. The following topics are covered in detail.

Miscellaneous obligations on producers of relocatable files

Support for stack unwinding

To support stack unwinding by debuggers, producers must always generate .debug_frame sections, even when:

  • Not generating other debug tables.
  • At high optimization levels.
  • Assembling hand-written assembly language, if that code calls code compiled from C or C++.

The debugging illusion (not mandatory)

Ideally, a user of a C/C++ source language debugger would like the illusion of:

  • Stepping through the source program sequence point (SP) by sequence point.
  • Being able to inspect the program's state at any sequence point, and seeing there the state predicted by the source language semantics.

For the purpose of debugging illusion, we define an observation point (OP) to be a point at which a debugger may (meaningfully) inspect a program's state. Most sequence points are also observation points. In addition

  • There is an OP just after each function call (at the pc value to which the call will return).
  • There is no OP at the SP after evaluation of function arguments but before the function call.

variable's scope extends from the point of declaration of the identifier to the end of the smallest enclosing block. A variable need not have a value everywhere in its scope - it may be initialized some way after its declaration.

When a user signals to a producer (by Q-o-I means) that it should favour quality of debugging over quality of generated code, the producer should strive (Q-o-I) to generate DWARF tables and code supporting this illusion. Specifically:

  • A statement should describe the code between consecutive OPs.
  • At each OP, every in-scope, initialized, source code variable should have a location (need not be in memory), and that location should hold the value predicted by the source language semantics.

It is not necessary to describe OPs in code the producer knows can never be executed (e.g. in if(0){i++;}).

Arm-specific DWARF definitions

DWARF register names

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. Numbers 0-127 encode in 1 byte, 128-16383 in 2 bytes.

Mapping from DWARF register number to Arm architecture register number
DWARF register number Arm core or co-processor registers Description
0-15 R0-R15 Arm core integer registers
16-63 None Obsolescent: 16-47 were previously used for both FPA and VFP registers (Note 1)
64-95 S0-S31 Legacy VFP-v2 use: D0-D15 alias S0, S2, … S30 ( Note 1, Note 4)
96-103 F0-F7 Obsolescent: FPA registers 0-7 (Note 1)
104-111 wCGR0-wCGR7 Intel wireless MMX general purpose registers 0-7
ACC0-ACC7 XScale accumulator register 0-7 (Note 2)
112-127 wR0-wR15 Intel wireless MMX data registers 0-15
128 SPSR Current SPSR register
129 SPSR_FIQ FIQ-mode SPSR
130 SPSR_IRQ IRQ-mode SPSR
131 SPSR_ABT ABT-mode SPSR
132 SPSR_UND UND-mode SPSR
133 SPSR_SVC SVC-mode SPSR
134-143 None Reserved for future allocation
144-150 R8_USR-R14_USR User mode registers
151-157 R8_FIQ-R14_FIQ Banked FIQ registers
158-159 R13_IRQ-R14_IRQ Banked IRQ registers
160-161 R13_ABT-R14_ABT Banked ABT registers
162-163 R13_UND-R14_UND Banked UND registers
164-165 R13_SVC-R14_SVC Banked SVC registers
166-191 None Reserved for future allocation
192-199 wC0-wC7 Intel wireless MMX control register in co-processor 0-7
200-255 None Reserved for future allocation
256-287 VFP-v3/Neon D0-D31 VFP-v3/Neon 64-bit register file (Note 4)
288-319 None Reserved to VFP/Neon
320-8191 None Reserved for future allocation
8192-16383 Vendor co-processor Unspecified vendor co-processor register (Note 3)

Notes

  1. In ADS toolkits, DWARF names 16-23 were used to represent FPA registers F0-F7 and 16-47 were used to represent VFP registers S0-S31. No application needs to use both numberings simultaneously but it can complicate decoding, so in RVDS new, non-overlapping, numbers 64-95 were allocated to VFP S0-S31. Debuggers that need to support legacy objects may need to handle both mappings.
  1. Current implementations of the version 1 XScale Architecture specification implement only acc0, though eight such registers (acc0-acc7) are defined architecturally in co-processor 0. The version 2 specification defines the Wireless MMX co-processor in Arm co-processor slots 0 and 1. No system can contain both acc0 and MMX, so these numberings can overlap.
  1. The vendor co-processor space is not specified by this ABI and should be used when there is unlikely to be a requirement for multiple vendors to support debugging such code. By using numbers in this space vendors can be sure that they will not conflict with future ABI allocations. If a set of co-processor registers is likely to be used directly from a high-level language and to require support of multiple toolkit vendors, then an application should be made to Arm for an allocation of a numbering in the reserved space.
  1. The VFP-v3 and Neon architectures extend the register file to 32 64-bit registers, posing significant difficulties to extending the ABI v2.0 VFP encodings. There is no simple scheme using 1-byte register numbers that is compatible with the legacies. We have, therefore, introduced a new, simple, more precisely specified scheme using 2-byte register numbers. The new numbering scheme should also be used for VFP-v2.

The CPSR, VFP and FPA control registers are not allocated a numbering above. It is considered unlikely that these will be needed for producing a stack back-trace in a debugger.

VFP-v3 and Neon register descriptions

Architecturally, VFP-v3 and the Neon SIMD unit share a register file comprising 32 64-bit registers, D0-D31. Registers D0-D31 are described by DWARF register numbers 256-287. Register numbers 288-319 are reserved in case of future register file expansion.

DWARF registers 64-95 are obsolescent (and will become obsolete in the next major revision of the ABI for the Arm Architecture).

In DWARF terms:

  • Register Dx is described as DW_OP_regx(256+x).

  • registers Q0-Q15 are described by composing two D registers together.

    Qx = DW_OP_regx(256+2x) DW_OP_piece(8) DW_OP_regx(256+2x+1) [DW_OP_piece(8)]

    (Note that the final DW_OP_piece(8) can be omitted because the whole register is used. It is left in above for expositional clarity).

  • S registers are described as bit-pieces of a register

    • S[2x] = DW_OP_regx(256 + (x >> 1)) DW_OP_bit_piece(32, 0)
    • S[2x+1] = DW_OP_regx(256 + (x >> 1)) DW_OP_bit_piece(32, 32)
  • Neon Half-word lanes and byte lanes are described in a similar way to S registers.

Producers should use this new numbering scheme for VFP-v2 before the ABI-v2.0 scheme (S0-S31 → 64-95) is declared obsolete. Consumers should accept both numberings for as long as there are legacy binaries.

DWARF line number information (ISA field)

GDWARF 6.2.5.2 Standard Opcodes, item 12, DW_LNS_set_isa, describes a single unsigned LEB128 operand that denotes the instruction set architecture (ISA) at the location identified by the line number table entry. The value of the operand is determined by the ABI for the architecture (this specification).

Under the Arm architecture there are many instruction set versions and variants, but few instruction set states. Under this ABI, the ISA field corresponding to a particular program address denotes the instruction set state encoded by the CPSR when the pc contains that address.

DW_LNS_set_isa values for the Arm Architecture
Name Value Meaning
DW_ISA_UNKNOWN 0 I-set state not available or not recorded.
DW_ISA_ARM_thumb 1 T-bit will be set in the CPSR when pc contains this code address.
DW_ISA_ARM_arm 2 T-bit will be clear in the CPSR when pc contains this code address.
  Other Reserved to the ABI for the Arm architecture.

Describing other endian data

Arm architecture version 6 allows programs to access data stored in the other byte order, either by executing REV* instructions, or by juggling the E bit in the PSR. Consequently, there is a need to describe in DWARF tables data that has been statically declared with a particular byte order.

This ABI mandates no particular way to describe the byte order of data manipulated by a programming language, but one could imagine a simple language extension like the following, or use of #pragma:

extern __big_endian T bx;     // bx contains big-endian data
extern __little_endian T lx;  // lx contains little-endian data

Usually, all data has the same byte order and this is recorded in the EI_DATA field of the header of the ELF file (as the value ELFDATA2MSB or ELFDATA2LSB).

To describe data that is explicitly declared big-endian or little-endian (by whatever means), use the DWARF 3.0 attribute DW_AT_endianity (0x65). It takes a single LEB128 constant argument value that is one of the following:

DW_END_default (= 0)
DW_END_big (= 1)              (Was 0 prior to the DWARF 3.0 standard)
DW_END_little (= 2)           (Was 1 prior to the DWARF 3.0 standard)

By default the Arm architecture is little endian, so DW_END_default should be interpreted as DW_END_little.

The DW_AT_endianity attributes can be attached to type entries as follows.

  • Attached to a base type (GDWARF, 5.1, Base Type Entries), this attribute gives the byte order of the data described by the base type.

    If this order differs from the default byte order recorded in the containing ELF file, a debugger should reverse the order of the bytes it fetches or stores when accessing values of that base type.

  • Attached to any other type (GDWARF, 5, Type Entries), this attribute indicates that the type was labeled explicitly (in some way) with the given byte order.

    When representing such a type across its user interface, a debugger should label the representation in some way that indicates it was declared with an explicit byte order. Some possible labels for big-endian follow.

    __big_endian T X;
    __declspec(big_endian) T X;
    T X __attribute__("big endian");
    #pragma arm_big_endian
    struct BigT { ... };
    #pragma no_arm_big_endian
    BigT X;
    

    Any such representation by a debugger is entirely quality of implementation.

Canonical Frame Address

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 CFA is the value of the stack pointer (r13) at the call site in the previous frame.

Common information entries

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 processors 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 targets with VFP and another for targets 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 DW_CFA_undefined.

    A debugger can use built-in knowledge of the procedure call standard or can deduce which registers are callee-saved by scanning all CIEs.

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

    (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 a callee-saved register R, its associated CIE must initialize R using one of the defined value methods (not DW_CFA_undefined).

Was this page helpful? Yes No