From owner-svn-src-all@FreeBSD.ORG Sat Jul 3 18:25:37 2010 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 833C4106566B; Sat, 3 Jul 2010 18:25:37 +0000 (UTC) (envelope-from alc@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 716408FC0C; Sat, 3 Jul 2010 18:25:37 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id o63IPb4U090050; Sat, 3 Jul 2010 18:25:37 GMT (envelope-from alc@svn.freebsd.org) Received: (from alc@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id o63IPbkT090047; Sat, 3 Jul 2010 18:25:37 GMT (envelope-from alc@svn.freebsd.org) Message-Id: <201007031825.o63IPbkT090047@svn.freebsd.org> From: Alan Cox Date: Sat, 3 Jul 2010 18:25:37 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r209669 - in head: share/man/man9 sys/vm X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 03 Jul 2010 18:25:37 -0000 Author: alc Date: Sat Jul 3 18:25:37 2010 New Revision: 209669 URL: http://svn.freebsd.org/changeset/base/209669 Log: Improve the comment and man page for vm_page_alloc(). Specifically, document one of the optional flags; clarify which of the flags are optional (and which are not), and remove mention of a restriction on the reclamation of cached pages that no longer holds since version 7. MFC after: 1 week Modified: head/share/man/man9/vm_page_alloc.9 head/sys/vm/vm_page.c Modified: head/share/man/man9/vm_page_alloc.9 ============================================================================== --- head/share/man/man9/vm_page_alloc.9 Sat Jul 3 18:19:59 2010 (r209668) +++ head/share/man/man9/vm_page_alloc.9 Sat Jul 3 18:25:37 2010 (r209669) @@ -26,7 +26,7 @@ .\" .\" $FreeBSD$ .\" -.Dd February 27, 2010 +.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 @@ -51,16 +51,15 @@ It is assumed that a page has not alread The page returned is inserted into the object, unless .Dv VM_ALLOC_NOOBJ is specified in the -.Fa page_req , -but is not inserted into a pmap. -The page may exists in the vm object cache, in which case it will +.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 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 @@ -70,40 +69,48 @@ must be locked if 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 by +There is no guarantee that the returned page will be zeroed, but it +will have the .Dv PG_ZERO -flag if it is zeroed. +flag set if it is zeroed. .It Dv VM_ALLOC_NOOBJ Do not associate the allocated page with a vm object. The .Fa object argument is ignored. .It Dv VM_ALLOC_NOBUSY -The page returned will not be busied. +The returned page will not have the +.Dv VPO_BUSY +flag set. .It Dv VM_ALLOC_WIRED -The returned page is 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 . Modified: head/sys/vm/vm_page.c ============================================================================== --- head/sys/vm/vm_page.c Sat Jul 3 18:19:59 2010 (r209668) +++ head/sys/vm/vm_page.c Sat Jul 3 18:25:37 2010 (r209669) @@ -1144,14 +1144,19 @@ 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 + * + * 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 *