project/captive/doc/CallType.html.pl

   1 #! /usr/bin/perl
   2 #
   3 # $Id$
   4 # Captive project doc Calling Types page Perl template.
   5 # Copyright (C) 2003 Jan Kratochvil <project-www.jankratochvil.net@jankratochvil.net>
   6 #
   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
  10 #
  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.
  15 #
  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
  19
  20
  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; };
  24 our $CVS_ID=q$Id$;
  25 use strict;
  26 use warnings;
  27
  28 BEGIN{ open F,"Makefile"; our $top_dir=pop @{[split /\s/,(grep /^top_srcdir/,<F>)[0]]}; eval "use lib '$top_dir'"; close F; }
  29 use My::Web;
  30 require CGI;
  31 BEGIN { Wuse 'project::captive::doc::Macros'; }
  32
  33
  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',
  39                 );
  40
  41
  42 print <<"HERE";
  43
  44
  45 <a name="calltype"><h1>API Function Calling Conventions</h1></a>
  46
  47         <p>Standard UNIX code compiled by GCC (GNU C&nbsp;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>
  51
  52         <p>W32 uses three different calling conventions in its ABI. They are all
  53         described in the
  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
  57         crashes.</p>
  58
  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>
  67
  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
  76         checked.</p>
  77
  78         <a name="calltype_cdecl"><h2>W32 Calling Convention &quot;cdecl&quot;</h2></a>
  79
  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>
  85
  86                 @{[ doc_img 'fig/calltype_cdecl',
  87                                 'W32 Calling Convention <span class="constant">cdecl</span> Scheme' ]}
  88
  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>
  95                 </table>
  96
  97         <a name="calltype_stdcall"><h2>W32 Calling Convention &quot;stdcall&quot;</h2></a>
  98
  99                 @{[ doc_img 'fig/calltype_stdcall',
 100                                 'W32 Calling Convention <span class="constant">stdcall</span> Scheme' ]}
 101
 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 &ndash; use @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl' ]}
 108                 instead.</p>
 109
 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>
 116                 </table>
 117
 118         <a name="calltype_fastcall"><h2>W32 Calling Convention &quot;fastcall&quot;</h2></a>
 119
 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 &ndash; use @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl' ]}
 129                 instead.</p>
 130
 131                 <p>GCC (GNU C&nbsp;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&nbsp;source level in the
 142                 @{[ a_href '#functype','relaying code' ]} generated by
 143                 <span class="fname">captivesym</span> relay generator.</p>
 144
 145                 @{[ doc_img 'fig/calltype_fastcall',
 146                                 'W32 Calling Convention <span class="constant">fastcall</span> Scheme' ]}
 147
 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 &ge;3.4 attribute      </td><td><span class="command">__attribute__((__fastcall__))</span></td></tr>
 154                         <tr><td>GCC &lt;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>
 157                 </table>
 158
 159
 160 HERE
 161
 162
 163 project::captive::doc::Macros->footer();