abi-aa is where the Arm ABI stopped being a PDF and started being a diff

Documents that used to be PDFs are now diffs

The repository describes itself as the official place for the latest documents of the Application Binary Interface for the Arm architecture, both for source files and officially released documents. The primary language of the repository is recorded as HTML, and the document links in the README point at `.rst` files, which is the detail that matters.

The specifications are ReStructuredText sources in named directories. `aapcs64/aapcs64.rst` is the Procedure Call Standard for the 64-bit architecture, `aapcs32/aapcs32.rst` the 32-bit one, `aaelf64/aaelf64.rst` the ELF specification, `aadwarf64/aadwarf64.rst` the DWARF specification, `cppabi64/cppabi64.rst` the C++ ABI, `atomicsabi64/atomicsabi64.rst` the atomics ABI and `sysvabi64/sysvabi64.rst` the System V ABI. Each directory also carries its build artefacts alongside the source, which is the normal layout for a specification that is compiled and published as PDF.

Why the format change is the substantive improvement is easy to state. The README includes a note that if there is no entry in the change history table for a release, there are no changes to the content of the document for that release. That claim only becomes checkable if the documents are text. An ABI change that is a corrected register number or a clarified return-value rule is invisible in a redrawn PDF and obvious in a text diff, and arguing with a compiler vendor about which quarter changed a rule is much easier when you can produce the diff yourself.

The other practical consequence is that a search for a rule inside the specification now works, since the text is in the repository rather than only inside a published document.

There is a `tools/` directory and a `.github/` directory with an Actions status badge, so the documents are built and checked automatically rather than being a static upload.

Legacy documents and historical Git releases

The document location tables have three columns: specification, latest, and last legacy release. The third column is the part most people do not expect.

Previous versions of the documents were released under a proprietary licence on developer.arm.com, and the README states those are now hosted in this repository under a legacy documents folder, following the same folder naming scheme as the main document folders. So `legacy-documents/bsabi32/ihi0036_D/ihi0036D_bsabi.pdf` is the 2019Q4 legacy release of the 32-bit base ABI, sitting in the tree next to the current `bsabi32/bsabi32.rst`.

The tables are exhaustive enough to be a map of the whole specification set. For 32-bit there are twelve documents: the introduction and base platform ABI, the procedure call standard, ELF, DWARF, C++, exception handling, run-time ABI, the C library ABI, debugging overlaid programs, the addenda and errata, and an advisory note on 8-byte stack alignment for SP. For 64-bit there are seven: the procedure call standard, ELF, DWARF, C++, the vector function ABI, the atomics ABI and the System V ABI.

Read the last legacy release column and you can see how much has moved. Several documents have not had a legacy release since 2018Q4. That column identifies the last legacy release; later revisions can be found in the repository’s Git history and releases. The atomics ABI and the System V ABI show `n/a` in that column, meaning no legacy release exists at all.

For a debugging session, that is the practical map. If your problem involves the 64-bit procedure call standard and you need to know what it said before, there is a 2018Q4 legacy document. For atomics, inspect the historical Git releases and source history to compare available revisions.

Quarterly releases, and an explicit no-change convention

Releases are named by quarter rather than by semantic version, which is the right convention for a specification and a poor one for a library.

The recent releases are 2025Q4 dated 2026-01-26, 2025Q1 dated 2025-04-07 and 2024Q3 dated 2024-09-05. So a release labelled for a quarter can be published months later, which is normal for a document that has to go through review.

The README states that the latest ABI releases are being made available only on GitHub, at the releases page of this repository. That is a change of distribution channel, and it means developer.arm.com is no longer where you get a current specification.

The convention about change history deserves a second look, because it is the mechanism that keeps quarterly releases cheap. If there is no entry in the change history table for a release, there are no changes to the content of the document for that release. In other words, a quarterly release is allowed to be a repackaging with no substantive edit, and the table is how you distinguish that from a real change. Without that convention every quarter would invent a change note to justify itself.

The repository is not archived. As of 2026-11-07, the most recent listed release is 2026Q3, published on 2026-11-03.

Two other parts of the repository exist that the tables do not show in the excerpt but the directory listing does: `design-documents/` and `semihosting/`, alongside `aadwarf64-morello/`, `aaelf64-morello/`, `aapcs64-morello/`, `baabielf64/`, `buildattr64/` and `memtagabielf64/`.

There is also a separate PAuth ABI Extension table with a latest and a last legacy document column, which is the pointer authentication extension.

Morello, SVE and PAuth are where drafts live

Three groups in the tables and directories are not the settled base specification, and treating them as settled is the most likely way to get this repository wrong.

