<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>
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>
<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>
<span class="productname">Microsoft Windows XP</span> as they are freely
downloadable at:
@{[ a_href 'http://www.microsoft.com/WindowsXP/pro/downloads/servicepacks/sp1/checkedbuild.asp' ]}</p>
- There may be @{[ a_href '#law','legal reasons' ]} you would not be allowed
+ There may be @{[ a_href 'Architecture.html.pl#law','legal reasons' ]} you would not be allowed
to use there files if you own license to a different version of
<span class="productname">Microsoft Windows</span>. Legal rights will very
depending on your country.</p>
Fortunately it is safe to never destroy
<span class="type">SharedCacheMap</span> and leave it leaked - everything
gets clean in the
- @{[ a_href '#sandbox','sandboxed environment' ]} soon anyway.</p>
+ @{[ a_href 'Details.html.pl#sandbox','sandboxed environment' ]} soon anyway.</p>
<p>There exist Map and Pin type objects for each
<span class="type">SharedCacheMap</span> although they look very similiar.
There can exist multiple Pin mappings of the same page (although
sharing the same memory space). This detaching must be implemented
even in the
- @{[ a_href '#synchronous','single-threaded' ]} W32 implementation
+ @{[ a_href 'Details.html.pl#synchronous','single-threaded' ]} W32 implementation
of this project as it is affecting the behaviour of Cache Manager.
It was never
- @{[ a_href '#TraceFS','seen' ]} how to behave if multiple dirty Pin
+ @{[ a_href 'CacheManager.html.pl#TraceFS','seen' ]} how to behave if multiple dirty Pin
mappings of the same page exist.</p>
</dd>
</dl>
<p>You can now pray a bit and snap the resulting Cache Manager tracing
from <span class="productname">WinDbg</span> by
- @{[ a_href '#WinDbg','W32 remote kernel debugging' ]}:</p>
+ @{[ a_href 'Reverse.html.pl#WinDbg','W32 remote kernel debugging' ]}:</p>
@{[ doc_img 'ntdebug-windbg-boot','Successfuly connected <span class="productname">WinDbg</span>' ]}
<a name="calltype"><h1>API Function Calling Conventions</h1></a>
<p>Standard UNIX code compiled by GCC (GNU C Compiler) running on host
- $gnulinux always uses @{[ a_href '#calltype_cdecl','cdecl' ]} ABI (Application
+ $gnulinux always uses @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl' ]} ABI (Application
Binary Interface) calling convention. This calling convention is also the
default declaration type of UNIX functions.</p>
arguments are cleaned by the callee. Possible inconsistencies in the
number of function arguments with the function prototype used by the
caller will result in fatal crash. Variable arguments lists cannot be
- passed by this convention – use @{[ a_href '#calltype_cdecl','cdecl' ]}
+ passed by this convention – use @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl' ]}
instead.</p>
<table border="1" align="center">
<span class="constant">EDX</span> respectively. Possible inconsistencies
in the number of function arguments with the function prototype used by
the caller will result in fatal crash. Variable arguments lists cannot be
- passed by this convention – use @{[ a_href '#calltype_cdecl','cdecl' ]}
+ passed by this convention – use @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl' ]}
instead.</p>
<p>GCC (GNU C Compiler) native support for this calling convention
non-persistent memory buffering of all the possible write requests.</p>
<span class="constant">sandbox commit buffer</span> is involved only in the
- case @{[ a_href '#sandbox','sandboxing feature' ]} is active. It will
+ case @{[ a_href 'Details.html.pl#sandbox','sandboxing feature' ]} is active. It will
buffer any writes to the device during the sandbox run to prevent
filesystem damage if the driver would fail in the meantime. If the
filesystem gets finally successfully unmounted this sandbox buffer can be
Now we need to transparently
@{[ captive_srcfile 'src/libcaptive/sandbox/sandbox.idl','connect' ]}
the device interface of <span class="type">GIOChannel</span> type through
- @{[ a_href '#sandbox','CORBA/ORBit' ]} to the sandboxed slave.
+ @{[ a_href 'Details.html.pl#sandbox','CORBA/ORBit' ]} to the sandboxed slave.
<p>Such device is still only a UNIX style GLib <span
class="type">GIOChannel</span> type at this point. As we need to supply it
<p>The filesystem driver is called by the core W32 kernel implementation of
<span class="constant">libcaptive</span> in
- @{[ a_href '#synchronous','synchronous way' ]} in single-shot manner instead of
+ @{[ a_href 'Details.html.pl#synchronous','synchronous way' ]} in single-shot manner instead of
the several reentrancies while waiting for the disk I/O completions as can
be seen in the original
<span class="productname">Microsoft Windows NT</span>.
<a href="#client_interface_customapp">a custom application accessing
the W32 filesystem driver</a>.</p>
- <p>@{[ a_href '#sandbox','CORBA/ORBit' ]} hits us again – we need to
+ <p>@{[ a_href 'Details.html.pl#sandbox','CORBA/ORBit' ]} hits us again – we need to
@{[ captive_srcfile 'src/libcaptive/sandbox/sandbox.idl','translate' ]}
the @{[ a_href '#client_interface','custom filesystem API interface' ]}
out of the sandboxed slave to the UNIX space.</p>
<a name="demultiplexing_master">demultiplexing single API operations</a>
to multiple its connected sandbox slaves in transparent way
as each of them handles
- @{[ a_href '#mounted_one','just one filesystem device' ]}.</p>
+ @{[ a_href 'Details.html.pl#mounted_one','just one filesystem device' ]}.</p>
<p>The rest of the story is not much special for this project since this is
a common UNIX problem how to offer user space implemented UNIX filesystem
needs multiple operating threads (each UNIX kernel operation needs
one free lufsd slot/thread to not to fail immediately).
As <span class="constant">libcaptive</span> is
- @{[ a_href '#synchronous','single-threaded' ]} all the operations
+ @{[ a_href 'Details.html.pl#synchronous','single-threaded' ]} all the operations
get always synchronized by
<span class="constant">liblufs-captivefs</span>
before their pass over to <span class="constant">libcaptive</span>.</p>
it expects to get full PC hardware access privileges and thus some
datastructures do not get initialized by it (need to be trapped later at
runtime stage). Some of the missing initializations are solved by
- @{[ a_href '#functype_wrap','API functions wrapping' ]}.
+ @{[ a_href 'APITypes.html.pl#functype_wrap','API functions wrapping' ]}.
<p>pros: Lightweight, easier to debug.</p>
<a name="emulmeth_fs"><h3>Filesystem Driver Inside Virtual Address Space</h3></a>
- <p>Unlike @{[ a_href '#method_ntoskrnl','previous method' ]} here we do not use
+ <p>Unlike @{[ a_href 'Details.html.pl#method_ntoskrnl','previous method' ]} here we do not use
even <span class="fname">ntoskrnl.exe</span> as the complete kernel part of
W32 is <a name="native_ntoskrnl">emulated from the project source
files</a>. <span class="fname">cdfs.sys</span> driver was successfuly ran
unimplemented function is fatal and results in program termination. When we
need to implement any required API function we have multiple choices to do
so:
- @{[ a_href '#functype_pass','Direct pass to original <span class="fname">ntoskrnl.exe</span>' ]},
- @{[ a_href '#functype_wrap','Wrap of the original <span class="fname">ntoskrnl.exe</span> function' ]},
- @{[ a_href '#functype_native_reactos','Native implementation – $ReactOS' ]},
- @{[ a_href '#functype_native_wine','Native implementation – $Wine' ]}
+ @{[ a_href 'APITypes.html.pl#functype_pass','Direct pass to original <span class="fname">ntoskrnl.exe</span>' ]},
+ @{[ a_href 'APITypes.html.pl#functype_wrap','Wrap of the original <span class="fname">ntoskrnl.exe</span> function' ]},
+ @{[ a_href 'APITypes.html.pl#functype_native_reactos','Native implementation – $ReactOS' ]},
+ @{[ a_href 'APITypes.html.pl#functype_native_wine','Native implementation – $Wine' ]}
or
- @{[ a_href '#functype_native_libcaptive','Native implementation – project specific' ]}.
- <!-- a_href '#functype_undef','Undefined function' -->
+ @{[ a_href 'APITypes.html.pl#functype_native_libcaptive','Native implementation – project specific' ]}.
+ <!-- a_href 'APITypes.html.pl#functype_undef','Undefined function' -->
<a name="sandbox"><h2>Sandboxing of W32 filesystem</h2></a>
<p>Library is called <span class="constant">unpatched</span> if no original
binary code is needed since all of its functions are completely emulated by
- @{[ a_href '#functype_native','the native implementations' ]} of this project.
+ @{[ a_href 'APITypes.html.pl#functype_native','the native implementations' ]} of this project.
The typical <span class="constant">unpatched</span> representative is
<span class="fname">hal.dll</span> as it specializes on the hardware
dependent code and therefore it must be completely replaced by this project
<span class="constant">PE-32</span> use the appropriate W32 specific
@{[ a_href '#calltype','cdecl/stdcall/fastcall call types' ]},
<span class="fname">.so</span> must be completely compiled in the standard
- UNIX @{[ a_href '#calltype_cdecl','cdecl call type semantics' ]}.
- @{[ a_href '#functype_native','Native function implementations' ]} do not need
+ UNIX @{[ a_href 'CallType.html.pl#calltype_cdecl','cdecl call type semantics' ]}.
+ @{[ a_href 'APITypes.html.pl#functype_native','Native function implementations' ]} do not need
to be explicitely exported by <span class="fname">captivesym</span> as they
are resolved automatically by the UNIX dynamic system linker. It may be
surprising you will have to fix all such missing symbol exports if you
itself. It was considered as a more sane way to support multiple W32
mounted disks by completely separately running project instances in
a different UNIX processes communicating from their sandboxes via
- @{[ a_href '#sandbox','CORBA sandbox interface' ]}. This sandboxing
+ @{[ a_href 'Details.html.pl#sandbox','CORBA sandbox interface' ]}. This sandboxing
feature is not yet deployed although its code is already prepared.</p>
<p>The project also does not support any state cleanup to be able to load
<span class="function">captive_shutdown()</span> the process address space is
no longer usable for any further project operations and the process is
expected to be terminated in the manner compatible with its driving
- @{[ a_href '#sandbox','CORBA sandbox interface' ]} control master.</p>
+ @{[ a_href 'Details.html.pl#sandbox','CORBA sandbox interface' ]} control master.</p>
<p>Each sandbox executing the untrusted W32 binary filesystem driver code
is connected through its
- @{[ a_href '#sandbox','CORBA sandbox interface' ]} at the point of upper
+ @{[ a_href 'Details.html.pl#sandbox','CORBA sandbox interface' ]} at the point of upper
layer <span class="constant">libcaptive</span>-specific filesystem API, at
the point of the bottom layer of <span class="type">GIOChannel</span>
device access and also for transfers of GLib logging
returns for any further write requests
<span class="constant">STATUS_LOG_FILE_FULL</status> error code.
Apparently it is caused by the fact this project is
- @{[ a_href '#synchronous','single-threaded' ]} and it ignores the spawn
+ @{[ a_href 'Details.html.pl#synchronous','single-threaded' ]} and it ignores the spawn
of parallel journalling thread during <span class="fname">ntfs.sys</span>
initialization.</p>
during the final filesystem unmount.</p>
<p>For these reasons it was mandatory to support
- @{[ a_href '#parent_connector','transparent volume remounting' ]}.</p>
+ @{[ a_href 'Details.html.pl#parent_connector','transparent volume remounting' ]}.</p>
<a name="parent_connector"><h2><span class="constant">ParentConnector</span> volume remounter</h2></a>
<p><span class="re">> It would have to run as part of the kernel which would mean
that if it went wrong it could crash the machine. With no source, we might not
be able to work around the problem.</span><br />
- @{[ a_href '#sandbox','Nope' ]},
+ @{[ a_href 'Details.html.pl#sandbox','Nope' ]},
@{[ a_href 'http://lufs.sourceforge.net/lufs/','Linux Userland File System (LUFS)' ]}
moves the filesystem implementation to UNIX userland where the Microsoft
Windows filesystem is completely unarmed by Captive jail of chroot(2),
the other kernel coders would not investigate any problems if someone had used
the NTFS wrapper.</span><br />
It does not apply to this project due to the implemented
- @{[ a_href '#sandbox','filesystem separation' ]}.</p>
+ @{[ a_href 'Details.html.pl#sandbox','filesystem separation' ]}.</p>
HERE
<p>DOS based @{[ a_href 'http://www.gnu.org/licenses/gpl.html','GPL-2.0' ]}
read-write NTFS driver. Filesystem structures are reverse engineered in the
- way of @{[ a_href '#LinuxNTFScompet','Linux-NTFS Project' ]}. As it is not very
+ way of @{[ a_href 'Related.html.pl#LinuxNTFScompet','Linux-NTFS Project' ]}. As it is not very
actively maintained it reaches a lower level of
<span class="productname">NTFS</span> compatibility.</p>
a network file sharing through a VMware virtual network card.</p>
<p>You need @{[ '$299' ]} for this product and you need to
- give up your system security by running un@{[ a_href '#sandbox','sandbox' ]}ed
+ give up your system security by running un@{[ a_href 'Details.html.pl#sandbox','sandbox' ]}ed
closed-source program in your GNU/Linux.</p>
<a name="wine"><h2>@{[ a_href 'http://www.winehq.com/','Wine Project' ]}</h2></a>
'Mark Russinovich' ]}.
<p>I assume its execution falls completely
- @{[ a_href '#existing_emulation','out of scope' ]}
+ @{[ a_href 'Architecture.html.pl#existing_emulation','out of scope' ]}
of this project as it is W32 userland.</p>
<p>This possibility was not yet investigated in any way.</p>
git://git.jankratochvil.net / www.jankratochvil.net.git / commitdiff