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.
This commit is contained in:
wollman 2003-09-28 03:15:21 +00:00
parent 13a44c8d5a
commit da6db53ccd

View File

@ -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
Not quite sure about this one.
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
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 .