diff options
author | wollman <wollman@FreeBSD.org> | 2003-09-28 03:15:21 +0000 |
---|---|---|
committer | wollman <wollman@FreeBSD.org> | 2003-09-28 03:15:21 +0000 |
commit | da6db53ccdc0838347d369c0fa4f2ae0cca449c2 (patch) | |
tree | 00339cd6483f94180445fcd0160a090df110bad5 /share | |
parent | 13a44c8d5af83073f39cf4d875c8e6a858323316 (diff) | |
download | FreeBSD-src-da6db53ccdc0838347d369c0fa4f2ae0cca449c2.zip FreeBSD-src-da6db53ccdc0838347d369c0fa4f2ae0cca449c2.tar.gz |
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.
Diffstat (limited to 'share')
-rw-r--r-- | share/man/man9/VOP_GETPAGES.9 | 112 |
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 . |