Skip to content

Commit 2b31904

Browse files
rjmccallrjmccall
authored
Merge pull request #98 from rjmccall/functions
[Editorial] Restructure the section on functions and calling conventions
2 parents d74f3d0 + e2a97bb commit 2b31904

File tree

1 file changed

+166
-102
lines changed

1 file changed

+166
-102
lines changed

‎abi.html

Lines changed: 166 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -39,10 +39,10 @@ <h2> Contents </h2>
3939
<li> <a href=#guards> 2.8 Initialization Guard Variables </a>
4040
<li> <a href=#rtti> 2.9 Run-Time Type Information (RTTI) </a>
4141
</ul>
42-
<li> <a href=#calls> Chapter 3: Function Calling Conventions and APIs </a>
42+
<li> <a href=#calls> Chapter 3: Code Emission and APIs </a>
4343
<ul>
44-
<li> <a href=#normal-call> 3.1 Non-virtual Function Calling Conventions </a>
45-
<li> <a href=#vcall> 3.2 Virtual Function Calling Conventions </a>
44+
<li> <a href=#functions> 3.1 Functions</a>
45+
<li> <a href=#vcall> 3.2 Virtual Calls</a>
4646
<li> <a href=#obj-ctor> 3.3 Construction and Destruction APIs</a>
4747
<li> <a href=#demangler> 3.4 Demangler API</a>
4848
</ul>
@@ -2850,15 +2850,11 @@ <h4><a href="#exception-matching-algorithm"> 2.9.8 The Exception Handler Matchin
28502850

28512851
<p> <hr> <p>
28522852
<a name="calls">
2853-
<h2><a href="#calls"> Chapter 3: Function Calling Conventions and APIs </a></h2>
2854-
<p> <hr> <p>
2853+
<h2><a href="#calls"> Chapter 3: Code Emission and APIs </a></h2>
2854+
<p> <hr>
28552855

28562856
<p>
2857-
In general, the calling conventions for C++ in this ABI
2858-
follow those specified by the underlying processor-specific ABI for C,
2859-
whenever there is an analogous construct in C.
2860-
This chapter specifies exceptions required by C++-specific semantics,
2861-
or by features without analogues in C.
2857+
This chapter describes how to define and call functions.
28622858
It also specifies the APIs of a variety of runtime utility routines
28632859
required to be part of the support library of an ABI-conforming
28642860
implementation for use by compiled code.
@@ -2867,96 +2863,137 @@ <h2><a href="#calls"> Chapter 3: Function Calling Conventions and APIs </a></h2>
28672863
which defines a large number of runtime utility routine APIs.
28682864

28692865
<p>
2870-
<a name="normal-call">
2871-
<h3><a href="#normal-call"> 3.1 Non-Virtual Function Calling Conventions </a></h3>
2866+
<a name="functions">
2867+
<h3><a href="#functions">3.1 Functions</a></h3>
28722868
</a>
28732869

28742870
<p>
2875-
<a name="value-parameter">
2876-
<h4><a href="#value-parameter"> 3.1.1 Value Parameters </a></h4>
2871+
In general, the calling conventions and rules for defining C++
2872+
functions in this ABI follow those specified for functions of
2873+
the corresponding type in the base C ABI. The corresponding type
2874+
is mostly determined by translating C++ constructs to their
2875+
obvious C analogues. This section specifies the behavior of
2876+
of features without analogues in C, as well as some exceptions
2877+
and extra rules required by C++-specific semantics.
28772878

28782879
<p>
2879-
In general, C++ value parameters are handled just like C parameters.
2880-
This includes class type parameters passed wholly or partially in registers.
2881-
There are, however, some special cases.
2882-
</p>
2883-
<ol type="1">
2884-
<li>
2885-
<p>
2886-
If the parameter type is <a href="#non-trivial">non-trivial for the
2887-
purposes of calls</a>, the caller must allocate space for a temporary
2888-
and pass that temporary by reference. Specifically:
2889-
</p>
2890-
<ul>
2891-
<li>Space is allocated by the caller in the usual manner for a temporary,
2892-
typically on the stack.</li>
2893-
<li>The caller evaluates the argument in the space provided.</li>
2894-
<li>The function is called, passing the address of the temporary as the
2895-
appropriate argument. In the callee, the address passed is used
2896-
as the address of the parameter variable.</li>
2897-
<li>If the type has a non-trivial destructor, the caller calls that
2898-
destructor after control returns to it (including when the caller
2899-
throws an exception), at the end of enclosing full-expression.
2900-
<li>If necessary (e.g. if the temporary was allocated on the heap),
2901-
the caller deallocates space after return and destruction.
2902-
</ul>
2880+
<a name="function-defs">
2881+
<h4><a href="#function-defs">3.1.1 Function Definitions</a></h4>
29032882

