Where is the x86-64 System V ABI documented?

Jeffrey Yasskin picture Jeffrey Yasskin · Aug 8, 2013 · Viewed 21.5k times · Source

The x86-64 System V ABI (used on everything except Windows) used to live at http://x86-64.org/documentation/abi.pdf, but that site has now fallen off the internet.

Is there a new authoritative home for the document?

Answer

Peter Cordes picture Peter Cordes · Oct 31, 2016

The System V x86-64 psABI is maintained on GitHub. H.J. Lu's github page has a wiki with links to the current versions of the x86-64 and i386 SystemV psABI documents, and to the forums where updates are discussed.

See also the tag wiki for direct links to the latest versions.

As of now, the current version for x86-64 is 1.0 (January 2018). There's a more recent 2018-dec draft version which (ironically) removes the "Draft" from the "Draft 1.0" version number in the PDF itself.
The x32 ABI (32-bit pointers in long mode) is part of the x86-64 ABI doc. See Chapter 10: ILP32 Programming Model.

The current version for i386 is 1.1. (Note that some OSes use an older version of the i386 ABI which doesn't require 16-byte stack alignment, only 4. GCC ended up depending on -mpreferred-stack-boundary=4 16-byte alignment for its SSE code-gen (perhaps unintentionally), and eventually the ABI got updated for Linux to enshrine that as an official requirement. I attempted a summary in a comment on GCC bug #40838. This breaks backwards compat with some hand-written asm that calls other functions.)

Unofficially, sign-extending narrow args to 32-bit is required (for both i386 and amd64), because clang depends on it. Hopefully a future ABI revision will document that.


Naming: psABI

The Processor Supplement (psABI) docs are designed as a supplement to the less-frequently-updated System V gABI (generic), hosted on SCO's website.


Other links

Also https://refspecs.linuxfoundation.org/ hosts a copy of the gABI from 1997.

https://uclibc.org/specs.html has psABI links for various non-x86 ISAs. (Although for example the ARM one only seems to document the ELF file layout, not the calling convention or process startup state.) https://uclibc.org/docs/psABI-x86_64.pdf is an outdated copy of the x86-64 psABI (0.99.7 from 2014). The version on GitHub has clearer wording of a few things and bugfixes in some examples.


Related: What are the calling conventions for UNIX & Linux system calls on i386 and x86-64 describes the system-call calling convention for x86-64 SysV (as well as i386 Linux vs. FreeBSD).

It also summarizes the function calling conventions for integer args. System calls don't take FP or SSE/AVX vector args, or structs by value, so the function-calling convention is more complicated.


Agner Fog has a calling conventions guide (covering Windows vs. Sys V, and the various conventions for 32-bit, and tips/tricks for writing functions you can use on either platform). This is a separate PDF from his optimization and microarchitecture guides and instruction tables (which are essential reading if you care about performance.)

Wikipedia has an x86 calling conventions article which describes various conventions, but mostly not in enough detail to use them for anything other than simple integer args. (e.g. no description of struct-packing rules).


Related: C++ ABI

GCC and Clang (on all architectures) use the C++ ABI originally developed for Itanium. https://itanium-cxx-abi.github.io/cxx-abi/. This is relevant for example for what requirements a C++ struct/class need to be passed in registers (e.g. being an aggregate according to some definition).