X-Git-Url: http://git.jankratochvil.net/?p=www.jankratochvil.net.git;a=blobdiff_plain;f=project%2Fcaptive%2Fdoc%2FAPITypes.pm;fp=project%2Fcaptive%2Fdoc%2FAPITypes.html.pl;h=60aea6f373c88a210422653a45120fb12fd4863d;hp=9c0476cfd24900b8bf300d92b1bf860db0f0d986;hb=19c5ad8e26ac320516b8427c416a9195ce4fea48;hpb=4df4c5409020cd58d7dd7f98a88653c96e860dfb diff --git a/project/captive/doc/APITypes.html.pl b/project/captive/doc/APITypes.pm similarity index 83% rename from project/captive/doc/APITypes.html.pl rename to project/captive/doc/APITypes.pm index 9c0476c..60aea6f 100755 --- a/project/captive/doc/APITypes.html.pl +++ b/project/captive/doc/APITypes.pm @@ -1,8 +1,6 @@ -#! /usr/bin/perl -# # $Id$ # Captive project doc APITypes page Perl template. -# Copyright (C) 2003 Jan Kratochvil +# Copyright (C) 2003-2005 Jan Kratochvil # # 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 @@ -25,24 +23,24 @@ our $CVS_ID=q$Id$; use strict; use warnings; -BEGIN{ open F,"Makefile"; our $top_dir=pop @{[split /\s/,(grep /^top_srcdir/,)[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"; -

API Function Implementation Choices

 +

API Function Implementation Choices

For each function exported by W32 ntoskrnl.exe and imported and called by the @@ -50,14 +48,14 @@ print <<"HERE"; functionality. Currently implemented functionality statistics are provided below:

