Import Upstream version 1.8.5

[hcoop/debian/openafs.git] / doc / txt / vm-integration

Copyright 2000, International Business Machines Corporation and others.
All Rights Reserved.

This software has been released under the terms of the IBM Public
License.  For details, see the LICENSE file in the top-level source
directory or online at http://www.openafs.org/dl/license10.html

Here's a quick guide to understanding the AFS 3 VM integration.  This
will help you do AFS 3 ports, since one of the trickiest parts of an
AFS 3 port is the integration of the virtual memory system with the
file system.

The issues arise because in AFS, as in any network file system,
changes may be made from any machine while references are being made
to a file on your own machine.  Data may be cached in your local
machine's VM system, and when the data changes remotely, the cache
manager must invalidate the old information in the VM system.

Furthermore, in some systems, there are pages of virtual memory
containing changes to the files that need to be written back to the
server at some time.  In these systems, it is important not to
invalidate those pages before the data has made it to the file system.
In addition, such systems often provide mapped file support, with read
and write system calls affecting the same shared virtual memory as is
used by the file should it be mapped.

As you may have guessed from the above, there are two general styles
of VM integration done in AFS 3: one for systems with limited VM
system caching, and one for more modern systems where mapped files
coexist with read and write system calls.

For the older systems, the function osi_FlushText exists.  Its goal is
to invalidate, or try to invalidate, caches where VM pages might cache
file information that's now obsolete.  Even if the invalidation is
impossible at the time the call is made, things should be setup so
that the invalidation happens afterwards.

I'm not going to say more about this type of system, since fewer and
fewer exist, and since I'm low on time.  If I get back to this paper
later, I'll remove this paragraph.  The rest of this note talks about
the more modern mapped file systems.

For mapped file systems, the function osi_FlushPages is called from
various parts of the AFS cache manager.  We assume that this function
must be called without holding any vnode locks, since it may call back
to the file system to do part of its work.

The function osi_FlushPages has a relatively complex specification.
If the file is open for writing, or if the data version of the pages
that could be in memory (vp->mapDV) is the current data version number
of the file, then this function has no work to do.  The rationale is
that if the file is open for writing, calling this function could
destroy data written to the file but not flushed from the VM system to
the cache file.  If mapDV >= DataVersion, then flushing the VM
system's pages won't change the fact that we can still only have pages
from data version == mapDV in memory.  That's because flushing all
pages from the VM system results in a post condition that the only
pages that might be in memory are from the current data version.

If neither of the two conditions above occur, then we actually
invalidate the pages, on a Sun by calling pvn_vptrunc.  This discards
the pages without writing any dirty pages to the cache file.  We then
set the mapDV field to the highest data version seen before we started
the call to flush the pages.  On systems that release the vnode lock
while doing the page flush, the file's data version at the end of this
procedure may be larger than the value we set mapDV to, but that's
only conservative, since a new could have been created from the
earlier version of the file.

There are a few times that we must call osi_FlushPages.  We should
call it at the start of a read or open call, so that we raise mapDV to
the current value, and get rid of any old data that might interfere
with later reads.  Raising mapDV to the current value is also
important, since if we wrote data with mapDV < DataVersion, then a
call to osi_FlushPages would discard this data if the pages were
modified w/o having the file open for writing (e.g. using a mapped
file).  This is why we also call it in afs_map.  We call it in
afs_getattr, since afs_getattr is the only function guaranteed to be
called between the time another client updates an executable, and the
time that our own local client tries to exec this executable; if we
fail to call osi_FlushPages here, we might use some pages from the
previous version of the executable file.

Also, note that we update mapDV after a store back to the server
completes, if we're sure that no other versions were created during
the file's storeback.  The mapDV invariant (that no pages from earlier
data versions exist in memory) remains true, since the only versions
that existed between the old and new mapDV values all contained the
same data.

Finally, note a serious incompleteness in this system: we aren't
really prepared to deal with mapped files correctly.  In particular,
there is no code to ensure that data stored in dirty VM pages ends up
in a cache file, except as a side effect of the segmap_release call
(on Sun 4s) that unmaps the data from the kernel map, and which,
because of the SM_WRITE flag, also calls putpage synchronously to get
rid of the data.

This problem needs to be fixed for any system that uses mapped files
seriously.  Note that the NeXT port's generic write call uses mapped
files, but that we've set a flag (close_flush) that ensures that all
dirty pages get flushed after every write call.  It is also something
of a performance hit, since it would be better to write those pages to
the cache asynchronously rather than after every write, as happens
now.