# $Id$
# Captive project doc Architecture page Perl template.
# 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
# the Free Software Foundation; exactly version 2 of June 1991 is required
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


package project::captive::doc::Architecture;
require 5.6.0;	# at least 'use warnings;' but we need some 5.6.0+ modules anyway
our $VERSION=do { my @r=(q$Revision$=~/\d+/g); sprintf "%d.".("%03d"x$#r),@r; };
our $CVS_ID=q$Id$;
use strict;
use warnings;

use My::Web;


sub handler
{
	BEGIN { Wuse 'project::captive::doc::Macros'; }
project::captive::doc::Macros->init(
		"title"=>'Captive NTFS Developer Documentation: Architecture',
		"rel_prev"=>'About.pm',
		"rel_next"=>'Components.pm',
		);


print <<"HERE";


<h1>Architecture</h1>

	<p>The principle of the
	project lies in the glue between
	<span class="productname">Microsoft Windows NT</span> kernel space
	environment and $gnulinux user space process environment:</p>

	@{[ doc_img 'arch-W32','Microsoft Windows Subsystems Architecture' ]}
	@{[ doc_img 'arch-captive','Captive Subsystems Architecture' ]}
	
	<h2 id="existing_emulation">Existing Emulation Projects</h2>

		<p>There were two well-known $freespeech projects emulating W32 subsystems
		to reach the compatibility with various W32 components:
		$Wine and $ReactOS. Sad moment is that the goals of this project do not fit
		very well into any role in those two ones. Therefore this project went
		its own way of emulation:</p>

		<table border="1" class="margin-center">
			<caption>Emulation Projects Characteristics</caption>
			<tr>
				<th>@{[ a_href '#guestosnote','Guest-OS' ]}</th>
				<th>@{[ a_href '#hostosnote' ,'Host-OS'  ]}</th>
				<th>Implements</th>
				<th>W32 kernel library</th>
				</tr>
			<tr>
				<td>$Wine</td>
				<td>$gnulinux</td>
				<td>W32 user space</td>
				<td><span class="fname">ntdll.dll</span></td>
				</tr>
			<tr>
				<td>$ReactOS</td>
				<td><span class="constant">i386</span> hardware</td>
				<td>W32 kernel and user space</td>
				<td><span class="fname">ntoskrnl.exe</span></td>
				</tr>
			<tr style="height: 1ex;"><td colspan="4"></td></tr>
			<tr>
				<td>this project</td>
				<td>$gnulinux</td>
				<td>W32 kernel</td>
				<td><span class="fname">ntoskrnl.exe</span></td>
				</tr>
		</table>

		<dl>
			<dt id="guestosnote">Guest-OS</dt>
			<dd>@{[ a_href 'http://www.vmware.com/support/reference/common/glossary/#guestos','Guest OS' ]}:
				An operating system that runs inside a&nbsp;virtual machine.</dd>
			<dt id="hostosnote">Host  OS</dt>
			<dd>@{[ a_href 'http://www.vmware.com/support/reference/common/glossary/#hostos' ,'Host  OS' ]}:
				An operating system that runs on the host machine.</dd>
		</dl>

		<p>While $ReactOS provides the necessary W32 kernel subsystem emulation
		code we also need to run such @{[ a_href '#guestosnote','Guest-OS' ]} in the
		@{[ a_href '#hostosnote','Host-OS' ]} $gnulinux. Initially it was planned to
		extend $Wine with the W32 kernel space emulation functionality but
		fortunately <span class="author">Steven Edwards</span> pointed to the $ReactOS
		which better suits the needs of this project by its already implemented W32
		kernel space emulation.</p>

		<p>The <span id="reactos_nocare">original reasons</span> for developing
		$ReactOS still make no sense to the author of this project. Free
		implementation of W32 platform standalone running on the machine hardware
		is no longer free as most od the W32 applications are usually closed source
		and the user still looses its freedom on the application level anyway. Even
		in the case of available free applications there still remains the
		disadvantage of loosing the Host-OS platform availability if implemented in
		the $Wine style. For these ideology incompatibilities not much effort was
		made for acceptance the fixes and improvements of $ReactOS by this project.
		Moreover new functionality is not being implemented to the $ReactOS part
		but it is coded in Gnome style in the project specific source files
		place.</p>

		<p>The most serious problem of $ReactOS is its dependence on the direct
		<span class="constant">i386</span> hardware instead of some
		@{[ a_href '#hostosnote','Host-OS' ]} as required by the goals of this project.
		W32 is designed to be hardware-independent using its
		<span class="fname">hal.dll</span>. Unfortunately $ReactOS does not follow
		this design and thus there are needed various patches and replaces of its
		various parts and its hardware-dependent code. Despite it $ReactOS code
		base still made a big asset for this project.</p>

		<p>Some API functions are provided both by
		<span class="fname">ntdll.dll</span> and
		<span class="fname">ntoskrnl.exe</span> in W32.
		<span class="author">Casper Hornstrup</span> enlightened such functions
		calling conventions have to be differentiated as
		<span class="fname">ntdll.dll</span> lives in the user space (low address
		space &ndash; below <span class="constant">0x80000000</span>) and
		<span class="fname">ntoskrnl.exe</span> in the kernel space (high address
		space &ndash; above <span class="constant">0x80000000</span>). Although they
		contain slightly different set of symbols (functions)
		<span class="fname">ntdll.dll</span> still can be considered as a&nbsp;user
		space interface to the kernel space implementation by
		<span class="fname">ntoskrnl.exe</span>.</p>

		<p>Currently there are
		no plans to ever extend the project's crossplatformity beyond the
		<span class="constant">i386</span> processor
			(<span class="constant">i386</span> used here as
			@{[ a_href 'http://www.intel.com/','Intel' ]} architecture covering 32-bit
			processors compatible with <span class="constant">i386</span>,
			<span class="constant">i486</span>, ...).</p>


	<h2 id="law">Laws and Licensing Conditions</h2>

		<p>If you are an <span class="productname">authorized user</span> of
		<span class="productname">Microsoft Windows NT</span> the laws in some
		countries give you the right to fully handle the product in any way you
		want. Therefore you can disassemble the product even in the case you had
		to agree with the product license forbidding such disassembly as the
		country laws override any such license agreement.</p>

		<h3 id="law_servicepack">Microsoft Service Pack</h3>

			<p>Sometimes you may have the legal license for
			<span class="productname">Microsoft Windows NT</span>
			but for various technical reasons you do not have the media and/or
			installation ready at the place of intended use of this project.</p>

			<p>Fortunately <span class="productname">Microsoft</span> provides
			$freebeer update packages for its
			<span class="productname">Microsoft Windows</span> products called
			<span class="productname">Service Packs</span>; the latest one is
			<span class="productname">@{[ a_href 'http://www.microsoft.com/WindowsXP/pro/downloads/servicepacks/sp1/checkedbuild.asp','Microsoft Windows XP Service Pack 1a' ]}</span>.</p>

			<p>This downloadable file contains the full versions of the essential
			files needed for the current stage of this product:
			<span class="fname">ntfs.sys</span>
			and
			<span class="fname">ntoskrnl.exe</span>.
			It even contains
			<span class="fname">cdfs.sys</span> and
			<span class="fname">fastfat.sys</span> for testing purposes.</p>

			<p><span class="productname">Service Pack</span> also contains
			EULA (End User License Agreement) paper disallowing any use of
			<span class="productname">Service Pack</span> outside its original
			intentions. According to the laws of some countries you need to be
			<span class="productname">authorized user</span> of the
			<span class="productname">Microsoft Windows XP</span> product to be
			allowed to use the files contained in such
			<span class="productname">Service Pack</span> without the bindings of its
			EULA. Even the interpretation of such laws may vary.</p>

			<p>It would be a&nbsp;breach of the law by the project author to provide
			automatic (=hidden) functionality to download and extract the
			<span class="productname">Service Pack</span> files. On the other hand it
			is perfectly legal to ask user for his/her confirmation whether he/she is
			really the <span class="productname">authorized user</span> of
			<span class="productname">Microsoft Windows XP</span> product and
			download/extract the <span class="productname">Service Pack</span> files
			accordingly.</p>

			@{[ doc_img 'captive-install-acquire-ask','Microsoft Windows Drivers Acquire Affirmation' ]}


HERE


exit;
}
1;