Merge branch 'ARM-software:main' into build-attributes

ARM-software · Nov 14, 2024 · d9264a5 · d9264a5
2 parents 2e82708 + 76d5612
commit d9264a5
Show file tree

Hide file tree

Showing 42 changed files with 2,280 additions and 468 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -7,9 +7,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: setup python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: '3.x'
     - name: install packages
@@ -18,7 +18,7 @@ jobs:
       run: tools/common/check-rst-syntax.sh
     - name: build PDFs
       run: tools/rst2pdf/generate-pdfs.sh PDFs
-    - uses: actions/upload-artifact@v2
+    - uses: actions/upload-artifact@v4
       with:
         name: PDFs
         path: PDFs
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -43,6 +43,41 @@ changes.
 If you want to make ABI changes that for some reason can't be discussed in
 public, you can send an email to [email protected].
 
+### Extension documents
+While the majority of new proposals can be added to existing
+documents. Proposals that extend the ABI, but are not yet stable are
+placed in an extension document. An example of an extension document
+is the PAuth Extension to ELF for Arm 64-bit Architecture. Extension
+documents have the following requirements:
+
+1. The document status must be Alpha.
+2. The document has an owner recorded in the table below. The owner
+   need not be from Arm.
+3. The document must not clash with other ABI extension documents, or
+   both extensions must be marked as being incompatible.
+
+
+The Arm approval process for accepting the extension is as follows:
+
+1. At least one person within Arm has reviewed and accepted the pull
+   request.
+2. There is a consensus within Arm that the extension can be added to
+   the ABI.
+
+Extension documents can move into the main ABI when the following conditions hold:
+
+1. The information in the document is stable.
+2. There is an implementation of the extension.
+3. The boundaries of when the extension applies are clear.
+
+An extension document that moves into the main ABI will add the
+necessary information to the main documents. In addition any design
+and rationale in the extension document will be moved to a new
+document in the design-documents folder.
+
+When the extension has either moved into the main ABI or has been
+withdrawn it will be moved to an archive folder.
+
 ## Manual checking of the PDF documents and Continuous Integration
 
 To check the outcome of your changes, run the `tools/rst2pdf/generate-pdfs.sh`