2904-
<p>
2905-
A C-style variadic argument of a type that is non-trivial for the
2906-
purposes of calls is passed the same way: the address of the temporary
2907-
is passed using the normal variadic mechanism, and <code>va_arg</code> in
2908-
the callee retrieves the address and treats it as a reference to the
2909-
temporary.
2910-
</li>
2911-
<li>
2912-
<p>
2913-
In the case where the parameter type is class
2914-
<code>std::decimal::decimal32</code>,
2915-
<code>std::decimal::decimal64</code>, or
2916-
<code>std::decimal::decimal128</code> as defined in TR 24733, the
2917-
parameter is passed the same as the corresponding native decimal
2918-
floating-point scalar type.
2919-
</p>
2920-
</li>
2921-
</ol>
2883+
<p>
2884+
For the most part, non-static member functions, including constructors
2885+
and destructors, are defined as if they were ordinary functions except
2886+
for the addition of the implicit parameters to the prototype as
2887+
described in the <a href="#parameters">section on parameters</a>.
2888+
2889+
<p>
2890+
The rules for <a href="#member-function-pointers">member function
2891+
pointers</a> may require aligning the first instruction of ordinary
2892+
non-static member functions (i.e. not constructors or destructors)
2893+
to a higher value than the platform would normally require.
2894+
2895+
<a name="parameters">
2896+
<h4><a href="#parameters">3.1.2 Parameters</a></h4>
2897+
</a>
2898+
2899+
<p>
2900+
<a name="this-parameters">
2901+
<h5><a href="#this-parameters">3.1.2.1 <code>this</code> Parameters</a></h5>
2902+
2903+
<p>
2904+
Non-static member functions, including constructors and destructors,
2905+
take an implicit <code>this</code> parameter of pointer type. It is
2906+
passed as if it were the first parameter in the function prototype,
2907+
except as modified for <a href="#non-trivial-return-values">non-trivial
2908+
return values</a>.
2909+
2910+
<p>
2911+
<a name="vtt-parameters">
2912+
<h5><a href="#vtt-parameters">3.1.2.2 <code>VTT</code> Parameters</a></h5>
29222913

29232914
<p>
2924-
<a name="reference-parameter">
2925-
<h4><a href="#reference-parameter"> 3.1.2 Reference Parameters </a></h4>
2915+
Base-subobject constructors and destructors for classes with virtual
2916+
bases take an implicit <a href="#vtable-ctor"><code>VTT</code></a>
2917+
parameter of pointer type. It is passed as if it were the second
2918+
parameter in the function prototype, immediately following the
2919+
<code>this</code> parameter, except as modified for
2920+
<a href="#non-trivial-return-values">non-trivial return values</a>.
2921+
2922+
<p>
2923+
<a name="non-trivial-parameters">
2924+
<h5><a href="#non-trivial-parameters">3.1.2.3 Non-Trivial Parameters</a></h5>
2925+
2926+
<p>
2927+
If a parameter type is a class type that is
2928+
<a href="#non-trivial">non-trivial for the purposes of calls</a>, the
2929+
caller must allocate space for a temporary and pass that temporary by
2930+
reference. Specifically:
2931+
2932+
<ul>
2933+
<li>Space is allocated by the caller in the usual manner for a temporary,
2934+
typically on the stack.</li>
2935+
<li>The caller evaluates the argument in the space provided.</li>
2936+
<li>The function is called, passing the address of the temporary as the
2937+
appropriate argument. In the callee, the address passed is used
2938+
as the address of the parameter variable.</li>
2939+
<li>If the type has a non-trivial destructor, the caller calls that
2940+
destructor after control returns to it (including when the caller
2941+
throws an exception).
2942+
<li>If necessary (e.g. if the temporary was allocated on the heap),
2943+
the caller deallocates space after return and destruction.
2944+
</ul>
2945+
2946+
<p>
2947+
A C-style variadic argument of a type that is non-trivial for the
2948+
purposes of calls is passed the same way: the address of the temporary
2949+
is passed using the normal variadic mechanism, and <code>va_arg</code> in
2950+
the callee retrieves the address and treats it as a reference to the
2951+
temporary.
2952+
2953+
<a name="special-class-parameters">
2954+
<h5><a href="#special-class-parameters">3.1.2.4 Parameters of Special Class Type</a></h5>
2955+
2956+
<p>
2957+
An argument of class
2958+
<code>std::decimal::decimal32</code>,
2959+
<code>std::decimal::decimal64</code>, or
2960+
<code>std::decimal::decimal128</code> as defined in TR 24733
2961+
is passed the same as the corresponding native decimal
2962+
floating-point scalar type.
2963+
2964+
<p>
2965+
<a name="reference-parameters">
2966+
<h5><a href="#reference-parameters">3.1.2.5 Reference Parameters</a></h5>
29262967

