21.8.6 Passing Arguments in Registers

This section describes the macros which let you control how various types of arguments are passed in registers or how they are arranged in the stack.

FUNCTION_ARG (cum, mode, type, named)

A C expression that controls whether a function argument is passed in a register, and which register.

The arguments are cum, which summarizes all the previous arguments; mode, the machine mode of the argument; type, the data type of the argument as a tree node or 0 if that is not known (which happens for C support library functions); and named, which is 1 for an ordinary argument and 0 for nameless arguments that correspond to `...' in the called function's prototype. type can be an incomplete type if a syntax error has previously occurred.

The value of the expression is usually either a reg RTX for the hard register in which to pass the argument, or zero to pass the argument on the stack.

For machines like the Vax and 68000, where normally all arguments are pushed, zero suffices as a definition.

The value of the expression can also be a parallel RTX. This is used when an argument is passed in multiple locations. The mode of the of the parallel should be the mode of the entire argument. The parallel holds any number of expr_list pairs; each one describes where part of the argument is passed. In each expr_list the first operand must be a reg RTX for the hard register in which to pass this part of the argument, and the mode of the register RTX indicates how large this part of the argument is. The second operand of the expr_list is a const_int which gives the offset in bytes into the entire argument of where this part starts. As a special exception the first expr_list in the parallel RTX may have a first operand of zero. This indicates that the entire argument is also stored on the stack.

The usual way to make the ISO library `stdarg.h' work on a machine where some arguments are usually passed in registers, is to cause nameless arguments to be passed on the stack instead. This is done by making FUNCTION_ARG return 0 whenever named is 0.

You may use the macro MUST_PASS_IN_STACK (mode, type) in the definition of this macro to determine if this argument is of a type that must be passed in the stack. If REG_PARM_STACK_SPACE is not defined and FUNCTION_ARG returns non-zero for such an argument, the compiler will abort. If REG_PARM_STACK_SPACE is defined, the argument will be computed in the stack and then loaded into a register.

MUST_PASS_IN_STACK (mode, type)

Define as a C expression that evaluates to nonzero if we do not know how to pass TYPE solely in registers. The file `expr.h' defines a definition that is usually appropriate, refer to `expr.h' for additional documentation.

FUNCTION_INCOMING_ARG (cum, mode, type, named)

Define this macro if the target machine has "register windows", so that the register in which a function sees an arguments is not necessarily the same as the one in which the caller passed the argument.

For such machines, FUNCTION_ARG computes the register in which the caller passes the value, and FUNCTION_INCOMING_ARG should be defined in a similar fashion to tell the function being called where the arguments will arrive.

If FUNCTION_INCOMING_ARG is not defined, FUNCTION_ARG serves both purposes.

FUNCTION_ARG_PARTIAL_NREGS (cum, mode, type, named)

A C expression for the number of words, at the beginning of an argument, that must be put in registers. The value must be zero for arguments that are passed entirely in registers or that are entirely pushed on the stack.

On some machines, certain arguments must be passed partially in registers and partially in memory. On these machines, typically the first n words of arguments are passed in registers, and the rest on the stack. If a multi-word argument (a double or a structure) crosses that boundary, its first few words must be passed in registers and the rest must be pushed. This macro tells the compiler when this occurs, and how many of the words should go in registers.

FUNCTION_ARG for these arguments should return the first register to be used by the caller for this argument; likewise FUNCTION_INCOMING_ARG, for the called function.

FUNCTION_ARG_PASS_BY_REFERENCE (cum, mode, type, named)

A C expression that indicates when an argument must be passed by reference. If nonzero for an argument, a copy of that argument is made in memory and a pointer to the argument is passed instead of the argument itself. The pointer is passed in whatever way is appropriate for passing a pointer to that type.

On machines where REG_PARM_STACK_SPACE is not defined, a suitable definition of this macro might be

#define FUNCTION_ARG_PASS_BY_REFERENCE\ (CUM, MODE, TYPE, NAMED) \ MUST_PASS_IN_STACK (MODE, TYPE)

FUNCTION_ARG_CALLEE_COPIES (cum, mode, type, named)

