From owner-svn-src-head@FreeBSD.ORG Fri Jul 12 14:25:58 2013 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id CD5B3CD4; Fri, 12 Jul 2013 14:25:58 +0000 (UTC) (envelope-from glebius@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id BE0BB1969; Fri, 12 Jul 2013 14:25:58 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r6CEPwmq028396; Fri, 12 Jul 2013 14:25:58 GMT (envelope-from glebius@svn.freebsd.org) Received: (from glebius@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r6CEPwjV028394; Fri, 12 Jul 2013 14:25:58 GMT (envelope-from glebius@svn.freebsd.org) Message-Id: <201307121425.r6CEPwjV028394@svn.freebsd.org> From: Gleb Smirnoff Date: Fri, 12 Jul 2013 14:25:58 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r253267 - 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: Fri, 12 Jul 2013 14:25:58 -0000 Author: glebius Date: Fri Jul 12 14:25:58 2013 New Revision: 253267 URL: http://svnweb.freebsd.org/changeset/base/253267 Log: Add manual page for vmem(9). Obtained from NetBSD, modified to match our implementation. Obtained from: NetBSD Added: head/share/man/man9/vmem.9 (contents, props changed) Modified: head/share/man/man9/Makefile Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Fri Jul 12 14:24:52 2013 (r253266) +++ head/share/man/man9/Makefile Fri Jul 12 14:25:58 2013 (r253267) @@ -339,6 +339,7 @@ MAN= accept_filter.9 \ vm_page_wakeup.9 \ vm_page_wire.9 \ vm_set_page_size.9 \ + vmem.9 \ vn_fullpath.9 \ vn_isdisk.9 \ vnode.9 \ Added: head/share/man/man9/vmem.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/vmem.9 Fri Jul 12 14:25:58 2013 (r253267) @@ -0,0 +1,323 @@ +.\" $NetBSD: vmem.9,v 1.15 2013/01/29 22:02:17 wiz Exp $ +.\" +.\" Copyright (c)2006 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.\" ------------------------------------------------------------ +.Dd July 12, 2013 +.Dt VMEM 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm vmem +.Nd general purpose resource allocator +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/vmem.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft vmem_t * +.Fn vmem_create \ +"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \ +"vmem_size_t qcache_max" "int flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_add \ +"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "int flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_xalloc \ +"vmem_t *vm" "const vmem_size_t size" "vmem_size_t align" \ +"const vmem_size_t phase" "const vmem_size_t nocross" \ +"const vmem_addr_t minaddr" "const vmem_addr_t maxaddr" "int flags" \ +"vmem_addr_t *addrp" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "int flags" "vmem_addr_t *addrp" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_free "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_destroy "vmem_t *vm" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Nm +is a general purpose resource allocator. +Despite its name, it can be used for arbitrary resources +other than virtual memory. +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_create +creates a new vmem arena. +.Pp +.Bl -tag -width qcache_max +.It Fa name +The string to describe the vmem. +.It Fa base +The start address of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa size +The size of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa quantum +The smallest unit of allocation. +.It Fa qcache_max +The largest size of allocations which can be served by quantum cache. +It is merely a hint and can be ignored. +.It Fa flags +Combination of +.Xr malloc 9 +wait flag and +.Nm +allocation strategy flag: +.Bl -tag -width M_FIRSTFIT +.It Dv M_FIRSTFIT +Prefer allocation performance. +.It Dv M_BESTFIT +Prefer space efficiency. +.El +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_add +adds a span of size +.Fa size +starting at +.Fa addr +to the arena. +Returns +0 +on success, +.Dv ENOMEM +on failure. +.Fa flags +is +.Xr malloc 9 +wait flag. +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_xalloc +allocates a resource from the arena. +.Pp +.Bl -tag -width nocross +.It Fa vm +The arena which we allocate from. +.It Fa size +Specify the size of the allocation. +.It Fa align +If zero, don't care about the alignment of the allocation. +Otherwise, request a resource segment starting at +offset +.Fa phase +from an +.Fa align +aligned boundary. +.It Fa phase +See the above description of +.Fa align . +If +.Fa align +is zero, +.Fa phase +should be zero. +Otherwise, +.Fa phase +should be smaller than +.Fa align . +.It Fa nocross +Request a resource which doesn't cross +.Fa nocross +aligned boundary. +.It Fa minaddr +Specify the minimum address which can be allocated, or +.Dv VMEM_ADDR_MIN +if the caller does not care. +.It Fa maxaddr +Specify the maximum address which can be allocated, or +.Dv VMEM_ADDR_MAX +if the caller does not care. +.It Fa flags +A bitwise OR of an allocation strategy and a +.Xr malloc 8 +wait flag. +The allocation strategy is one of +.Dv M_FIRSTFIT +and +.Dv M_BESTFIT . +.It Fa addrp +On success, if +.Fa addrp +is not +.Dv NULL , +.Fn vmem_xalloc +overwrites it with the start address of the allocated span. +.El +.Pp +.\" ------------------------------------------------------------ +.Fn vmem_xfree +frees resource allocated by +.Fn vmem_xalloc +to the arena. +.Pp +.Bl -tag -width addr +.It Fa vm +The arena which we free to. +.It Fa addr +The resource being freed. +It must be the one returned by +.Fn vmem_xalloc . +Notably, it must not be the one from +.Fn vmem_alloc . +Otherwise, the behaviour is undefined. +.It Fa size +The size of the resource being freed. +It must be the same as the +.Fa size +argument used for +.Fn vmem_xalloc . +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_alloc +allocates a resource from the arena. +.Pp +.Bl -tag -width flags +.It Fa vm +The arena which we allocate from. +.It Fa size +Specify the size of the allocation. +.It Fa flags +A bitwise OR of an +.Nm +allocation strategy flag (see above) and a +.Xr malloc 9 +sleep flag. +.It Fa addrp +On success, if +.Fa addrp +is not +.Dv NULL , +.Fn vmem_alloc +overwrites it with the start address of the allocated span. +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_free +frees resource allocated by +.Fn vmem_alloc +to the arena. +.Pp +.Bl -tag -width addr +.It Fa vm +The arena which we free to. +.It Fa addr +The resource being freed. +It must be the one returned by +.Fn vmem_alloc . +Notably, it must not be the one from +.Fn vmem_xalloc . +Otherwise, the behaviour is undefined. +.It Fa size +The size of the resource being freed. +It must be the same as the +.Fa size +argument used for +.Fn vmem_alloc . +.El +.Pp +.\" ------------------------------------------------------------ +.Fn vmem_destroy +destroys a vmem arena. +.Pp +.Bl -tag -width vm +.It Fa vm +The vmem arena being destroyed. +The caller should ensure that no one will use it anymore. +.El +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +.Fn vmem_create +returns a pointer to the newly allocated vmem_t. +Otherwise, it returns +.Dv NULL . +.Pp +On success, +.Fn vmem_xalloc +and +.Fn vmem_alloc +return 0. +Otherwise, +.Dv ENOMEM +is returned. +.\" ------------------------------------------------------------ +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented within the file +.Pa sys/kern/subr_vmem.c . +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr malloc 9 +.Rs +.%A Jeff Bonwick +.%A Jonathan Adams +.%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources" +.%J "2001 USENIX Annual Technical Conference" +.%D 2001 +.Re +.\" ------------------------------------------------------------ +.Sh HISTORY +The +.Nm +allocator was originally implemented in +.Nx . +It was introduced in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +Original implementation of +.Nm +was written by +.An "YAMAMOTO Takashi" . +The +.Fx +port was made by +.An "Jeff Roberson" . +.Sh BUGS +.Pp +.Nm +relies on +.Xr malloc 9 , +so it cannot be used as early during system bootstrap as +.Xr extent 9 .