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:
Garrett Wollman
parent
79fa677d99
commit
43b5281bad
@ -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 .
|
||||
|
||||
Loading…
Reference in New Issue
Block a user