The Morello documents are `aaelf64-morello`, `aadwarf64-morello` and `aapcs64-morello`, listed as their own directories rather than as variants inside the main 64-bit directories. `baabielf64`, `buildattr64` and `memtagabielf64` sit in the same neighbourhood, covering the base ABI for ELF, build attributes and memory tagging.

SVE is handled differently and the table explains how. There is a separate section for the Arm 64-bit architecture with SVE support, and in the latest column the procedure call standard and DWARF entries both say content merged with the main 64-bit document, pointing at `aapcs64` and `aadwarf64`. Their last legacy releases are beta documents: `SVEpcs 00bet1` and `SVEdwf 00bet1`. So the SVE rules were once separate drafts and are now folded into the main documents, with the betas preserved in the legacy tree.

The vector function ABI is the one document the SVE table points at rather than duplicating, with a note that it is identical to the document in the 64-bit section.

What this means practically is that the SVE and Morello material should be read as part of a moving specification rather than a contract you can implement against without checking the current text. The PAuth extension is in the same category, and the README's own guidance about defect reporting supports that reading: defects in documents in this repository go to the GitHub issue tracker, while defects in documents still only hosted on developer.arm.com go by email to an address given in the README.

Two channels for reporting defects is itself a signal about which documents are frozen and which are still moving.

Licence: Creative Commons with a patent grant, and how that differs from code

The licence is the most easily misread thing in this repository, so it is worth being precise.

The README states the ABI releases are licensed under the Creative Commons Attribution-ShareAlike 4.0 International License plus a grant of Patent License. The repository's own licence field is recorded as a custom licence GitHub cannot categorise, with a `LICENSE.md` file at the root, which is consistent with a document licence rather than a software licence.

What CC BY-SA 4.0 means for an engineer using these documents: you may copy and redistribute the specifications, including commercially, provided you attribute Arm and share adaptations under the same terms. The ShareAlike clause attaches to the document, not to your code, so adopting a calling convention rule from the specification does not oblige you to license your implementation under CC BY-SA.

The patent grant is the part that distinguishes this from ordinary Creative Commons. A specification describes how to produce a binary that another vendor's tooling must accept. The documents include a patent licence; consult the applicable licence terms for its scope and conditions.

That older regime is visible in the repository. Previous versions of the documents were released under a proprietary licence on developer.arm.com and are now hosted here in the legacy documents folder. So the same project contains material under two different terms, and if you are quoting an old rule in a design document you are quoting proprietary-licensed text rather than CC BY-SA text. Read `LICENSE.md` before reproducing anything.

This is not legal advice. It is the reason to check which document and which quarter you are quoting, because the licence changed.

How to actually use this when something does not link

The practical workflow this repository enables is narrow and worth stating, because a specification repository is easy to over-estimate.

You use it when you have a binary that behaves differently on Arm than you expect, or you are writing or reviewing code that must interoperate with someone else's. The question is almost always one of: what does the standard say, and did it say something different when this binary was built? For the second half, consult the relevant legacy document or compare historical Git releases.

The documents that come up most often are the procedure call standard for register assignment and argument passing, the ELF specification for relocations and section handling, DWARF for debugging information layout, the C++ ABI for vtables, mangling and unwinding, the atomics ABI for lock-free primitives, and the exception handling ABI for unwind tables. For 32-bit code, the run-time ABI and the C library ABI cover the runtime support code an embedded image needs.

Two pieces of process advice follow from the repository rather than from any individual document. First, record the quarterly release you are reasoning against, because the no-change convention means an absent entry is itself information and a later release may or may not have altered the rule you rely on. Second, prefer the current source over the legacy PDF when the two appear to differ, since the legacy documents are historical and the source is what is being maintained.

What the repository is not is a conformance suite, a test harness or a reference implementation. There is no way to check your compiler against it from here. If you want validation rather than a citation, you need to compare behaviour against a known-good implementation on the target, and use these documents to explain the difference you find.

Editorial conclusion

abi-aa is the reference to work from when you are implementing or debugging anything that depends on the calling convention, unwind rules, C++ ABI or atomics behaviour on Arm, and its historical releases and Git history allow you to compare revisions. Do not expect tooling from it, because what it publishes is documents and releases rather than code, and treat the Morello and SVE documents as drafts to check rather than settled contracts. Verify first which quarterly release your compiler and runtime actually implement, since the change history table is the authority on whether a given quarter altered a document at all.

Frequently asked questions

Official sources

1. ARM-software/abi-aa on GitHub
2. Issues
3. README
4. Releases