Author: jhb
Date: Wed Dec 14 22:22:19 2011
New Revision: 228509
URL: http://svn.freebsd.org/changeset/base/228509
Log:
Add a helper API to allow in-kernel code to map portions of shared memory
objects created by shm_open(2) into the kernel's address space. This
provides a convenient way for creating shared memory buffers between
userland and the kernel without requiring custom character devices.
Added:
head/share/man/man9/shm_map.9 (contents, props changed)
Modified:
head/share/man/man9/Makefile
head/sys/kern/uipc_shm.c
head/sys/sys/mman.h
Modified: head/share/man/man9/Makefile
==
--- head/share/man/man9/MakefileWed Dec 14 22:14:05 2011
(r228508)
+++ head/share/man/man9/MakefileWed Dec 14 22:22:19 2011
(r228509)
@@ -234,6 +234,7 @@ MAN=accept_filter.9 \
sema.9 \
sf_buf.9 \
sglist.9 \
+ shm_map.9 \
signal.9 \
sleep.9 \
sleepqueue.9 \
@@ -,6 +1112,7 @@ MLINKS+=sglist.9 sglist_alloc.9 \
sglist.9 sglist_reset.9 \
sglist.9 sglist_slice.9 \
sglist.9 sglist_split.9
+MLINKS+=shm_map.9 shm_unmap.9
MLINKS+=signal.9 cursig.9 \
signal.9 execsigs.9 \
signal.9 issignal.9 \
Added: head/share/man/man9/shm_map.9
==
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man9/shm_map.9 Wed Dec 14 22:22:19 2011
(r228509)
@@ -0,0 +1,187 @@
+.\
+.\ Copyright (c) 2011 Advanced Computing Technologies LLC
+.\ Written by: John H. Baldwin j...@freebsd.org
+.\ 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 December 14, 2011
+.Dt SHM_MAP 9
+.Os
+.Sh NAME
+.Nm shm_map ,
+.Nm shm_unmap
+.Nd map shared memory objects into the kernel's address space
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/mman.h
+.Ft int
+.Fn shm_map struct file *fp size_t size off_t offset void **memp
+.Ft int
+.Fn shm_unmap struct file *fp void *mem size_t size
+.Sh DESCRIPTION
+The
+.Nm shm_map
+and
+.Nm shm_unmap
+functions provide an API for mapping shared memory objects into the kernel.
+Shared memory objects are created by
+.Xr shm_open 2 .
+These objects can then be passed into the kernel via file descriptors.
+.Pp
+A shared memory object cannot be shrunk while it is mapped into the kernel.
+This is to avoid invalidating any pages that may be wired into the kernel's
+address space.
+Shared memory objects can still be grown while mapped into the kernel.
+.Pp
+To simplify the accounting needed to enforce the above requirement,
+callers of this API are required to unmap the entire region mapped by
+.Nm shm_map
+when calling
+.Nm shm_unmap .
+Unmapping only a portion of the region is not permitted.
+.Pp
+The
+.Nm shm_map
+function locates the shared memory object associated with the open file
+.Fa fp .
+It maps the region of that object described by
+.Fa offset
+and
+.Fa size
+into the kernel's address space.
+If it succeeds,
+.Fa *memp
+will be set to the start of the mapping.
+All pages for the range will be wired into memory upon successful return.
+.Pp
+The
+.Nm shm_unmap
+function unmaps a region previously mapped by
+.Nm shm_map .
+The
+.Fa mem
+argument should match the value previously returned in
+.Fa *memp ,
+and the
+.Fa size
+argument should match the value passed to
+.Nm shm_map .
+.Pp
+Note that
+.Nm shm_map
+will not hold an extra reference on the open file
+.Fa fp
+for the lifetime of the mapping.
+Instead,
+the calling code is required to do this if it wishes to use
+.Nm shm_unmap
+on the region in the future.
