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";
-use project::captive::doc::Macros;
+require CGI;
+BEGIN { Wuse 'project::captive::doc::Macros'; }
-My::Web->init(
+project::captive::doc::Macros->init(
"__PACKAGE__"=>__PACKAGE__,
"title"=>'Captive NTFS Developer Documentation: API Functions',
- "head_css"=>$doc_Macros_head_css,
+ "rel_prev"=>'Details.html.pl',
+ "rel_next"=>'CallType.html.pl',
);
-My::Web->heading();
print <<"HERE";
<table border="1" align="center">
<tr><th>Function type </th><th>Items</th><th>Portion</th></tr>
- <tr><td>@{[ a_href '#functype_pass','pass' ]} </td><td> 81</td><td> 26%</td></tr>
- <tr><td>@{[ a_href '#functype_wrap','wrap' ]} </td><td> 2</td><td> 0%</td></tr>
- <tr><td>@{[ a_href '#functype_native_reactos','native-ReactOS' ]}</td><td> 113</td><td> 36%</td></tr>
- <tr><td>@{[ a_href '#functype_native_libcaptive','native-own' ]} </td><td> 116</td><td> 38%</td></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>
<caption>Function Implementation Types Statistics</caption>
</table>
+ @{[ doc_img 'ratio','Functions Reusal Ratio' ]}
+
<p>As there are several choices to implement each function the usual
attempts/investigations ordering is listed in the sections below.</p>
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 '#functype_native','native implementation' ]} since there is no
- possibility to @{[ a_href '#functype_pass','pass' ]} the data symbol instead of
+ @{[ 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
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
- $W->{"top_dir"}.'/project/Pod2Html.html.pl?cvs=priv/captive/src/libcaptive/ke/captivesym.pl',
+ '/project/Pod2Html.html.pl?cvs=priv/captive/src/libcaptive/ke/captivesym.pl',
'src/libcaptive/ke/captivesym.pl' ]}</span>
<a name="functype_pass"><h2>Direct Pass to Original "ntoskrnl.exe"</h2></a>
<a name="functype_pass_fromunix"><h3>Pass from UNIX Code</h3></a>
<p>Control flow begins in some standard UNIX code. Such code is always
- using @{[ a_href '#calltype_cdecl','cdecl call type' ]} for all its
- intracalls. <a href="#functype_native_reactos">Native functions
+ 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
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_cdecl','cdecl call type' ]}.</p>
+ @{[ a_href 'CallType.html.pl#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>
<p>This function type is similiar to the
- @{[ a_href '#functype_pass_fromunix','previous one' ]} with the exception
+ @{[ a_href 'APITypes.html.pl#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 '#functype_pass_fromunix','described above' ]} gets
+ mechanism @{[ a_href 'APITypes.html.pl#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 '#functype_pass_fromunix','from UNIX code' ]}. UNIX code always
- uses relay with external @{[ a_href '#calltype_cdecl','cdecl call type' ]}
+ @{[ 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' ]}
but in this case a relay with the appropriate
@{[ a_href '#calltype','cdecl/stdcall/fastcall call type' ]} is used.</p>
<a name="functype_wrap_fromunix"><h3>Wrapping of Call from UNIX Code</h3></a>
<p>The code control flow has no special hardcore features since it is
- very similiar to <a href="#functype_pass_fromunix">the direct pass to
+ very similiar to <a href="APITypes.html.pl#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_cdecl','cdecl call type' ]} manner.
+ standard UNIX @{[ a_href 'CallType.html.pl#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
<a name="functype_wrap_fromw32"><h3>Wrapping of Call from W32 Code</h3></a>
<p>This scheme is a combination of the
- <a href="#functype_wrap_fromunix">previous wrap of a call from
- UNIX code</a> and the <a href="#functype_pass_fromw32">direct pass from
+ <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
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="#functype_pass">passed to the original
+ <p>Some functions can be <a href="APITypes.html.pl#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
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="#functype_native_reactos"><span class="productname">ReactOS</span> implementations</a>.
+ <a href="APITypes.html.pl#functype_native_reactos"><span class="productname">ReactOS</span> implementations</a>.
@{[ doc_img 'fig/functype_native_fromunix',
'Function Type: <span class="constant">native</span> from UNIX 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_cdecl','cdecl call type' ]} manner.</p>
+ standard UNIX @{[ a_href 'CallType.html.pl#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>
'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="#functype_native_fromw32">previous call of
+ <a href="APITypes.html.pl#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="#functype_pass_fromw32">the case of passing control from W32
+ <a href="APITypes.html.pl#functype_pass_fromw32">the case of passing control from W32
call</a>.</p>
<p>The original W32 function implementation located in the original
<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="#functype_pass">pass some function calls to the
+ possible to <a href="APITypes.html.pl#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 '#functype_pass','pass' ]} were reimplemented by this project
+ @{[ a_href 'APITypes.html.pl#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>
HERE
-My::Web->footer();
+project::captive::doc::Macros->footer();
git://git.jankratochvil.net / www.jankratochvil.net.git / blobdiff