top logo menu kitty mascot
AROS.ORG Developers Localization Bounties

AROS Application Binary Interface

Inhalt

Introduction

This document describes the Application Binary Interface (ABI) of AROS: the rules that compiled code must follow so that programs, libraries, devices and the kernel can work together without being built from the same sources at the same time.

It covers the parts of the ABI that are common to every CPU:

Everything that depends on the processor (register usage, vector formats, compiler options, relocation types) is described in a separate page for each CPU family:

The intended readers are people who write assembly or compiler support for AROS, who port AROS to a new platform, who write libraries and drivers, or who need to debug at the machine level. Application programmers who only use C and the system headers get the ABI for free from the compiler and the AROS_* macros, but may still find the sections on data types, tag lists and hooks useful.

The SMP (multi-processor) aspects of the ABI are not covered here.

Terminology

Rule
A statement using must, must not or is describes something that binary compatibility depends on.
Implementation note
A statement introduced as an implementation note describes how the current sources do something. Code must not depend on it.
Port
A combination of a platform and a CPU that AROS can be built for, for example pc-x86_64, linux-x86_64, raspi-aarch64 or amiga-m68k.
Native port
A port where AROS runs directly on the hardware.
Hosted port
A port where AROS runs as a program on top of another operating system (the host), such as Linux, macOS or Windows.
Module
Any loadable AROS binary: a program, library, device, resource, handler or class.

Design principles

AROS defines its own ABI

AROS is a stand-alone operating system. Its ABI is defined by AROS, for AROS, and is the same whether AROS runs natively or hosted.

For each CPU the AROS ABI is based on a well-known C calling standard (for example the System V AMD64 ABI on x86_64 or AAPCS64 on AArch64) with a small number of AROS specific additions. Where AROS says something different from the base standard, or from the conventions of any other operating system, AROS code follows the AROS rule.

One ABI for each CPU

There is exactly one AROS ABI for each ABI target listed in ABI targets. The platform is not part of it. An ordinary application or library that is built for an ABI target and that only uses the public AROS interfaces must run unchanged on every port of that target. For example, the same x86_64 binary must run on pc-x86_64, linux-x86_64, darwin-x86_64 and mingw32-x86_64.

The only binaries that are expected to be specific to one port are those that talk to the platform itself: the kernel, the bootstrap, hardware drivers, and the drivers that connect a hosted AROS to its host.

Hosted ports do not influence the ABI

A host operating system has its own ABI, and it will often differ from the AROS one: it may reserve a register, lay out variadic arguments differently, require a different stack alignment or use a different calling convention altogether. None of this changes the AROS ABI.

  • A hosted port must run the same AROS binaries as the native port for the same CPU, with the same compiler settings.
  • A hosted port must not be built with a modified ABI in order to suit its host. A port that can only run binaries built specially for it is not acceptable.
  • It is the responsibility of each hosted implementation to provide whatever mechanism is needed to work around the constraints of its host. Those mechanisms belong in the port's own kernel, bootstrap and host-interface code and must be invisible to applications.

The requirements are set out in detail in Hosted ports.

Relationship to AmigaOS

On m68k, AROS aims to be binary compatible with AmigaOS 3.x: structures have the same layout, library functions take their arguments in the same registers, and AmigaOS executables can be loaded and run. See the m68k page.

On every other CPU, AROS is source compatible with the AmigaOS API. The register names that appear in function definitions are kept for documentation and for m68k, but arguments are passed using the C calling convention of the CPU.

ABI targets

ABI target Data model Byte order FPU Base calling standard Details
m68k ILP32 big soft AmigaOS register calls m68k
i386 ILP32 little x87 System V i386 (cdecl) x86
x86_64 LP64 little SSE2 System V AMD64 x86
arm ILP32 little soft AAPCS arm
armhf ILP32 little VFP AAPCS, VFP variant arm
armeb ILP32 big soft AAPCS arm
aarch64 LP64 little NEON AAPCS64 arm
ppc ILP32 big hard System V PowerPC ppc
riscv ILP32 little D RISC-V psABI, ILP32D riscv
riscv64 LP64 little D RISC-V psABI, LP64D riscv

Two ABI targets are never binary compatible with each other, even when they share a CPU. In particular arm and armhf pass floating point arguments differently and their binaries must not be mixed.

Data representation

Fundamental types

The system headers define a set of fixed-size types in <exec/types.h>. Their sizes are the same on all targets, except for the pointer-sized types.

Type Size Notes
BYTE/UBYTE 8 bits  
WORD/UWORD 16 bits  
LONG/ULONG 32 bits Always 32 bits, including on 64-bit targets. C type int.
QUAD/UQUAD 64 bits  
IPTR/SIPTR size of a pointer Integer that can hold a pointer. C type long.
APTR size of a pointer void *
BOOL 16 bits C type short
FLOAT 32 bits IEEE 754 single
DOUBLE 64 bits IEEE 754 double
BPTR size of a pointer See BCPL pointers and strings

The 32-bit targets use the ILP32 data model (int, long and pointers are 32 bits). The 64-bit targets use LP64 (int is 32 bits; long and pointers are 64 bits).

The following C types are fixed by the AROS toolchains on every target:

C type Definition
size_t unsigned long
ptrdiff_t long
wchar_t unsigned int (32 bits)

Bemerkung

A value that may hold a pointer must be stored in an IPTR (or SIPTR, APTR), never in a ULONG. This is the most common source of errors when AmigaOS code is moved to a 64-bit target.

Byte order

Multi-byte values are stored in the natural byte order of the ABI target, as listed in ABI targets. The macro AROS_BIG_ENDIAN is 1 on big-endian targets and 0 otherwise. Data that is exchanged with files or other machines has the byte order defined by its format and must be converted with the AROS_BE2LONG() family of macros.

Alignment and structure layout

System structures are laid out using the natural alignment rules of the C compiler for the target. There is no global packing. The consequences are:

  • On m68k, 16-bit and larger types are aligned to 2 bytes, which gives the same structure layout as AmigaOS.
  • On the other 32-bit targets, 32-bit types and pointers are aligned to 4 bytes.
  • On 64-bit targets, pointers, IPTR and QUAD are aligned to 8 bytes.

A structure that describes a file format or an on-disk or on-wire layout is declared with the __packed attribute and has the same layout everywhere.

Each CPU page lists the alignment constants (AROS_LONGALIGN, AROS_PTRALIGN, AROS_WORSTALIGN and so on) from <aros/cpu.h>. AROS_WORSTALIGN is the alignment that is sufficient for any object, and is the minimum alignment of memory returned by the Exec allocators.

Tag items

struct TagItem consists of two pointer-sized, pointer-aligned slots on every target:

struct TagItem
{
    Tag  ti_Tag;    /* occupies one IPTR-sized slot */
    IPTR ti_Data;
};

A tag list is therefore an array of IPTR pairs. On 64-bit targets the 32-bit tag value is padded to 8 bytes.

BCPL pointers and strings

BPTR and BSTR are the handle types of dos.library.

  • On m68k a BPTR is an address divided by four and a BSTR is a BPTR to a string that starts with a length byte, as on AmigaOS.
  • On all other targets a BPTR is an ordinary pointer and a BSTR points to an ordinary NUL-terminated string.

Code must always use BADDR(), MKBADDR() and the AROS_BSTR_* macros from <dos/bptr.h>, which do the right thing on every target, and must use BNULL for an empty BPTR.

Calling conventions

AROS has four kinds of function interface:

C functions

Ordinary C functions follow the base calling standard of the ABI target, as given in ABI targets and detailed on the CPU pages. This includes argument passing, return values, the set of registers a function must preserve, and stack alignment at the point of a call.

Library bases and vector tables

A library (and equally a device or resource) is represented by a library base: a pointer to a struct Library followed by the library's own data. Its functions are reached through a vector table that is located immediately below the base, at negative offsets:

lower addresses
        +---------------------------+
        | vector n                  |  base - n * LIB_VECTSIZE
        |   ...                     |
        | vector 5  (first public)  |
        | vector 4  ExtFunc         |
        | vector 3  Expunge         |
        | vector 2  Close           |
        | vector 1  Open            |  base - LIB_VECTSIZE
base -> +---------------------------+
        | struct Library            |
        | library specific data     |
        +---------------------------+
higher addresses
  • Each function has a fixed library vector offset (LVO) number n, starting at 1. The vector for function n is at base - n * LIB_VECTSIZE.
  • The first four vectors are reserved for Open, Close, Expunge and a reserved function. Public functions start at vector 5.
  • LVO numbers are part of a library's public interface and never change once published.

The size and content of a vector depend on the CPU:

ABI target LIB_VECTSIZE Vector content
m68k 6 A JMP instruction to the function
32-bit, not m68k 4 The address of the function
64-bit 8 The address of the function

On m68k a caller jumps into the vector. On all other targets the vector holds a function pointer which the caller loads and calls. Code must not hard-code either form: use the macros below, __AROS_GETVECADDR() to read a vector, and SetFunction() to change one. SetFunction() takes the offset as a negative byte count, that is -n * LIB_VECTSIZE.

Library functions

A library function is defined and called with the AROS_LH (header) and AROS_LC (call) macro families from <aros/libcall.h>. Each argument names the m68k register it is assigned to:

AROS_LH2(APTR, AllocMem,
    AROS_LHA(IPTR,  byteSize,     D0),
    AROS_LHA(ULONG, requirements, D1),
    struct ExecBase *, SysBase, 33, Exec)
{
    AROS_LIBFUNC_INIT
    ...
    AROS_LIBFUNC_EXIT
}

How the arguments and the library base are passed depends on the target:

ABI target Passing of arguments and library base
m68k Each argument in the named register. Base in A6.
i386 Arguments on the stack in the order written. Base passed as an extra first argument, in %eax.
all others Arguments as for a C function, in the order written. Base passed as an extra last argument.

On every target except m68k the register names are ignored. Passing the base last (or in a register that is not otherwise used for arguments) means that a function which does not need its base can simply not declare it.

Programs normally do not use AROS_LC directly. The headers in <proto/> provide each library function as an inline function or macro that passes the library base for the caller.

C-style library functions

A library may also export functions that are written as plain C functions with no register assignment and no library base argument. The C library and most ported libraries are built this way.

Such a function is called through a small stub in the link library. The stub loads the library base, fetches the function address from the vector table and jumps to it, leaving all argument registers and the stack exactly as the caller set them up. The function therefore sees an ordinary C call.

While jumping through the vector the stub leaves the library base in a scratch register, where the library can pick it up if it needs it:

ABI target Register carrying the library base
m68k A0
i386 %eax
x86_64 %r11
arm, armhf, armeb r12 (ip)
aarch64 x16
ppc r12
riscv, riscv64 t6

These registers are temporaries in the base calling standard, so no register is permanently reserved for a library base on any target.

Libraries with a separate base for each opener or each task

A library can be built so that every opener, or every task, gets its own copy of the library base. C-style functions of such a library, and the libraries it uses in turn, find the right base through a task storage slot (provided by task.resource) rather than through a reserved register. This is handled entirely by the code that genmodule generates and by the link libraries (the _rel variants); it places no requirement on callers.

User functions and hooks

A function that the system calls back (an interrupt handler, a task entry point, a hook, a class dispatcher) is defined with the AROS_UFH macro family from <aros/asmcall.h> and called with AROS_UFC.

  • On m68k each argument is passed in the named register.
  • On all other targets, including i386, the function is an ordinary C function that takes the arguments in the order written.

A struct Hook entry point always has this form:

AROS_UFH3(IPTR, MyHook,
    AROS_UFHA(struct Hook *, hook,    A0),
    AROS_UFHA(APTR,          object,  A2),
    AROS_UFHA(APTR,          message, A1))
{
    AROS_USERFUNC_INIT
    ...
    AROS_USERFUNC_EXIT
}

Hooks are called with CallHookPkt() or the CALLHOOKPKT() macro. Note that the order of the arguments is hook, object, message on every target; only m68k uses the registers.

Variadic functions, tag lists and messages

Many functions have a variadic form that takes a tag list or a method message directly as arguments, for example OpenWindowTags() or DoMethod(). The following rules apply on all targets:

  • Every tag, tag value, method identifier and message field that is passed as a variadic argument occupies one IPTR-sized slot. Smaller values are widened. On a 64-bit target a pointer or an IPTR value must not be truncated to 32 bits, and an integer constant that is passed where a pointer-sized value is expected must have the right type.
  • A structure that mirrors a variadic argument list, such as a BOOPSI method message, declares each field with the STACKED attribute so that the structure has the same layout as the list of slots.
  • The variadic function converts its arguments into a real struct TagItem array or message before calling the non-variadic function. On most targets the arguments are passed in registers and must be copied; the AROS_SLOWSTACKTAGS, AROS_SLOWSTACKMETHODS and AROS_SLOWSTACKHOOKS macro families hide the difference. On m68k and i386 the arguments are already laid out contiguously on the stack and are used in place.

Code must never assume that variadic arguments form an array in memory. New variadic wrappers must be written with the AROS_SLOWSTACK* macros.

The stack

Programs can request a larger stack by defining the __stack variable; the startup code then re-runs main() on a stack of that size.

Program and module entry

Programs

The entry point of a program is the first byte of its first code segment. It has this interface:

AROS_PROCH(entry, argstr, argsize, SysBase)

SIPTR entry(STRPTR argstr, ULONG argsize, struct ExecBase *SysBase);

argstr and argsize describe the command line. The return value is the program's return code. On m68k the arguments arrive in A0 and D0 as on AmigaOS; see the m68k page.

The standard startup code provides this entry point, places it in the .aros.startup section so that it is linked first, initialises the C runtime and calls main().

Libraries, devices and resources

A module is found through its struct Resident ("ROMTag") structure. Its initialisation function receives the library base, the segment list of the module and SysBase, in that order (D0, A0, A6 on m68k).

Finding SysBase

SysBase, the base of exec.library, is the root from which every other system service is reached.

  • On m68k the address of SysBase is stored at absolute address 4, as on AmigaOS.
  • On all other targets there is no fixed address. SysBase is passed to every program and module when it is started, as shown above, and the startup code stores it in the global variable SysBase.

Code other than m68k code must never read address 4.

Executable file format

ELF relocatable objects

AROS programs and modules are ELF files of type ET_REL, that is, relocatable objects, on every target. A module is the result of a final partial link (ld -r) by collect-aros, the linker driver of the AROS toolchain, with all references between its own object files resolved.

  • The file must match the ELF class, byte order and machine type of the ABI target.
  • collect-aros marks the file with EI_OSABI = ELFOSABI_AROS (15) and EI_ABIVERSION = 1.
  • There is no dynamic linking. A module must not have undefined symbols (undefined weak symbols resolve to zero) and must not contain common symbols. Code in different modules is connected at run time through libraries and their vector tables, not through symbols.
  • There is no dynamic global offset table or procedure linkage table. Modules must be compiled as non-position-independent code.
  • There is no ELF thread-local storage. See Thread-local storage.

Loading

LoadSeg() turns the allocatable sections of the file into a segment list, the same structure AmigaOS uses: a chain of memory blocks, each starting with its size and a BPTR to the next. It then applies the relocations. The CPU pages list the relocation types each loader accepts; a module that contains any other relocation type is not loaded.

Segments are placed wherever memory is available. Because of this:

  • a module must not assume any particular load address, and
  • code must be built with a code model that works at any address. The required compiler options are given on each CPU page.

A section whose name ends in .MEMF_CHIP, .MEMF_LOCAL, .MEMF_KICK, .MEMF_FAST or .MEMF_PUBLIC is loaded into memory of that type.

Hunk format

The m68k ports also load AmigaOS "hunk" executables, and the binaries on amiga-m68k installation media are distributed in hunk format; see the m68k page.

Symbol sets

Constructors, destructors, library auto-opening and module initialisation functions are collected at link time into symbol sets (the ADD2INIT(), ADD2EXIT(), ADD2LIBS() macros of <aros/symbolsets.h>). collect-aros gathers the entries of each set into a table that the startup code walks. This is an agreement between the toolchain and the startup code, not something the loader knows about.

Thread-local storage

AROS has no ELF thread-local storage and reserves no thread pointer register for applications. The GNU toolchain is configured without TLS support and the LLVM toolchain uses emulated TLS.

Per-task data is kept in task storage slots (AllocTaskStorageSlot(), GetTaskStorageSlot() and SetTaskStorageSlot() of task.resource) or in tc_UserData.

Where a CPU defines a thread pointer register it is not available to applications; the CPU pages give the details.

C and C++ runtime

Processor state of a task

Hosted ports

This section turns the principle that hosted ports do not influence the ABI into concrete requirements.

Requirements

  1. Same binaries. A hosted port must load and run the same ELF modules as every other port for its ABI target. AROS code for a hosted port is built with the AROS cross-toolchain and the same ABI-affecting options as the native port, never with the host's compiler conventions.
  2. All registers behave as the AROS ABI says. If the host treats a register differently from the AROS ABI, for example by reserving it for its own use or by not preserving it, the port must hide this. AROS code remains free to use every register that the AROS ABI makes available.
  3. Host calls are confined. Only the port's own modules call the host, and only through the mechanisms below. Every such call must convert between the two ABIs where they differ: calling convention, variadic argument layout, stack alignment, and registers that the host may clobber.
  4. Task state is complete. The port's task switching must save and restore everything that the AROS ABI defines as belonging to a task, whatever the host's own notion of thread state is.
  5. Host restrictions are the port's problem. Restrictions such as a prohibition on memory that is both writable and executable, or a host that sends asynchronous signals on the task's stack, must be handled inside the port.

Mechanisms

hostlib.resource
Lets a module open a host shared library and obtain the addresses of host functions. Calls to host functions are serialised and bracketed by the port.
The host interface
A table of functions that the host-side bootstrap hands to the AROS kernel. On ports where the bootstrap is built with a compiler that uses a different calling convention, the entries are declared with the AROS convention so that AROS code calls them normally.
AROS_HOST_BARRIER
A macro from <aros/cpu.h> that must follow each call into the host. It tells the compiler about registers that the host may have changed although the AROS ABI says they are preserved. It expands to nothing on ports where no register is affected.
Calling convention attributes
Where the host uses a different calling convention, host function pointers are declared with an explicit attribute so that the compiler generates the conversion. The Windows-hosted x86_64 port, for example, declares Windows functions as ms_abi.
Argument layout shims
Where the host lays out arguments differently, the port calls the host through a prototype that puts each argument where the host expects it. <host_vacall.h> does this for variadic host functions on macOS on AArch64.

These mechanisms exist so that the differences are dealt with at the boundary. They must not be used as a reason to build AROS itself differently.

ABI version

aros.library reports the major version of the ABI through ArosInquire() with the AI_ArosABIMajor tag. The value -1 means that the ABI is still under development and may change; this is the value in the current development tree. The same value is installed as the file ENVARC:ABI.

Executables carry EI_ABIVERSION = 1 in their ELF header, as described in Executable file format. The loaders do not currently verify the OS ABI or ABI version fields.

Source references

The ABI is defined by the following parts of the AROS source tree. Where this document and the sources disagree, the sources are authoritative.

Location Content
compiler/include/aros/cpu.h CPU selection and defaults
arch/<cpu>-all/include/aros/cpu.h Per-CPU types, alignment and vector format
arch/<cpu>-all/include/aros/genmodule.h Per-CPU library stubs
arch/<cpu>-all/include/aros/cpucontext.h Saved processor state
compiler/arossupport/include/libcall.h AROS_LH/AROS_LC
compiler/arossupport/include/asmcall.h AROS_UFH/AROS_UFC
compiler/include/exec/types.h Fundamental types
compiler/include/exec/libraries.h Library base and vectors
compiler/include/utility/tagitem.h Tag items and variadic tags
compiler/include/utility/hooks.h Hooks
compiler/include/dos/bptr.h BPTR and BSTR
compiler/include/dos/elf.h ELF definitions
rom/dos/internalloadseg_elf.c ELF loader and relocations
tools/collect-aros Linker driver
tools/genmodule Module glue code generator
tools/crosstools Toolchain patches
configure.in ABI-affecting compiler flags