Cache Manager functionality update according to the latest betatests.

[www.jankratochvil.net.git] / project / captive / doc / CacheManager.html.pl

diff --git a/project/captive/doc/CacheManager.html.pl b/project/captive/doc/CacheManager.html.pl
index cc519f1..7b18551 100755 (executable)
--- a/project/captive/doc/CacheManager.html.pl
+++ b/project/captive/doc/CacheManager.html.pl
@@ -27,16 +27,16 @@ 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";
-use project::captive::doc::Macros;
+require CGI;
+BEGIN { Wuse 'project::captive::doc::Macros'; }
 
 
-My::Web->init(
+project::captive::doc::Macros->init(
                "__PACKAGE__"=>__PACKAGE__,
                "title"=>'Captive NTFS Developer Documentation: NT Cache Manager',
-               "head_css"=>$doc_Macros_head_css,
+               "rel_prev"=>'Reverse.html.pl',
+               "rel_next"=>'Details.html.pl',
                );
-My::Web->heading();
 
 
 print <<"HERE";
@@ -103,7 +103,10 @@ print <<"HERE";
        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>
+       or Pin mappings exist. Only in the case of 
+       <span class="constant">FO_STREAM_FILE</span> (virtual device file)
+       it is permitted to extend mapped size even in the case of existing
+       (and dirty) Map or Pin mappings.</p>
 
        <p><span class="type">PCACHE_MANAGER_CALLBACKS</type> argument can be
        safely ignored:</p>
@@ -219,7 +222,14 @@ print <<"HERE";
 
        <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>
+       expect it and it would corrupt its data buffers. There is just a&nbsp;strict
+       difference between <span class="function">CcPinRead()</span> and
+       <span class="function">CcPinMappedData()</span> function calls where
+       <span class="function">CcPinRead()</span> is required to re-read its data
+       blocks even if they were currently already Map mapped (unless it was already
+       also Pin mapped at least once). On the opposite side
+       <span class="function">CcPinMappedData()</span> must not re-read the given
+       blocks, moreover it blocks are required to be already Map mapped by the caller.</p>
 
        <p>Cache Manager of this project will destroy Pin or Map mappings after
        their last unreferencing (in opposite of
@@ -293,8 +303,16 @@ print <<"HERE";
                        <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.c' ]}.
+                       Original system functions being wrapped should be called with their
+                       original name. Your wrapping functions should have the first letter
+                       of their name replaced by character
+                       <span class="command">'T'</span> - wrapping of
+                       <span class="function">CcInitializeCacheMap()</span> must be
+                       done be your function
+                       <span class="function">TcInitializeCacheMap()</span>.
+                       Prototypes of both the wrapping and wrapped functions must be the same.
+                       You must also export all the wrapped functions by
                        @{[ 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>
@@ -308,4 +326,4 @@ print <<"HERE";
 HERE
 
 
-My::Web->footer();
+project::captive::doc::Macros->footer();