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 require CGI;
  28
  29
  30 sub handler
  31 {
  32         BEGIN { Wuse 'project::captive::doc::Macros'; }
  33 project::captive::doc::Macros->init(
  34                 "title"=>'Captive NTFS Developer Documentation: API Calling Conventions',
  35                 "rel_prev"=>'APITypes.pm',
  36                 "rel_next"=>'TODO.pm',
  37                 );
  38
  39
  40 print <<"HERE";
  41
  42
  43 <h1 id="calltype">API Function Calling Conventions</h1>
  44
  45         <p>Standard UNIX code compiled by GCC (GNU C&nbsp;Compiler) running on host
  46         $gnulinux always uses @{[ a_href 'CallType.pm#calltype_cdecl','cdecl' ]} ABI (Application
  47         Binary Interface) calling convention. This calling convention is also the
  48         default declaration type of UNIX functions.</p>
  49
  50         <p>W32 uses three different calling conventions in its ABI. They are all
  51         described in the
  52         <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>.
  53         There is always necessary to have the proper function declaration
  54         (prototype) in the caller scope to prevent all sorts of unexpected
  55         crashes.</p>
  56
  57         <p>Unfortunately some non-matching combinations of calling conventions
  58         result in hard to debug bugs: the caller gets back an unexpected stack
  59         pointer from the callee and upon return it will restore registers from the
  60         wrong stack pointer place. Since the caller will finally reclaim its stack
  61         frame from its (uncorrupted) <span class="constant">EBP</span> stack frame
  62         pointer the caller will return to the caller of the caller correctly. Just
  63         the registers remain corrupted causing crashes of completely unrelated code
  64         executed far, far away...</p>
  65
  66         <p><span class="constant">EDI</span>, <span class="constant">ESI</span> and
  67         <span class="constant">EBX</span> registers are always saved on the stack.
  68         They are stored on the stack in this particular order from bottom to top
  69         addresses (using the <span class="instruction">push EBX</span>,
  70         <span class="instruction">push ESI</span>,
  71         <span class="instruction">push EDI</span> sequence). Fortunately $gnulinux
  72         GCC has the same register saving behaviour. If some register corruption
  73         occurs the calling type presented between the caller and callee should be
  74         checked.</p>
  75
  76         <h2 id="calltype_cdecl">W32 Calling Convention &quot;cdecl&quot;</h2>
  77
  78                 <p>The only calling convention in the UNIX world. The default one for all
  79                 the compilers. All the arguments are passed on the stack, no arguments
  80                 are cleaned by the callee. Possible inconsistencies in the number of
  81                 function arguments with the function prototype used by the caller is
  82                 harmless. Variable arguments lists can be passed by this convention.</p>
  83
  84                 @{[ doc_img 'fig/calltype_cdecl',
  85                                 'W32 Calling Convention <span class="constant">cdecl</span> Scheme' ]}
  86
  87                 <table border="0" width="100%"><tr><td align="center"><table border="1">
  88                         <caption>Calling Convention <span class="constant">cdecl</span> Characteristics</caption>
  89                         <tr><td>Arguments freed by         </td><td>caller</td></tr>
  90                         <tr><td>Arguments on the stack     </td><td>#0 ... #(n-1)</td></tr>
  91                         <tr><td>Arguments in the registers </td><td>none</td></tr>
  92                         <tr><td>GCC attribute              </td><td><span class="command">__attribute__((__cdecl__))</span> (default)</td></tr>
  93                 </table></td></tr></table>
  94
  95         <h2 id="calltype_stdcall">W32 Calling Convention &quot;stdcall&quot;</h2>
  96
  97                 @{[ doc_img 'fig/calltype_stdcall',
  98                                 'W32 Calling Convention <span class="constant">stdcall</span> Scheme' ]}
  99
 100                 <p>Convention never used in the UNIX world. It needs to be specified for
 101                 W32 compilers. All the arguments are passed on the stack, all the
 102                 arguments are cleaned by the callee. Possible inconsistencies in the
 103                 number of function arguments with the function prototype used by the
 104                 caller will result in fatal crash. Variable arguments lists cannot be
 105                 passed by this convention &ndash; use @{[ a_href 'CallType.pm#calltype_cdecl','cdecl' ]}
 106                 instead.</p>
 107
 108                 <table border="0" width="100%"><tr><td align="center"><table border="1">
 109                         <caption>Calling Convention <span class="constant">stdcall</span> Characteristics</caption>
 110                         <tr><td>Arguments freed by         </td><td>callee</td></tr>
 111                         <tr><td>Arguments on the stack     </td><td>#0 ... #(n-1)</td></tr>
 112                         <tr><td>Arguments in the registers </td><td>none</td></tr>
 113                         <tr><td>GCC attribute              </td><td><span class="command">__attribute__((__stdcall__))</span></td></tr>
 114                 </table></td></tr></table>
 115
 116         <h2 id="calltype_fastcall">W32 Calling Convention &quot;fastcall&quot;</h2>
 117
 118                 <p>Convention never used in the UNIX world. It needs to be specified for
 119                 W32 compilers. Convention used in the W32 world for its low calling
 120                 overhead. All but the first two arguments are passed on the stack, such
 121                 arguments are cleaned by the callee. First two arguments are passed in
 122                 the registers <span class="constant">ECX</span> and
 123                 <span class="constant">EDX</span> respectively. Possible inconsistencies
 124                 in the number of function arguments with the function prototype used by
 125                 the caller will result in fatal crash. Variable arguments lists cannot be
 126                 passed by this convention &ndash; use @{[ a_href 'CallType.pm#calltype_cdecl','cdecl' ]}
 127                 instead.</p>
 128
 129                 <p>GCC (GNU C&nbsp;Compiler) native support for this calling convention
 130                 is pretty fresh and it is currently present only in the recent CVS
 131                 versions since 21st December of 2002 which should get released as GCC
 132                 version 3.4. This project solved the unsupported calling convention by
 133                 declaration of arguments passed in registers by
 134                 <span class="command">__attribute__((__regparm__(3)))</span>.
 135                 W32 passes the arguments in registers in the order
 136                 <span class="constant">ECX</span>, <span class="constant">EDX</span> but
 137                 GCC passes them in registers <span class="constant">EAX</span>,
 138                 <span class="constant">EDX</span>, <span class="constant">ECX</span>.
 139                 This incompatibility is compensated at C&nbsp;source level in the
 140                 @{[ a_href '#functype','relaying code' ]} generated by
 141                 <span class="fname">captivesym</span> relay generator.</p>
 142
 143                 @{[ doc_img 'fig/calltype_fastcall',
 144                                 'W32 Calling Convention <span class="constant">fastcall</span> Scheme' ]}
 145
 146                 <table border="0" width="100%"><tr><td align="center"><table border="1">
 147                         <caption>Calling Convention <span class="constant">fastcall</span> Characteristics</caption>
 148                         <tr><td>Arguments freed by         </td><td>callee</td></tr>
 149                         <tr><td>Arguments on the stack     </td><td>#2 ... #(n-1)</td></tr>
 150                         <tr><td>Arguments in the registers </td><td><span class="constant">ECX</span>=#0,
 151                                                                                                                                                                                                         <span class="constant">EDX</span>=#1</td></tr>
 152                         <tr><td>GCC &ge;3.4 attribute      </td><td><span class="command">__attribute__((__fastcall__))</span></td></tr>
 153                         <tr><td>GCC &lt;3.4 attr. emulation</td><td><span class="command">__attribute__((__stdcall__))</span></td></tr>
 154                         <tr><td>                           </td><td><span class="command">__attribute__((__regparm__(3) /* EAX,EDX,ECX */))</span></td></tr>
 155                 </table></td></tr></table>
 156
 157
 158 HERE
 159
 160
 161 project::captive::doc::Macros->footer();
 162 }
 163 1;