From 0d73e1bf9abf79db911f049f8a7240f088b84076 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Sat, 10 Oct 2026 07:24:24 -0500 Subject: [PATCH] Add a Developer Resources section with links to ABI documentation We need to refer to these rather often, but there hasn't been a common place to locate this information. --- src/SUMMARY.md | 8 +- src/appendix/additional-resources.md | 156 +++++++++++++++++++++++++++ 2 files changed, 161 insertions(+), 3 deletions(-) create mode 100644 src/appendix/additional-resources.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 7c4ffe7b05..22d235e00b 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -274,10 +274,12 @@ [Appendix C: Code Index](./appendix/code-index.md) -[Appendix D: Compiler Lecture Series](./appendix/compiler-lecture.md) +[Appendix D: Additional Resources](./appendix/additional-resources.md) -[Appendix E: Bibliography](./appendix/bibliography.md) +[Appendix E: Compiler Lecture Series](./appendix/compiler-lecture.md) -[Appendix F: Reading club sessions](./appendix/reading-club.md) +[Appendix F: Bibliography](./appendix/bibliography.md) + +[Appendix G: Reading club sessions](./appendix/reading-club.md) [Appendix Z: HumorRust](./appendix/humorust.md) diff --git a/src/appendix/additional-resources.md b/src/appendix/additional-resources.md new file mode 100644 index 0000000000..272cbe5704 --- /dev/null +++ b/src/appendix/additional-resources.md @@ -0,0 +1,156 @@ +# Additional Resources + +## ABIs and Platform Specifics + +### System V + +The System V ABIs are defined by a General ABI (gABI), which cross-platform things like linking +behavior and the ELF format, and by processor-speciic ABIs (psABI) that define data layout and +calling convention. The gABI can be found at . + +#### ARM (Arm32 and AArch64) + +ABIs are located at . The aapcs32 and aapcs64 directories +are likely the most interesting. These ABIs are actively developed and discussed at that repository. + +#### AMDGPU + +The LLVM guide at is likely the best collection of +resources for this architecture. + +#### AVR + +The AVR calling convention is detailed at the GCC Wiki, . The +wiki is actively updated as needed. + +#### BPF + +A minimal ABI is defined at . + +#### CSky + +The LLVM documentation links to , which contains +a document `C-SKY_V2_CPU_Applications_Binary_Interface_Standards_Manual.pdf`. + +#### Hexagon + +The Hexagon ABI can be found at . + +#### Loongarch + +ABIs are located at , with a rendered version at +. This ABI is actively +developed and discussed at that repository. + +#### m68k + +An ABI is described at . + +#### MIPS + +The o32 ("old 32") ABI is described in [_System V Application Binary Interface: MIPS +RISC Processor Supplement_](https://refspecs.linuxfoundation.org/elf/mipsabi.pdf). +The n32 and n64 ("new 32" and "new 64") ABIs are described in the [_MIPSproTM N32 ABI +Handbook_](https://irix7.com/techpubs/007-2816-005.pdf). There is also a porting guide for n64 that +may be helpful . + +#### MSP430 + +The document _MSP430 Embedded Application Binary Interface_ is available at +. + +#### NVPTX + +LLVM documentation directs to . + +#### PowerPC + +There are a few relevant documents for PowerPC ABI: + +* [_System V Application Binary Interface: PowerPC Processor + Supplement_](https://refspecs.linuxfoundation.org/elf/elfspec_ppc.pdf) is the original 32-bit + PowerPC ABI specification. +* [_Power Architecture™ 32-bit Application Binary Interface Supplement 1.0 - Linux® & + Embedded_](https://web.archive.org/web/20120608163804/https://www.power.org/resources/downloads/Power-Arch-32-bit-ABI-supp-1.0-Unified.pdf) + (web archive) is the latest version of the 32-bit ABI. Its source is hosted at + but effectively unmaintained. +* [_64-bit PowerPC ELF Application Binary Interface Supplement + 1.9_](https://refspecs.linuxfoundation.org/ELF/ppc64/PPC-elf64abi-1.9.html) is the original 64-bit + ABI, last updated in 2004. This is known as ELFv1, and still used by default on some big endian + PowerPC64 targets. +* [_64-bit ELF V2 ABI Specification: Power + Architecture_](https://openpower.foundation/specifications/64bitelfabi/) is the replacement ABI + and used by default on most PowerPC64 targets. + +#### RISC-V + +Ratified RISC-V ABIs are located at . More +recent snapshots can be viewed at , with +development happening at . + +#### s390x + +The ABI is located at with a published PDF available at +. This ABI is actively developed and discussed +at that repository. + +Historical ISAs can be found at . + has a great overview of other ABI +components such as linking and TLS. + +#### SPARC + +_SCD 2.4.1_ available at describes both the +32-bit and 64-bit ABIs. _SPARC psABI 3.0_, available at that same link, is an older description of +the 32-bit ABI. + +#### x86 + +The 32-bit ABI (i386) is located at . The 64-bit ABI (amd64) +is located at . Both of these are +actively developed and discussed on mailing lists at and +. + +#### Xtensa + +TODO + +### Apple + +Apple largely follows the System V ABIs but documents a few exceptions at the following links: + +* Arm64: +* x86: + +### Microsoft + +Microsoft's x86-64 ABI is defined at . +There are a few different x86-32 conventions: + +* Cdecl (default): +* Stdcall: +* Fastcall: +* Thiscall: + +As well as a few that aren't supported by Rust (`__clrcall`, `__vectorcall`, `__preserve_none`). + +Aarch64 targets generally use the AAPCS64 calling convention. There are some exceptions listed at +. + +Register mappings for arm64ec are documented at +. + does a great job of explaining more about +how this works. + +#### Wasm + +The way that C types are broken down into Wasm types is described at +. + +### Additional Resources for Platform Specifics + +The following links aggregate more resources + +* Links to other resources such as ELF and DWARF: +* Links to a number of standards including ISAs +* More about System V ABIs, especially x86: