@c @c COPYRIGHT (c) 1988-2002. @c On-Line Applications Research Corporation (OAR). @c All rights reserved. @c @c $Id$ @c @chapter Calling Conventions @section Introduction Each high-level language compiler generates subroutine entry and exit code based upon a set of rules known as the compiler's calling convention. These rules address the following issues: @itemize @bullet @item register preservation and usage @item parameter passing @item call and return mechanism @end itemize A compiler's calling convention is of importance when interfacing to subroutines written in another language either assembly or high-level. Even when the high-level language and target processor are the same, different compilers may use different calling conventions. As a result, calling conventions are both processor and compiler dependent. RTEMS supports the Embedded Application Binary Interface (EABI) calling convention. Documentation for EABI is available by sending a message with a subject line of "EABI" to eabi@@goth.sis.mot.com. @section Programming Model This section discusses the programming model for the PowerPC architecture. @subsection Non-Floating Point Registers The PowerPC architecture defines thirty-two non-floating point registers directly visible to the programmer. In thirty-two bit implementations, each register is thirty-two bits wide. In sixty-four bit implementations, each register is sixty-four bits wide. These registers are referred to as @code{gpr0} to @code{gpr31}. Some of the registers serve defined roles in the EABI programming model. The following table describes the role of each of these registers: @ifset use-ascii @example @group +---------------+----------------+------------------------------+ | Register Name | Alternate Name | Description | +---------------+----------------+------------------------------+ | r1 | sp | stack pointer | +---------------+----------------+------------------------------+ | | | global pointer to the Small | | r2 | na | Constant Area (SDA2) | +---------------+----------------+------------------------------+ | r3 - r12 | na | parameter and result passing | +---------------+----------------+------------------------------+ | | | global pointer to the Small | | r13 | na | Data Area (SDA) | +---------------+----------------+------------------------------+ @end group @end example @end ifset @ifset use-tex @sp 1 @tex \centerline{\vbox{\offinterlineskip\halign{ \vrule\strut#& \hbox to 1.75in{\enskip\hfil#\hfil}& \vrule#& \hbox to 1.75in{\enskip\hfil#\hfil}& \vrule#& \hbox to 2.50in{\enskip\hfil#\hfil}& \vrule#\cr \noalign{\hrule} &\bf Register Name &&\bf Alternate Names&&\bf Description&\cr\noalign{\hrule} &r1&&sp&&stack pointer&\cr\noalign{\hrule} &r2&&NA&&global pointer to the Small&\cr &&&&&Constant Area (SDA2)&\cr\noalign{\hrule} &r3 - r12&&NA&¶meter and result passing&\cr\noalign{\hrule} &r13&&NA&&global pointer to the Small&\cr &&&&&Data Area (SDA2)&\cr\noalign{\hrule} }}\hfil} @end tex @end ifset @ifset use-html @html
Register Name Alternate Name Description
r1 sp stack pointer
r2 na global pointer to the Small Constant Area (SDA2)
r3 - r12 NA parameter and result passing
r13 NA global pointer to the Small Data Area (SDA)
@end html @end ifset @subsection Floating Point Registers The PowerPC architecture includes thirty-two, sixty-four bit floating point registers. All PowerPC floating point instructions interpret these registers as 32 double precision floating point registers, regardless of whether the processor has 64-bit or 32-bit implementation. The floating point status and control register (fpscr) records exceptions and the type of result generated by floating-point operations. Additionally, it controls the rounding mode of operations and allows the reporting of floating exceptions to be enabled or disabled. @subsection Special Registers The PowerPC architecture includes a number of special registers which are critical to the programming model: @table @b @item Machine State Register The MSR contains the processor mode, power management mode, endian mode, exception information, privilege level, floating point available and floating point excepiton mode, address translation information and the exception prefix. @item Link Register The LR contains the return address after a function call. This register must be saved before a subsequent subroutine call can be made. The use of this register is discussed further in the @b{Call and Return Mechanism} section below. @item Count Register The CTR contains the iteration variable for some loops. It may also be used for indirect function calls and jumps. @end table @section Call and Return Mechanism The PowerPC architecture supports a simple yet effective call and return mechanism. A subroutine is invoked via the "branch and link" (@code{bl}) and "brank and link absolute" (@code{bla}) instructions. This instructions place the return address in the Link Register (LR). The callee returns to the caller by executing a "branch unconditional to the link register" (@code{blr}) instruction. Thus the callee returns to the caller via a jump to the return address which is stored in the LR. The previous contents of the LR are not automatically saved by either the @code{bl} or @code{bla}. It is the responsibility of the callee to save the contents of the LR before invoking another subroutine. If the callee invokes another subroutine, it must restore the LR before executing the @code{blr} instruction to return to the caller. It is important to note that the PowerPC subroutine call and return mechanism does not automatically save and restore any registers. The LR may be accessed as special purpose register 8 (@code{SPR8}) using the "move from special register" (@code{mfspr}) and "move to special register" (@code{mtspr}) instructions. @section Calling Mechanism All RTEMS directives are invoked using the regular PowerPC EABI calling convention via the @code{bl} or @code{bla} instructions. @section Register Usage As discussed above, the call instruction does not automatically save any registers. It is the responsibility of the callee to save and restore any registers which must be preserved across subroutine calls. The callee is responsible for saving callee-preserved registers to the program stack and restoring them before returning to the caller. @section Parameter Passing RTEMS assumes that arguments are placed in the general purpose registers with the first argument in register 3 (@code{r3}), the second argument in general purpose register 4 (@code{r4}), and so forth until the seventh argument is in general purpose register 10 (@code{r10}). If there are more than seven arguments, then subsequent arguments are placed on the program stack. The following pseudo-code illustrates the typical sequence used to call a RTEMS directive with three (3) arguments: @example load third argument into r5 load second argument into r4 load first argument into r3 invoke directive @end example @section User-Provided Routines All user-provided routines invoked by RTEMS, such as user extensions, device drivers, and MPCI routines, must also adhere to these same calling conventions.