-#! /usr/bin/perl
-#
# $Id$
# Captive project doc APITypes page Perl template.
-# Copyright (C) 2003 Jan Kratochvil <project-www.jankratochvil.net@jankratochvil.net>
+# Copyright (C) 2003
-2005 Jan Kratochvil <project-www.jankratochvil.net@jankratochvil.net>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
use strict;
use warnings;
-BEGIN{ open F,"Makefile"; our $top_dir=pop @{[split /\s/,(grep /^top_srcdir/,<F>)[0]]}; eval "use lib '$top_dir'"; close F; }
use My::Web;
require CGI;
BEGIN { Wuse 'project::captive::doc::Macros'; }
+sub handler
+{
project::captive::doc::Macros->init(
- "__PACKAGE__"=>__PACKAGE__,
"title"=>'Captive NTFS Developer Documentation: API Functions',
- "rel_prev"=>'Details.html.pl',
- "rel_next"=>'CallType.html.pl',
+ "rel_prev"=>'Details.pm',
+ "rel_next"=>'CallType.pm',
);
print <<"HERE";
-<a name="functype"><h1>API Function Implementation Choices</h1></a>
+<h1 id="functype">API Function Implementation Choices</h1>
<p>For each function exported by W32
<span class="fname">ntoskrnl.exe</span> and imported and called by the
functionality. Currently implemented functionality statistics are provided
below:</p>
- <table border="1" align="center">
- <tr><th>Function type </th><th>Items</th><th>Portion</th></tr>
- <tr><td>@{[ a_href 'APITypes.html.pl#functype_pass','pass' ]} </td><td> 81</td><td> 26%</td></tr>
- <tr><td>@{[ a_href 'APITypes.html.pl#functype_wrap','wrap' ]} </td><td> 2</td><td> 0%</td></tr>
- <tr><td>@{[ a_href 'APITypes.html.pl#functype_native_reactos','native-ReactOS' ]}</td><td> 113</td><td> 36%</td></tr>
- <tr><td>@{[ a_href 'APITypes.html.pl#functype_native_libcaptive','native-own' ]} </td><td> 116</td><td> 38%</td></tr>
+ <table border="0" width="100%"><tr><td align="center"><table border="1">
<caption>Function Implementation Types Statistics</caption>
- </table>
+ <tr><th>Function type </th><th>Items</th><th>Portion</th></tr>
+ <tr><td>@{[ a_href 'APITypes.pm#functype_pass','pass' ]} </td><td> 81</td><td> 26%</td></tr>
+ <tr><td>@{[ a_href 'APITypes.pm#functype_wrap','wrap' ]} </td><td> 2</td><td> 0%</td></tr>
+ <tr><td>@{[ a_href 'APITypes.pm#functype_native_reactos','native-ReactOS' ]}</td><td> 113</td><td> 36%</td></tr>
+ <tr><td>@{[ a_href 'APITypes.pm#functype_native_libcaptive','native-own' ]} </td><td> 116</td><td> 38%</td></tr>
+ </table></td></tr></table>
@{[ doc_img 'ratio','Functions Reusal Ratio' ]}
contain already prepared content at the runtime. There is a problem
with <span class="constant">patched</span> libraries where it is necessary
to also fully implement the data symbol as
- @{[ a_href 'APITypes.html.pl#functype_native','native implementation' ]} since there is no
- possibility to @{[ a_href 'APITypes.html.pl#functype_pass','pass' ]} the data symbol instead of
+ @{[ a_href 'APITypes.pm#functype_native','native implementation' ]} since there is no
+ possibility to @{[ a_href 'APITypes.pm#functype_pass','pass' ]} the data symbol instead of
the original W32 data location and therefore there will be two instances of
such data variable place. As there will be also the uncaught references for
such W32 data location from the <span class="constant">patched</span>
<span class="fname">captivesym</span>-specific source file syntax please
see its documentation:
<span class="fname">@{[ a_href
- '/project/Pod2Html.html.pl?cvs=captive/src/libcaptive/ke/captivesym.pl',
+ '/project/Pod2Html.pm?cvs=captive/src/libcaptive/ke/captivesym.pl',
'src/libcaptive/ke/captivesym.pl' ]}</span>
+ </p>
- <a name="functype_pass"><h2>Direct Pass to Original "ntoskrnl.exe"</h2></a>
+ <h2 id="functype_pass">Direct Pass to Original "ntoskrnl.exe"</h2>
<p>Simple (standalone) functions such as
<span class="function">RtlTimeToSecondsSince1970()</span> can be simply
<span class="constant">GenericTable</span> subsystem or
<span class="constant">LargeMcb</span> handling.</p>
- <a name="functype_pass_fromunix"><h3>Pass from UNIX Code</h3></a>
+ <h3 id="functype_pass_fromunix">Pass from UNIX Code</h3>
<p>Control flow begins in some standard UNIX code. Such code is always
- using @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl call type' ]} for all its
- intracalls. <a href="APITypes.html.pl#functype_native_reactos">Native functions
+ using @{[ a_href 'CallType.pm#calltype_cdecl','cdecl call type' ]} for all its
+ intracalls. <a href="APITypes.pm#functype_native_reactos">Native functions
compiled from <span class="productname">ReactOS</span> sources</a> use
their own @{[ a_href '#calltype','cdecl/stdcall/fastcall' ]} declarations
but these call type modifications are discarded during compilation for
will return to the UNIX jump table relay which will debug dump the
return value and it will finally pass the control back to the UNIX
caller in the standard UNIX
- @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl call type' ]}.</p>
+ @{[ a_href 'CallType.pm#calltype_cdecl','cdecl call type' ]}.</p>
@{[ doc_img 'fig/functype_patched_pass_fromunix',
'Function Type: <span class="constant">pass</span> from UNIX Code' ]}
- <a name="functype_pass_fromw32"><h3>Pass from W32 Code</h3></a>
+ <h3 id="functype_pass_fromw32">Pass from W32 Code</h3>
<p>This function type is similiar to the
- @{[ a_href 'APITypes.html.pl#functype_pass_fromunix','previous one' ]} with the exception
+ @{[ a_href 'APITypes.pm#functype_pass_fromunix','previous one' ]} with the exception
of more complicated entry point. Unfortunately W32 libraries call their
own functions directly, using the <span class="instruction">call</span>
instructions without any patchable jump table. Even the
according to the relocation table record as such library intra-call
instruction has no relocation due to its relative argument offset on
<span class="constant">i386</span>. This time the double-breakpoint
- mechanism @{[ a_href 'APITypes.html.pl#functype_pass_fromunix','described above' ]} gets
+ mechanism @{[ a_href 'APITypes.pm#functype_pass_fromunix','described above' ]} gets
handy since it will catch the entry point when the function gets
called. <span class="constant">SIGSEGV</span> handler gets invoked by
the <span class="instruction">hlt</span> instruction and it will
<p>The jump table relay used for the callers from W32 code is
a different one than the relay being used for the callers
- @{[ a_href 'APITypes.html.pl#functype_pass_fromunix','from UNIX code' ]}. UNIX code always
- uses relay with external @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl call type' ]}
+ @{[ a_href 'APITypes.pm#functype_pass_fromunix','from UNIX code' ]}. UNIX code always
+ uses relay with external @{[ a_href 'CallType.pm#calltype_cdecl','cdecl call type' ]}
but in this case a relay with the appropriate
@{[ a_href '#calltype','cdecl/stdcall/fastcall call type' ]} is used.</p>
@{[ vskip() ]}
- <table border="1" align="center">
+ <table border="0" width="100%"><tr><td align="center"><table border="1">
+ <caption>Function Type <span class="constant">pass</span> Characteristics</caption>
<tr><td><span class="fname">captivesym</span> keyword</td><td>pass</td></tr>
<tr><td>Native code function name </td><td>(no implementation)</td></tr>
<tr><td>W32 traced code from UNIX function name </td><td>FUNCNAME</td></tr>
<tr><td>W32 traced code from W32 function name </td><td>FUNCNAME_cdecl/_stdcall/_fastcall</td></tr>
<tr><td>Entry/exit debug tracing from UNIX code </td><td>yes</td></tr>
<tr><td>Entry/exit debug tracing from W32 code </td><td>yes</td></tr>
- <caption>Function Type <span class="constant">pass</span> Characteristics</caption>
- </table>
+ </table></td></tr></table>
- <a name="functype_wrap"><h2>Wrap of the Original "ntoskrnl.exe" Function</h2></a>
+ <h2 id="functype_wrap">Wrap of the Original "ntoskrnl.exe" Function</h2>
- <a name="functype_wrap_fromunix"><h3>Wrapping of Call from UNIX Code</h3></a>
+ <h3 id="functype_wrap_fromunix">Wrapping of Call from UNIX Code</h3>
<p>The code control flow has no special hardcore features since it is
- very similiar to <a href="APITypes.html.pl#functype_pass_fromunix">the direct pass to
+ very similiar to <a href="APITypes.pm#functype_pass_fromunix">the direct pass to
W32 function from UNIX code</a>. All the wrapping is done in the
- standard UNIX @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl call type' ]} manner.
+ standard UNIX @{[ a_href 'CallType.pm#calltype_cdecl','cdecl call type' ]} manner.
Jump table debug dumping relays are provided twice — the
"outer" one to trace the parameters from the function caller
and the "inner" one to trace the call from the wrapper to the
@{[ doc_img 'fig/functype_patched_wrap_fromunix',
'Function Type: <span class="constant">wrap</span> from UNIX Code' ]}
- <a name="functype_wrap_fromw32"><h3>Wrapping of Call from W32 Code</h3></a>
+ <h3 id="functype_wrap_fromw32">Wrapping of Call from W32 Code</h3>
<p>This scheme is a combination of the
- <a href="APITypes.html.pl#functype_wrap_fromunix">previous wrap of a call from
- UNIX code</a> and the <a href="APITypes.html.pl#functype_pass_fromw32">direct pass from
+ <a href="APITypes.pm#functype_wrap_fromunix">previous wrap of a call from
+ UNIX code</a> and the <a href="APITypes.pm#functype_pass_fromw32">direct pass from
the W32 code</a>. The control is caught and redirected by
<span class="constant">SIGSEGV</span> handler from the breakpoint
placed at the entry to the original W32 function code. The second entry
@{[ vskip() ]}
- <p>Some functions can be <a href="APITypes.html.pl#functype_pass">passed to the original
+ <p>Some functions can be <a href="APITypes.pm#functype_pass">passed to the original
code</a> but they need their parameters to be checked/prepared.
Currently, such wrapping is only needed for the
<span class="function">ExAllocateFromPagedLookasideList()</span> function
differ across different <span class="fname">ntoskrnl.exe</span>
versions.</p>
- <table border="1" align="center">
+ <table border="0" width="100%"><tr><td align="center"><table border="1">
+ <caption>Function Type <span class="constant">wrap</span> Characteristics</caption>
<tr><td><span class="fname">captivesym</span> keyword</td><td>wrap</td></tr>
<tr><td>Native UNIX wrapping code function name </td><td>FUNCNAME_wrap</td></tr>
<tr><td>W32 traced wraping code from UNIX func. name </td><td>FUNCNAME</td></tr>
<tr><td>W32 traced original code function name </td><td>FUNCNAME_orig</td></tr>
<tr><td>Entry/exit debug tracing from UNIX code </td><td>yes</td></tr>
<tr><td>Entry/exit debug tracing from W32 code </td><td>yes</td></tr>
- <caption>Function Type <span class="constant">wrap</span> Characteristics</caption>
- </table>
+ </table></td></tr></table>
- <a name="functype_native"><h2>Native Implementation</h2></a>
+ <h2 id="functype_native">Native Implementation</h2>
- <a name="functype_native_fromunix"><h3>Native Implementation Called from UNIX Code</h3></a>
+ <h3 id="functype_native_fromunix">Native Implementation Called from UNIX Code</h3>
<p>This is the simplest case of a function call as it is fully
handled only by the compiler and/or linker.</p>
the callee are provided with full source file debug information for the
debugger. Also the callee usually debug dumps its entry/exit parameters
by custom debug dumps in the
- <a href="APITypes.html.pl#functype_native_reactos"><span class="productname">ReactOS</span> implementations</a>.
+ <a href="APITypes.pm#functype_native_reactos"><span class="productname">ReactOS</span> implementations</a>.
+ </p>
@{[ doc_img 'fig/functype_native_fromunix',
'Function Type: <span class="constant">native</span> from UNIX Code' ]}
- <a name="functype_native_fromw32"><h3>Native Implementation of
- "unpatched" Library Function Called from W32 Code</h3></a>
+ <h3 id="functype_native_fromw32">Native Implementation of
+ "unpatched" Library Function Called from W32 Code</h3>
@{[ doc_img 'fig/functype_unpatched_native_fromw32',
'Function Type: <span class="constant">native</span> of <span class="constant">unpatched</span> from W32 Code' ]}
code with the appropriate
@{[ a_href '#calltype','cdecl/stdcall/fastcall call type' ]} while the
relay will call the implementation of the native function in the
- standard UNIX @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl call type' ]} manner.</p>
+ standard UNIX @{[ a_href 'CallType.pm#calltype_cdecl','cdecl call type' ]} manner.</p>
- <a name="functype_native_fromw32_patched"><h3>Native Implementation of "patched" Library Function Called from W32 Code</h3></a>
+ <h3 id="functype_native_fromw32_patched">Native Implementation of "patched" Library Function Called from W32 Code</h3>
@{[ doc_img 'fig/functype_patched_native_fromw32',
'Function Type: <span class="constant">native</span> of <span class="constant">patched</span> from W32 Code' ]}
<p>The calling scheme is similiar to the
- <a href="APITypes.html.pl#functype_native_fromw32">previous call of
+ <a href="APITypes.pm#functype_native_fromw32">previous call of
<span class="constant">unpatched</span> library function from W32
code</a> but the call control is redirected from the entry point of the
original W32 binary implementation by the breakpoint and its
<span class="constant">SIGSEGV</span> handler as in
- <a href="APITypes.html.pl#functype_pass_fromw32">the case of passing control from W32
+ <a href="APITypes.pm#functype_pass_fromw32">the case of passing control from W32
call</a>.</p>
<p>The original W32 function implementation located in the original
project is running pure W32 kernel space environment (in $gnulinux user
space!).</p>
- <a name="functype_native_reactos"><h3>Native Implementation
- - <span class="productname">ReactOS</span></h3></a>
+ <h3 id="functype_native_reactos">Native Implementation
+ - <span class="productname">ReactOS</span></h3>
<p>Some functions are already implemented in the $ReactOS
project and they can be used as they are. Although it would be
- possible to <a href="APITypes.html.pl#functype_pass">pass some function calls to the
+ possible to <a href="APITypes.pm#functype_pass">pass some function calls to the
original code</a> it is more handy to provide native implementation as
there is better control of the data handling during debugging sessions
due to the provided debugging symbols.</p>
</blockquote>
<p>Functions that were not possible to
- @{[ a_href 'APITypes.html.pl#functype_pass','pass' ]} were reimplemented by this project
+ @{[ a_href 'APITypes.pm#functype_pass','pass' ]} were reimplemented by this project
and placed in the project's implementation directories
@{[ a_href '#reactos_nocare','instead of extending' ]} $ReactOS code.</p>
- <a name="functype_native_wine"><h3>Native Implementation – <span class="productname">Wine</span></h3></a>
+ <h3 id="functype_native_wine">Native Implementation – <span class="productname">Wine</span></h3>
<p>Even though $Wine only implements the
<span class="productname">Microsoft Windows NT</span> user space, there
still are some common functions which could be copied from the $Wine
project.</p>
- <a name="functype_native_libcaptive"><h3>Native Implementation – Project Specific</h3></a>
+ <h3 id="functype_native_libcaptive">Native Implementation – Project Specific</h3>
<p>As the last resort it was necessary to provide completely own
implementation of some API functions such as PC hardware dependent
@{[ vskip() ]}
- <table border="1" align="center">
+ <table border="0" width="100%"><tr><td align="center"><table border="1">
+ <caption>Function Type <span class="constant">native</span> Characteristics</caption>
<tr><td><span class="fname">captivesym</span> keyword</td><td>(none; just the symbol name)</td></tr>
<tr><td>Native code function name </td><td>FUNCTIONNAME</td></tr>
<tr><td>Native traced code from W32 code func. name </td><td>FUNCTIONNAME_cdecl/_std...</td></tr>
<tr><td>Entry/exit debug tracing from UNIX code </td><td>no</td></tr>
<tr><td>Entry/exit debug tracing from W32 code </td><td>yes</td></tr>
- <caption>Function Type <span class="constant">native</span> Characteristics</caption>
- </table>
+ </table></td></tr></table>
- <a name="functype_undef"><h2>Undefined Function</h2></a>
+ <h2 id="functype_undef">Undefined Function</h2>
<p>Functions not defined by any of the previous function types cannot be
called by any W32 code including the code of the library implementing
<span class="constant">undef</span> type to prevent unresolved symbol
reference.</p>
- <table border="1" align="center">
+ <table border="0" width="100%"><tr><td align="center"><table border="1">
+ <caption>Function Type <span class="constant">undef</span> Characteristics</caption>
<tr><td><span class="fname">captivesym</span> keyword</td><td>undef</td></tr>
<tr><td>Native code function name </td><td>(no implementation)</td></tr>
<tr><td>Native traced code function name </td><td>FUNCTIONNAME_cdecl/_stdcall/_fastcall</td></tr>
<tr><td>Debug tracing message from UNIX code </td><td>yes</td></tr>
<tr><td>Debug tracing message from W32 code </td><td>yes</td></tr>
- <caption>Function Type <span class="constant">undef</span> Characteristics</caption>
- </table>
+ </table></td></tr></table>
HERE
project::captive::doc::Macros->footer();
+}
+1;
git://git.jankratochvil.net / www.jankratochvil.net.git / blobdiff