doc/txt/vm-integration

   1 Copyright 2000, International Business Machines Corporation and others.
   2 All Rights Reserved.
   3
   4 This software has been released under the terms of the IBM Public
   5 License.  For details, see the LICENSE file in the top-level source
   6 directory or online at http://www.openafs.org/dl/license10.html
   7
   8 Here's a quick guide to understanding the AFS 3 VM integration.  This
   9 will help you do AFS 3 ports, since one of the trickiest parts of an
  10 AFS 3 port is the integration of the virtual memory system with the
  11 file system.
  12
  13 The issues arise because in AFS, as in any network file system,
  14 changes may be made from any machine while references are being made
  15 to a file on your own machine.  Data may be cached in your local
  16 machine's VM system, and when the data changes remotely, the cache
  17 manager must invalidate the old information in the VM system.
  18
  19 Furthermore, in some systems, there are pages of virtual memory
  20 containing changes to the files that need to be written back to the
  21 server at some time.  In these systems, it is important not to
  22 invalidate those pages before the data has made it to the file system.
  23 In addition, such systems often provide mapped file support, with read
  24 and write system calls affecting the same shared virtual memory as is
  25 used by the file should it be mapped.
  26
  27 As you may have guessed from the above, there are two general styles
  28 of VM integration done in AFS 3: one for systems with limited VM
  29 system caching, and one for more modern systems where mapped files
  30 coexist with read and write system calls.
  31
  32 For the older systems, the function osi_FlushText exists.  Its goal is
  33 to invalidate, or try to invalidate, caches where VM pages might cache
  34 file information that's now obsolete.  Even if the invalidation is
  35 impossible at the time the call is made, things should be setup so
  36 that the invalidation happens afterwards.
  37
  38 I'm not going to say more about this type of system, since fewer and
  39 fewer exist, and since I'm low on time.  If I get back to this paper
  40 later, I'll remove this paragraph.  The rest of this note talks about
  41 the more modern mapped file systems.
  42
  43 For mapped file systems, the function osi_FlushPages is called from
  44 various parts of the AFS cache manager.  We assume that this function
  45 must be called without holding any vnode locks, since it may call back
  46 to the file system to do part of its work.
  47
  48 The function osi_FlushPages has a relatively complex specification.
  49 If the file is open for writing, or if the data version of the pages
  50 that could be in memory (vp->mapDV) is the current data version number
  51 of the file, then this function has no work to do.  The rationale is
  52 that if the file is open for writing, calling this function could
  53 destroy data written to the file but not flushed from the VM system to
  54 the cache file.  If mapDV >= DataVersion, then flushing the VM
  55 system's pages won't change the fact that we can still only have pages
  56 from data version == mapDV in memory.  That's because flushing all
  57 pages from the VM system results in a post condition that the only
  58 pages that might be in memory are from the current data version.
  59
  60 If neither of the two conditions above occur, then we actually
  61 invalidate the pages, on a Sun by calling pvn_vptrunc.  This discards
  62 the pages without writing any dirty pages to the cache file.  We then
  63 set the mapDV field to the highest data version seen before we started
  64 the call to flush the pages.  On systems that release the vnode lock
  65 while doing the page flush, the file's data version at the end of this
  66 procedure may be larger than the value we set mapDV to, but that's
  67 only conservative, since a new could have been created from the
  68 earlier version of the file.
  69
  70 There are a few times that we must call osi_FlushPages.  We should
  71 call it at the start of a read or open call, so that we raise mapDV to
  72 the current value, and get rid of any old data that might interfere
  73 with later reads.  Raising mapDV to the current value is also
  74 important, since if we wrote data with mapDV < DataVersion, then a
  75 call to osi_FlushPages would discard this data if the pages were
  76 modified w/o having the file open for writing (e.g. using a mapped
  77 file).  This is why we also call it in afs_map.  We call it in
  78 afs_getattr, since afs_getattr is the only function guaranteed to be
  79 called between the time another client updates an executable, and the
  80 time that our own local client tries to exec this executable; if we
  81 fail to call osi_FlushPages here, we might use some pages from the
  82 previous version of the executable file.
  83
  84 Also, note that we update mapDV after a store back to the server
  85 completes, if we're sure that no other versions were created during
  86 the file's storeback.  The mapDV invariant (that no pages from earlier
  87 data versions exist in memory) remains true, since the only versions
  88 that existed between the old and new mapDV values all contained the
  89 same data.
  90
  91 Finally, note a serious incompleteness in this system: we aren't
  92 really prepared to deal with mapped files correctly.  In particular,
  93 there is no code to ensure that data stored in dirty VM pages ends up
  94 in a cache file, except as a side effect of the segmap_release call
  95 (on Sun 4s) that unmaps the data from the kernel map, and which,
  96 because of the SM_WRITE flag, also calls putpage synchronously to get
  97 rid of the data.
  98
  99 This problem needs to be fixed for any system that uses mapped files
 100 seriously.  Note that the NeXT port's generic write call uses mapped
 101 files, but that we've set a flag (close_flush) that ensures that all
 102 dirty pages get flushed after every write call.  It is also something
 103 of a performance hit, since it would be better to write those pages to
 104 the cache asynchronously rather than after every write, as happens
 105 now.