docs/32241: vm_page_alloc.9 rewrite

[Chad David]

>Number: 32241
>Category: docs
>Synopsis: vm_page_alloc.9 rewrite
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Fri Nov 23 21:40:01 PST 2001
>Closed-Date:
>Last-Modified:
>Originator: Chad David
>Release: FreeBSD 5.0-CURRENT i386
>Organization:
ACNS Inc.
>Environment:
System: FreeBSD colnta 4.4-STABLE FreeBSD 4.4-STABLE #9: Tue Nov 20 16:38:27 MST 2001 davidc@colnta:/mnt1/obj/usr/src/sys/COLNTA i386

>Description:
The vm_page_alloc.9 man page is crap (I'm allowed to say that
because I wrote it).
>How-To-Repeat:
man vm_page_alloc
>Fix:
Apply this patch.

--- ../../src/share/man/man9/vm_page_alloc.9 Wed Jul 18 00:09:13 2001
+++ vm_page_alloc.9 Fri Nov 23 22:02:59 2001
@@ -31,7 +31,7 @@
.Os
.Sh NAME
.Nm vm_page_alloc
-.Nd "allocates a page for the object and index"
+.Nd "allocate a page for a vm_object"
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
@@ -41,34 +41,36 @@
.Sh DESCRIPTION
The
.Fn vm_page_alloc
-function allocates a page for
-.Fa pindex
-in the VM object
-.Fa object .
-It is assumed that a page has not already been allocated for
+function allocates a page at
.Fa pindex
-and
+within
.Fa object .
+It is assumed that a page has not already been allocated at
+.Fa pindex .
+The page returned is inserted into the object, but is not inserted
+into the pmap.
.Pp
-The
.Fn vm_page_alloc
-function will not block.
+will not block.
.Pp
Its arguments are:
.Bl -tag -width ".Fa page_req"
.It Fa object
The VM object to allocate the page for.
.It Fa pindex
-The index of the page that should be allocated.
+The index into the object at which the page should be inserted.
.It Fa page_req
A flag indicating how the page should be allocated.
.Bl -tag -width ".Dv VM_ALLOC_INTERRUPT"
.It Dv VM_ALLOC_NORMAL
The page should be allocated with no special treatment.
.It Dv VM_ALLOC_SYSTEM
-The page can be allocated even if the buffer cache queue is empty
-and the free count is above the interrupt reserved water mark.
-This should be used only when the system really needs the page.
+The page can be allocated if the cache is empty and the free page
+count is above the interrupt reserved water mark. If
+.Dv VM_ALLOC_INTERRUPT
+is set the page can be allocated as long as the free page count is
+greater than zero.
+This flag should be used only when the system really needs the page.
.It Dv VM_ALLOC_INTERRUPT
.Fn vm_page_alloc
is being called during an interrupt and therefore the cache cannot

>Release-Note:
>Audit-Trail:
>Unformatted:

To Unsubscribe: send mail to majo...@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message