project/captive/doc/Architecture.html.pl

   1 #! /usr/bin/perl
   2 #
   3 # $Id$
   4 # Captive project doc Architecture page Perl template.
   5 # Copyright (C) 2003 Jan Kratochvil <project-www.jankratochvil.net@jankratochvil.net>
   6 #
   7 # This program is free software; you can redistribute it and/or modify
   8 # it under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation; exactly version 2 of June 1991 is required
  10 #
  11 # This program is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program; if not, write to the Free Software
  18 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19
  20
  21 package project::captive::doc::Architecture;
  22 require 5.6.0;  # at least 'use warnings;' but we need some 5.6.0+ modules anyway
  23 our $VERSION=do { my @r=(q$Revision$=~/\d+/g); sprintf "%d.".("%03d"x$#r),@r; };
  24 our $CVS_ID=q$Id$;
  25 use strict;
  26 use warnings;
  27
  28 BEGIN{ open F,"Makefile"; our $top_dir=pop @{[split /\s/,(grep /^top_srcdir/,<F>)[0]]}; eval "use lib '$top_dir'"; close F; }
  29 use My::Web;
  30 require CGI;
  31 BEGIN { Wuse 'project::captive::doc::Macros'; }
  32
  33
  34 project::captive::doc::Macros->init(
  35                 "__PACKAGE__"=>__PACKAGE__,
  36                 "title"=>'Captive NTFS Developer Documentation: Architecture',
  37                 "rel_prev"=>'About.html.pl',
  38                 "rel_next"=>'Components.html.pl',
  39                 );
  40
  41
  42 print <<"HERE";
  43
  44
  45 <h1>Architecture</h1>
  46
  47         <p>The principle of the
  48         project lies in the glue between
  49         <span class="productname">Microsoft Windows NT</span> kernel space
  50         environment and $gnulinux user space process environment:</p>
  51
  52         @{[ doc_img 'arch-W32','Microsoft Windows Subsystems Architecture' ]}
  53         @{[ doc_img 'arch-captive','Captive Subsystems Architecture' ]}
  54
  55         <a name="existing_emulation"><h2>Existing Emulation Projects</h2></a>
  56
  57                 <p>There were two well-known $freespeech projects emulating W32 subsystems
  58                 to reach the compatibility with various W32 components:
  59                 $Wine and $ReactOS. Sad moment is that the goals of this project do not fit
  60                 very well into any role in those two ones. Therefore this project went
  61                 its own way of emulation:</p>
  62
  63                 <table align="center" border="1">
  64                         <tr>
  65                                 <th>@{[ a_href '#guestosnote','Guest-OS' ]}</th>
  66                                 <th>@{[ a_href '#hostosnote' ,'Host-OS'  ]}</th>
  67                                 <th>Implements</th>
  68                                 <th>W32 kernel library</th>
  69                                 </tr>
  70                         <tr>
  71                                 <td>$Wine</td>
  72                                 <td>$gnulinux</td>
  73                                 <td>W32 user space</td>
  74                                 <td><span class="fname">ntdll.dll</span></td>
  75                                 </tr>
  76                         <tr>
  77                                 <td>$ReactOS</td>
  78                                 <td><span class="constant">i386</span> hardware</td>
  79                                 <td>W32 kernel and user space</td>
  80                                 <td><span class="fname">ntoskrnl.exe</span></td>
  81                                 </tr>
  82                         <tr style="height: 1ex;"></tr>
  83                         <tr>
  84                                 <td>this project</td>
  85                                 <td>$gnulinux</td>
  86                                 <td>W32 kernel</td>
  87                                 <td><span class="fname">ntoskrnl.exe</span></td>
  88                                 </tr>
  89                         <caption>Emulation Projects Characteristics</caption>
  90                 </table>
  91
  92                 <dl>
  93                         <a name="guestosnote"><dt>Guest-OS</dt></a>
  94                         <dd>@{[ a_href 'http://www.vmware.com/support/reference/common/glossary/#guestos','Guest OS' ]}:
  95                                 An operating system that runs inside a&nbsp;virtual machine.</dd>
  96                         <a name="hostosnote" ><dt>Host  OS</dt></a>
  97                         <dd>@{[ a_href 'http://www.vmware.com/support/reference/common/glossary/#hostos' ,'Host  OS' ]}:
  98                                 An operating system that runs on the host machine.</dd>
  99                 </dl>
 100
 101                 <p>While $ReactOS provides the necessary W32 kernel subsystem emulation
 102                 code we also need to run such @{[ a_href '#guestosnote','Guest-OS' ]} in the
 103                 @{[ a_href '#hostosnote','Host-OS' ]} $gnulinux. Initially it was planned to
 104                 extend $Wine with the W32 kernel space emulation functionality but
 105                 fortunately <span class="author">Steven Edwards</span> pointed to the $ReactOS
 106                 which better suits the needs of this project by its already implemented W32
 107                 kernel space emulation.</p>
 108
 109                 <p>The <a name="reactos_nocare">original reasons</a> for developing
 110                 $ReactOS still make no sense to the author of this project. Free
 111                 implementation of W32 platform standalone running on the machine hardware
 112                 is no longer free as most od the W32 applications are usually closed source
 113                 and the user still looses its freedom on the application level anyway. Even
 114                 in the case of available free applications there still remains the
 115                 disadvantage of loosing the Host-OS platform availability if implemented in
 116                 the $Wine style. For these ideology incompatibilities not much effort was
 117                 made for acceptance the fixes and improvements of $ReactOS by this project.
 118                 Moreover new functionality is not being implemented to the $ReactOS part
 119                 but it is coded in Gnome style in the project specific source files
 120                 place.</p>
 121
 122                 <p>The most serious problem of $ReactOS is its dependence on the direct
 123                 <span class="constant">i386</span> hardware instead of some
 124                 @{[ a_href '#hostosnote','Host-OS' ]} as required by the goals of this project.
 125                 W32 is designed to be hardware-independent using its
 126                 <span class="fname">hal.dll</span>. Unfortunately $ReactOS does not follow
 127                 this design and thus there are needed various patches and replaces of its
 128                 various parts and its hardware-dependent code. Despite it $ReactOS code
 129                 base still made a big asset for this project.</p>
 130
 131
 132
 133
 134
 135                 <p>Some API functions are provided both by
 136                 <span class="fname">ntdll.dll</span> and
 137                 <span class="fname">ntoskrnl.exe</span> in W32.
 138                 <span class="author">Casper Hornstrup</span> enlightened such functions
 139                 calling conventions have to be differentiated as
 140                 <span class="fname">ntdll.dll</span> lives in the user space (low address
 141                 space &ndash; below <span class="constant">0x80000000</span>) and
 142                 <span class="fname">ntoskrnl.exe</span> in the kernel space (high address
 143                 space &ndash; above <span class="constant">0x80000000</span>). Although they
 144                 contain slightly different set of symbols (functions)
 145                 <span class="fname">ntdll.dll</span> still can be considered as a&nbsp;user
 146                 space interface to the kernel space implementation by
 147                 <span class="fname">ntoskrnl.exe</span>.</p>
 148
 149                 <p>Currently there are
 150                 no plans to ever extend the project's crossplatformity beyond the
 151                 <span class="constant">i386</span> processor
 152                         (<span class="constant">i386</span> used here as
 153                         @{[ a_href 'http://www.intel.com/','Intel' ]} architecture covering 32-bit
 154                         processors compatible with <span class="constant">i386</span>,
 155                         <span class="constant">i486</span>, ...).</p>
 156
 157
 158         <a name="law"><h2>Laws and Licensing Conditions</h2></a>
 159
 160                 <p>If you are an <span class="productname">authorized user</span> of
 161                 <span class="productname">Microsoft Windows NT</span> the laws in some
 162                 countries give you the right to fully handle the product in any way you
 163                 want. Therefore you can disassemble the product even in the case you had
 164                 to agree with the product license forbidding such disassembly as the
 165                 country laws override any such license agreement.</p>
 166
 167                 <a name="law_servicepack"><h3>Microsoft Service Pack</h3></a>
 168
 169                         <p>Sometimes you may have the legal license for
 170                         <span class="productname">Microsoft Windows NT</span>
 171                         but for various technical reasons you do not have the media and/or
 172                         installation ready at the place of intended use of this project.</p>
 173
 174                         <p>Fortunately <span class="productname">Microsoft</span> provides
 175                         $freebeer update packages for its
 176                         <span class="productname">Microsoft Windows</span> products called
 177                         <span class="productname">Service Packs</span>; the latest one is
 178                         <span class="productname">@{[ a_href 'http://www.microsoft.com/WindowsXP/pro/downloads/servicepacks/sp1/checkedbuild.asp','Microsoft Windows XP Service Pack 1a' ]}</span>.</p>
 179
 180                         <p>This downloadable file contains the full versions of the essential
 181                         files needed for the current stage of this product:
 182                         <span class="fname">ntfs.sys</span>
 183                         and
 184                         <span class="fname">ntoskrnl.exe</span>.
 185                         It even contains
 186                         <span class="fname">cdfs.sys</span> and
 187                         <span class="fname">fastfat.sys</span> for testing purposes.</p>
 188
 189                         <p><span class="productname">Service Pack</span> also contains
 190                         EULA (End User License Agreement) paper disallowing any use of
 191                         <span class="productname">Service Pack</span> outside its original
 192                         intentions. According to the laws of some countries you need to be
 193                         <span class="productname">authorized user</span> of the
 194                         <span class="productname">Microsoft Windows XP</span> product to be
 195                         allowed to use the files contained in such
 196                         <span class="productname">Service Pack</span> without the bindings of its
 197                         EULA. Even the interpretation of such laws may vary.</p>
 198
 199                         <p>It would be a&nbsp;breach of the law by the project author to provide
 200                         automatic (=hidden) functionality to download and extract the
 201                         <span class="productname">Service Pack</span> files. On the other hand it
 202                         is perfectly legal to ask user for his/her confirmation whether he/she is
 203                         really the <span class="productname">authorized user</span> of
 204                         <span class="productname">Microsoft Windows XP</span> product and
 205                         download/extract the <span class="productname">Service Pack</span> files
 206                         accordingly.</p>
 207
 208                         @{[ doc_img 'captive-install-acquire-ask','Microsoft Windows Drivers Acquire Affirmation' ]}
 209
 210
 211 HERE
 212
 213
 214 project::captive::doc::Macros->footer();