ARM Procedure Call Standard

The first choice - 32-bit PC vs 26-bit PC - is fixed by your ARM CPU.

The second choice - implicit vs explicit stack-limit checking - is fixed by a combination of memory-management hardware and operating system software: if your ARM-based environment supports implicit stack-limit checking then use it; otherwise use explicit stack-limit checking.

The third choice - of how to pass floating-point arguments - supports efficient argument passing in both of the following circumstances:

• the floating point instruction set is emulated by software and floating point operations are dynamically very rare;
• the floating point instruction set is supported by hardware or floating point operations are dynamically common.

Only the fourth choice between reentrant and non-reentrant variants is a true user level choice. Further, as the alternatives are compatible, each may be used where appropriate.

32-bit PC vs 26-bit PC

Newer ARM CPUs use a 32-bit program counter (in r15) and a separate PSR.

In 26-bit CPU modes, the PC + PSR is written to r14 by an ARM branch with link instruction, so it is natural for the APCS to require the reinstatement of the caller's PSR at function exit (a caller's PSR is preserved across a function call).

In 32-bit CPU modes this reinstatement would be unacceptably expensive in comparison to the gain from it, so the APCS does not require it and a caller's PSR flags may be corrupted by a function call.

Implicit vs Explicit Stack-Limit Checking

Safe programming practices demand that stack overflow be detected.

The APCS defines conventions for software stack-limit checking sufficient to support efficiently most requirements (including those of multiple threads and chunked stacks).

The majority of ARM-based systems are expected to require software stack-limit checking.

Floating-Point Arguments in Floating-Point Registers

On systems using a slow software emulation and making little use of floating-point, there is a small disadvantage to passing floating-point arguments in floating-point registers: all variadic functions (such as printf) become slower, while only function calls which actually take floating-point arguments become faster.

If your system has no floating-point hardware and is expected to make little use of floating point, then it is better not to pass floating-point arguments in floating-point registers. Otherwise, the opposite choice is best.

Reentrant vs Non-Reentrant Code

In general, code to be placed in ROM or loaded into a shared library is expected to be reentrant, while applications are expected not to be.

See also "C Language Calling Conventions".

APCS-2 Compatibility

APCS-R (APCS-2 for Acorn's RISC OS) is the following variant of APCS-3:

APCS-U (APCS-2 for Acorn's RISCiX) is the following variant of APCS-3:

The C compiler widens arguments of type float to type double to support inter-working between ANSI C and classic C.

Char, short, pointer and other integral values occupy 1 word in an argument list. Char and short values are widened by the C compiler during argument marshalling.

On the ARM, characters are naturally unsigned. In -pcc mode, the C compiler treats a plain char as signed, widening its value appropriately when used as an argument, (classic C lacks the signed char type, so plain chars are considered signed; ANSI C has signed, unsigned and plain chars, the third, conventionally reflecting the natural signedness of characters).

A structured value occupies an integral number of integer words (even if it contains only floating point values).

Argument List Marshalling

If passing floating-point (FP) arguments in FP registers, the first 4 FP arguments are loaded into FP registers.

The first 4 of the remaining argument words are loaded into a1-a4, and the remainder are pushed on to the stack in reverse order (so that arguments later in the argument list have higher addresses than those earlier in the argument list). As a consequence, a FP value can be passed in integer registers, or even split between an integer register and the stack.

This follows from the need to support variadic functions, (functions having a variable number of arguments, such as printf, scanf, etc.). Alternatives which avoid the passing of FP values in integer registers require that a caller know that a variadic function is being called, and use different argument marshalling conventions for variadic and non-variadic functions.

Non-Simple Value Return

A structure is called integer-like if its size is less than or equal to one word, and the offset of each of its addressable sub-fields is zero. An integer-like structured result is considered simple and is returned in a1.

struct {int a:8, b:8, c:8, d:8;}

and

union {int i; char *p;}

are both integer-like; however

struct {char a; char b; char c; char d;}

is not.

A multi-word or non-integer-like result is returned to an address passed as an additional first argument to the function call. At the machine level:

    TT tt = f(x, ...);

    TT tt; f(&tt, x, ...);

The important issues for function entry are:

• establishing the static base (if the function is to be reentrant);
• creating the stack backtrace data structure (if needed);
• saving the floating point variable registers (if required);
• checking for stack overflow (if the stack chunk limit is explicit).

If function F calls function G immediately before an exit from F, the call- exit sequence can often be replaced instead by a return to G. After this transformation, the return to G is called a tail call or tail continuation.

There are many subtle difficulties with tail continuations. Suppose stacked arguments are unstacked by callers (almost mandatory for variadic callees), then G cannot be directly tail-called if G itself takes stacked arguments. This is because there is no return to F to unstack them. Of course, if this call to G takes fewer arguments than the current call to F, then some of F's stacked arguments can be replaced by G's stacked arguments. However, this can be hard to assert if F is variadic. More straightforwardly, there may be no tail-call of G if the address of any of F's arguments or local variables has "leaked out" of F. This is because on return to G, the address may be invalidated by adjustment of the stack pointer. In general, this precludes tail calls if any local variable or argument has its address taken.

If a function is a leaf function, or all function calls from its body are tail calls and, in both cases, the function uses no v-registers (v1-v7) then the function need create no stack backtrace structure (such functions will also be termed frameless).

A leaf function which makes no use of static data need not establish a static base.

Function Entry - Establishing the Static Base

The ARM shared library mechanism supports both the direct linking together of functions into a link unit, and the indirect linking of functions with the stubs of other link units. Thus a reentrant function can be entered directly via a call from the same link unit (an intra-link-unit call), or indirectly via a function pointer or direct call from another link unit (an inter-link-unit call).

The general scheme for establishing the static base in reentrant code is:

    intra MOV ip, sb  ; intra link unit (LU) calls target here
    inter             ; inter-LU calls target here, having loaded
                      ; ip via an inter-LU or fn-pointer veneer.
    
          <create backtrace structure, saving sb>
    
          MOV sb, ip  ; establish sb for this LU
    
          <rest of entry>

    MOV    ip, sp     ; save current sp, ready to save as old sp
    STMFD  sp!, {a1-a4, v1-v5, sb, fp, ip, lr, pc}  ; as needed
    SUB    fp, ip, #4

Each of the registers v1-v7 need only be saved if it used by the called function. The minimum set of registers to be saved is {fp, old-sp, lr, pc}.

A reentrant function must avoid using ip in its entry sequence:

    STMFD  sp!, {sp, lr, pc}
    STMFD  sp!, {a1-a4, v1-v5, sb, fp}              ; as needed
    ADD    fp, sp, #8+4*|{a1-a4, v1-v5, sb, fp}|    ; as used above

For variadic functions the entry sequence is more complicated again. Usually, it will be desired or required to make a contiguous argument list on the stack. For non-reentrant variadic functions this can be done by:

    MOV    ip, sp           ; save current sp, ready to save as old sp
    STMFD  sp!, {a1-a4}     ; push arguments on stack
    SFMFD  f0, 4, [sp]!     ; push FP arguments on stack...
    STMFD  sp!, {v1-v6, fp, ip, lr, pc}       ; as needed
    SUB    fp, ip, #20      ; if all of a1-a4 pushed...

If floating point arguments are not being passed in floating point registers then there is no need for the SFMFD. SFM is not supported by the issue-1 floating-point instruction set and must be simulated by 4 STFEs. See the next section,"Function Entry - Saving and Restoring Floating Point Registers".

For reentrant variadic functions, the requirements are yet more complicated and the sequence becomes less elegant.

Function Entry - Saving and Restoring Floating Point Registers

• SFM and LFM are exact inverses;
• a SFM will never trap, whatever the IEEE trap mode and the value transferred (unlike a STFE which can trap on storing a signalling NaN);
• SFM and LFM transfer 3-word internal representations of floating point values which vary from implementation to implementation, and which, in general, are unrelated to any of the supported IEEE representations;
• any 1-4, cyclically contiguous floating-point registers can be transferred by SFM/LFM (e.g. {f4-f7}, {f6,f7,f0}, {f7,f0}, {f1}).

    SFMFD  f4, 4, [sp]!           ; save f4-f7 on a Full Descending stack,
                                  ; adjusting sp as values are pushed.

    LFMEA  f4, 4, [fp, #-N]       ; restore f4-f7; fp-N points just
                                  ; above the floating point save area.

In issue-1 instruction set compatibility modes, SFM and LFM have to be simulated using sequences of STFEs and LDFEs.

Function Entry - Checking for Stack Limit Violations

In other environments, the validity of the stack must be checked on function entry and, perhaps at other times. There are three cases:

• the function uses 256 bytes or less of stack space;
• the function uses more than 256 bytes of stack space, but the amount is known and bounded at compile time;
• the function uses an amount of stack space unknown until run time.

In Modula-2, Pascal and other languages there may be arrays created on block entry or passed as open array arguments, the size of which is unknown until run time. Spiritually, these are located in the callee's stack frame, so impact stack limit checking. In practice, this adds little complication, as discussed in "Stack Limit Checking - Vari-Sized Frames".

The check for stack limit violation is made at the end of the function entry sequence, by which time ip is available as a work register. If the check fails, a standard run-time support function (__rt_stkovf_split_small or __rt_stkovf_split_big) is called. Each environment which supports explicit stack limit checking must provide these functions, which can do one of the following:

• terminate execution;
• extend the existing stack chunk, decrementing sl;
• allocate a new stack chunk, resetting sp and sl to point into it, and guaranteeing that an immediate repeat of the limit check will succeed.

    <create stack backtrace structure> 
    
    CMPS   sp, sl
    BLLT   |__rt_stkovf_split_small|
    SUB    sp, sp, #<size of locals>    ; <= 256, by hypothesis

    SUB    ip, sp, #FrameSizeBound      ; can be done in 1 instr
    CMPS   ip, sl
    BLLT   |__rt_stkovf_split_big|
    SUB    sp, sp, #InitFrameSize       ; may take more than 1 instr

InitFrameSize is the initial stack frame size: subsequent adjustments within the called function require no limit check.

After a call to __rt_stkovf_split_big, fp and sp do not, necessarily, point into the same stack chunk. Arguments passed on the stack must be addressed by offsets from fp, not by offsets from sp.

Stack Limit Checking - Vari-Sized Frames

The handling of frames the size of which is unknown at compile time, is identical to the handling of large frames, save that:

• the computation of the proposed new stack pointer is more complicated, involving arguments to the function itself;
• the addressing of the vari-sized objects is more complicated than the addressing of fixed size objects need be;
• the vari-sized objects have to be initialised by the called function.

        |                               |
        +-------------------------------+
        | Stack-based arguments         |
        +-------------------------------+
        | Stack backtrace data structure|  <--- fp points here
        | ... reg save area...          |
        +-------------------------------+
        +-------------------------------+
        | Area for vari-sized objects,  |
        | passed by value or created on |
        | block entry                   |
        +-------------------------------+
        | Fixed size remainder of frame |
        +-------------------------------+  <--- sp points here

The callee addresses the copied objects via pointers located in the fixed size part of the stack frame, immediately above sp. These can be addressed relative to sp. The original arguments are all addressable relative to fp.

After a call to __rt_stkovf_split_big, fp and sp do not, necessarily, point into the same stack chunk. Arguments passed on the stack must be addressed by offsets from fp, not by offsets from sp.

If a nested block extends the stack by an amount which can't be known until run time then the block entry must include a stack limit check.

Function Exit

Exit from functions which use no stack and save no floating point registers is particularly simple:

    MOV    pc, lr

Exit from other functions which save no floating-point registers is by:

    LDMEA  fp, {v1-v5, sb, fp, sp, pc}        ; as saved

    typedef struct {...; int a; ...} foo;
    int foo_get_a(foo* f) {return(f-a);}

    LDR    a1, [a1, #aOffset]
    MOV    pc, lr                 ; MOVS in 26-bit modes

    int get(Stream *s)
    {
        if (s->cnt > 0)
        { --s;
            return *(s-p++);
        }
        else
        {
            ...
        }
    }

    get
        MOV    a3, a1
    ; if (s->cnt > 0)
        LDR    a2, [a3, #cntOffset]
        CMPS   a2, #0
    ; try the fast case,frameless and heavily conditionalized
        SUBGT  a2, a2, #1
        STRGT  a2, [a3, #cntOffset]
        LDRGT  a2, [a3, #pOffset]
        LDRBGT a1, [a2], #1
        STRGT  a2, [a3, #pOffset]
        MOVGT  pc, lr
    ; else, form a stack frame and handle the rest as normal code.
        MOV    ip, sp
        STMDB  sp!, {v1-v3, fp, ip, lr, pc}
        CMP    sp, sl
        BLLT   |__rt_stkovf_split_small|
        ...
        LDMEA  fp, {v1-v3, fp, sp, pc}

    extern void *malloc(size_t n)
    {
        return primitive_alloc(NOTGCABLEBIT, BYTESTOWORDS(n));
    }

    malloc
        ADD    a1, a1, #3         ; 1S
        MOV    a2, a1, LSR #2     ; 1S - BITESTOWORDS(n)
        MOV    a1, #1073741824    ; 1S - NOTGCABLEBIT
        B      primitive_alloc    ; 1N+2S = 4S

    MOV    ip, pc