29272968
<p>
29282969
Reference parameters are handled by passing a pointer to the object
29292970
bound to the reference.
29302971

29312972
<p>
2932-
<a name="empty-parameter">
2933-
<h4><a href="#empty-parameter"> 3.1.3 Empty Parameters </a></h4>
2973+
<a name="empty-parameters">
2974+
<h5><a href="#empty-parameters">3.1.2.6 Empty Parameters</a></h5>
29342975

29352976
<p>
2936-
Empty classes will be passed no differently from ordinary classes. If
2937-
passed in registers the NaT bit must not be set on all registers that
2938-
make up the class.
2939-
</p>
2977+
Arguments of empty class types that are not non-trivial for the purposes
2978+
of calls are passed no differently from ordinary classes.
29402979

29412980
<p>
2942-
The contents of the single byte parameter slot are unspecified,
2943-
and the callee may not depend on any particular value.
2944-
On Itanium, the associated NaT bit must not be set
2945-
if the parameter slot is associated with a register.
2946-
2981+
On Itanium, the NaT bit must be set on all registers that are associated
2982+
with the argument.
29472983

29482984
<p>
2949-
<a name="return-value">
2950-
<h4><a href="#return-value"> 3.1.4 Return Values </a></h4>
2985+
<a name="return-values">
2986+
<h4><a href="#return-values">3.1.3 Return Values</a></h4>
29512987

29522988
<p>
2953-
In general, C++ return values are handled just like C return values.
2954-
This includes class type results returned in registers.</p>
2989+
<a name="non-trivial-return-values">
2990+
<h5><a href="#non-trivial-return-values">3.1.3.1 Non-trivial Return Values</a></h5>
29552991

29562992
<p>
2957-
However, if the return type is <a href="#non-trivial">non-trivial for
2958-
the purposes of calls</a>, the caller passes an address as an implicit
2959-
parameter. The callee then constructs the return value into this address.
2993+
If the return type is a class type that is
2994+
<a href="#non-trivial">non-trivial for the purposes of calls</a>,
2995+
the caller passes an address as an implicit parameter.
2996+
The callee then constructs the return value into this address.
29602997
If the return type has a non-trivial destructor, the caller is responsible
29612998
for destroying the temporary when control is returned to it <i>normally</i>.
29622999
If an exception is thrown out of the callee after the return value is
@@ -2965,61 +3002,88 @@ <h4><a href="#return-value"> 3.1.4 Return Values </a></h4>
29653002
return value before propagating the exception to the caller. Thus,
29663003
in general, the caller is responsible for destroying the return value
29673004
after, and only after, the callee returns control to the caller normally.
2968-
</p>
29693005

29703006
<p>
29713007
The address passed need not be of temporary memory; copy elision may
29723008
cause it to point anywhere, including to global or heap-allocated memory.
3009+
29733010
<p>
3011+
C ABIs usually provide treatment for "indirect" return values, e.g. when
3012+
returning a large aggregate that cannot fit in registers. In some cases,
3013+
this treatment may not be suitable for non-trivial C++ return values, such
3014+
as if the convention requires implicit copying or does not permit the
3015+
return value to be constructed at an arbitrary address. If the treatment
3016+
exists and is suitable, it is used for non-trivial return values.
3017+
Otherwise, the pointer is passed as if it were the first parameter in
3018+
the function prototype, preceding all other parameters, including the
3019+
<code>this</code> and <code>VTT</code> parameters.
29743020