- - - - - - +
Function type ItemsPortion
@{[ a_href 'APITypes.html.pl#functype_pass','pass' ]} 81 26%
@{[ a_href 'APITypes.html.pl#functype_wrap','wrap' ]} 2 0%
@{[ a_href 'APITypes.html.pl#functype_native_reactos','native-ReactOS' ]} 113 36%
@{[ a_href 'APITypes.html.pl#functype_native_libcaptive','native-own' ]} 116 38%
+ + + + +
-
Function Implementation Types Statistics
+
Function type ItemsPortion
@{[ a_href 'APITypes.pm#functype_pass','pass' ]} 81 26%
@{[ a_href 'APITypes.pm#functype_wrap','wrap' ]} 2 0%
@{[ a_href 'APITypes.pm#functype_native_reactos','native-ReactOS' ]} 113 36%
@{[ a_href 'APITypes.pm#functype_native_libcaptive','native-own' ]} 116 38%
@{[ doc_img 'ratio','Functions Reusal Ratio' ]} @@ -71,8 +69,8 @@ print <<"HERE"; contain already prepared content at the runtime. There is a problem with patched 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 patched @@ -94,10 +92,11 @@ print <<"HERE"; captivesym-specific source file syntax please see its documentation: @{[ 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' ]} +

-

Direct Pass to Original "ntoskrnl.exe"

 +

Direct Pass to Original "ntoskrnl.exe"

Simple (standalone) functions such as RtlTimeToSecondsSince1970() can be simply @@ -109,11 +108,11 @@ print <<"HERE"; GenericTable subsystem or LargeMcb handling.

-

Pass from UNIX Code

 +

Pass from UNIX Code

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. Native functions + using @{[ a_href 'CallType.pm#calltype_cdecl','cdecl call type' ]} for all its + intracalls. Native functions compiled from ReactOS sources use their own @{[ a_href '#calltype','cdecl/stdcall/fastcall' ]} declarations but these call type modifications are discarded during compilation for @@ -186,15 +185,15 @@ print <<"HERE"; 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' ]}.

+ @{[ a_href 'CallType.pm#calltype_cdecl','cdecl call type' ]}.

@{[ doc_img 'fig/functype_patched_pass_fromunix', 'Function Type: pass from UNIX Code' ]} -

Pass from W32 Code

 +

Pass from W32 Code

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 call instructions without any patchable jump table. Even the @@ -202,7 +201,7 @@ print <<"HERE"; according to the relocation table record as such library intra-call instruction has no relocation due to its relative argument offset on i386. 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. SIGSEGV handler gets invoked by the hlt instruction and it will @@ -224,8 +223,8 @@ print <<"HERE";

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.

@@ -234,24 +233,24 @@ print <<"HERE"; @{[ vskip() ]} - +
+ - -
Function Type pass Characteristics
captivesym keywordpass
Native code function name (no implementation)
W32 traced code from UNIX function name FUNCNAME
W32 traced code from W32 function name FUNCNAME_cdecl/_stdcall/_fastcall
Entry/exit debug tracing from UNIX code yes
Entry/exit debug tracing from W32 code yes
Function Type pass Characteristics
+
-

Wrap of the Original "ntoskrnl.exe" Function

 +

Wrap of the Original "ntoskrnl.exe" Function

-

Wrapping of Call from UNIX Code

 +

Wrapping of Call from UNIX Code

The code control flow has no special hardcore features since it is - very similiar to the direct pass to + very similiar to the direct pass to W32 function from UNIX code. 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 @@ -262,11 +261,11 @@ print <<"HERE"; @{[ doc_img 'fig/functype_patched_wrap_fromunix', 'Function Type: wrap from UNIX Code' ]} -

Wrapping of Call from W32 Code

+

Wrapping of Call from W32 Code

This scheme is a combination of the - previous wrap of a call from - UNIX code and the direct pass from + previous wrap of a call from + UNIX code and the direct pass from the W32 code. The control is caught and redirected by SIGSEGV handler from the breakpoint placed at the entry to the original W32 function code. The second entry @@ -281,7 +280,7 @@ print <<"HERE"; @{[ vskip() ]} -

Some functions can be passed to the original +

Some functions can be passed to the original code but they need their parameters to be checked/prepared. Currently, such wrapping is only needed for the ExAllocateFromPagedLookasideList() function @@ -298,7 +297,8 @@ print <<"HERE"; differ across different ntoskrnl.exe versions.

- +
+ @@ -306,12 +306,11 @@ print <<"HERE"; - -
Function Type wrap Characteristics
captivesym keywordwrap
Native UNIX wrapping code function name FUNCNAME_wrap
W32 traced wraping code from UNIX func. name FUNCNAME
W32 traced original code function name FUNCNAME_orig
Entry/exit debug tracing from UNIX code yes
Entry/exit debug tracing from W32 code yes
Function Type wrap Characteristics
+
-

Native Implementation

 +

Native Implementation

-

Native Implementation Called from UNIX Code

 +

Native Implementation Called from UNIX Code

This is the simplest case of a function call as it is fully handled only by the compiler and/or linker.

@@ -328,13 +327,14 @@ print <<"HERE"; 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 - ReactOS implementations. + ReactOS implementations. +

@{[ doc_img 'fig/functype_native_fromunix', 'Function Type: native from UNIX Code' ]} -

Native Implementation of - "unpatched" Library Function Called from W32 Code

 +

Native Implementation of + "unpatched" Library Function Called from W32 Code

@{[ doc_img 'fig/functype_unpatched_native_fromw32', 'Function Type: native of unpatched from W32 Code' ]} @@ -358,20 +358,20 @@ print <<"HERE"; 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.

+ standard UNIX @{[ a_href 'CallType.pm#calltype_cdecl','cdecl call type' ]} manner.

-

Native Implementation of "patched" Library Function Called from W32 Code

 +

Native Implementation of "patched" Library Function Called from W32 Code

@{[ doc_img 'fig/functype_patched_native_fromw32', 'Function Type: native of patched from W32 Code' ]}

The calling scheme is similiar to the - previous call of + previous call of unpatched library function from W32 code but the call control is redirected from the entry point of the original W32 binary implementation by the breakpoint and its SIGSEGV handler as in - the case of passing control from W32 + the case of passing control from W32 call.

The original W32 function implementation located in the original @@ -392,12 +392,12 @@ print <<"HERE"; project is running pure W32 kernel space environment (in $gnulinux user space!).

-

Native Implementation - - ReactOS

 +

Native Implementation + - ReactOS

Some functions are already implemented in the $ReactOS project and they can be used as they are. Although it would be - possible to pass some function calls to the + possible to pass some function calls to the original code 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.

@@ -417,18 +417,18 @@ print <<"HERE";

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.

-

Native Implementation – Wine

 +

Native Implementation – Wine

Even though $Wine only implements the Microsoft Windows NT user space, there still are some common functions which could be copied from the $Wine project.

-

Native Implementation – Project Specific

 +

Native Implementation – Project Specific

As the last resort it was necessary to provide completely own implementation of some API functions such as PC hardware dependent @@ -436,16 +436,16 @@ print <<"HERE"; @{[ vskip() ]} - +
+ - -
Function Type native Characteristics
captivesym keyword(none; just the symbol name)
Native code function name FUNCTIONNAME
Native traced code from W32 code func. name FUNCTIONNAME_cdecl/_std...
Entry/exit debug tracing from UNIX code no
Entry/exit debug tracing from W32 code yes
Function Type native Characteristics
+
-

Undefined Function

+

Undefined Function

Functions not defined by any of the previous function types cannot be called by any W32 code including the code of the library implementing @@ -464,17 +464,19 @@ print <<"HERE"; undef type to prevent unresolved symbol reference.

- +
+ - -
Function Type undef Characteristics
captivesym keywordundef
Native code function name (no implementation)
Native traced code function name FUNCTIONNAME_cdecl/_stdcall/_fastcall
Debug tracing message from UNIX code yes
Debug tracing message from W32 code yes
Function Type undef Characteristics
+
HERE project::captive::doc::Macros->footer(); +} +1;