[aadwarf64]] Add DW_CFA_AARCH64_set_ra_state stack frame operation (#346)

The DW_CFA_AARCH64_set_ra_state operation updates the RA_SIGN_STATE
pseudo register with the current signing state. If the signing state
includes signing is DW_AARCH64_RA_SIGNED_SP_PC, then it also provides
the offset to the signing instruction so that the PC value used in the
signing can be calculated.

The DW_CFA_AARCH64_negate_ra_state_with_pc operation has been marked as
deprecated. This is because it has been found that it is not suitable
for describing all cases where the PC was used to sign the return
address (see #327)

The contents of the RA_SIGN_STATE pseudo register is also changed from
being described in terms of a set of bits to being a series of defined
values.

Previously the state of the RA_SIGN_STATE pseudo register was changed
implicitly by the DW_CFA_AARCH64_negate_ra_state and
DW_CFA_AARCH64_set_ra_state operations. This meant that the actual
encoding was actually internal to any implementation.

Now with the introduction of the DW_CFA_AARCH64_set_ra_state operation
the encoding has been made externally visible. So the opportunity has
been taken now to change the encoding to a simpler form.

Author: walkerkd

aadwarf64/aadwarf64.rst

@@ -179,11 +179,23 @@ The following support level definitions are used by the Arm ABI specifications:
    The content of this specification is a draft, and Arm considers the
    likelihood of future incompatible changes to be significant.
 
-Content relating to SVE should be considered as having **Beta** support level.
+Content relating to SVE should be considered as having **Beta** or **Alpha**
+support level.
 This includes:
 
 * DWARF register names marked as **Beta** in `DWARF register names`_
-* Recommended expression of the vector types (`Vector types`_)
+* Recommended expression of the vector types marked as **Beta** in
+  `Vector types`_
+* Changes in vector length marked as **Alpha**
+
+Content relating to the return address state and instructions should be
+considered as having **Alpha** support level.
+This includes:
+
+* The ``RA_SIGN_STATE`` pseudo register ra_state encoding marked as **Alpha**
+  in `DWARF register names`_ `Note 8`_
+* The ``DW_CFA_AARCH64_set_ra_state`` instruction marked as as **Alpha**
+  in `Call frame instructions`_
 
 All other content in this document is at the **Release** quality level.
 
@@ -197,43 +209,51 @@ changes to the content of the document for that release.
 
 .. table::
 
-  +--------+-----------------------------+----------------------------------------+
-  | Issue  | Date                        | Change                                 |
-  +========+=============================+========================================+
-  | 00bet3 | 16\ :sup:`th` December 2010 | Beta release.                          |
-  +--------+-----------------------------+----------------------------------------+
-  | 1.0    | 22\ :sup:`nd` May 2013      | First public release.                  |
-  +--------+-----------------------------+----------------------------------------+
-  | 2018Q4 | 31\ :sup:`st` December 2018 | Add SVE and pointer                    |
-  |        |                             | authentication support.                |
-  +--------+-----------------------------+----------------------------------------+
-  | 2019Q4 | 30\ :sup:`th` January 2020  | Minor layout changes.                  |
-  +--------+-----------------------------+----------------------------------------+
-  | 2020Q2 | 1\ :sup:`st` June 2020      | Add requirements for unwinding MTE     |
-  |        |                             | tagged stack. Describe DWARF           |
-  |        |                             | representation of SVE vector types.    |
-  +--------+-----------------------------+----------------------------------------+
-  | 2020Q4 | 21\ :sup:`st` December 2020 | - document released on Github          |
-  |        |                             | - new Licence_: CC-BY-SA-4.0           |
-  |        |                             | - new sections on Contributions_,      |
-  |        |                             |   `Trademark notice`_, and Copyright_  |
-  |        |                             | - AArch64 DWARF pointer signing        |
-  |        |                             |   operations table columns switched    |
-  |        |                             | - Add Thread ID register numbers.      |
-  +--------+-----------------------------+----------------------------------------+
-  | 2022Q1 | 1\ :sup:`st` April 2022     | - Release of Pointer authentication.   |
-  |        |                             | - In `Call frame instructions`_,       |
-  |        |                             |   document a limitation of             |
-  |        |                             |   DW_CFA_AARCH64_negate_ra_state.      |
-  +--------+-----------------------------+----------------------------------------+
-  | 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.                 |
-  +--------+-----------------------------+----------------------------------------+
+  +--------+-----------------------------+-------------------------------------------+
+  | Issue  | Date                        | Change                                    |
+  +========+=============================+===========================================+
+  | 00bet3 | 16\ :sup:`th` December 2010 | Beta release.                             |
+  +--------+-----------------------------+-------------------------------------------+
+  | 1.0    | 22\ :sup:`nd` May 2013      | First public release.                     |
+  +--------+-----------------------------+-------------------------------------------+
+  | 2018Q4 | 31\ :sup:`st` December 2018 | Add SVE and pointer                       |
+  |        |                             | authentication support.                   |
+  +--------+-----------------------------+-------------------------------------------+
+  | 2019Q4 | 30\ :sup:`th` January 2020  | Minor layout changes.                     |
+  +--------+-----------------------------+-------------------------------------------+
+  | 2020Q2 | 1\ :sup:`st` June 2020      | Add requirements for unwinding MTE        |
+  |        |                             | tagged stack. Describe DWARF              |
+  |        |                             | representation of SVE vector types.       |
+  +--------+-----------------------------+-------------------------------------------+
+  | 2020Q4 | 21\ :sup:`st` December 2020 | - document released on Github             |
+  |        |                             | - new Licence_: CC-BY-SA-4.0              |
+  |        |                             | - new sections on Contributions_,         |
+  |        |                             |   `Trademark notice`_, and Copyright_     |
+  |        |                             | - AArch64 DWARF pointer signing           |
+  |        |                             |   operations table columns switched       |
+  |        |                             | - Add Thread ID register numbers.         |
+  +--------+-----------------------------+-------------------------------------------+
+  | 2022Q1 | 1\ :sup:`st` April 2022     | - Release of Pointer authentication.      |
+  |        |                             | - In `Call frame instructions`_,          |
+  |        |                             |   document a limitation of                |
+  |        |                             |   DW_CFA_AARCH64_negate_ra_state.         |
+  +--------+-----------------------------+-------------------------------------------+
+  | 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.                    |
+  +--------+-----------------------------+-------------------------------------------+
+  |        |                             | - Added DW_CFA_AARCH64_set_ra_state at    |
+  |        |                             |   **Alpha** quality.                      |
+  |        |                             | - Deprecated                              |
+  |        |                             |   DW_CFA_AARCH64_negate_ra_state_with_pc. |
+  |        |                             | - Redefined ra_state representation in    |
+  |        |                             |   the RA_SIGN_STATE pseudo register at    |
+  |        |                             |   **Alpha** quality.                      |
+  +--------+-----------------------------+-------------------------------------------+
 
 
 References
@@ -478,33 +498,31 @@ integers.
       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                    |
-      +--------+--------+----------------------------------+
+      register.
+
+      (**Alpha**) Only bits[0-3] are meaningful and are initialized to
+      ``DW_AARCH64_RA_NOT_SIGNED``.
+
+     .. class:: aadwarf64-vendor-return-address-state
+
+     .. table:: AArch64 vendor return address state
+
+      +--------------------------------+--------+-----------------------------------------------------------------+
+      | Return address state           | Value  | Description                                                     |
+      +================================+========+=================================================================+
+      | ``DW_AARCH64_RA_NOT_SIGNED``   | 0      | Return address not signed                                       |
+      +--------------------------------+--------+-----------------------------------------------------------------+
+      | ``DW_AARCH64_RA_SIGNED_SP``    | 1      | Return address signed with SP                                   |
+      +--------------------------------+--------+-----------------------------------------------------------------+
+      | ``DW_AARCH64_RA_SIGNED_SP_PC`` | 2      | Return address signed with SP+PC                                |
+      +--------------------------------+--------+-----------------------------------------------------------------+
+      |                                | 3 - 15 | (reserved for future use)                                       |
+      +--------------------------------+--------+-----------------------------------------------------------------+
 
    .. _Note 9:
 
    9. Normally, the program counter is restored from the return address, however
-      having both LR and PC columns is useful for describing asynchronously
+      having both LR and PC diversifiers is useful for describing asynchronously
       created stack frames. A DWARF expression may use this register to restore
       the context in case of a signal context.
 
@@ -600,28 +618,47 @@ Call frame instructions
 -----------------------
 
 This ABI defines the following vendor call frame instructions:
-``DW_CFA_AARCH64_negate_ra_state`` and ``DW_CFA_AARCH64_negate_ra_state_with_pc``.
+``DW_CFA_AARCH64_set_ra_state``, ``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``   | \-        | \-        |
-   +--------------------------------------------+-------------+------------+-----------+-----------+
-   | ``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_with_pc`` operation negates bit[0] and
-bit[1] of the RA_SIGN_STATE pseudo-register, and instructs the unwinder to
+   +-------------------------------------------------------------+-------------+------------+------------------+----------------+
+   | 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`` (**Deprecated**) | 0           | ``0x2C``   | \-               | \-             |
+   +-------------------------------------------------------------+-------------+------------+------------------+----------------+
+   | ``DW_CFA_AARCH64_set_ra_state`` (**Alpha**)                 | 0           | ``0x2B``   | ULEB128 ra_state | SLEB128 offset |
+   +-------------------------------------------------------------+-------------+------------+------------------+----------------+
+
+The ``DW_CFA_AARCH64_negate_ra_state`` instruction toggles between the
+``DW_AARCH64_RA_NOT_SIGNED`` and ``DW_AARCH64_RA_SIGNED_SP`` return address
+states in RA_SIGN_STATE pseudo-register. It does not take any operands.
+
+The ``DW_CFA_AARCH64_set_ra_state`` instruction takes two operands: an unsigned
+LEB128 value representing a return address state ra_state; and a signed LEB128
+factored offset. The required action is to set the RA_SIGN_STATE pseudo-register
+to the ra_state value and if the ra_state value is ``DW_AARCH64_RA_SIGNED_SP_PC``
+to capture the current code location + (offset * ``code_alignment_factor``)
+as the signing/authenticating PAC instruction, otherwise it is has the value 0.
+The code location information can be used for authenticating the return address.
+
+The ``DW_CFA_AARCH64_negate_ra_state_with_pc`` instruction toggles between the
+``DW_AARCH64_RA_NOT_SIGNED`` and ``DW_AARCH64_RA_SIGNED_SP_PC`` return
+address state in 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 is **Deprecated**
+and the ``DW_CFA_AARCH64_set_ra_state`` instruction should be used instead.
+
+*The ``DW_CFA_AARCH64_negate_ra_state`` instruction is deprecated because it is
+unable to correctly represent the return address signing state when the code
+flow is not linear between the signing/authenticating PAC instructions.*
+
 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.