Having had to spend several hours today figuring out just what it is that

VOP_GETPAGES() is supposed to do, share the results with everyone who isn't
Alan Cox.

1 files changed, 101 insertions, 11 deletions

diff --git a/share/man/man9/VOP_GETPAGES.9 b/share/man/man9/VOP_GETPAGES.9
index d8135fb..4df198c 100644
--- a/share/man/man9/VOP_GETPAGES.9
+++ b/share/man/man9/VOP_GETPAGES.9
@@ -1,6 +1,7 @@
 .\" -*- nroff -*-
 .\"
 .\" Copyright (c) 1996 Doug Rabson
+.\" Copyright 2003, Garrett A. Wollman
 .\"
 .\" All rights reserved.
 .\"
@@ -28,7 +29,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 24, 1996
+.Dd September 27, 2003
 .Os
 .Dt VOP_GETPAGES 9
 .Sh NAME
@@ -44,29 +45,118 @@
 .Ft int
 .Fn VOP_PUTPAGES "struct vnode *vp" "vm_page_t *m" "int count" "int sync" "int *rtvals" "vm_ooffset_t offset"
 .Sh DESCRIPTION
+The
+.Fn VOP_GETPAGES
+method is called to read in pages of virtual memory which are backed by
+ordinary files.
+If other adjacent pages are backed by adjacent regions of the same file,
+.Fn VOP_GETPAGES
+is requested to read those pages as well, although it is not required to
+do so.
+The
+.Fn VOP_PUTPAGES
+method does the converse; that is to say, it writes out adjacent dirty
+pages of virtual memory.
+.Pp
+On entry, the vnode lock is held but neither the page queue nor VM object
+locks are held.  Both methods return in the same state on both success and
+error returns.
+.Pp
 The arguments are:
 .Bl -tag -width reqpage
 .It Fa vp
 The file to access.
 .It Fa m
-A page ???
+Pointer to the first element of an array of contiguous pages representing a
+contiguous region of the file to be read or written.
 .It Fa count
-How many pages to access.
+The number of pages in the array.
 .It Fa sync
-Nonzero if the write should be synchronous.
+.Dv VM_PAGER_PUT_SYNC
+if the write should be synchronous.
 .It Fa rtvals
-???
+An array of VM system result codes indicating the status of each
+page written by
+.Fn VOP_PUTPAGES .
 .It Fa reqpage
-???
+The index in the page array of the requested page; i.e., the one page which
+the implementation of this method must handle.
 .It Fa offset
-Offset in the file to start accessing.
+Offset in the file at which the mapped pages begin.
+.El
+.Pp
+The status of the
+.Fn VOP_PUTPAGES
+method is returned on a page-by-page basis in the array 
+.Fa rtvals[] .
+The possible status values are as follows:
+.Bl -tag -width VM_PAGER_ERROR
+.It Dv VM_PAGER_OK
+The page was successfully written.
+The implementation must call
+.Xr vm_pager_undirty 9
+to mark the page as clean.
+.It Dv VM_PAGER_PEND
+The page was scheduled to be written asynchronously.
+When the write completes, the completion callback should
+call
+.Xr vm_object_pip_wakeup 9
+and
+.Xr vm_page_io_finish 9
+to clear the busy flag and awaken any other threads waiting for this page,
+in addition to calling
+.Xr vm_page_undirty 9 .
+.It Dv VM_PAGER_BAD
+The page was entirely beyond the end of the backing file.
+This condition should not be possible if the vnode's filesystem
+is correctly implemented.
+.It Dv VM_PAGER_ERROR
+The page could not be written because of an error on the underlying storage
+medium or protocol.
+.It Dv VM_PAGER_FAIL
+Treated identically to
+.Dv VM_PAGER_ERROR
+.It Dv VM_PAGER_AGAIN
+The page was not handled by this request.
 .El
 .Pp
-Not quite sure about this one.
+The
+.Fn VOP_GETPAGES
+method is expected to release any pages in
+.Fa m
+that it does not successfully handle, by calling
+.Xr vm_page_free 9 .
+When it succeeds,
+.Fn VOP_GETPAGES
+must set the valid bits appropriately, clear the dirty bit
+(using
+.Xr vm_page_undirty 9 ) ,
+either activate the page (if its wanted bit is set)
+or deactivate it (otherwise), and finally call
+.Xr vm_page_wakeup 9
+to arouse any threads currently waiting for the page to be faulted in,
+for each page read.
 .Sh RETURN VALUES
-Zero is returned on success, otherwise an error is returned.
+If it successfully reads 
+.Fa m[reqpage] ,
+.Fn VOP_GETPAGES
+returns
+.Dv VM_PAGER_OK ;
+otherwise,
+.Dv VM_PAGER_ERROR .
+By convention, the return value of
+.Fn VOP_PUTPAGES
+is
+.Fa rtvals[0] .
 .Sh SEE ALSO
+.Xr vm_object_pip_wakeup 9 ,
+.Xr vm_page_free 9 ,
+.Xr vm_page_io_finish 9 ,
+.Xr vm_page_undirty 9 ,
+.Xr vm_page_wakeup 9 ,
 .Xr vnode 9
 .Sh AUTHORS
-This man page was written by
-.An Doug Rabson .
+This manual page was written by
+.An Doug Rabson
+and then substantially rewritten by
+.An Garrett Wollman .