Skip to content

[aaelf64-morello][aapcs64-morello] Document pure-capability benchmark ABI #365

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jrtc27 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[aaelf64-morello][aapcs64-morello] Document pure-capability benchmark ABI #365

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 38 additions & 3 deletions aaelf64-morello/aaelf64-morello.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -306,6 +306,24 @@ A Morello toolchain can emit ELF Note sections in accordance to [CHERI_ELF_].
The following Morello-specific ELF Note types are used, allocated from the
space reserved by [CHERI_ELF_] for processor-specific use:

.. _Morello-specific note types:

.. class:: aaelf64-morello-note-types

.. table:: Morello-specific note types

+------------+----------------------------------------+-----------------------------------------------------------+
| Value | Name | Description |
+------------+----------------------------------------+-----------------------------------------------------------+
| 0x80000000 | NT_CHERI_MORELLO_PURECAP_BENCHMARK_ABI | Whether the object uses the pure-capability benchmark ABI |
+------------+----------------------------------------+-----------------------------------------------------------+

.. note::

NT_CHERI_MORELLO_PURECAP_BENCHMARK_ABI has a Desc Size of 4, and Desc should
be interpreted as a 4-byte boolean value, with values other than 0 and 1
reserved.
Copy link
Contributor

@smithp35 smithp35 Jan 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some things that may be worth mentioning:

  • Does the absence of the note imply a value of 0?
  • Do all input objects have to have the same value?
  • Is the linker expected to propagate a consolidated note into the executable/shared-object like .note.gnu.property or can it be discarded?

Copy link
Contributor Author

@jrtc27 jrtc27 Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the first two, yes, that should be documented here (and the answer to both is yes). For the last one, that's not really something that's up to this spec to document, that's a CHERI ELF gABI point (to which the answer is, yes, they get propagated as they're all about annotating binaries with the details ABI variant is in use, normally incompatible if different with the compat TLS ABI as a rare exception).


.. _Morello-specific NT_CHERI_TLS_ABI types:

.. class:: aaelf64-morello-NT_CHERI_TLS_ABI-types
Expand Down Expand Up @@ -346,8 +364,10 @@ expected definition.
The type of any other symbol defined in an executable section can be
``STT_NOTYPE``. A linker is only required to provide long-branch and PLT support
for symbols of type ``STT_FUNC``. A linker is also only required to provide
interworking support for A64 and C64 symbols of type ``STT_FUNC`` (interworking
for untyped symbols must be encoded directly in the object file)
interworking support for A64 and C64 symbols of type ``STT_FUNC``, and only if
not using the pure-capability benchmark ABI (interworking for untyped symbols
or the pure-capability benchmark ABI must be encoded directly in the object
file).

Symbol names
^^^^^^^^^^^^
Expand Down Expand Up @@ -451,14 +471,19 @@ apply to symbols of type ``STT_FUNC`` and ``STT_GNU_IFUNC``:

- If the symbol addresses a C64 instruction, its value is the address of the
instruction with bit 0 set (in a relocatable object, the section offset with
bit 0 set).
bit 0 set) if not using the pure-capability benchmark ABI, otherwise it is
Copy link
Contributor

@smithp35 smithp35 Jan 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be worth moving the ABI distinction further up in the paragraph, or perhaps using a full stop before otherwise.

A suggestion:

If the symbol addresses a C64 instruction, its value depends on the ABI used. If not using the pure-capability benchmark ABI the value is the address of the instruction with bit 0 set (in a relocatable object, the section offset with
Comment view  bit 0 set). If using the pure-capability benchmark ABI the value is the same as for a symbol addressing an A64 instruction.

Copy link
Contributor Author

@jrtc27 jrtc27 Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, I can try to rework this bullet point a bit more, I was trying to be minimally disruptive of the existing wording but you're right that affected the clarity here (and found this one the hardest to write at the time)

Copy link
Contributor

@smithp35 smithp35 Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I agree that isn't an easy edit to make.

the same as for a symbol addressing an A64 instruction.

.. note::
This allows a linker to distinguish A64 and C64 code symbols without having
to refer to the map. An A64 symbol will always have an even value, while a
C64 symbol will always have an odd value. However, a linker should strip the
discriminating bit from the value before using it for relocation.

Due to the pure-capability benchmark ABI using integer BR/BLR for indirect
Copy link
Contributor

@smithp35 smithp35 Jan 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Following https://github.com/ARM-software/abi-aa/blob/main/aapcs64-morello/aapcs64-morello.rst#611general-purpose-registers could this be something like:

Due to the pure-capability benchmark ABI using a 64-bit context for indirect calls using BL/BLR, bit 0 ...

I don't have a particularly strong opinion here. If integer vs capability is a well used term in the CHERI/Morello community then leave it as is.

Copy link
Contributor Author

@jrtc27 jrtc27 Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that makes it less clear, and to me "in a 64-bit context" in the linked description means "in the context of an operand that is to be interpreted as a 64-bit integer", i.e. the context is the instruction and operand number, not that the instruction is within such a context. And yes, integer (or (integer) address) vs capability is a normal distinction to be making within CHERI. I can change it to be a bit less terse though with something like "Due to the pure-capability benchmark ABI using BR/BLR with a 64-bit integer X register for ..." if you think that would be clearer?

Copy link
Contributor

@smithp35 smithp35 Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think your suggested replacement looks good to me.

"Due to the pure-capability benchmark ABI using BR/BLR with a 64-bit integer X register for ..."

calls, bit 0 is part of the branch target rather than the new value to use
for PSTATE.C64, and so this distinction cannot be used.

Relocation
----------

Expand Down Expand Up @@ -1258,6 +1283,11 @@ allow correct linker relaxation:
.tlsdesccall sym
blr c1

.. note::

In the pure-capability benchmark ABI, the final ``blr c1`` is replaced with
``blr x1``.

General Dynamic to Initial Exec relaxation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -1398,6 +1428,11 @@ allow correct linker relaxation:
.tgot_tlsdesccall sym
blr c2

.. note::

In the pure-capability benchmark ABI, the final ``blr c2`` is replaced with
``blr x2``.

General Dynamic to Initial Exec relaxation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
14 changes: 13 additions & 1 deletion aapcs64-morello/aapcs64-morello.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@
affiliates. All rights reserved.

.. _AAPCS64: https://github.com/ARM-software/abi-aa/releases
.. |UCAM-CL-TR-986-url| replace:: https://ctsrd-cheri.github.io/morello-early-performance-results/
.. _UCAM-CL-TR-986: https://ctsrd-cheri.github.io/morello-early-performance-results/

Morello extensions to Procedure Call Standard for the Arm® 64-bit Architecture (AArch64)
****************************************************************************************
Expand Down Expand Up @@ -216,6 +218,8 @@ This document refers to, or is referred to by, the following documents.
+------------------+--------------------------+--------------------------------------------------------------------------------------------+
| AAPCS64_ | IHI 005D | Procedure Call Standard for the Arm 64-bit Architecture. |
+------------------+--------------------------+--------------------------------------------------------------------------------------------+
| UCAM-CL-TR-986_ | |UCAM-CL-TR-986-url| | Early performance results from the prototype Morello microarchitecture |
+------------------+--------------------------+--------------------------------------------------------------------------------------------+

Terms and Abbreviations
-----------------------
Expand All @@ -242,6 +246,12 @@ Deriving a capability
when CV2 is a copy of CV1 with optionally removed permissions and/or
optionally narrowed bounds (base increased or limit reduced).

Pure-capability benchmark ABI
A variant of the normal pure-capability ABI to work around known
limitations in the microarchitecture of the Morello implementation and more
closely model the essential overheads of CHERI. See UCAM-CL-TR-986_ for
more details of the motivation.

More specific terminology is defined when it is first used.

.. raw:: pdf
Expand Down Expand Up @@ -486,6 +496,8 @@ Subroutine Calls

The A64 and C64 states contain primitive subroutine call instructions, BL and BLR, which performs a branch-with-link operation. The effect of executing BL is to transfer the sequentially next value of the program counter - the return address - into the link register (LR or CLR) and the destination address into the program counter. The effect of executing BLR is similar except that the new PC value is constructed from the specified register.

.. note::
For C64 code in the pure-capability benchmark ABI, the value of CLR after a BL or BLR will have bit 0 set and must be cleared by the callee before returning with ``ret x30``.

Use of CIP0 and CIP1 by the linker
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -718,7 +730,7 @@ Interworking between data model variants of AAPCS64 (although technically possib

Interworking between AAPCS64 and AAPCS64-cap is not supported.

Interworking between A64 and C64 states is supported. The linker will insert a veneer at direct branches between different states. The veneer will perform both the state switch and range extensions. It is the responsibility of the callee to switch state on return.
Interworking between A64 and C64 states is supported if not using the pure-capability benchmark ABI. The linker will insert a veneer at direct branches between different states. The veneer will perform both the state switch and range extensions. It is the responsibility of the callee to switch state on return.

.. raw:: pdf

Expand Down