project/captive/doc/CallType.pm

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