-#! /usr/bin/perl
-#
# $Id$
# Captive project doc Details 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
+{
+ BEGIN { Wuse 'project::captive::doc::Macros'; }
project::captive::doc::Macros->init(
"__PACKAGE__"=>__PACKAGE__,
"title"=>'Captive NTFS Developer Documentation: Implementation Details',
- "rel_prev"=>'CacheManager.html.pl',
- "rel_next"=>'APITypes.html.pl',
+ "rel_prev"=>'CacheManager.pm',
+ "rel_next"=>'APITypes.pm',
);
<h1>Implementation Details</h1>
- <a name="emulmeth"><h2>Choice of the Emulation Methods</h2></a>
+ <h2 id="emulmeth">Choice of the Emulation Methods</h2>
<p>The intent of the project was to get reliable read-write access to
<span class="productname">NTFS</span> partition. There are several possible
ways to achieve that:</p>
- <a name="emulmeth_vm"><h3>Virtualmachine Running the Original W32 Subsystem</h3></a>
+ <h3 id="emulmeth_vm">Virtualmachine Running the Original W32 Subsystem</h3>
<p>Creating virtual-hardware PC and running the original W32 binaries
including their boot-loader etc. Disk device access would be passed as
requirement of fully installed
<span class="productname">Microsoft Windows NT</span> product.</p>
- <a name="method_ntoskrnl"><h3>"ntoskrnl.exe" Inside Virtual Address Space</h3></a>
+ <h3 id="method_ntoskrnl">"ntoskrnl.exe" Inside Virtual Address Space</h3>
<p>This solution was chosen by the project. Binary filesystem driver and
also <span class="fname">ntoskrnl.exe</span> binary file are required.
emulation, therefore such instructions must be trapped and emulated/ignored
from case to case.</p>
- <p>Also the <a name="init_ntoskrnl">initialization code of <span
- class="fname">ntoskrnl.exe</span></a> is not executed by this project since
+ <p>Also the <span id="init_ntoskrnl">initialization code of <span
+ class="fname">ntoskrnl.exe</span></span> is not executed by this project since
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 'APITypes.html.pl#functype_wrap','API functions wrapping' ]}.
+ @{[ a_href 'APITypes.pm#functype_wrap','API functions wrapping' ]}.</p>
<p>pros: Lightweight, easier to debug.</p>
<span class="fname">ntoskrnl.exe</span> parts, missing documentation needed
for the implementation.</p>
- <a name="emulmeth_fs"><h3>Filesystem Driver Inside Virtual Address Space</h3></a>
+ <h3 id="emulmeth_fs">Filesystem Driver Inside Virtual Address Space</h3>
- <p>Unlike @{[ a_href 'Details.html.pl#method_ntoskrnl','previous method' ]} here we do not use
+ <p>Unlike @{[ a_href 'Details.pm#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
+ W32 is <span id="native_ntoskrnl">emulated from the project source
+ files</span>. <span class="fname">cdfs.sys</span> driver was successfuly ran
in this manner in the former versions of this project but the possibility
to run without <span class="fname">ntoskrnl.exe</span> was dropped since it
had no licensing gains (you need the original
<span class="fname">ntoskrnl.exe</span>, its missing documentation.</p>
- <a name="apichoice"><h2>API Function Implementation Choices</h2></a>
+ <h2 id="apichoice">API Function Implementation Choices</h2>
<p>During the initial point of the project development all the API
functions were defined as unimplemented, of course. Any call of such
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 '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' ]}
+ @{[ a_href 'APITypes.pm#functype_pass','Direct pass to original <span class="fname">ntoskrnl.exe</span>' ]},
+ @{[ a_href 'APITypes.pm#functype_wrap','Wrap of the original <span class="fname">ntoskrnl.exe</span> function' ]},
+ @{[ a_href 'APITypes.pm#functype_native_reactos','Native implementation – $ReactOS' ]},
+ @{[ a_href 'APITypes.pm#functype_native_wine','Native implementation – $Wine' ]}
or
- @{[ a_href 'APITypes.html.pl#functype_native_libcaptive','Native implementation – project specific' ]}.
- <!-- a_href 'APITypes.html.pl#functype_undef','Undefined function' -->
+ @{[ a_href 'APITypes.pm#functype_native_libcaptive','Native implementation – project specific' ]}.
+ <!-- a_href 'APITypes.pm#functype_undef','Undefined function' -->
+ </p>
- <a name="sandbox"><h2>Sandboxing of W32 Filesystem</h2></a>
+ <h2 id="sandbox">Sandboxing of W32 Filesystem</h2>
<p>The emulated W32 environment running the original W32 filesystem driver
is separated from the rest of UNIX OS. It achieves the following goals:</p>
peers.</p>
- <a name="patched"><h2>"patched" vs. "unpatched" Libraries</h2></a>
+ <h2 id="patched">"patched" vs. "unpatched" Libraries</h2>
<p>Library is called <span class="constant">patched</span> if we require
loading its original binary code file. Project needs to patch it to be able
<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 'APITypes.html.pl#functype_native','the native implementations' ]} of this project.
+ @{[ a_href 'APITypes.pm#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
<a href="#native_ntoskrnl">native implementation of
<span class="fname">ntoskrnl.exe</span></a> but it no longer applies.</p>
- <a name="mman"><h2>Memory Management</h2></a>
+ <h2 id="mman">Memory Management</h2>
<p>Original <span class="productname">Microsoft Windows NT</span>
architecture uses two address space areas – user space and kernel space.
moving operations between W32 kernel space and W32 user space memory areas
(such as <span class="function">MmSafeCopyToUser()</span>).</p>
- <a name="unicode"><h2>Unicode Strings and Characters</h2></a>
+ <h2 id="unicode">Unicode Strings and Characters</h2>
<p>W32 platform uses 16-bit type <span class="type">wchar_t</span> while $gnulinux uses a
32-bit one. This can be problem during GCC (GNU C Compiler)
</li>
</ul>
- <a name="binfmt"><h2>Supported Binary Formats</h2></a>
+ <h2 id="binfmt">Supported Binary Formats</h2>
<p>The native W32 binary format is identified as
<span class="constant">PE-32</span> (Portable Executable 32-bit), such
<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.html.pl#calltype_cdecl','cdecl call type semantics' ]}.
- @{[ a_href 'APITypes.html.pl#functype_native','Native function implementations' ]} do not need
+ UNIX @{[ a_href 'CallType.pm#calltype_cdecl','cdecl call type semantics' ]}.
+ @{[ a_href 'APITypes.pm#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
original <span class="constant">PE-32</span> binary file.</p>
- <a name="mounted_one"><h2>At Most One Mounted Filesystem</h2></a>
+ <h2 id="mounted_one">At Most One Mounted Filesystem</h2>
<p>The project technically supports only one (exactly one...) mounted
filesystem device and only one filesystem driver. There is nothing
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 'Details.html.pl#sandbox','CORBA sandbox interface' ]}. This sandboxing
+ @{[ a_href 'Details.pm#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 'Details.html.pl#sandbox','CORBA sandbox interface' ]} control master.</p>
+ @{[ a_href 'Details.pm#sandbox','CORBA sandbox interface' ]} control master.</p>
<p>Each sandbox executing the untrusted W32 binary filesystem driver code
is connected through its
- @{[ a_href 'Details.html.pl#sandbox','CORBA sandbox interface' ]} at the point of upper
+ @{[ a_href 'Details.pm#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
messages/warnings/errors out of the sandbox to the user.</p>
- <a name="synchronous"><h2>Multithreading and Multiple Processors</h2></a>
+ <h2 id="synchronous">Multithreading and Multiple Processors</h2>
<p>W32 platform stands on its thorough architecture parallelism. It
must lock all its objects to maintain coherence in presence of
<span class="function">g_idle_add_full()</span> with
<span class="function">g_main_context_iteration()</span> called during
<span class="function">KeWaitForSingleObject()</span>.</p>
- Since there is a possibility a real W32 parallel threading would
+ <p>Since there is a possibility a real W32 parallel threading would
be yet needed in the future all the code that would be hit by W32
multithreading capability is marked by
<span class="constant">TODO:thread</span> comment.</p>
is done during cleanup of the project's execution by
<span class="function">captive_shutdown()</span>.</p>
- <a name="paranoia"><h2>Paranoia Checks</h2></a>
+ <h2 id="paranoia">Paranoia Checks</h2>
<p>A general approach of software projects development is to implement
many internal sanity checks during the development stage but to produce the
has to be fixed, of course.</p>
- <a name="logfile"><h2>STATUS_LOG_FILE_FULL</h2></a>
+ <h2 id="logfile">STATUS_LOG_FILE_FULL</h2>
<p>After writing approx. 1MB of data on NTFS test partition NTFS driver
returns for any further write requests
- <span class="constant">STATUS_LOG_FILE_FULL</status> error code.
+ <span class="constant">STATUS_LOG_FILE_FULL</span> error code.
Apparently it is caused by the fact this project is
- @{[ a_href 'Details.html.pl#synchronous','single-threaded' ]} and it ignores the spawn
+ @{[ a_href 'Details.pm#synchronous','single-threaded' ]} and it ignores the spawn
of parallel journalling thread during <span class="fname">ntfs.sys</span>
initialization.</p>
<p>Fortunately <span class="fname">ntfs.sys</span> will clear its
journalling log file during filesystem unmount. This project will therefore
- remount the volume if <span class="constant">STATUS_LOG_FILE_FULL</status>
+ remount the volume if <span class="constant">STATUS_LOG_FILE_FULL</span>
is detected to workaround missing journalling thread.</p>
<p>Similiar behaviour can be seen during write of compressed files —
during the final filesystem unmount.</p>
<p>For these reasons it was mandatory to support
- @{[ a_href 'Details.html.pl#parent_connector','transparent volume remounting' ]}.</p>
+ @{[ a_href 'Details.pm#parent_connector','transparent volume remounting' ]}.</p>
- <a name="parent_connector"><h2><span class="constant">ParentConnector</span> volume remounter</h2></a>
+ <h2 id="parent_connector"><span class="constant">ParentConnector</span> volume remounter</h2>
<p>The sandbox master component of this project has control of restarting
its sandbox slaves containing the W32 filesystem. Target goal of
HERE
-project::captive::doc::Macros->footer();
+exit;
+}
+1;
git://git.jankratochvil.net / www.jankratochvil.net.git / blobdiff