svn commit: r215659 - in stable/7: share/man/man9 sys/vm

[Alan Cox]

Author: alc
Date: Mon Nov 22 07:17:27 2010
New Revision: 215659
URL: http://svn.freebsd.org/changeset/base/215659

Log:
  MFC r204415, r204416, r209669
    Improve the comment and man page for vm_page_alloc().

Modified:
  stable/7/share/man/man9/vm_page_alloc.9
  stable/7/sys/vm/vm_page.c
Directory Properties:
  stable/7/share/man/man9/   (props changed)
  stable/7/sys/   (props changed)
  stable/7/sys/cddl/contrib/opensolaris/   (props changed)
  stable/7/sys/contrib/dev/acpica/   (props changed)
  stable/7/sys/contrib/pf/   (props changed)

Modified: stable/7/share/man/man9/vm_page_alloc.9
==============================================================================
--- stable/7/share/man/man9/vm_page_alloc.9	Mon Nov 22 07:00:47 2010	(r215658)
+++ stable/7/share/man/man9/vm_page_alloc.9	Mon Nov 22 07:17:27 2010	(r215659)
@@ -26,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 13, 2001
+.Dd July 3, 2010
 .Dt VM_PAGE_ALLOC 9
 .Os
 .Sh NAME
@@ -38,7 +38,7 @@
 .In vm/vm.h
 .In vm/vm_page.h
 .Ft vm_page_t
-.Fn vm_page_alloc "vm_object_t object" "vm_pindex_t pindex" "int page_req"
+.Fn vm_page_alloc "vm_object_t object" "vm_pindex_t pindex" "int req"
 .Sh DESCRIPTION
 The
 .Fn vm_page_alloc
@@ -48,46 +48,75 @@ 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.
+The page returned is inserted into the object, unless
+.Dv VM_ALLOC_NOOBJ
+is specified in the
+.Fa req .
+The page may exist in the vm object cache, in which case it will
+be reactivated instead, moving from the cache into the object page list.
 .Pp
 .Fn vm_page_alloc
-will not block.
+will not sleep.
 .Pp
 Its arguments are:
-.Bl -tag -width ".Fa page_req"
+.Bl -tag -width ".Fa object"
 .It Fa object
 The VM object to allocate the page for.
+The
+.Fa object
+must be locked if
+.Dv VM_ALLOC_NOOBJ
+is not specified.
 .It Fa pindex
 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.
+.It Fa req
+The bitwise-inclusive OR of a class and any optional flags indicating
+how the page should be allocated.
+.Pp
+Exactly one of the following classes must be specified:
 .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 if the cache queue is empty and the free
+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
-be accessed.
-The page will only be returned successfully if the free count is greater
+is being called during an interrupt.
+A page will be returned successfully if the free page count is greater
 than zero.
+.El
+.Pp
+The optional flags are:
+.Bl -tag -width ".Dv VM_ALLOC_IFNOTCACHED"
 .It Dv VM_ALLOC_ZERO
 Indicate a preference for a pre-zeroed page.
-There is no guarantee that the page thus returned will be zeroed, but
-it will be marked as such.
+There is no guarantee that the returned page will be zeroed, but it
+will have the
+.Dv PG_ZERO
+flag set if it is zeroed.
 .It Dv VM_ALLOC_NOOBJ
-The page is associated with an unmanaged memory region, that is, there
-is no backing VM object.
-This is typically used to allocate pages within the kernel virtual
-address space.
+Do not associate the allocated page with a vm object.
+The
+.Fa object
+argument is ignored.
+.It Dv VM_ALLOC_NOBUSY
+The returned page will not have the
+.Dv VPO_BUSY
+flag set.
+.It Dv VM_ALLOC_WIRED
+The returned page will be wired.
+.It Dv VM_ALLOC_IFCACHED
+Allocate the page only if it is cached.
+Otherwise, return
+.Dv NULL .
+.It Dv VM_ALLOC_IFNOTCACHED
+Only allocate the page if it is not cached in the
+.Fa object .
+If the page at the specified
+.Fa pindex
+is cached, NULL is returned instead.
 .El
 .El
 .Sh RETURN VALUES

Modified: stable/7/sys/vm/vm_page.c
==============================================================================
--- stable/7/sys/vm/vm_page.c	Mon Nov 22 07:00:47 2010	(r215658)
+++ stable/7/sys/vm/vm_page.c	Mon Nov 22 07:17:27 2010	(r215659)
@@ -1037,13 +1037,23 @@ vm_page_cache_transfer(vm_object_t orig_
  *	Allocate and return a memory cell associated
  *	with this VM object/offset pair.
  *
- *	page_req classes:
+ *	The caller must always specify an allocation class.
+ *
+ *	allocation classes:
  *	VM_ALLOC_NORMAL		normal process request
  *	VM_ALLOC_SYSTEM		system *really* needs a page
  *	VM_ALLOC_INTERRUPT	interrupt time request
- *	VM_ALLOC_ZERO		zero page
  *
- *	This routine may not block.
+ *	optional allocation flags:
+ *	VM_ALLOC_ZERO		prefer a zeroed page
+ *	VM_ALLOC_WIRED		wire the allocated page
+ *	VM_ALLOC_NOOBJ		page is not associated with a vm object
+ *	VM_ALLOC_NOBUSY		do not set the page busy
+ *	VM_ALLOC_IFCACHED	return page only if it is cached
+ *	VM_ALLOC_IFNOTCACHED	return NULL, do not reactivate if the page
+ *				is cached
+ *
+ *	This routine may not sleep.
  */
 vm_page_t
 vm_page_alloc(vm_object_t object, vm_pindex_t pindex, int req)