If defined, a C expression that indicates when it is the called function's responsibility to make a copy of arguments passed by invisible reference. Normally, the caller makes a copy and passes the address of the copy to the routine being called. When FUNCTION_ARG_CALLEE_COPIES is defined and is nonzero, the caller does not make a copy. Instead, it passes a pointer to the "live" value. The called function must not modify this value. If it can be determined that the value won't be modified, it need not make a copy; otherwise a copy must be made.

CUMULATIVE_ARGS

A C type for declaring a variable that is used as the first argument of FUNCTION_ARG and other related values. For some target machines, the type int suffices and can hold the number of bytes of argument so far.

There is no need to record in CUMULATIVE_ARGS anything about the arguments that have been passed on the stack. The compiler has other variables to keep track of that. For target machines on which all arguments are passed on the stack, there is no need to store anything in CUMULATIVE_ARGS; however, the data structure must exist and should not be empty, so use int.

INIT_CUMULATIVE_ARGS (cum, fntype, libname, indirect)

A C statement (sans semicolon) for initializing the variable cum for the state at the beginning of the argument list. The variable has type CUMULATIVE_ARGS. The value of fntype is the tree node for the data type of the function which will receive the args, or 0 if the args are to a compiler support library function. The value of indirect is nonzero when processing an indirect call, for example a call through a function pointer. The value of indirect is zero for a call to an explicitly named function, a library function call, or when INIT_CUMULATIVE_ARGS is used to find arguments for the function being compiled.

When processing a call to a compiler support library function, libname identifies which one. It is a symbol_ref rtx which contains the name of the function, as a string. libname is 0 when an ordinary C function call is being processed. Thus, each time this macro is called, either libname or fntype is nonzero, but never both of them at once.

INIT_CUMULATIVE_LIBCALL_ARGS (cum, mode, libname)

Like INIT_CUMULATIVE_ARGS but only used for outgoing libcalls, it gets a MODE argument instead of fntype, that would be NULL. indirect would always be zero, too. If this macro is not defined, INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname, 0) is used instead.

INIT_CUMULATIVE_INCOMING_ARGS (cum, fntype, libname)

Like INIT_CUMULATIVE_ARGS but overrides it for the purposes of finding the arguments for the function being compiled. If this macro is undefined, INIT_CUMULATIVE_ARGS is used instead.

The value passed for libname is always 0, since library routines with special calling conventions are never compiled with GCC. The argument libname exists for symmetry with INIT_CUMULATIVE_ARGS.

FUNCTION_ARG_ADVANCE (cum, mode, type, named)

A C statement (sans semicolon) to update the summarizer variable cum to advance past an argument in the argument list. The values mode, type and named describe that argument. Once this is done, the variable cum is suitable for analyzing the following argument with FUNCTION_ARG, etc.

This macro need not do anything if the argument in question was passed on the stack. The compiler knows how to track the amount of stack space used for arguments without any special help.

FUNCTION_ARG_PADDING (mode, type)

If defined, a C expression which determines whether, and in which direction, to pad out an argument with extra space. The value should be of type enum direction: either upward to pad above the argument, downward to pad below, or none to inhibit padding.

The amount of padding is always just enough to reach the next multiple of FUNCTION_ARG_BOUNDARY; this macro does not control it.

This macro has a default definition which is right for most systems. For little-endian machines, the default is to pad upward. For big-endian machines, the default is to pad downward for an argument of constant size shorter than an int, and upward otherwise.

PAD_VARARGS_DOWN

If defined, a C expression which determines whether the default implementation of va_arg will attempt to pad down before reading the next argument, if that argument is smaller than its aligned space as controlled by PARM_BOUNDARY. If this macro is not defined, all such arguments are padded down if BYTES_BIG_ENDIAN is true.

FUNCTION_ARG_BOUNDARY (mode, type)

If defined, a C expression that gives the alignment boundary, in bits, of an argument with the specified mode and type. If it is not defined, PARM_BOUNDARY is used for all arguments.

FUNCTION_ARG_REGNO_P (regno)

A C expression that is nonzero if regno is the number of a hard register in which function arguments are sometimes passed. This does not include implicit arguments such as the static chain and the structure-value address. On many machines, no registers can be used for this purpose since all function arguments are pushed on the stack.

LOAD_ARGS_REVERSED

If defined, the order in which arguments are loaded into their respective argument registers is reversed so that the last argument is loaded first. This macro only affects arguments passed in registers.