From owner-svn-src-head@FreeBSD.ORG Thu Sep 12 19:51:41 2013 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id 270A0DC8; Thu, 12 Sep 2013 19:51:41 +0000 (UTC) (envelope-from jhb@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 12EEB227E; Thu, 12 Sep 2013 19:51:41 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r8CJpeeC070191; Thu, 12 Sep 2013 19:51:40 GMT (envelope-from jhb@svn.freebsd.org) Received: (from jhb@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r8CJpebt070189; Thu, 12 Sep 2013 19:51:40 GMT (envelope-from jhb@svn.freebsd.org) Message-Id: <201309121951.r8CJpebt070189@svn.freebsd.org> From: John Baldwin Date: Thu, 12 Sep 2013 19:51:40 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r255495 - head/share/man/man9 X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 12 Sep 2013 19:51:41 -0000 Author: jhb Date: Thu Sep 12 19:51:40 2013 New Revision: 255495 URL: http://svnweb.freebsd.org/changeset/base/255495 Log: Document several recent changes to vm_map_find(9): - Document the max_addr parameter that restricts mappings to a subset of the map's address space. - Document VMFS_ALIGNED_SPACE and update for the rename of VMFS_SUPER_SPACE. In addition, use a table that describes the different find space strategies in more detail. Reviewed by: alc Approved by: re (kib) Modified: head/share/man/man9/vm_map_find.9 Modified: head/share/man/man9/vm_map_find.9 ============================================================================== --- head/share/man/man9/vm_map_find.9 Thu Sep 12 19:36:04 2013 (r255494) +++ head/share/man/man9/vm_map_find.9 Thu Sep 12 19:51:40 2013 (r255495) @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd May 10, 2008 +.Dd September 12, 2013 .Dt VM_MAP_FIND 9 .Os .Sh NAME @@ -38,8 +38,8 @@ .Ft int .Fo vm_map_find .Fa "vm_map_t map" "vm_object_t object" "vm_ooffset_t offset" -.Fa "vm_offset_t *addr" "vm_size_t length" "int find_space" -.Fa "vm_prot_t prot" "vm_prot_t max" "int cow" +.Fa "vm_offset_t *addr" "vm_size_t length" "vm_offset_t max_addr" +.Fa "int find_space" "vm_prot_t prot" "vm_prot_t max" "int cow" .Fc .Sh DESCRIPTION The @@ -47,9 +47,13 @@ The function attempts to find a free region in the target .Fa map , with the given -.Fa length , -and will also optionally create a mapping of -.Fa object . +.Fa length. +If a free region is found, +.Fn vm_map_find +creates a mapping of +.Fa object +via a call to +.Xr vm_map_insert 9 . .Pp The arguments .Fa offset , @@ -69,26 +73,56 @@ the reference count on the object must b by the caller before calling this function to account for the new entry. .Pp If +.Fa max_addr +is non-zero, +it specifies an upper bound on the mapping. +The mapping will only succeed if a free region can be found that resides +entirely below +.Fa max_addr . +.Pp +The .Fa find_space -is either -.Dv VMFS_ALIGNED_SPACE -or -.Dv VMFS_ANY_SPACE , -the function will call +argument specifies the strategy to use when searching for a free region of +the requested length. +For all values other than +.Dv VMFS_NO_SPACE , .Xr vm_map_findspace 9 -to discover a free region. -Moreover, if -.Fa find_space +is called to locate a free region of the requested length with a starting +address at or above +.Fa *addr . +The following strategies are supported: +.Bl -tag -width Dv VMFS_ALIGNED_SPACE Ns Pq Fa n +.It Dv VMFS_NO_SPACE +The mapping will only succeed if there is a free region of the requested +length at the given address +.Fa *addr . +.It Dv VMFS_ANY_SPACE +The mapping will succeed as long as there is a free region. +.It Dv VMFS_SUPER_SPACE +The mapping will succeed as long as there is a free region that begins on +a superpage boundary. +If +.Fa object is -.Dv VMFS_ALIGNED_SPACE , -the address of the free region will be optimized for the use of superpages. -Otherwise, if -.Fa find_space +.Pf non- Dv NULL +and is already backed by superpages, +then the mapping will require a free region that aligns relative to the +existing superpages rather than one beginning on a superpage boundary. +.It Dv VMFS_OPTIMAL_SPACE +The mapping will succeed as long as there is a free region. +However, if +.Fa object is -.Dv VMFS_NO_SPACE , -.Xr vm_map_insert 9 -is called with the given address, -.Fa addr . +.Pf non- Dv NULL +and is already backed by superpages, +this strategy will attempt to find a free region aligned relative to +the existing superpages. +.It Dv VMFS_ALIGNED_SPACE Ns Pq Fa n +The mapping will succeed as long as there is a free region that aligns on +a +.Pf 2^ Fa n +boundary. +.El .Sh IMPLEMENTATION NOTES This function acquires a lock on .Fa map