4 # Captive project doc Calling Types page Perl template.
5 # Copyright (C) 2003 Jan Kratochvil <project-www.jankratochvil.net@jankratochvil.net>
7 # This program is free software; you can redistribute it and/or modify
8 # it under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; exactly version 2 of June 1991 is required
11 # This program is distributed in the hope that it will be useful,
12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 # GNU General Public License for more details.
16 # You should have received a copy of the GNU General Public License
17 # along with this program; if not, write to the Free Software
18 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21 package project::captive::doc::CallType;
22 require 5.6.0; # at least 'use warnings;' but we need some 5.6.0+ modules anyway
23 our $VERSION=do { my @r=(q$Revision$=~/\d+/g); sprintf "%d.".("%03d"x$#r),@r; };
28 BEGIN{ open F,"Makefile"; our $top_dir=pop @{[split /\s/,(grep /^top_srcdir/,<F>)[0]]}; eval "use lib '$top_dir'"; close F; }
31 BEGIN { Wuse 'project::captive::doc::Macros'; }
34 project::captive::doc::Macros->init(
35 "__PACKAGE__"=>__PACKAGE__,
36 "title"=>'Captive NTFS Developer Documentation: API Calling Conventions',
37 "rel_prev"=>'APITypes.html.pl',
38 "rel_next"=>'TODO.html.pl',
45 <a name="calltype"><h1>API Function Calling Conventions</h1></a>
47 <p>Standard UNIX code compiled by GCC (GNU C Compiler) running on host
48 $gnulinux always uses @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl' ]} ABI (Application
49 Binary Interface) calling convention. This calling convention is also the
50 default declaration type of UNIX functions.</p>
52 <p>W32 uses three different calling conventions in its ABI. They are all
54 <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vclang/html/_core_argument_passing_and_naming_conventions.asp"><span class="productname">Microsoft</span> documentation</a>.
55 There is always necessary to have the proper function declaration
56 (prototype) in the caller scope to prevent all sorts of unexpected
59 <p>Unfortunately some non-matching combinations of calling conventions
60 result in hard to debug bugs: the caller gets back an unexpected stack
61 pointer from the callee and upon return it will restore registers from the
62 wrong stack pointer place. Since the caller will finally reclaim its stack
63 frame from its (uncorrupted) <span class="constant">EBP</span> stack frame
64 pointer the caller will return to the caller of the caller correctly. Just
65 the registers remain corrupted causing crashes of completely unrelated code
66 executed far, far away...</p>
68 <p><span class="constant">EDI</span>, <span class="constant">ESI</span> and
69 <span class="constant">EBX</span> registers are always saved on the stack.
70 They are stored on the stack in this particular order from bottom to top
71 addresses (using the <span class="instruction">push EBX</span>,
72 <span class="instruction">push ESI</span>,
73 <span class="instruction">push EDI</span> sequence). Fortunately $gnulinux
74 GCC has the same register saving behaviour. If some register corruption
75 occurs the calling type presented between the caller and callee should be
78 <a name="calltype_cdecl"><h2>W32 Calling Convention "cdecl"</h2></a>
80 <p>The only calling convention in the UNIX world. The default one for all
81 the compilers. All the arguments are passed on the stack, no arguments
82 are cleaned by the callee. Possible inconsistencies in the number of
83 function arguments with the function prototype used by the caller is
84 harmless. Variable arguments lists can be passed by this convention.</p>
86 @{[ doc_img 'fig/calltype_cdecl',
87 'W32 Calling Convention <span class="constant">cdecl</span> Scheme' ]}
89 <table border="1" align="center">
90 <tr><td>Arguments freed by </td><td>caller</td></tr>
91 <tr><td>Arguments on the stack </td><td>#0 ... #(n-1)</td></tr>
92 <tr><td>Arguments in the registers </td><td>none</td></tr>
93 <tr><td>GCC attribute </td><td><span class="command">__attribute__((__cdecl__))</span> (default)</td></tr>
94 <caption>Calling Convention <span class="constant">cdecl</span> Characteristics</caption>
97 <a name="calltype_stdcall"><h2>W32 Calling Convention "stdcall"</h2></a>
99 @{[ doc_img 'fig/calltype_stdcall',
100 'W32 Calling Convention <span class="constant">stdcall</span> Scheme' ]}
102 <p>Convention never used in the UNIX world. It needs to be specified for
103 W32 compilers. All the arguments are passed on the stack, all the
104 arguments are cleaned by the callee. Possible inconsistencies in the
105 number of function arguments with the function prototype used by the
106 caller will result in fatal crash. Variable arguments lists cannot be
107 passed by this convention – use @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl' ]}
110 <table border="1" align="center">
111 <tr><td>Arguments freed by </td><td>callee</td></tr>
112 <tr><td>Arguments on the stack </td><td>#0 ... #(n-1)</td></tr>
113 <tr><td>Arguments in the registers </td><td>none</td></tr>
114 <tr><td>GCC attribute </td><td><span class="command">__attribute__((__stdcall__))</span></td></tr>
115 <caption>Calling Convention <span class="constant">stdcall</span> Characteristics</caption>
118 <a name="calltype_fastcall"><h2>W32 Calling Convention "fastcall"</h2></a>
120 <p>Convention never used in the UNIX world. It needs to be specified for
121 W32 compilers. Convention used in the W32 world for its low calling
122 overhead. All but the first two arguments are passed on the stack, such
123 arguments are cleaned by the callee. First two arguments are passed in
124 the registers <span class="constant">ECX</span> and
125 <span class="constant">EDX</span> respectively. Possible inconsistencies
126 in the number of function arguments with the function prototype used by
127 the caller will result in fatal crash. Variable arguments lists cannot be
128 passed by this convention – use @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl' ]}
131 <p>GCC (GNU C Compiler) native support for this calling convention
132 is pretty fresh and it is currently present only in the recent CVS
133 versions since 21st December of 2002 which should get released as GCC
134 version 3.4. This project solved the unsupported calling convention by
135 declaration of arguments passed in registers by
136 <span class="command">__attribute__((__regparm__(3)))</span>.
137 W32 passes the arguments in registers in the order
138 <span class="constant">ECX</span>, <span class="constant">EDX</span> but
139 GCC passes them in registers <span class="constant">EAX</span>,
140 <span class="constant">EDX</span>, <span class="constant">ECX</span>.
141 This incompatibility is compensated at C source level in the
142 @{[ a_href '#functype','relaying code' ]} generated by
143 <span class="fname">captivesym</span> relay generator.</p>
145 @{[ doc_img 'fig/calltype_fastcall',
146 'W32 Calling Convention <span class="constant">fastcall</span> Scheme' ]}
148 <table border="1" align="center">
149 <tr><td>Arguments freed by </td><td>callee</td></tr>
150 <tr><td>Arguments on the stack </td><td>#2 ... #(n-1)</td></tr>
151 <tr><td>Arguments in the registers </td><td><span class="constant">ECX</span>=#0,
152 <span class="constant">EDX</span>=#1</td></tr>
153 <tr><td>GCC ≥3.4 attribute </td><td><span class="command">__attribute__((__fastcall__))</span></td></tr>
154 <tr><td>GCC <3.4 attr. emulation</td><td><span class="command">__attribute__((__stdcall__))</span></td></tr>
155 <tr><td> </td><td><span class="command">__attribute__((__regparm__(3) /* EAX,EDX,ECX */))</span></td></tr>
156 <caption>Calling Convention <span class="constant">fastcall</span> Characteristics</caption>
163 project::captive::doc::Macros->footer();