IAR Application Note V850 Calling Convention SUMMARY This application note describes the calling convention used by IAR Systems V850 compiler for C and Embedded C++. The intended audience is developers who write tools and libraries in assembly language. KEYWORDS Calling convention, v850, and assembler libraries. What is a Calling Convention? A calling convention is the way one function in a program calls another function. For the average programmer of high-level languages this is of little interest since the compiler will handle this automatically. However, if a function is written in assembler it is imperative to know where and how its parameters can be found, how return to the program location from where it was called, and how store the return value. It is also important to know which registers an assembler-level routine can destroy. If the programmer makes a conservative assumption concerning the available register the program might be ineffective. If the program destroys too many registers the result would be a broken program. Function Declarations In C, a function must be declared in order for the compiler to know how to call it. A declaration could look like: int a_function(int first, char * second); This means that the function takes two parameters: an integer and a pointer to a character. The function returns a value, an integer. In the general case, this is the only knowledge the compiler has about a function. Hence it must be able to deduce the calling convention from this information. The rest of this document will describe how this is done. Function Parameters When deciding how to pass parameters to a function each parameter is considered in turn. The method selected is primarily based on the type of the 1
parameter. It is also based on the availability of parameter registers, which is the fastest method of passing parameters. The rest of this section will cover how parameters are passed to a function and how the method is selected. Register Parameters vs. Stack Parameters Parameters can be passed to a function using two basic methods: in registers or on the stack. Clearly it is much more efficient to use registers than to take a detour via memory. The calling convention is designed to utilize registers as much as possible. There is only a limited number of registers that can be used for passing parameters, when no more registers are available the remaining parameters are passed on the stack. In addition, the parameters are passed on the stack in the following cases: Structures. (Structs, unions, and classes.) Unnamed parameters to variable length functions, i.e. functions declared as foo(param1, ), e.g. printf. Hidden Parameters In addition to the parameters visible in a function declaration and definition, there can also be hidden parameters: If the function returns a structure the memory location to store the struct is passed as an extra parameter. Notice that it is always treated as the first parameter. If the function is a non-static Embedded C++ member function then, the this pointer is passed as the first parameter (but placed after the return structure pointer, if any). The reason for the requirement that the member function must be non-static is that static member methods do not have a this pointer. Register Parameters Simple parameters such as integers (of all sizes) and pointers (commonly known as scalars) require one register. The same is true for floats. On the other hand, doubles require two registers. The assignment of registers to parameters is a straightforward process. The first parameter is assigned to the first register in the table below, the second parameter to the second register etc. Should there be no more available registers, the parameter is passed on the stack. If a double parameter should be passed in registers, it can only be passed using a register pair listed in the Double column in the table below. If, for example, R1 has been assigned to a scalar parameter, the next available register pair is [R6, R7]. The register R5 will be allocated by the next scalar parameter, if any. Note also that the lower part of the double is not always stored in the register with the lowest number, see the table below for details. 2
The following table describes the available registers: Register Double Description (Low, High) R1 R5 R1, R5 Could be used for return value. R6 R7 R6, R7 R8 R9 R8, R9 Not available for v0, and for v1 when large code model is used. R10 R11 R11, R10 R12 R13 R13, R12 R14 R15 R15,R14 R16 R17 R18 R19 R17,R16 R19,R18 Possibly not available due to register locking. Stack Parameters Stack parameters are stored in the main memory at the location pointed to by the stack pointer. Below the stack pointer (towards low memory) is free space that the called function can use. The first (stack) parameter is stored at the location pointed to by the stack pointer. The next is stored on the next location on the stack that is dividable by four, etc. It is the responsibility of the calling function to clean the stack after the called function has returned. Low memory? <Free stack memory> SP? Param 1 Param 2 Param n <The callers stack frame> High memory? Returning a value from a function The return value of a function, if any, can be scalar (e.g. integers and pointers), floating point, or a structure. 3
Scalar and floating point Scalar and float values are returned using register R1. Double values use the register pair R1, R5. Structures If a structure is returned the caller of the function is responsible to allocate memory for the return value. A pointer to the memory is passed as a hidden first parameter that always is allocated to register R1. The called function must return the value of the location in register R1. Permanent vs. Scratch Register A function must restore register R10 through to R30, except the registers that are used as parameter registers. Register R1, R5 to R9, and any other register that is used as a parameter register can be used as scratch registers by the function. Return Location A function written in assembly should, when finished, return to the caller by jumping to the address pointed to by the register LP. Typically, this is done by the following instruction: JMP [LP] If a function should call another function the original value of LP must be stored somewhere. This is normally done on the stack, for example: ADD 4,SP ST.W LP,0[SP] JARL a_function,lp LD.W 0[SP],LP ADD 4,SP <do something> JMP [LP] A Note on Compatibility Note that the number of registers available to register allocation depends on the selected processor, memory model, and the number of registers locked by the user. This means that code written for one combination of the those options should not be used by code compiled with another combination. Fortunately, simple functions that only use R1 and R5 to R8 have the same calling convention regardless of the selected options. Examples The following section shows a series of examples of declarations and the corresponding calling convention. The complexities of the examples increase towards the end. 4
Example 1 Assume that we have the following function declaration: int add1(int); This function takes one parameter in register R1 and the return value is passe back to its caller in register R1. The following assembler routine is compatible with the declaration, it will return a value that is one number higher than the value of its parameter. add1: ADD 1,R1 JMP [LP] Example 2 This example shows how structures are passed on the stack. Assume that we have the following declarations: struct a_struct { int a; }; int a_function(struct a_struct x, int y); The calling function must reserve four bytes on the top of the stack and copy the value of the struct to that location. The integer parameter y is passed in register R1. Example 3 The function below will return a struct. It is the responsibility of the calling function to allocate a memory location for the return value and pass a pointer to it as a hidden first parameter. struct a_struct { int a; }; struct a_struct a_function( int x); The pointer to the location where the return value should be stored is passed in R1. The parameter x is passed in R5. The calling function assumes that R1 is untouched. Assume that if the function instead would have been declared to return a pointer to the structure: struct a_struct * a_function( int x); In this case the return value is a scalar so there is no hidden parameter. The parameter x is passed in R1 and the return value is returned in R1. Example 4 In Embedded C++ it is possible to declare a class. It is similar to a C structure but in addition to data members, it can contain member functions, or methods. A method has a pointer to the object named this that it operates on. 5
class a_class { public: int doit(int x); }; In the example above the this pointer is passed in R1 and the parameter x is passed in R5. Note that it is not possible to implement methods in assembly language at this point. Future Reservations IAR Systems reserves the rights to change the calling convention at any time. At this point it is unlikely that the calling convention of scalar and double parameters would ever change. However, we are currently investigating if it would be feasible to pass and return small structures in registers rather than on the stack. 6