@@ -109,6 +144,7 @@ document | owner | Github handle
 [Morello extensions to ELF for the Arm 64-bit Architecture](https://github.com/ARM-software/abi-aa/tree/master/aaelf64-morello) | Silviu Baranga | @sbaranga-arm
 [Morello Descriptor ABI for the Arm 64-bit Architecture](https://github.com/ARM-software/abi-aa/tree/master/descabi-morello) | Silviu Baranga | @sbaranga-arm
 [Memtag ABI Extension to ELF for the Arm 64-bit Architecture](https://github.com/ARM-software/abi-aa/tree/master/memtagabielf64) | Mitch Phillips | @hctim
+[C/C++ Atomics Application Binary Interface Standard for the Arm 64-bit Architecture](https://github.com/ARM-software/abi-aa/tree/master/atomicsabi64) | Luke Geeson | @lukeg101
 
 3. Merging the change
 

diff --git a/README.md b/README.md
@@ -71,14 +71,16 @@ ELF for the Arm 64-bit Architecture                                | [aaelf64](a
 DWARF for the Arm 64-bit Architecture                              | [aadwarf64](aadwarf64/aadwarf64.rst) | [2020Q2](legacy-documents/aadwarf64/ihi0057_E/IHI0057_E_2020Q2_aadwarf64.pdf)
 C++ ABI for the Arm 64-bit Architecture                            | [cppabi64](cppabi64/cppabi64.rst)    | [2020Q2](legacy-documents/cppabi64/ihi0059_E/IHI0059E_2020Q2_cppabi64.pdf)
 Vector Function ABI for the Arm 64-bit Architecture                | [vfabia64](vfabia64/vfabia64.rst)    | [2019Q2](legacy-documents/vfabia64/101129_1920/101129_1920_01_en.pdf)
+C/C++ Atomics ABI for the Arm 64-bit Architecture                  | [atomicsabi64](atomicsabi64/atomicsabi64.rst)    | n/a
+System V ABI for the Arm 64-bit Architecture                       | [sysvabi64](sysvabi64/sysvabi64.rst) | n/a
 
 
 ### ABI for the Arm 64-bit Architecture with SVE support
 
 specification                                                                                                                 | latest                                             | last legacy release
 ---                                                                                                                           | ---                                                | ---
 Procedure Call Standard for the Arm 64-bit Architecture with SVE support                                                      | content merged with [aapcs64](aapcs64/aapcs64.rst) | [SVEpcs 00bet1](legacy-documents/aapcs64-sve/100986_0000/abi_sve_aapcs64_100986_0000_00_en.pdf)
-DWARF for the Arm 64-bit Architecture with SVE support                                                                        | content merged with [aadwarf64](aadwarf64/aawarf64.rst) | [SVEdwf 00bet1](legacy-documents/aadwarf64-sve/100985_0000/abi_sve_aadwarf_100985_0000_00_en.pdf)
+DWARF for the Arm 64-bit Architecture with SVE support                                                                        | content merged with [aadwarf64](aadwarf64/aadwarf64.rst) | [SVEdwf 00bet1](legacy-documents/aadwarf64-sve/100985_0000/abi_sve_aadwarf_100985_0000_00_en.pdf)
 Vector Function ABI for the Arm 64-bit Architecture (identical to document in *ABI for the Arm 64-bit Architecture* section)  |  [vfabia64](vfabia64/vfabia64.rst) | [2019Q2](legacy-documents/vfabia64/101129_1920/101129_1920_01_en.pdf)
 
 ### PAuth ABI Extension

diff --git a/aadwarf32/aadwarf32.rst b/aadwarf32/aadwarf32.rst
@@ -1,11 +1,11 @@
 ..
-   Copyright (c) 2003-2007, 2012, 2018, 2020-2023, Arm Limited and its affiliates.  All rights reserved.
+   Copyright (c) 2003-2007, 2012, 2018, 2020-2024, Arm Limited and its affiliates.  All rights reserved.
    CC-BY-SA-4.0 AND Apache-Patent-License
    See LICENSE file for details
 
-.. |release| replace:: 2023Q3
-.. |date-of-issue| replace:: 6\ :sup:`th` October 2023
-.. |copyright-date| replace:: 2003-2007, 2012, 2018, 2020-2023
+.. |release| replace:: 2024Q3
+.. |date-of-issue| replace:: 5\ :sup:`th` September 2024
+.. |copyright-date| replace:: 2003-2007, 2012, 2018, 2020-2024
 .. |footer| replace:: Copyright © |copyright-date|, Arm Limited and its
                       affiliates. All rights reserved.
 

diff --git a/aadwarf64-morello/aadwarf64-morello.rst b/aadwarf64-morello/aadwarf64-morello.rst
@@ -1,11 +1,11 @@
 ..
-   Copyright (c) 2020-2023, Arm Limited and its affiliates.  All rights reserved.
+   Copyright (c) 2020-2024, Arm Limited and its affiliates.  All rights reserved.
    CC-BY-SA-4.0 AND Apache-Patent-License
    See LICENSE file for details
 
-.. |release| replace:: 2023Q3
-.. |date-of-issue| replace:: 6\ :sup:`th` October 2023
-.. |copyright-date| replace:: 2020-2023
+.. |release| replace:: 2024Q3
+.. |date-of-issue| replace:: 5\ :sup:`th` September 2024
+.. |copyright-date| replace:: 2020-2024
 .. |footer| replace:: Copyright © |copyright-date|, Arm Limited and its
                       affiliates. All rights reserved.
 

diff --git a/aadwarf64/aadwarf64.rst b/aadwarf64/aadwarf64.rst
@@ -1,11 +1,11 @@
 ..
-   Copyright (c) 2010, 2013, 2018, 2020-2023, Arm Limited and its affiliates.  All rights reserved.
+   Copyright (c) 2010, 2013, 2018, 2020-2024, Arm Limited and its affiliates.  All rights reserved.
    CC-BY-SA-4.0 AND Apache-Patent-License
    See LICENSE file for details
 
-.. |release| replace:: 2023Q3
-.. |date-of-issue| replace:: 6\ :sup:`th` October 2023
-.. |copyright-date| replace:: 2010, 2013, 2018, 2020-2023
+.. |release| replace:: 2024Q3
+.. |date-of-issue| replace:: 5\ :sup:`th` September 2024
+.. |copyright-date| replace:: 2010, 2013, 2018, 2020-2024
 .. |footer| replace:: Copyright © |copyright-date|, Arm Limited and its
                       affiliates. All rights reserved.
 
@@ -229,6 +229,11 @@ changes to the content of the document for that release.
   | 2022Q3 | 20\ :sup:`th` October 2022  | - Added `Changes in vector length`_ at |
   |        |                             |   **Alpha** quality.                   |
   +--------+-----------------------------+----------------------------------------+
+  | 2024Q3 | 5\ :sup:`th` September 2024 | In `DWARF register names_` and         |
+  |        |                             | `Call frame instructions`_, add Dwarf  |
+  |        |                             | support for unwinding with             |
+  |        |                             | FEAT_PAuth_LR enabled.                 |
+  +--------+-----------------------------+----------------------------------------+
 
 
 References
@@ -470,11 +475,31 @@ integers.
    .. _Note 8:
 
    8. 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[0] 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.
+      been signed with a PAC, and whether the value of PC has been used as a
+      diversifier for the return address signing. This information can be used
+      when unwinding. It is an unsigned integer with the same size as a general
+      register. Only bit[0] and bit[1] are meaningful and are initialized to zero.
+
+      Bit[0] indicates whether the return address has been signed. A value of 0
+      indicates the return address has not been signed. A value of 1 indicates
+      the return address has been signed.
+
+      Bit[1] indicates whether the value of PC has been used as a diversifier for
+      signing the return address. A value of 0 indicates the value of PC has not
+      been used for return address signing. A value of 1 indicates the value of PC
+      has been used for return address signing.
+
+      +--------+--------+----------------------------------+
+      | Bit[1] | Bit[0] | State                            |
+      +========+========+==================================+
+      | 0      | 0      | Return address not signed        |
+      +--------+--------+----------------------------------+
+      | 0      | 1      | Return address signed with SP    |
+      +--------+--------+----------------------------------+
+      | 1      | 1      | Return address signed with SP+PC |
+      +--------+--------+----------------------------------+
+      | 1      | 0      | Invalid state                    |
+      +--------+--------+----------------------------------+
 
    .. _Note 9:
 
@@ -574,25 +599,37 @@ a CIE augmentation string.
 Call frame instructions
 -----------------------
 
-This ABI defines one vendor call frame instruction
-``DW_CFA_AARCH64_negate_ra_state``.
+This ABI defines the following vendor call frame instructions:
+``DW_CFA_AARCH64_negate_ra_state`` and ``DW_CFA_AARCH64_negate_ra_state_with_pc``.
 
 .. class:: aadwarf64-vendor-cfa-operations
 
 .. table:: AArch64 vendor CFA operations
 
-   +------------------------------------+-------------+------------+-----------+-----------+
-   | Instruction                        | High 2 bits | Low 6 bits | Operand 1 | Operand 2 |
-   +====================================+=============+============+===========+===========+
-   | ``DW_CFA_AARCH64_negate_ra_state`` | 0           | ``0x2D``   | \-        | \-        |
-   +------------------------------------+-------------+------------+-----------+-----------+
+   +--------------------------------------------+-------------+------------+-----------+-----------+
+   | Instruction                                | High 2 bits | Low 6 bits | Operand 1 | Operand 2 |
+   +============================================+=============+============+===========+===========+
+   | ``DW_CFA_AARCH64_negate_ra_state``         | 0           | ``0x2D``   | \-        | \-        |
+   +--------------------------------------------+-------------+------------+-----------+-----------+
+   | ``DW_CFA_AARCH64_negate_ra_state_with_pc`` | 0           | ``0x2C``   | \-        | \-        |
+   +--------------------------------------------+-------------+------------+-----------+-----------+
 
 The ``DW_CFA_AARCH64_negate_ra_state`` operation negates bit[0] of the
 RA_SIGN_STATE pseudo-register. It does not take any operands.
-The ``DW_CFA_AARCH64_negate_ra_state`` must not be mixed with other DWARF
-Register Rule Instructions (GDWARF_, §6.4.2.3) on the RA_SIGN_STATE
-pseudo-register in one Common Information Entry (CIE) and Frame Descriptor
-Entry (FDE) program sequence.
+
+The ``DW_CFA_AARCH64_negate_ra_state_with_pc`` operation negates bit[0] and
+bit[1] of the RA_SIGN_STATE pseudo-register, and instructs the unwinder to
+capture the current code location. The code location information can be used
+for authenticating the return address.
+
+The ``DW_CFA_AARCH64_negate_ra_state_with_pc`` instruction must be placed within
+the debug frame in a position that refers to the exact code location of the
+signing/authenticating PAC instructions.
+
+The ``DW_CFA_AARCH64_negate_ra_state`` and ``DW_CFA_AARCH64_negate_ra_state_with_pc``
+instructions must not be mixed with other DWARF Register Rule Instructions
+(GDWARF_, §6.4.2.3) on the RA_SIGN_STATE pseudo-register in one Common
+Information Entry (CIE) and Frame Descriptor Entry (FDE) program sequence.
 
 .. _DWARF expression operations:
 

diff --git a/aaelf32/aaelf32.rst b/aaelf32/aaelf32.rst
@@ -1,11 +1,11 @@
 ..
-   Copyright (c) 2005-2009, 2012, 2015, 2018, 2020-2023, Arm Limited and its affiliates. All rights
+   Copyright (c) 2005-2009, 2012, 2015, 2018, 2020-2024, Arm Limited and its affiliates. All rights
    reserved. CC-BY-SA-4.0 AND Apache-Patent-License See LICENSE file
    for details
 
-.. |release| replace:: 2023Q3
-.. |date-of-issue| replace:: 6\ :sup:`th` October 2023
-.. |copyright-date| replace:: 2005-2009, 2012, 2015, 2018, 2020-2023
+.. |release| replace:: 2024Q3
+.. |date-of-issue| replace:: 5\ :sup:`th` September 2024
+.. |copyright-date| replace:: 2005-2009, 2012, 2015, 2018, 2020-2024
 .. |footer| replace:: Copyright © |copyright-date|, Arm Limited and its
                       affiliates. All rights reserved.
 .. |armarmv5_link| replace:: https://developer.arm.com/docs/ddi0100/latest/armv5-architecture-reference-manual
@@ -980,6 +980,8 @@ potential for conflicts.
   +-------------------+---------------------------------------------------------------------+
   | ``llvm``          | The LLVM/Clang projects                                             |
   +-------------------+---------------------------------------------------------------------+
+  | ``mchp``          | Microchip Technology Inc.                                           |
+  +-------------------+---------------------------------------------------------------------+
   | ``PSI``           | PalmSource Inc.                                                     |
   +-------------------+---------------------------------------------------------------------+
   | ``RAL``           | Rowley Associates Ltd                                               |
@@ -1765,7 +1767,7 @@ The following nomenclature is used for the operation:
   +---------+----------------------------------+------------+---------------+----------------------------------------+
   | 2       | :code:`R_ARM_ABS32`              | Static     | Data          | :code:`(S + A) | T`                    |
   +---------+----------------------------------+------------+---------------+----------------------------------------+
-  | 3       | :code:`R_ARM_REL32`              | Static     | Data          | :code:`((S + A) | T) | – P`            |
+  | 3       | :code:`R_ARM_REL32`              | Static     | Data          | :code:`((S + A) | T) – P`              |
   +---------+----------------------------------+------------+---------------+----------------------------------------+
   | 4       | :code:`R_ARM_LDR_PC_G0`          | Static     | Arm           | :code:`S + A – P`                      |
   +---------+----------------------------------+------------+---------------+----------------------------------------+

diff --git a/aaelf64-morello/aaelf64-morello.rst b/aaelf64-morello/aaelf64-morello.rst
@@ -1,11 +1,11 @@
 ..
-   Copyright (c) 2020-2023, Arm Limited and its affiliates.  All rights reserved.
+   Copyright (c) 2020-2024, Arm Limited and its affiliates.  All rights reserved.
    CC-BY-SA-4.0 AND Apache-Patent-License
    See LICENSE file for details
 
-.. |release| replace:: 2023Q3
-.. |date-of-issue| replace:: 6\ :sup:`th` October 2023
-.. |copyright-date| replace:: 2020-2023
+.. |release| replace:: 2024Q3
+.. |date-of-issue| replace:: 5\ :sup:`th` September 2024
+.. |copyright-date| replace:: 2020-2024
 .. |footer| replace:: Copyright © |copyright-date|, Arm Limited and its
                       affiliates. All rights reserved.