29753021
<p>
2976-
If the C ABI uses a special rule for "indirect" return values, e.g. when
2977-
the return type is too large to fit in registers, that rule is used to
2978-
pass the pointer. Otherwise the pointer is passed as the first parameter,
2979-
preceding all other parameters (including the <code>this</code> and
2980-
<code>VTT</code> parameters).
2981-
</p>
3022+
<a name="special-class-return-values">
3023+
<h5><a href="#special-class-return-values">3.1.3.2 Return Values of Special Class Type</a></h5>
29823024

29833025
<p>
2984-
Reference return values are returned as if pointers to the object bound
2985-
to the reference.
2986-
</p>
3026+
A return value of class
3027+
<code>std::decimal::decimal32</code>,
3028+
<code>std::decimal::decimal64</code>, or
3029+
<code>std::decimal::decimal128</code> as defined in TR 24733 is
3030+
returned the same as the corresponding native decimal floating-point
3031+
scalar type.
29873032

29883033
<p>
2989-
Another exception is that a return value type of class
2990-
<code>std::decimal::decimal32</code>,
2991-
<code>std::decimal::decimal64</code>, or
2992-
<code>std::decimal::decimal128</code> as defined in TR 24733 is
2993-
returned the same as the corresponding native decimal floating-point
2994-
scalar type.
2995-
</p>
3034+
<a name="reference-return-values">
3035+
<h5><a href="#reference-return-values">3.1.3.3 Reference Return Values</a></h5>
3036+
3037+
<p>
3038+
A return value of reference type is returned as a pointer to the object
3039+
bound to the reference.
3040+
3041+
<p>
3042+
<a name="empty-return-values">
3043+
<h5><a href="#emptty-return-values">3.1.3.4 Empty Return Values</a></h5>
29963044

29973045
<p>
2998-
A result of an empty class type will be returned as though it were
2999-
a struct containing a single char,
3000-
i.e. <code>struct S { char c; };</code>.
3001-
The actual content of the return register is unspecified.
3002-
On Itanium, the associated NaT bit must not be set.
3046+
A return value of an empty class type that is not non-trivial for
3047+
the purposes of calls will be returned as though it were the
3048+
following C type:
3049+
3050+
<pre>struct { char c; };</pre>
30033051

3052+
<p>
3053+
On Itanium, the NaT bit must not be set for any register associated with
3054+
this return value.
30043055

30053056
<p>
30063057
<a name="return-value-ctor">
3007-
<h4><a href="#return-value-ctor"> 3.1.5 Constructor Return Values </a></h4>
3058+
<h5><a href="#return-value-ctor">3.1.3.5 Constructor Return Values</a></h5>
30083059

30093060
<p>
30103061
Constructors return <code>void</code> results.
30113062

3063+
<p>
3064+
Some platforms are known to modify this rule to specify that constructors
3065+
return a pointer to <code>this</code>. This may permit more efficient
3066+
code generation in the caller.
30123067

30133068
<p>
30143069
<a name="return-value-dtor">
3015-
<h4><a href="#return-value-dtor"> 3.1.5 Destructor Return Values </a></h4>
3070+
<h5><a href="#return-value-dtor">3.1.3.6 Destructor Return Values</a></h5>
30163071

30173072
<p>
30183073
Destructors return <code>void</code> results.
30193074

3075+
<p>
3076+
Some platforms are known to modify this rule to specify that destructors
3077+
return a pointer to <code>this</code>. This may permit more efficient
3078+
code generation in the caller. This modified rule does not apply to
3079+
deleting destructors. It also does not apply when making a virtual call
3080+
to a complete-object destructor, so that
3081+
<a href="#vtable-components"><code>this</code>-adjustment thunks</a>
3082+
do not need to adjust the return value after the call.
3083+
30203084
<p>
30213085
<a name="vcall">
3022-
<h3><a href="#vcall"> 3.2 Virtual Function Calling Conventions </a></h3>
3086+
<h3><a href="#vcall">3.2 Virtual Calls</a></h3>
30233087
</a>
30243088

30253089
<p>
@@ -3075,7 +3139,7 @@ <h4><a href="#vcall-general"> 3.2.1 General </a></h4>
30753139

30763140
<p>
30773141
<a name="vcall.vtable">
3078-
<h4><a href="#vcall.vtable"> 3.2.2 Virtual Table Components </a>x</h4>
3142+
<h4><a href="#vcall.vtable"> 3.2.2 Virtual Table Components </a></h4>
30793143

30803144
<p>
30813145
For each virtual function declared in a class C,

0 commit comments

Comments
 (0)