ePenguin
/
ePenguin-Software-Framework
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
stable
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '921394911f'
${ noResults }
ePenguin-Software-Framework/toolchains/avr/share/doc/gccint/Varargs.html

271 lines
15 KiB
HTML
Raw Normal View History Unescape Escape

the monkey dances and laughs and sings and dances
4 years ago
<html lang="en">
<head>
<title>Varargs - GNU Compiler Collection (GCC) Internals</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="GNU Compiler Collection (GCC) Internals">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Target-Macros.html#Target-Macros" title="Target Macros">
<link rel="prev" href="Stack-and-Calling.html#Stack-and-Calling" title="Stack and Calling">
<link rel="next" href="Trampolines.html#Trampolines" title="Trampolines">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1988-2015 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Funding Free Software'', the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below). A copy of the license is included in the section entitled
``GNU Free Documentation License''.
(a) The FSF's Front-Cover Text is:
A GNU Manual
(b) The FSF's Back-Cover Text is:
You have freedom to copy and modify this GNU Manual, like GNU
software. Copies published by the Free Software Foundation raise
funds for GNU development.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Varargs"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Trampolines.html#Trampolines">Trampolines</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Stack-and-Calling.html#Stack-and-Calling">Stack and Calling</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Target-Macros.html#Target-Macros">Target Macros</a>
<hr>
</div>
<h3 class="section">17.10 Implementing the Varargs Macros</h3>
<p><a name="index-varargs-implementation-4327"></a>
GCC comes with an implementation of <code>&lt;varargs.h&gt;</code> and
<code>&lt;stdarg.h&gt;</code> that work without change on machines that pass arguments
on the stack. Other machines require their own implementations of
varargs, and the two machine independent header files must have
conditionals to include it.
<p>ISO <code>&lt;stdarg.h&gt;</code> differs from traditional <code>&lt;varargs.h&gt;</code> mainly in
the calling convention for <code>va_start</code>. The traditional
implementation takes just one argument, which is the variable in which
to store the argument pointer. The ISO implementation of
<code>va_start</code> takes an additional second argument. The user is
supposed to write the last named argument of the function here.
<p>However, <code>va_start</code> should not use this argument. The way to find
the end of the named arguments is with the built-in functions described
below.
<div class="defun">
&mdash; Macro: <b>__builtin_saveregs</b> ()<var><a name="index-g_t_005f_005fbuiltin_005fsaveregs-4328"></a></var><br>
<blockquote><p>Use this built-in function to save the argument registers in memory so
that the varargs mechanism can access them. Both ISO and traditional
versions of <code>va_start</code> must use <code>__builtin_saveregs</code>, unless
you use <code>TARGET_SETUP_INCOMING_VARARGS</code> (see below) instead.
<p>On some machines, <code>__builtin_saveregs</code> is open-coded under the
control of the target hook <code>TARGET_EXPAND_BUILTIN_SAVEREGS</code>. On
other machines, it calls a routine written in assembler language,
found in <samp><span class="file">libgcc2.c</span></samp>.
<p>Code generated for the call to <code>__builtin_saveregs</code> appears at the
beginning of the function, as opposed to where the call to
<code>__builtin_saveregs</code> is written, regardless of what the code is.
This is because the registers must be saved before the function starts
to use them for its own purposes.
<!-- i rewrote the first sentence above to fix an overfull hbox. -mew -->
<!-- 10feb93 -->
</p></blockquote></div>
<div class="defun">
&mdash; Macro: <b>__builtin_next_arg</b> (<var>lastarg</var>)<var><a name="index-g_t_005f_005fbuiltin_005fnext_005farg-4329"></a></var><br>
<blockquote><p>This builtin returns the address of the first anonymous stack
argument, as type <code>void *</code>. If <code>ARGS_GROW_DOWNWARD</code>, it
returns the address of the location above the first anonymous stack
argument. Use it in <code>va_start</code> to initialize the pointer for
fetching arguments from the stack. Also use it in <code>va_start</code> to
verify that the second parameter <var>lastarg</var> is the last named argument
of the current function.
</p></blockquote></div>
<div class="defun">
&mdash; Macro: <b>__builtin_classify_type</b> (<var>object</var>)<var><a name="index-g_t_005f_005fbuiltin_005fclassify_005ftype-4330"></a></var><br>
<blockquote><p>Since each machine has its own conventions for which data types are
passed in which kind of register, your implementation of <code>va_arg</code>
has to embody these conventions. The easiest way to categorize the
specified data type is to use <code>__builtin_classify_type</code> together
with <code>sizeof</code> and <code>__alignof__</code>.
<p><code>__builtin_classify_type</code> ignores the value of <var>object</var>,
considering only its data type. It returns an integer describing what
kind of type that is&mdash;integer, floating, pointer, structure, and so on.
<p>The file <samp><span class="file">typeclass.h</span></samp> defines an enumeration that you can use to
interpret the values of <code>__builtin_classify_type</code>.
</p></blockquote></div>
<p>These machine description macros help implement varargs:
<div class="defun">
&mdash; Target Hook: rtx <b>TARGET_EXPAND_BUILTIN_SAVEREGS</b> (<var>void</var>)<var><a name="index-TARGET_005fEXPAND_005fBUILTIN_005fSAVEREGS-4331"></a></var><br>
<blockquote><p>If defined, this hook produces the machine-specific code for a call to
<code>__builtin_saveregs</code>. This code will be moved to the very
beginning of the function, before any parameter access are made. The
return value of this function should be an RTX that contains the value
to use as the return of <code>__builtin_saveregs</code>.
</p></blockquote></div>
<div class="defun">
&mdash; Target Hook: void <b>TARGET_SETUP_INCOMING_VARARGS</b> (<var>cumulative_args_t args_so_far, machine_mode mode, tree type, int *pretend_args_size, int second_time</var>)<var><a name="index-TARGET_005fSETUP_005fINCOMING_005fVARARGS-4332"></a></var><br>
<blockquote><p>This target hook offers an alternative to using
<code>__builtin_saveregs</code> and defining the hook
<code>TARGET_EXPAND_BUILTIN_SAVEREGS</code>. Use it to store the anonymous
register arguments into the stack so that all the arguments appear to
have been passed consecutively on the stack. Once this is done, you can
use the standard implementation of varargs that works for machines that
pass all their arguments on the stack.
<p>The argument <var>args_so_far</var> points to the <code>CUMULATIVE_ARGS</code> data
structure, containing the values that are obtained after processing the
named arguments. The arguments <var>mode</var> and <var>type</var> describe the
last named argument&mdash;its machine mode and its data type as a tree node.
<p>The target hook should do two things: first, push onto the stack all the
argument registers <em>not</em> used for the named arguments, and second,
store the size of the data thus pushed into the <code>int</code>-valued
variable pointed to by <var>pretend_args_size</var>. The value that you
store here will serve as additional offset for setting up the stack
frame.
<p>Because you must generate code to push the anonymous arguments at
compile time without knowing their data types,
<code>TARGET_SETUP_INCOMING_VARARGS</code> is only useful on machines that
have just a single category of argument register and use it uniformly
for all data types.
<p>If the argument <var>second_time</var> is nonzero, it means that the
arguments of the function are being analyzed for the second time. This
happens for an inline function, which is not actually compiled until the
end of the source file. The hook <code>TARGET_SETUP_INCOMING_VARARGS</code> should
not generate any instructions in this case.
</p></blockquote></div>
<div class="defun">
&mdash; Target Hook: bool <b>TARGET_STRICT_ARGUMENT_NAMING</b> (<var>cumulative_args_t ca</var>)<var><a name="index-TARGET_005fSTRICT_005fARGUMENT_005fNAMING-4333"></a></var><br>
<blockquote><p>Define this hook to return <code>true</code> if the location where a function
argument is passed depends on whether or not it is a named argument.
<p>This hook controls how the <var>named</var> argument to <code>TARGET_FUNCTION_ARG</code>
is set for varargs and stdarg functions. If this hook returns
<code>true</code>, the <var>named</var> argument is always true for named
arguments, and false for unnamed arguments. If it returns <code>false</code>,
but <code>TARGET_PRETEND_OUTGOING_VARARGS_NAMED</code> returns <code>true</code>,
then all arguments are treated as named. Otherwise, all named arguments
except the last are treated as named.
<p>You need not define this hook if it always returns <code>false</code>.
</p></blockquote></div>
<div class="defun">
&mdash; Target Hook: void <b>TARGET_CALL_ARGS</b> (<var>rtx, tree</var>)<var><a name="index-TARGET_005fCALL_005fARGS-4334"></a></var><br>
<blockquote><p>While generating RTL for a function call, this target hook is invoked once
for each argument passed to the function, either a register returned by
<code>TARGET_FUNCTION_ARG</code> or a memory location. It is called just
before the point where argument registers are stored. The type of the
function to be called is also passed as the second argument; it is
<code>NULL_TREE</code> for libcalls. The <code>TARGET_END_CALL_ARGS</code> hook is
invoked just after the code to copy the return reg has been emitted.
This functionality can be used to perform special setup of call argument
registers if a target needs it.
For functions without arguments, the hook is called once with <code>pc_rtx</code>
passed instead of an argument register.
Most ports do not need to implement anything for this hook.
</p></blockquote></div>
<div class="defun">
&mdash; Target Hook: void <b>TARGET_END_CALL_ARGS</b> (<var>void</var>)<var><a name="index-TARGET_005fEND_005fCALL_005fARGS-4335"></a></var><br>
<blockquote><p>This target hook is invoked while generating RTL for a function call,
just after the point where the return reg is copied into a pseudo. It
signals that all the call argument and return registers for the just
emitted call are now no longer in use.
Most ports do not need to implement anything for this hook.
</p></blockquote></div>
<div class="defun">
&mdash; Target Hook: bool <b>TARGET_PRETEND_OUTGOING_VARARGS_NAMED</b> (<var>cumulative_args_t ca</var>)<var><a name="index-TARGET_005fPRETEND_005fOUTGOING_005fVARARGS_005fNAMED-4336"></a></var><br>
<blockquote><p>If you need to conditionally change ABIs so that one works with
<code>TARGET_SETUP_INCOMING_VARARGS</code>, but the other works like neither
<code>TARGET_SETUP_INCOMING_VARARGS</code> nor <code>TARGET_STRICT_ARGUMENT_NAMING</code> was
defined, then define this hook to return <code>true</code> if
<code>TARGET_SETUP_INCOMING_VARARGS</code> is used, <code>false</code> otherwise.
Otherwise, you should not define this hook.
</p></blockquote></div>
<div class="defun">
&mdash; Target Hook: rtx <b>TARGET_LOAD_BOUNDS_FOR_ARG</b> (<var>rtx slot, rtx arg, rtx slot_no</var>)<var><a name="index-TARGET_005fLOAD_005fBOUNDS_005fFOR_005fARG-4337"></a></var><br>
<blockquote><p>This hook is used by expand pass to emit insn to load bounds of
<var>arg</var> passed in <var>slot</var>. Expand pass uses this hook in case
bounds of <var>arg</var> are not passed in register. If <var>slot</var> is a
memory, then bounds are loaded as for regular pointer loaded from
memory. If <var>slot</var> is not a memory then <var>slot_no</var> is an integer
constant holding number of the target dependent special slot which
should be used to obtain bounds. Hook returns RTX holding loaded bounds.
</p></blockquote></div>
<div class="defun">
&mdash; Target Hook: void <b>TARGET_STORE_BOUNDS_FOR_ARG</b> (<var>rtx arg, rtx slot, rtx bounds, rtx slot_no</var>)<var><a name="index-TARGET_005fSTORE_005fBOUNDS_005fFOR_005fARG-4338"></a></var><br>
<blockquote><p>This hook is used by expand pass to emit insns to store <var>bounds</var> of
<var>arg</var> passed in <var>slot</var>. Expand pass uses this hook in case
<var>bounds</var> of <var>arg</var> are not passed in register. If <var>slot</var> is a
memory, then <var>bounds</var> are stored as for regular pointer stored in
memory. If <var>slot</var> is not a memory then <var>slot_no</var> is an integer
constant holding number of the target dependent special slot which
should be used to store <var>bounds</var>.
</p></blockquote></div>
<div class="defun">
&mdash; Target Hook: rtx <b>TARGET_LOAD_RETURNED_BOUNDS</b> (<var>rtx slot</var>)<var><a name="index-TARGET_005fLOAD_005fRETURNED_005fBOUNDS-4339"></a></var><br>
<blockquote><p>This hook is used by expand pass to emit insn to load bounds
returned by function call in <var>slot</var>. Hook returns RTX holding
loaded bounds.
</p></blockquote></div>
<div class="defun">
&mdash; Target Hook: void <b>TARGET_STORE_RETURNED_BOUNDS</b> (<var>rtx slot, rtx bounds</var>)<var><a name="index-TARGET_005fSTORE_005fRETURNED_005fBOUNDS-4340"></a></var><br>
<blockquote><p>This hook is used by expand pass to emit insn to store <var>bounds</var>
returned by function call into <var>slot</var>.
</p></blockquote></div>
<div class="defun">
&mdash; Target Hook: rtx <b>TARGET_CHKP_FUNCTION_VALUE_BOUNDS</b> (<var>const_tree ret_type, const_tree fn_decl_or_type, bool outgoing</var>)<var><a name="index-TARGET_005fCHKP_005fFUNCTION_005fVALUE_005fBOUNDS-4341"></a></var><br>
<blockquote><p>Define this to return an RTX representing the place where a function
returns bounds for returned pointers. Arguments meaning is similar to
<code>TARGET_FUNCTION_VALUE</code>.
</p></blockquote></div>
<div class="defun">
&mdash; Target Hook: void <b>TARGET_SETUP_INCOMING_VARARG_BOUNDS</b> (<var>cumulative_args_t args_so_far, enum machine_mode mode, tree type, int *pretend_args_size, int second_time</var>)<var><a name="index-TARGET_005fSETUP_005fINCOMING_005fVARARG_005fBOUNDS-4342"></a></var><br>
<blockquote><p>Use it to store bounds for anonymous register arguments stored
into the stack. Arguments meaning is similar to
<code>TARGET_SETUP_INCOMING_VARARGS</code>.
</p></blockquote></div>
</body></html>