doc update
authorshort <>
Thu, 2 Oct 2003 11:43:34 +0000 (11:43 +0000)
committershort <>
Thu, 2 Oct 2003 11:43:34 +0000 (11:43 +0000)
project/captive/Preview.html.pl
project/captive/doc/Index.html.pl
project/captive/doc/dia/TraceFS.dia [new file with mode: 0644]
project/captive/doc/dia/TraceFS.gif [new file with mode: 0644]
project/captive/doc/dia/TraceFS.png [new file with mode: 0644]
project/captive/doc/dia/cache-manager.dia
project/captive/doc/dia/cache-manager.gif
project/captive/doc/dia/cache-manager.png

index 2a37114..a4c8248 100755 (executable)
@@ -47,6 +47,7 @@ print img("doc/fig/functype_patched_wrap_fromw32","Wrapping of Call from W32 Cod
 print img("doc/ntdebug-windbg-boot","Windows NT Remote Kernel Debug Mode Boot");
 print img("captive-install-acquire","Captive Microsoft Windows Drivers Acquire");
 print img("doc/dia/arch-all","Captive Components Architecture");
+print img("doc/dia/TraceFS","TraceFS Hooking");
 
 
 My::Web->footer();
index 5782ec1..2f0b691 100755 (executable)
@@ -61,11 +61,12 @@ my($img_base,$caption)=@_;
        return $r;
 }
 
-sub captive_srcfile ($)
+sub captive_srcfile ($;$)
 {
-my($filename)=@_;
+my($filename,$text)=@_;
 
-       a_href 'http://cvs.jankratochvil.net/viewcvs/*checkout*/priv/captive/'.$filename.'?rev=HEAD',$filename;
+       a_href 'http://cvs.jankratochvil.net/viewcvs/*checkout*/priv/captive/'.$filename.'?rev=HEAD',
+                       ($text || $filename);
 }
 
 my $freespeech=a_href 'http://www.gnu.org/philosophy/free-sw.html','Free';
@@ -85,71 +86,99 @@ my $GnomeVFSmodule=productname 'http://developer.gnome.org/doc/API/gnome-vfs/mod
 my $gnulinux='GNU/Linux';
 
 
-# FIXME:
-# Compatibility with NT4 etc. - just legal reasons.
-
-# FIXME:
-# name="cache_manager" Cache Manager
-
-# FIXME:
-# name="sandbox"
+print <<"HERE";
 
 
-print <<"HERE";
+<h1>About</h1>
+
+       <h2>Reasons for the Implementation</h2>
+
+               <p>Currently there is no possibility to any of the available $freespeech
+                       ($freespeech used in the following text in the meaning of
+                       &quot;@{[ a_href 'http://www.gnu.org/philosophy/free-sw.html','free as in speech' ]}&quot;)
+               operating systems to reliably write to the most common disk partition
+               filesystem type &ndash; <span class="productname">Microsoft NTFS</span>. It would
+               be already supported a long time ago but there is no proper documentation of
+               <span class="productname">NTFS</span> filesystem data structures available.
+               Since <span class="productname">Microsoft</span> corporation continues in its
+               propagation of <span class="productname">Microsoft Windows NT</span>
+                       (<span class="productname">NT</span> identifier used in the following text
+                       applies to all the products of <span class="productname">Microsoft</span>
+                       <span class="productname">NT</span> series such as
+                       <span class="productname">NT&nbsp;4.0</span>,
+                       <span class="productname">2000</span> as NT-5.0
+                       and
+                       <span class="productname">XP</span> as NT-5.1.)
+               based operating systems <span class="productname">NTFS</span> is the default
+               disk file system type for vendor preinstalled <span class="productname">Microsoft Windows</span>.
+
+               <p>Unfortunately the <span class="productname">NTFS</span> filesystem has too
+               complex data structure to allow a complete reverse enginnering process in
+               reasonable time. Currently available $freespeech solutions such as $LinuxNTFS
+               filesystem have already implemented reliable reverse
+               engineered read-only access. However <a name="reliability">reliabile</a>
+               read-write part of the access would require much better
+               knowledge of the <span class="productname">NTFS</span> data structures.
+               Currently only rewriting of already existing file data blocks is supported
+               by $LinuxNTFS &mdash; no file creation, no file deletion, no directory operations etc.
+               Also any future versions of <span class="productname">NTFS</span> filesystem
+               would require another major reverse engineering effort.</p>
+
+
+       <h2>Challenges of the Project</h2>
+
+               <p>The <a name="NTFSgoal">ultimate goal</a> of this project is definitely the
+               free implementation of @{[ a_href '#reliability','reliable' ]} read-write <span
+               class="productname">NTFS</span> filesystem driver. This project chose to
+               solve this problem in the style of $Wine project by using the original binary
+               <span class="fname">ntfs.sys</span> and emulating all the required layers of
+               <span class="productname">Microsoft Windows NT</span> for it.</p>
+
+               <p>Unfortunately this effort is tainted by only partial and generally
+               insufficient documentation of API between filesystem driver
+               (<span class="fname">ntfs.sys</span>) and the
+               <span class="productname">Microsoft Windows NT</span>
+               (&quot;@{[ a_href 'http://mail.gnu.org/archive/html/libtool/2000-09/msg00000.html','W32' ]}&quot;
+               in the following text) kernel <span class="fname">ntoskrnl.exe</span>. Note
+               that this API is a different than the one being used in the $Wine project
+               since <span class="productname">Wine</span> implements only the user space
+               part of W32.</p>
+
+
+       <h2>Microsoft Windows Versions Compatibility</h2>
+
+               <p>Currently this project supports only driver files of
+               <span class="productname">Microsoft Windows XP</span> (NT-5.1)
+               in the following releases:</p>
 
+               <ul>
+                       <li>Microsoft Windows XP Service Pack 1a Checked Build U.S.</li>
+                       <li>Microsoft Windows XP Service Pack 1a Free Build U.S.</li>
+                       <li>Microsoft Windows XP (No Service Pack) Checked Build U.S.</li>
+                       <li>Microsoft Windows XP (No Service Pack) Free Build U.S.</li>
+               </ul>
 
-<h1>Reasons for the Implementation</h1>
-
-       <p>Currently there is no possibility to any of the available $freespeech
-               ($freespeech used in the following text in the meaning of
-               &quot;@{[ a_href 'http://www.gnu.org/philosophy/free-sw.html','free as in speech' ]}&quot;)
-       operating systems to reliably write to the most common disk partition
-       filesystem type &ndash; <span class="productname">Microsoft NTFS</span>. It would
-       be already supported a long time ago but there is no proper documentation of
-       <span class="productname">NTFS</span> filesystem data structures available.
-       Since <span class="productname">Microsoft</span> corporation continues in its
-       propagation of <span class="productname">Microsoft Windows NT</span>
-               (<span class="productname">NT</span> identifier used in the following text
-               applies to all the products of <span class="productname">Microsoft</span>
-               <span class="productname">NT</span> series such as
-               <span class="productname">NT&nbsp;4.0</span>,
-               <span class="productname">2000</span> as NT-5.0
-               and
-               <span class="productname">XP</span> as NT-5.1.)
-       based operating systems <span class="productname">NTFS</span> is the default
-       disk file system type for vendor preinstalled <span class="productname">Microsoft Windows</span>.
-
-       <p>Unfortunately the <span class="productname">NTFS</span> filesystem has too
-       complex data structure to allow a complete reverse enginnering process in
-       reasonable time. Currently available $freespeech solutions such as $LinuxNTFS
-       filesystem have already implemented reliable reverse
-       engineered read-only access. However <a name="reliability">reliabile</a>
-       read-write part of the access would require much better
-       knowledge of the <span class="productname">NTFS</span> data structures.
-       Currently only rewriting of already existing file data blocks is supported
-       by $LinuxNTFS &mdash; no file creation, no file deletion, no directory operations etc.
-       Also any future versions of <span class="productname">NTFS</span> filesystem
-       would require another major reverse engineering effort.</p>
-
-
-<h1>Challenges of the Project</h1>
-
-       <p>The <a name="NTFSgoal">ultimate goal</a> of this project is definitely the
-       free implementation of @{[ a_href '#reliability','reliable' ]} read-write <span
-       class="productname">NTFS</span> filesystem driver. This project chose to
-       solve this problem in the style of $Wine project by using the original binary
-       <span class="fname">ntfs.sys</span> and emulating all the required layers of
-       <span class="productname">Microsoft Windows NT</span> for it.</p>
-
-       <p>Unfortunately this effort is tainted by only partial and generally
-       insufficient documentation of API between filesystem driver
-       (<span class="fname">ntfs.sys</span>) and the
-       <span class="productname">Microsoft Windows NT</span>
-       (&quot;@{[ a_href 'http://mail.gnu.org/archive/html/libtool/2000-09/msg00000.html','W32' ]}&quot;
-       in the following text) kernel <span class="fname">ntoskrnl.exe</span>. Note
-       that this API is a different than the one being used in the $Wine project
-       since <span class="productname">Wine</span> implements only the user space
-       part of W32.</p>
+               <p>The latest list of supported driver files can be found in:
+               @{[ captive_srcfile 'src/install/acquire/w32-mod-id.captivemodid.xml' ]}</p>
+
+               <p>Microsoft Windows NTFS filesystem driver is capable of accessing even
+               the older formats of the filesystem. Porting to Microsoft Windows 2003
+               Server is expected to be done soon. There can be also a danger of Microsoft
+               Windows upgrading NTFS disk filesystem where you would no longer be able
+               to access your NTFS disk by your original
+               <span class="productname">Microsoft Windows</span> version.
+               This upgrade does not happen as it occurs only during complete CD-ROM
+               Microsoft Windows system installation &ndash; such operation is not performed
+               by this project.</p>
+
+               <p>There is no problem technically obtaining the needed driver files of
+               <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
+               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>
 
 
 <h1>Architecture</h1>
@@ -405,7 +434,7 @@ print <<"HERE";
                <span class="fname">.so</span> file for the production version of the
                original <span class="constant">PE-32</span> binary file.</p>
 
-       <h2>Reverse Engineering</h2>
+       <a name="reverse"><h2>Reverse Engineering</h2></a>
 
                <p>This project has no intentions to reverse engineer and document the
                filesystem data structures themselves since they are being encapsulated by
@@ -464,7 +493,7 @@ print <<"HERE";
                                <p>PDB file found at '.\\FILENAME.pdb'</p>
                        </blockquote>
 
-               <h3><span class="productname">WinDbg</span> Windows NT kernel debugging</h3>
+               <a name="WinDbg"><h3><span class="productname">WinDbg</span> Windows NT kernel debugging</h3></a>
 
                        <p><span class="productname">WinDbg</span> is downloadable from:
                        @{[ a_href 'http://www.microsoft.com/whdc/ddk/debugging/installx86.mspx' ]}</p>
@@ -604,8 +633,7 @@ print <<"HERE";
                various methods described in this document.
                The &quot;<span class="constant">libcaptive</span>&quot; box cannot be
                further dissected as it is just an implementation of a&nbsp;set of
-               @{[ a_href 'http://cvs.jankratochvil.net/viewcvs/*checkout*/priv/captive/src/libcaptive/ke/exports.captivesym?rev=HEAD',
-                               'API functions' ]}.
+               @{[ captive_srcfile 'src/libcaptive/ke/exports.captivesym','API functions' ]}.
                It could be separated to several subsystems such as the
                @{[ a_href '#cache_manager','Cache Manager' ]},
                Memory Manager, Object Manager, Runtime Library, I/O&nbsp;Manager
@@ -668,8 +696,7 @@ print <<"HERE";
                due to @{[ a_href '#log_file_full','NTFS log file full' ]}.
 
                Now we need to transparently
-               @{[ a_href 'http://cvs.jankratochvil.net/viewcvs/*checkout*/priv/captive/src/libcaptive/sandbox/sandbox.idl?rev=HEAD',
-                               'connect' ]}
+               @{[ 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.
 
@@ -733,8 +760,7 @@ print <<"HERE";
                the W32 filesystem driver</a>.</p>
 
                <p>@{[ a_href '#sandbox','CORBA/ORBit' ]} hits us again &ndash; we need to
-               @{[ a_href 'http://cvs.jankratochvil.net/viewcvs/*checkout*/priv/captive/src/libcaptive/sandbox/sandbox.idl?rev=HEAD',
-                               'translate' ]}
+               @{[ 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>
 
@@ -863,6 +889,42 @@ print <<"HERE";
                messages/warnings/errors out of the sandbox to the user.</p>
 
 
+       <a name="sandbox"><h2>Sandboxing of W32 filesystem</h2></a>
+
+               <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>
+
+               <ul>
+                       <li><b>Restartable</b>: W32 driver can be restartde in clean state if it crashed</li>
+                       <li><b>Secure</b>: Malicious W32 code cannot affect the security of UNIX OS</li>
+                       <li><b>Stable</b>: Buggy W32 cannot crash any part of UNIX OS</li>
+               </ul>
+
+               <p>Sandboxing is provided with the following attributes:</p>
+               
+               <ul>
+                       <li>standalone UNIX process with separate memory space</li>
+                       <li>chroot(2) in empty directory to prevent any UNIX OS filesystem access</li>
+                       <li>setuid(2) to own user/group to prevent interaction with UNIX processes</li>
+                       <li>setrlimit(2) to limit system resources available for W32 environment</li>
+                       <li>the only connection with the UNIX OS by CORBA/ORBit RPC</li>
+               </ul>
+
+               <p>This security is almost the same as provided by
+               emulated virtual machines such as
+               @{[ a_href 'http://www.vmware.com/solutions/security.html','VMware' ]}.</p>
+
+               @{[ doc_img 'dia/inheritance','Sandboxing Scheme' ]}
+
+               <p>Project can be also used in non-sandboxed mode by
+               <span class="command">--no-sandbox</span> option as it is easier to debug
+               without CORBA/ORBit RPC. In this case the
+               <span class="type">DirectorySlave</span>/<span class="type">FileSlave</span>
+               options are used directly instead of their
+               <span class="type">DirectoryParent</span>/<span class="type">FileParent</span>
+               peers.</p>
+
+
 <h1>Choice of the Emulation Methods</h1>
 
        <p>The intent of the project was to get reliable read-write access to
@@ -933,6 +995,259 @@ print <<"HERE";
 
 <h1>Implementation Details</h1>
 
+       <a name="cache_manager"><h2>NT Cache Manager</h2></a>
+
+               <p>Although there exist some 3rd party documents about
+               <span class="productname">NT Cache Manager</span> W32 subsystem such as
+               <span class="productname">@{[ a_href 'http://www.osr.com/ntinsider/1996/cacheman.htm',
+                               'The NT Cache Manager Description' ]}</span> or
+               <span class="productname">@{[ a_href 'http://www.winntmag.com/Articles/Print.cfm?ArticleID=3864',
+                               'Learn About NT'."'".'s&nbsp;File-system Cache' ]}</span>
+               they are definitely insufficient for compatible
+               <span class="productname">NT Cache Manager</span> reimplementation.</p>
+
+               <p><span class="productname">NT Cache Manager</span> is about mapping
+               filesystem objects such as regular file data, filesystem bitmap or
+               journalling zone (log file). It is also being used by the filesystem for
+               mapping of virtual volume files representing the whole underlying
+               filesystem device.</p>
+
+               <p>The original W32 <span class="productname">NT Cache Manager</span>
+               is much more complicated as it must coordinate its effort with
+               other W32 subsystems like mapping of executable files
+               (<span class="type">ImageSectionObject</span>), insufficient system
+               resources from <span class="productname">NT Memory Manager</span>
+               or general effort to perform caching features for system performance.</p>
+               <span class="productname">NT Cache Manager</span> of this project has much
+               simpler goal - it just needs to provide compatible
+               <span class="productname">NT Cache Manager</span> functionality while
+               the other goals of its W32 counterpart are left to be successfuly handled
+               by UNIX OS in much more efficient way.</p>
+
+               @{[ doc_img 'dia/cache-manager',
+                               '<span class="productname">NT Cache Manager</span> Architecture' ]}
+
+               <p>Cache Manager objects are always bound to
+               <span class="type">FCB</span> (File Control Block).
+               <span class="type">FileObject</span> (or its associated
+               <span class="type">HANDLE</span>) serve only as reference
+               to <span class="type">FCB</span> and there can be multiple
+               <span class="type">FileObject</span>/<span class="type">HANDLE</span>
+               items for one <span class="type">FCB</span>. It is a bit misleading
+               you must use <span class="type">FileObject</span> pointer while calling
+               most of the Cache Manager functions.</p>
+
+               <p>Before using any other Cache Manager functions you must first call
+               <span class="function">CcInitializeCacheMap()</span>. You must give the
+               maximum mapped object offset. Each mapped object byte must have at most one
+               mapped memory location - no shared pages are allowed. Also any subsequent
+               mapping request is expected to be mapped into continuous memory region.
+               It implies you must reserve the memory region for possible future mapping
+               during the initial <span class="function">CcInitializeCacheMap()</span>
+               moment sized according to the given maximum mapped object offset. 
+               This is the approach currently implemented by this project although it
+               cannot be used for 3rd party <span class="fname">ext2fsd.sys</span>
+               driver as it initialized Cache Manager by the whole media device size
+               and it surprisingly succeeds for original
+               <span class="productname">Microsoft Windows</span> 
+               <span class="productname">Cache Manager</span>.
+               I expect the space reservation should be postponed to the first mapping
+               request and expect no multiple mappings will be done in the case
+               of memory-exceeding <span class="function">CcInitializeCacheMap()</span>
+               reservation request. <span class="function">CcSetFileSizes()</span>
+               changing the reserved memory area size may assume no existing Map
+               or Pin mappings exist.</p>
+
+               <p><span class="type">PCACHE_MANAGER_CALLBACKS</type> argument can be
+               safely ignored:</p>
+
+               <dl>
+                       <dt><span class="function">AcquireForReadAhead()</span>/<span class="function">ReleaseFromReadAhead()</span></dt>
+                       <dd>
+                               <p>As any readahead functionality is optional these entries are
+                               never used by Cache Manager implementation of this project.</p>
+                       </dd>
+
+                       <dt><span class="function">AcquireForLazyWrite()</span>/<span class="function">ReleaseFromLazyWrite()</span></dt>
+                       <dd>
+                               <p>Even the write-behind functionality is optional for Cache Manager.
+                               It is being done in asynchronous way in the original
+                               <span class="productname">Microsoft Windows</span>
+                               <span class="productname">Cache Manager</span>.
+                               implementation and it is ignored by Cache Manager implementation of
+                               this project.</p>
+
+                               <p>Cache Manager does not need to write any data if not explicitely
+                               requested by the driver. It is even expected to silently drop any
+                               pending dirty data blocks during filesystem shutdown.
+                               Forced dirty block write by function
+                               <span class="function">CcFlushCache()</span> should be written without
+                               any wrapping surrounding
+                               <span class="function">AcquireForLazyWrite()</span>/<span class="function">ReleaseFromLazyWrite()</span>
+                               pair.</p>
+                       </dd>
+               </dl>
+
+               <p><span class="function">CcUninitializeCacheMap()</span> is just
+               a suggestion for Cache Manager that driver will no longer reference
+               given <span class="type">SharedCacheMap</span>. The uninitialization
+               can be postponed to any later moment in original 
+               <span class="productname">Microsoft Windows</span> 
+               <span class="productname">Cache Manager</span>
+               as it may be locked by existing
+               <span class="type">ImageSectionObject</span>
+               of some file being executed etc.
+               <a name="sharedcachemap_leak">It is fatal to destroy
+               <span class="type">SharedCacheMap</span></a>
+               in the moment you see no other
+               references to it as the driver will access it for some moment
+               even after <span class="function">CcUninitializeCacheMap()</span>.
+               I am not sure if it is a bug of the driver or whether there are some rules
+               how long after <span class="function">CcUninitializeCacheMap()</span>
+               completion given <span class="type">SharedCacheMap</span> still exists.
+               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>
+
+               <p>There exist Map and Pin type objects for each
+               <span class="type">SharedCacheMap</span> although they look very similiar.
+               Only these objects give you access to any memory data
+               &mdash; <span class="type">SharedCacheMap</span> only reserved the space
+               to ensure continuous mapping of the forthcoming mappings but it did not map
+               any data into it.</p>
+
+               <p>Mapping of 'new' Map or Pin will create the new object only in the case
+               no such mapping exists now. Otherwise you will just get the reference to
+               the existing object with increased usecount.</p>
+
+               <dl>
+                       <dt>Map</dt>
+                       <dd>
+                               <p>Map mapping is always at most one for each
+                               <span class="type">SharedCacheMap</span>. Base offset/length of such
+                               mapping have no meaning as there can be only single Map.</p>
+
+                               <p>Apparently Map size can be arbitrary long according
+                               to its <span class="type">SharedCacheMap</span> reserved space.</p>
+
+                               <p>You cannot modify the memory mapped by Map in any way.
+                               As it is the same memory area (address) as the pages used by Pin
+                               objects you always access the last modified version by possible
+                               Pin of the same page.</p>
+                       </dd>
+
+                       <dt>Pin</dt>
+                       <dd>
+                               <p>Pin mapping always represents just one physical page
+                               (<span class="constant">PAGE_SIZE</span> &nspan; 4096 for i386).
+                               Its base offset/length can be safely extended to be aligned to the
+                               requested page.</p>
+
+                               <p>Pin can have associated pair of oldest and newest
+                               <span class="type>LSN</span> (Linear Sequence Number). It can be
+                               set by <span class="function">CcSetDirtyPinnedData()</span>
+                               and Cache Manager always tracks the lowest and highest
+                               reported <span class="type>LSN</span> for each page.
+                               <span class="type>LSN</span> is assumed to be
+                               <span class="constant">0</span> if not set.</p>
+
+                               <p>Any existing Pin mapping will be reused for further mappings
+                               as long as it is not ThreadOwned. In the moment you use
+                               <span class="function">CcSetBcbOwnerPointer()</span> you will detach
+                               the associated Pin pages from its
+                               <span class="type">SharedCacheMap</span>.
+                               Although they will further act as valid Pin mappings they will be no
+                               longer reused during new Pin mapping of the same page.
+                               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
+                               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
+                               mappings of the same page exist.</p>
+                       </dd>
+               </dl>
+
+               <p>Only the pages not yet present in the memory must be read from the disk.
+               You must not read any pages you do not need to as the driver does not
+               expect it and it would corrupt its data buffers.</p>
+
+               <p>Cache Manager of this project will destroy Pin or Map mappings after
+               their last unreferencing (in opposite of
+               @{[ a_href 'sharedcachemap_leak','leaked <span class="type">SharedCacheMap</span>' ]}).
+               Despite it any dirty pages may still be held as the pages
+               (including their <span class="type>LSN</span>s) are cached associated
+               with <span class="type">SharedCacheMap</span>. It may be also possible
+               original <span class="productname">Microsoft Windows</span> 
+               <span class="productname">Cache Manager</span>
+               postpones Pin mapping destroy to later time but it does not matter.</p>
+
+
+               <h3>TraceFS NT Cache Manager Tracer</h3>
+
+                       <p>@{[ a_href '#cache_manager','Cache Manager behaviour' ]} would be hard
+                       to analyze just by @{[ a_href '#reverse','reverse engineering' ]} as it
+                       is pretty complicated code cooperating with many other W32 kernel
+                       subsystems. It was chosen as easier way to trace it instead and validate
+                       all the Cache Manager assumptions by Cache Manager simulator.</p>
+
+                       @{[ doc_img 'dia/TraceFS','TraceFS Hooking' ]}
+
+                       <p>You must prepare your driver to be hooked
+                       (<span class="fname">ntfs.sys</span> in this case):</p>
+
+                       src/TraceFS/hookfs.pl
+                       <blockquote class="command">
+                               <p>@{[ captive_srcfile './src/TraceFS/hookfs.pl' ]} ntfs.sys ./src/TraceFS/TraceFS-W32/TraceFS.sys &gt;hooked/ntfs.sys</p>
+                       </blockquote>
+
+                       <p>This <span class="fname">hooked/ntfs.sys</span> file must be replaced
+                       in the <span class="fname">%System32%\\drivers</span> directory.
+                       Beware as
+                       <span class="productname">Microsoft Windows</span>
+                       has many backups of these system files such as
+                       <span class="fname">%System32%\\dllcache</span> &mdash; delete them
+                       all!</p>
+
+                       <p>You also need to install
+                       <span class="fname">./src/TraceFS/TraceFS-W32/TraceFS.sys</span>
+                       into <span class="fname">%System32%\\drivers</span> directory
+                       and import <span class="fname">TraceFS/TraceFS-W32/TraceFS.reg</span>
+                       registry file to initialize the debug driver during system boot.</p>
+
+                       <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>
+
+                       @{[ doc_img 'ntdebug-windbg-boot','Successfuly connected <span class="productname">WinDbg</span>' ]}
+
+                       <p>The resulting trace file should be processed by
+                       @{[ captive_srcfile './src/TraceFS/checktrace.pl' ]} Perl Cache Manager
+                       implementation to validate its assumptions about Cache Manager behaviour.
+                       Any seen incompatibilies will be reported &mdash; your target is to reach
+                       as few error messages as possible.</p>
+
+
+                       <h4>TraceFS for general API tracing</h4>
+
+                       <p>Although TraceFS was up to now used only for tracing of
+                       <span class="productname">NT Cache Manager</span> it can be easily
+                       used ever for any other NT kernel API tracing. You need to provide
+                       appropriate function wrappers in the main source file
+                       @{[ captive_srcfile './src/TraceFS/TraceFS-W32/TraceFS.c' ]}
+                       and you must also export them in
+                       @{[ captive_srcfile './src/TraceFS/TraceFS-W32/TraceFS.def' ]}.
+                       @{[ captive_srcfile './src/TraceFS/hookfs.pl' ]} has no hardcoded
+                       function names &ndash; it will hook exactly the exported entries.</p>
+
+                       <p>Framework for thread synchronizations and debug tracing is provided to
+                       prevent mangling of messages while running by multiple threads at once.
+                       Testing was done just on uniprocessor machine, SMP kernel may need some
+                       fixes.</p>
+                       
+
        <a name="functype"><h2>API Function Implementation Choices</h2></a>
 
                <p>For each function exported by W32
@@ -942,7 +1257,7 @@ print <<"HERE";
                below:</p>
 
                <table border="1" align="center">
-                       <tr><th>Function type                                        </th><th>Items</th><th>Portion</th></tr>
+                       <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>
@@ -977,9 +1292,7 @@ print <<"HERE";
 
                <p>All the exporting magic is handled by custom script
                <span class="fname">captivesym</span> processing the definition file
-               <span class="fname">@{[ a_href
-                               'http://cvs.jankratochvil.net/viewcvs/*checkout*/priv/captive/src/libcaptive/ke/exports.captivesym?rev=HEAD',
-                               'src/libcaptive/ke/exports.captivesym' ]}</span>
+               <span class="fname">@{[ captive_srcfile 'src/libcaptive/ke/exports.captivesym' ]}</span>
                to produce the intermediate relaying code
                <span class="fname">src/libcaptive/ke/exports.c</span>. For details of the
                <span class="fname">captivesym</span>-specific source file syntax please
diff --git a/project/captive/doc/dia/TraceFS.dia b/project/captive/doc/dia/TraceFS.dia
new file mode 100644 (file)
index 0000000..977bb63
--- /dev/null
@@ -0,0 +1,740 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<dia:diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
+  <dia:diagramdata>
+    <dia:attribute name="background">
+      <dia:color val="#ffffff"/>
+    </dia:attribute>
+    <dia:attribute name="paper">
+      <dia:composite type="paper">
+        <dia:attribute name="name">
+          <dia:string>#A4#</dia:string>
+        </dia:attribute>
+        <dia:attribute name="tmargin">
+          <dia:real val="2.8222"/>
+        </dia:attribute>
+        <dia:attribute name="bmargin">
+          <dia:real val="2.8222"/>
+        </dia:attribute>
+        <dia:attribute name="lmargin">
+          <dia:real val="2.8222"/>
+        </dia:attribute>
+        <dia:attribute name="rmargin">
+          <dia:real val="2.8222"/>
+        </dia:attribute>
+        <dia:attribute name="is_portrait">
+          <dia:boolean val="true"/>
+        </dia:attribute>
+        <dia:attribute name="scaling">
+          <dia:real val="0.25"/>
+        </dia:attribute>
+        <dia:attribute name="fitto">
+          <dia:boolean val="false"/>
+        </dia:attribute>
+      </dia:composite>
+    </dia:attribute>
+    <dia:attribute name="grid">
+      <dia:composite type="grid">
+        <dia:attribute name="width_x">
+          <dia:real val="1"/>
+        </dia:attribute>
+        <dia:attribute name="width_y">
+          <dia:real val="1"/>
+        </dia:attribute>
+        <dia:attribute name="visible_x">
+          <dia:int val="1"/>
+        </dia:attribute>
+        <dia:attribute name="visible_y">
+          <dia:int val="1"/>
+        </dia:attribute>
+      </dia:composite>
+    </dia:attribute>
+    <dia:attribute name="guides">
+      <dia:composite type="guides">
+        <dia:attribute name="hguides"/>
+        <dia:attribute name="vguides"/>
+      </dia:composite>
+    </dia:attribute>
+  </dia:diagramdata>
+  <dia:layer name="Background" visible="true">
+    <dia:object type="Standard - Box" version="0" id="O0">
+      <dia:attribute name="obj_pos">
+        <dia:point val="-19,-6"/>
+      </dia:attribute>
+      <dia:attribute name="obj_bb">
+        <dia:rectangle val="-19.5,-6.5;47.5,36.5"/>
+      </dia:attribute>
+      <dia:attribute name="elem_corner">
+        <dia:point val="-19,-6"/>
+      </dia:attribute>
+      <dia:attribute name="elem_width">
+        <dia:real val="66"/>
+      </dia:attribute>
+      <dia:attribute name="elem_height">
+        <dia:real val="42"/>
+      </dia:attribute>
+      <dia:attribute name="border_width">
+        <dia:real val="1"/>
+      </dia:attribute>
+      <dia:attribute name="border_color">
+        <dia:color val="#ffffff"/>
+      </dia:attribute>
+      <dia:attribute name="show_background">
+        <dia:boolean val="false"/>
+      </dia:attribute>
+    </dia:object>
+    <dia:object type="Standard - ZigZagLine" version="0" id="O1">
+      <dia:attribute name="obj_pos">
+        <dia:point val="14,30"/>
+      </dia:attribute>
+      <dia:attribute name="obj_bb">
+        <dia:rectangle val="12.4,11.75;15.6,30.25"/>
+      </dia:attribute>
+      <dia:attribute name="orth_points">
+        <dia:point val="14,30"/>
+        <dia:point val="14,19"/>
+        <dia:point val="14,19"/>
+        <dia:point val="14,12"/>
+      </dia:attribute>
+      <dia:attribute name="orth_orient">
+        <dia:enum val="1"/>
+        <dia:enum val="0"/>
+        <dia:enum val="1"/>
+      </dia:attribute>
+      <dia:attribute name="line_width">
+        <dia:real val="0.5"/>
+      </dia:attribute>
+      <dia:attribute name="line_style">
+        <dia:enum val="4"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow">
+        <dia:enum val="1"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow_length">
+        <dia:real val="1.6"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow_width">
+        <dia:real val="1.6"/>
+      </dia:attribute>
+      <dia:connections>
+        <dia:connection handle="0" to="O18" connection="1"/>
+        <dia:connection handle="1" to="O5" connection="6"/>
+      </dia:connections>
+    </dia:object>
+    <dia:object type="Standard - ZigZagLine" version="0" id="O2">
+      <dia:attribute name="obj_pos">
+        <dia:point val="34,19"/>
+      </dia:attribute>
+      <dia:attribute name="obj_bb">
+        <dia:rectangle val="12.4,11.75;34.25,19.25"/>
+      </dia:attribute>
+      <dia:attribute name="orth_points">
+        <dia:point val="34,19"/>
+        <dia:point val="34,17"/>
+        <dia:point val="14,17"/>
+        <dia:point val="14,12"/>
+      </dia:attribute>
+      <dia:attribute name="orth_orient">
+        <dia:enum val="1"/>
+        <dia:enum val="0"/>
+        <dia:enum val="1"/>
+      </dia:attribute>
+      <dia:attribute name="line_color">
+        <dia:color val="#ff0000"/>
+      </dia:attribute>
+      <dia:attribute name="line_width">
+        <dia:real val="0.5"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow">
+        <dia:enum val="1"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow_length">
+        <dia:real val="1.6"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow_width">
+        <dia:real val="1.6"/>
+      </dia:attribute>
+      <dia:connections>
+        <dia:connection handle="0" to="O14" connection="1"/>
+        <dia:connection handle="1" to="O5" connection="6"/>
+      </dia:connections>
+    </dia:object>
+    <dia:object type="Standard - ZigZagLine" version="0" id="O3">
+      <dia:attribute name="obj_pos">
+        <dia:point val="14,30"/>
+      </dia:attribute>
+      <dia:attribute name="obj_bb">
+        <dia:rectangle val="13.75,22.75;35.6,30.25"/>
+      </dia:attribute>
+      <dia:attribute name="orth_points">
+        <dia:point val="14,30"/>
+        <dia:point val="14,25"/>
+        <dia:point val="34,25"/>
+        <dia:point val="34,23"/>
+      </dia:attribute>
+      <dia:attribute name="orth_orient">
+        <dia:enum val="1"/>
+        <dia:enum val="0"/>
+        <dia:enum val="1"/>
+      </dia:attribute>
+      <dia:attribute name="line_color">
+        <dia:color val="#ff0000"/>
+      </dia:attribute>
+      <dia:attribute name="line_width">
+        <dia:real val="0.5"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow">
+        <dia:enum val="1"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow_length">
+        <dia:real val="1.6"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow_width">
+        <dia:real val="1.6"/>
+      </dia:attribute>
+      <dia:connections>
+        <dia:connection handle="0" to="O18" connection="1"/>
+        <dia:connection handle="1" to="O14" connection="6"/>
+      </dia:connections>
+    </dia:object>
+    <dia:group>
+      <dia:object type="Standard - Box" version="0" id="O4">
+        <dia:attribute name="obj_pos">
+          <dia:point val="-10,3"/>
+        </dia:attribute>
+        <dia:attribute name="obj_bb">
+          <dia:rectangle val="-10.25,2.75;27.25,12.25"/>
+        </dia:attribute>
+        <dia:attribute name="elem_corner">
+          <dia:point val="-10,3"/>
+        </dia:attribute>
+        <dia:attribute name="elem_width">
+          <dia:real val="37"/>
+        </dia:attribute>
+        <dia:attribute name="elem_height">
+          <dia:real val="9"/>
+        </dia:attribute>
+        <dia:attribute name="border_width">
+          <dia:real val="0.5"/>
+        </dia:attribute>
+        <dia:attribute name="show_background">
+          <dia:boolean val="true"/>
+        </dia:attribute>
+      </dia:object>
+      <dia:group>
+        <dia:object type="Standard - Box" version="0" id="O5">
+          <dia:attribute name="obj_pos">
+            <dia:point val="2,8"/>
+          </dia:attribute>
+          <dia:attribute name="obj_bb">
+            <dia:rectangle val="1.75,7.75;26.25,12.25"/>
+          </dia:attribute>
+          <dia:attribute name="elem_corner">
+            <dia:point val="2,8"/>
+          </dia:attribute>
+          <dia:attribute name="elem_width">
+            <dia:real val="24"/>
+          </dia:attribute>
+          <dia:attribute name="elem_height">
+            <dia:real val="4"/>
+          </dia:attribute>
+          <dia:attribute name="border_width">
+            <dia:real val="0.5"/>
+          </dia:attribute>
+          <dia:attribute name="show_background">
+            <dia:boolean val="true"/>
+          </dia:attribute>
+        </dia:object>
+        <dia:object type="Standard - Text" version="0" id="O6">
+          <dia:attribute name="obj_pos">
+            <dia:point val="14,11"/>
+          </dia:attribute>
+          <dia:attribute name="obj_bb">
+            <dia:rectangle val="2.1695,8.6;25.8305,11.6"/>
+          </dia:attribute>
+          <dia:attribute name="text">
+            <dia:composite type="text">
+              <dia:attribute name="string">
+                <dia:string>#Cache Manager#</dia:string>
+              </dia:attribute>
+              <dia:attribute name="font">
+                <dia:font name="Helvetica-Bold"/>
+              </dia:attribute>
+              <dia:attribute name="height">
+                <dia:real val="3"/>
+              </dia:attribute>
+              <dia:attribute name="pos">
+                <dia:point val="14,11"/>
+              </dia:attribute>
+              <dia:attribute name="color">
+                <dia:color val="#000000"/>
+              </dia:attribute>
+              <dia:attribute name="alignment">
+                <dia:enum val="1"/>
+              </dia:attribute>
+            </dia:composite>
+          </dia:attribute>
+        </dia:object>
+      </dia:group>
+      <dia:group>
+        <dia:object type="Standard - Box" version="0" id="O7">
+          <dia:attribute name="obj_pos">
+            <dia:point val="-6,8"/>
+          </dia:attribute>
+          <dia:attribute name="obj_bb">
+            <dia:rectangle val="-6.25,7.75;0.25,12.25"/>
+          </dia:attribute>
+          <dia:attribute name="elem_corner">
+            <dia:point val="-6,8"/>
+          </dia:attribute>
+          <dia:attribute name="elem_width">
+            <dia:real val="6"/>
+          </dia:attribute>
+          <dia:attribute name="elem_height">
+            <dia:real val="4"/>
+          </dia:attribute>
+          <dia:attribute name="border_width">
+            <dia:real val="0.5"/>
+          </dia:attribute>
+          <dia:attribute name="show_background">
+            <dia:boolean val="true"/>
+          </dia:attribute>
+        </dia:object>
+        <dia:object type="Standard - Text" version="0" id="O8">
+          <dia:attribute name="obj_pos">
+            <dia:point val="-3,11"/>
+          </dia:attribute>
+          <dia:attribute name="obj_bb">
+            <dia:rectangle val="-4.1385,8.6;-1.8615,11.6"/>
+          </dia:attribute>
+          <dia:attribute name="text">
+            <dia:composite type="text">
+              <dia:attribute name="string">
+                <dia:string>#...#</dia:string>
+              </dia:attribute>
+              <dia:attribute name="font">
+                <dia:font name="Helvetica-Bold"/>
+              </dia:attribute>
+              <dia:attribute name="height">
+                <dia:real val="3"/>
+              </dia:attribute>
+              <dia:attribute name="pos">
+                <dia:point val="-3,11"/>
+              </dia:attribute>
+              <dia:attribute name="color">
+                <dia:color val="#000000"/>
+              </dia:attribute>
+              <dia:attribute name="alignment">
+                <dia:enum val="1"/>
+              </dia:attribute>
+            </dia:composite>
+          </dia:attribute>
+        </dia:object>
+      </dia:group>
+      <dia:object type="Standard - Text" version="0" id="O9">
+        <dia:attribute name="obj_pos">
+          <dia:point val="0,6"/>
+        </dia:attribute>
+        <dia:attribute name="obj_bb">
+          <dia:rectangle val="-9.504,3.6;9.504,6.6"/>
+        </dia:attribute>
+        <dia:attribute name="text">
+          <dia:composite type="text">
+            <dia:attribute name="string">
+              <dia:string>#ntoskrnl.exe#</dia:string>
+            </dia:attribute>
+            <dia:attribute name="font">
+              <dia:font name="Helvetica-Bold"/>
+            </dia:attribute>
+            <dia:attribute name="height">
+              <dia:real val="3"/>
+            </dia:attribute>
+            <dia:attribute name="pos">
+              <dia:point val="0,6"/>
+            </dia:attribute>
+            <dia:attribute name="color">
+              <dia:color val="#000000"/>
+            </dia:attribute>
+            <dia:attribute name="alignment">
+              <dia:enum val="1"/>
+            </dia:attribute>
+          </dia:composite>
+        </dia:attribute>
+      </dia:object>
+    </dia:group>
+    <dia:object type="Standard - ZigZagLine" version="0" id="O10">
+      <dia:attribute name="obj_pos">
+        <dia:point val="-7,30"/>
+      </dia:attribute>
+      <dia:attribute name="obj_bb">
+        <dia:rectangle val="-7.25,11.75;-2.4,30.25"/>
+      </dia:attribute>
+      <dia:attribute name="orth_points">
+        <dia:point val="-7,30"/>
+        <dia:point val="-7,15"/>
+        <dia:point val="-4,15"/>
+        <dia:point val="-4,12"/>
+      </dia:attribute>
+      <dia:attribute name="orth_orient">
+        <dia:enum val="1"/>
+        <dia:enum val="0"/>
+        <dia:enum val="1"/>
+      </dia:attribute>
+      <dia:attribute name="line_color">
+        <dia:color val="#0000ff"/>
+      </dia:attribute>
+      <dia:attribute name="line_width">
+        <dia:real val="0.5"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow">
+        <dia:enum val="1"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow_length">
+        <dia:real val="1.6"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow_width">
+        <dia:real val="1.6"/>
+      </dia:attribute>
+      <dia:connections>
+        <dia:connection handle="0" to="O16" connection="1"/>
+      </dia:connections>
+    </dia:object>
+    <dia:object type="Standard - ZigZagLine" version="0" id="O11">
+      <dia:attribute name="obj_pos">
+        <dia:point val="-7,30"/>
+      </dia:attribute>
+      <dia:attribute name="obj_bb">
+        <dia:rectangle val="-7.25,11.75;13.6,30.25"/>
+      </dia:attribute>
+      <dia:attribute name="orth_points">
+        <dia:point val="-7,30"/>
+        <dia:point val="-7,16"/>
+        <dia:point val="12,16"/>
+        <dia:point val="12,12"/>
+      </dia:attribute>
+      <dia:attribute name="orth_orient">
+        <dia:enum val="1"/>
+        <dia:enum val="0"/>
+        <dia:enum val="1"/>
+      </dia:attribute>
+      <dia:attribute name="line_color">
+        <dia:color val="#0000ff"/>
+      </dia:attribute>
+      <dia:attribute name="line_width">
+        <dia:real val="0.5"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow">
+        <dia:enum val="1"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow_length">
+        <dia:real val="1.6"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow_width">
+        <dia:real val="1.6"/>
+      </dia:attribute>
+      <dia:connections>
+        <dia:connection handle="0" to="O16" connection="1"/>
+      </dia:connections>
+    </dia:object>
+    <dia:object type="Standard - Text" version="0" id="O12">
+      <dia:attribute name="obj_pos">
+        <dia:point val="28,22"/>
+      </dia:attribute>
+      <dia:attribute name="obj_bb">
+        <dia:rectangle val="27.95,21.3553;28,22.3053"/>
+      </dia:attribute>
+      <dia:attribute name="text">
+        <dia:composite type="text">
+          <dia:attribute name="string">
+            <dia:string>##</dia:string>
+          </dia:attribute>
+          <dia:attribute name="font">
+            <dia:font name="Courier"/>
+          </dia:attribute>
+          <dia:attribute name="height">
+            <dia:real val="0.8"/>
+          </dia:attribute>
+          <dia:attribute name="pos">
+            <dia:point val="28,22"/>
+          </dia:attribute>
+          <dia:attribute name="color">
+            <dia:color val="#000000"/>
+          </dia:attribute>
+          <dia:attribute name="alignment">
+            <dia:enum val="1"/>
+          </dia:attribute>
+        </dia:composite>
+      </dia:attribute>
+    </dia:object>
+    <dia:object type="Standard - ZigZagLine" version="0" id="O13">
+      <dia:attribute name="obj_pos">
+        <dia:point val="14,30"/>
+      </dia:attribute>
+      <dia:attribute name="obj_bb">
+        <dia:rectangle val="-3.6,11.75;14.25,30.25"/>
+      </dia:attribute>
+      <dia:attribute name="orth_points">
+        <dia:point val="14,30"/>
+        <dia:point val="14,27"/>
+        <dia:point val="-2,27"/>
+        <dia:point val="-2,12"/>
+      </dia:attribute>
+      <dia:attribute name="orth_orient">
+        <dia:enum val="1"/>
+        <dia:enum val="0"/>
+        <dia:enum val="1"/>
+      </dia:attribute>
+      <dia:attribute name="line_color">
+        <dia:color val="#00ff00"/>
+      </dia:attribute>
+      <dia:attribute name="line_width">
+        <dia:real val="0.5"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow">
+        <dia:enum val="1"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow_length">
+        <dia:real val="1.6"/>
+      </dia:attribute>
+      <dia:attribute name="end_arrow_width">
+        <dia:real val="1.6"/>
+      </dia:attribute>
+      <dia:connections>
+        <dia:connection handle="0" to="O18" connection="1"/>
+      </dia:connections>
+    </dia:object>
+    <dia:group>
+      <dia:object type="Standard - Box" version="0" id="O14">
+        <dia:attribute name="obj_pos">
+          <dia:point val="24,19"/>
+        </dia:attribute>
+        <dia:attribute name="obj_bb">
+          <dia:rectangle val="23.75,18.75;44.25,23.25"/>
+        </dia:attribute>
+        <dia:attribute name="elem_corner">
+          <dia:point val="24,19"/>
+        </dia:attribute>
+        <dia:attribute name="elem_width">
+          <dia:real val="20"/>
+        </dia:attribute>
+        <dia:attribute name="elem_height">
+          <dia:real val="4"/>
+        </dia:attribute>
+        <dia:attribute name="border_width">
+          <dia:real val="0.5"/>
+        </dia:attribute>
+        <dia:attribute name="border_color">
+          <dia:color val="#ff0000"/>
+        </dia:attribute>
+        <dia:attribute name="show_background">
+          <dia:boolean val="true"/>
+        </dia:attribute>
+      </dia:object>
+      <dia:object type="Standard - Text" version="0" id="O15">
+        <dia:attribute name="obj_pos">
+          <dia:point val="34,22"/>
+        </dia:attribute>
+        <dia:attribute name="obj_bb">
+          <dia:rectangle val="24.4465,19.6;43.5535,22.6"/>
+        </dia:attribute>
+        <dia:attribute name="text">
+          <dia:composite type="text">
+            <dia:attribute name="string">
+              <dia:string>#TraceFS.sys#</dia:string>
+            </dia:attribute>
+            <dia:attribute name="font">
+              <dia:font name="Helvetica-Bold"/>
+            </dia:attribute>
+            <dia:attribute name="height">
+              <dia:real val="3"/>
+            </dia:attribute>
+            <dia:attribute name="pos">
+              <dia:point val="34,22"/>
+            </dia:attribute>
+            <dia:attribute name="color">
+              <dia:color val="#000000"/>
+            </dia:attribute>
+            <dia:attribute name="alignment">
+              <dia:enum val="1"/>
+            </dia:attribute>
+          </dia:composite>
+        </dia:attribute>
+      </dia:object>
+    </dia:group>
+    <dia:group>
+      <dia:object type="Standard - Box" version="0" id="O16">
+        <dia:attribute name="obj_pos">
+          <dia:point val="-16,30"/>
+        </dia:attribute>
+        <dia:attribute name="obj_bb">
+          <dia:rectangle val="-16.25,29.75;2.25,34.25"/>
+        </dia:attribute>
+        <dia:attribute name="elem_corner">
+          <dia:point val="-16,30"/>
+        </dia:attribute>
+        <dia:attribute name="elem_width">
+          <dia:real val="18"/>
+        </dia:attribute>
+        <dia:attribute name="elem_height">
+          <dia:real val="4"/>
+        </dia:attribute>
+        <dia:attribute name="border_width">
+          <dia:real val="0.5"/>
+        </dia:attribute>
+        <dia:attribute name="border_color">
+          <dia:color val="#0000ff"/>
+        </dia:attribute>
+        <dia:attribute name="show_background">
+          <dia:boolean val="true"/>
+        </dia:attribute>
+      </dia:object>
+      <dia:object type="Standard - Text" version="0" id="O17">
+        <dia:attribute name="obj_pos">
+          <dia:point val="-7,33"/>
+        </dia:attribute>
+        <dia:attribute name="obj_bb">
+          <dia:rectangle val="-15.0685,30.55;1.1185,33.7"/>
+        </dia:attribute>
+        <dia:attribute name="text">
+          <dia:composite type="text">
+            <dia:attribute name="string">
+              <dia:string>#fastfat.sys#</dia:string>
+            </dia:attribute>
+            <dia:attribute name="font">
+              <dia:font name="Helvetica-Bold"/>
+            </dia:attribute>
+            <dia:attribute name="height">
+              <dia:real val="3"/>
+            </dia:attribute>
+            <dia:attribute name="pos">
+              <dia:point val="-7,33"/>
+            </dia:attribute>
+            <dia:attribute name="color">
+              <dia:color val="#000000"/>
+            </dia:attribute>
+            <dia:attribute name="alignment">
+              <dia:enum val="1"/>
+            </dia:attribute>
+          </dia:composite>
+        </dia:attribute>
+      </dia:object>
+    </dia:group>
+    <dia:group>
+      <dia:object type="Standard - Box" version="0" id="O18">
+        <dia:attribute name="obj_pos">
+          <dia:point val="7,30"/>
+        </dia:attribute>
+        <dia:attribute name="obj_bb">
+          <dia:rectangle val="6.75,29.75;21.25,34.25"/>
+        </dia:attribute>
+        <dia:attribute name="elem_corner">
+          <dia:point val="7,30"/>
+        </dia:attribute>
+        <dia:attribute name="elem_width">
+          <dia:real val="14"/>
+        </dia:attribute>
+        <dia:attribute name="elem_height">
+          <dia:real val="4"/>
+        </dia:attribute>
+        <dia:attribute name="border_width">
+          <dia:real val="0.5"/>
+        </dia:attribute>
+        <dia:attribute name="border_color">
+          <dia:color val="#00ff00"/>
+        </dia:attribute>
+        <dia:attribute name="show_background">
+          <dia:boolean val="true"/>
+        </dia:attribute>
+      </dia:object>
+      <dia:object type="Standard - Text" version="0" id="O19">
+        <dia:attribute name="obj_pos">
+          <dia:point val="14,33"/>
+        </dia:attribute>
+        <dia:attribute name="obj_bb">
+          <dia:rectangle val="7.9115,30.55;20.1385,33.7"/>
+        </dia:attribute>
+        <dia:attribute name="text">
+          <dia:composite type="text">
+            <dia:attribute name="string">
+              <dia:string>#ntfs.sys#</dia:string>
+            </dia:attribute>
+            <dia:attribute name="font">
+              <dia:font name="Helvetica-Bold"/>
+            </dia:attribute>
+            <dia:attribute name="height">
+              <dia:real val="3"/>
+            </dia:attribute>
+            <dia:attribute name="pos">
+              <dia:point val="14,33"/>
+            </dia:attribute>
+            <dia:attribute name="color">
+              <dia:color val="#000000"/>
+            </dia:attribute>
+            <dia:attribute name="alignment">
+              <dia:enum val="1"/>
+            </dia:attribute>
+          </dia:composite>
+        </dia:attribute>
+      </dia:object>
+    </dia:group>
+    <dia:object type="Standard - Text" version="0" id="O20">
+      <dia:attribute name="obj_pos">
+        <dia:point val="15,21"/>
+      </dia:attribute>
+      <dia:attribute name="obj_bb">
+        <dia:rectangle val="15,19.35;22.442,21.5"/>
+      </dia:attribute>
+      <dia:attribute name="text">
+        <dia:composite type="text">
+          <dia:attribute name="string">
+            <dia:string>#hooked#</dia:string>
+          </dia:attribute>
+          <dia:attribute name="font">
+            <dia:font name="Helvetica-Bold"/>
+          </dia:attribute>
+          <dia:attribute name="height">
+            <dia:real val="2"/>
+          </dia:attribute>
+          <dia:attribute name="pos">
+            <dia:point val="15,21"/>
+          </dia:attribute>
+          <dia:attribute name="color">
+            <dia:color val="#000000"/>
+          </dia:attribute>
+          <dia:attribute name="alignment">
+            <dia:enum val="0"/>
+          </dia:attribute>
+        </dia:composite>
+      </dia:attribute>
+    </dia:object>
+    <dia:object type="Standard - Text" version="0" id="O21">
+      <dia:attribute name="obj_pos">
+        <dia:point val="14,-1"/>
+      </dia:attribute>
+      <dia:attribute name="obj_bb">
+        <dia:rectangle val="-19.858,-4.25;47.908,-0.1"/>
+      </dia:attribute>
+      <dia:attribute name="text">
+        <dia:composite type="text">
+          <dia:attribute name="string">
+            <dia:string>#TraceFS Cache Manager hooking#</dia:string>
+          </dia:attribute>
+          <dia:attribute name="font">
+            <dia:font name="Helvetica-Bold"/>
+          </dia:attribute>
+          <dia:attribute name="height">
+            <dia:real val="4"/>
+          </dia:attribute>
+          <dia:attribute name="pos">
+            <dia:point val="14,-1"/>
+          </dia:attribute>
+          <dia:attribute name="color">
+            <dia:color val="#000000"/>
+          </dia:attribute>
+          <dia:attribute name="alignment">
+            <dia:enum val="1"/>
+          </dia:attribute>
+        </dia:composite>
+      </dia:attribute>
+    </dia:object>
+  </dia:layer>
+</dia:diagram>
diff --git a/project/captive/doc/dia/TraceFS.gif b/project/captive/doc/dia/TraceFS.gif
new file mode 100644 (file)
index 0000000..bd90bcc
Binary files /dev/null and b/project/captive/doc/dia/TraceFS.gif differ
diff --git a/project/captive/doc/dia/TraceFS.png b/project/captive/doc/dia/TraceFS.png
new file mode 100644 (file)
index 0000000..dbed736
Binary files /dev/null and b/project/captive/doc/dia/TraceFS.png differ
index ea045eb..3efa82d 100644 (file)
         <dia:point val="-2,-6"/>
       </dia:attribute>
       <dia:attribute name="obj_bb">
-        <dia:rectangle val="-2.5,-6.5;117.5,33.5"/>
+        <dia:rectangle val="-2.5,-6.5;118.5,33.5"/>
       </dia:attribute>
       <dia:attribute name="elem_corner">
         <dia:point val="-2,-6"/>
       </dia:attribute>
       <dia:attribute name="elem_width">
-        <dia:real val="119"/>
+        <dia:real val="120"/>
       </dia:attribute>
       <dia:attribute name="elem_height">
         <dia:real val="39"/>
         <dia:point val="79,2"/>
       </dia:attribute>
       <dia:attribute name="obj_bb">
-        <dia:rectangle val="78.75,1.75;115.25,14.25"/>
+        <dia:rectangle val="78.75,1.75;116.25,14.25"/>
       </dia:attribute>
       <dia:attribute name="elem_corner">
         <dia:point val="79,2"/>
       </dia:attribute>
       <dia:attribute name="elem_width">
-        <dia:real val="36"/>
+        <dia:real val="37"/>
       </dia:attribute>
       <dia:attribute name="elem_height">
         <dia:real val="12"/>
         <dia:point val="83,10"/>
       </dia:attribute>
       <dia:attribute name="obj_bb">
-        <dia:rectangle val="83,8.35;116.314,12.5"/>
+        <dia:rectangle val="83,8.4;116.264,12.4"/>
       </dia:attribute>
       <dia:attribute name="text">
         <dia:composite type="text">
@@ -826,7 +826,7 @@ dirty: &lt;LSNoldest .. LSNnewest&gt;#</dia:string>
           <dia:point val="14,5"/>
         </dia:attribute>
         <dia:attribute name="obj_bb">
-          <dia:rectangle val="2.5655,2.55;25.4845,5.7"/>
+          <dia:rectangle val="2.5655,2.6;25.4345,5.6"/>
         </dia:attribute>
         <dia:attribute name="text">
           <dia:composite type="text">
@@ -884,7 +884,7 @@ dirty: &lt;LSNoldest .. LSNnewest&gt;#</dia:string>
           <dia:point val="14,14"/>
         </dia:attribute>
         <dia:attribute name="obj_bb">
-          <dia:rectangle val="7.0205,11.55;21.0295,14.7"/>
+          <dia:rectangle val="7.0205,11.6;20.9795,14.6"/>
         </dia:attribute>
         <dia:attribute name="text">
           <dia:composite type="text">
@@ -942,7 +942,7 @@ dirty: &lt;LSNoldest .. LSNnewest&gt;#</dia:string>
           <dia:point val="14,23"/>
         </dia:attribute>
         <dia:attribute name="obj_bb">
-          <dia:rectangle val="0.5855,20.55;27.4645,23.7"/>
+          <dia:rectangle val="0.5855,20.6;27.4145,23.6"/>
         </dia:attribute>
         <dia:attribute name="text">
           <dia:composite type="text">
@@ -1031,7 +1031,7 @@ start .. end#</dia:string>
           <dia:point val="43,5"/>
         </dia:attribute>
         <dia:attribute name="obj_bb">
-          <dia:rectangle val="35.971,2.55;50.079,5.7"/>
+          <dia:rectangle val="35.971,2.6;50.029,5.6"/>
         </dia:attribute>
         <dia:attribute name="text">
           <dia:composite type="text">
@@ -1119,7 +1119,7 @@ start .. end#</dia:string>
           <dia:point val="43,18"/>
         </dia:attribute>
         <dia:attribute name="obj_bb">
-          <dia:rectangle val="38.875,16.35;47.175,20.5"/>
+          <dia:rectangle val="38.875,16.4;47.125,20.4"/>
         </dia:attribute>
         <dia:attribute name="text">
           <dia:composite type="text">
@@ -1178,7 +1178,7 @@ start + x#</dia:string>
           <dia:point val="43,26"/>
         </dia:attribute>
         <dia:attribute name="obj_bb">
-          <dia:rectangle val="36.664,23.55;49.386,26.7"/>
+          <dia:rectangle val="36.664,23.6;49.336,26.6"/>
         </dia:attribute>
         <dia:attribute name="text">
           <dia:composite type="text">
@@ -1300,7 +1300,7 @@ start + y#</dia:string>
           <dia:point val="64,11"/>
         </dia:attribute>
         <dia:attribute name="obj_bb">
-          <dia:rectangle val="55.816,9.35;72.234,15.5"/>
+          <dia:rectangle val="55.816,9.4;72.184,15.4"/>
         </dia:attribute>
         <dia:attribute name="text">
           <dia:composite type="text">
@@ -1393,7 +1393,7 @@ start + x#</dia:string>
           <dia:point val="64,22"/>
         </dia:attribute>
         <dia:attribute name="obj_bb">
-          <dia:rectangle val="55.816,20.35;72.234,26.5"/>
+          <dia:rectangle val="55.816,20.4;72.184,26.4"/>
         </dia:attribute>
         <dia:attribute name="text">
           <dia:composite type="text">
@@ -1426,7 +1426,7 @@ start + x#</dia:string>
         <dia:point val="83,8"/>
       </dia:attribute>
       <dia:attribute name="obj_bb">
-        <dia:rectangle val="83,6.35;88.264,8.5"/>
+        <dia:rectangle val="83,6.4;88.214,8.4"/>
       </dia:attribute>
       <dia:attribute name="text">
         <dia:composite type="text">
index 250e781..c9ae2c6 100644 (file)
Binary files a/project/captive/doc/dia/cache-manager.gif and b/project/captive/doc/dia/cache-manager.gif differ
index 8d73a1b..fc5c3f8 100644 (file)
Binary files a/project/captive/doc/dia/cache-manager.png and b/project/captive/doc/dia/cache-manager.png differ