svn commit: r254078 - user/attilio/vmobj-readlock/share/man/man9

Attilio Rao attilio at FreeBSD.org
Wed Aug 7 22:37:06 UTC 2013 

Author: attilio
Date: Wed Aug  7 22:37:05 2013
New Revision: 254078
URL: http://svnweb.freebsd.org/changeset/base/254078

Log:
  - Garbage collect pages and entries not relevant anymore
  - Introduce a new manpage for the new busy mechanism
  
  Sponsored by:	EMC / Isilon storage division
  Partially reviewed by:	jeff

Added:
  user/attilio/vmobj-readlock/share/man/man9/vm_page_busy.9   (contents, props changed)
Deleted:
  user/attilio/vmobj-readlock/share/man/man9/vm_page_io.9
  user/attilio/vmobj-readlock/share/man/man9/vm_page_sleep_if_busy.9
  user/attilio/vmobj-readlock/share/man/man9/vm_page_wakeup.9
Modified:
  user/attilio/vmobj-readlock/share/man/man9/Makefile
  user/attilio/vmobj-readlock/share/man/man9/VOP_GETPAGES.9
  user/attilio/vmobj-readlock/share/man/man9/vm_page_alloc.9

Modified: user/attilio/vmobj-readlock/share/man/man9/Makefile
==============================================================================
--- user/attilio/vmobj-readlock/share/man/man9/Makefile	Wed Aug  7 22:21:00 2013	(r254077)
+++ user/attilio/vmobj-readlock/share/man/man9/Makefile	Wed Aug  7 22:37:05 2013	(r254078)
@@ -332,11 +332,8 @@ MAN=	accept_filter.9 \
 	vm_page_grab.9 \
 	vm_page_hold.9 \
 	vm_page_insert.9 \
-	vm_page_io.9 \
 	vm_page_lookup.9 \
 	vm_page_rename.9 \
-	vm_page_sleep_if_busy.9 \
-	vm_page_wakeup.9 \
 	vm_page_wire.9 \
 	vm_set_page_size.9 \
 	vmem.9 \
@@ -1465,6 +1462,21 @@ MLINKS+=vm_page_bits.9 vm_page_clear_dir
 	vm_page_bits.9 vm_page_test_dirty.9 \
 	vm_page_bits.9 vm_page_undirty.9 \
 	vm_page_bits.9 vm_page_zero_invalid.9
+MLINKS+=vm_page_busy.9 vm_page_busied.9 \
+	vm_page_busy.9 vm_page_busy_downgrade.9 \
+	vm_page_busy.9 vm_page_busy_sleep.9 \
+	vm_page_busy.9 vm_page_sbusied.9 \
+	vm_page_busy.9 vm_page_sbusy.9 \
+	vm_page_busy.9 vm_page_sleep_if_busy.9 \
+	vm_page_busy.9 vm_page_sunbusy.9 \
+	vm_page_busy.9 vm_page_trysbusy.9 \
+	vm_page_busy.9 vm_page_tryxbusy.9 \
+	vm_page_busy.9 vm_page_xbusied.9 \
+	vm_page_busy.9 vm_page_xbusy.9 \
+	vm_page_busy.9 vm_page_xunbusy.9 \
+	vm_page_busy.9 vm_page_assert_sbusied.9 \
+	vm_page_busy.9 vm_page_assert_unbusied.9 \
+	vm_page_busy.9 vm_page_assert_xbusied.9
 MLINKS+=vm_page_aflag.9 vm_page_aflag_clear.9 \
 	vm_page_aflag.9 vm_page_aflag_set.9 \
 	vm_page_aflag.9 vm_page_reference.9
@@ -1473,10 +1485,6 @@ MLINKS+=vm_page_free.9 vm_page_free_toq.
 	vm_page_free.9 vm_page_try_to_free.9
 MLINKS+=vm_page_hold.9 vm_page_unhold.9
 MLINKS+=vm_page_insert.9 vm_page_remove.9
-MLINKS+=vm_page_io.9 vm_page_io_finish.9 \
-	vm_page_io.9 vm_page_io_start.9
-MLINKS+=vm_page_wakeup.9 vm_page_busy.9 \
-	vm_page_wakeup.9 vm_page_flash.9
 MLINKS+=vm_page_wire.9 vm_page_unwire.9
 MLINKS+=VOP_ACCESS.9 VOP_ACCESSX.9
 MLINKS+=VOP_ATTRIB.9 VOP_GETATTR.9 \

Modified: user/attilio/vmobj-readlock/share/man/man9/VOP_GETPAGES.9
==============================================================================
--- user/attilio/vmobj-readlock/share/man/man9/VOP_GETPAGES.9	Wed Aug  7 22:21:00 2013	(r254077)
+++ user/attilio/vmobj-readlock/share/man/man9/VOP_GETPAGES.9	Wed Aug  7 22:37:05 2013	(r254078)
@@ -102,7 +102,7 @@ When the write completes, the completion
 call
 .Xr vm_object_pip_wakeup 9
 and
-.Xr vm_page_io_finish 9
+.Xr vm_page_sunbusy 9
 to clear the busy flag and awaken any other threads waiting for this page,
 in addition to calling
 .Xr vm_page_undirty 9 .
@@ -139,7 +139,7 @@ For example,
 .Fn VOP_GETPAGES
 may either activate a page (if its wanted bit is set)
 or deactivate it (otherwise), and finally call
-.Xr vm_page_wakeup 9
+.Xr vm_page_xunbusy 9
 to arouse any threads currently waiting for the page to be faulted in.
 .Sh RETURN VALUES
 If it successfully reads
@@ -156,9 +156,9 @@ is
 .Sh SEE ALSO
 .Xr vm_object_pip_wakeup 9 ,
 .Xr vm_page_free 9 ,
-.Xr vm_page_io_finish 9 ,
+.Xr vm_pagge_sunbusy 9 ,
 .Xr vm_page_undirty 9 ,
-.Xr vm_page_wakeup 9 ,
+.Xr vm_page_xunbusy 9 ,
 .Xr vnode 9
 .Sh AUTHORS
 This manual page was written by

Modified: user/attilio/vmobj-readlock/share/man/man9/vm_page_alloc.9
==============================================================================
--- user/attilio/vmobj-readlock/share/man/man9/vm_page_alloc.9	Wed Aug  7 22:21:00 2013	(r254077)
+++ user/attilio/vmobj-readlock/share/man/man9/vm_page_alloc.9	Wed Aug  7 22:37:05 2013	(r254078)
@@ -91,9 +91,7 @@ than zero.
 The optional flags are:
 .Bl -tag -width ".Dv VM_ALLOC_IFNOTCACHED"
 .It Dv VM_ALLOC_NOBUSY
-The returned page will not have the
-.Dv VPO_BUSY
-flag set.
+The returned page will not be exclusive busy.
 .It Dv VM_ALLOC_NODUMP
 The returned page will not be included in any kernel core dumps
 regardless of whether or not it is mapped in to KVA.
@@ -112,6 +110,8 @@ Only allocate the page if it is not cach
 If the page at the specified
 .Fa pindex
 is cached, NULL is returned instead.
+.It Dv VM_ALLOC_SBUSY
+The returned page will be shared busy.
 .It Dv VM_ALLOC_WIRED
 The returned page will be wired.
 .It Dv VM_ALLOC_ZERO

Added: user/attilio/vmobj-readlock/share/man/man9/vm_page_busy.9
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ user/attilio/vmobj-readlock/share/man/man9/vm_page_busy.9	Wed Aug  7 22:37:05 2013	(r254078)
@@ -0,0 +1,216 @@
+.\"
+.\" Copyright (c) 2013 EMC Corp.
+.\" 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 August 07, 2013
+.Dt vm_page_busy 9
+.Os
+.Sh NAME
+.Nm vm_page_busied ,
+.Nm vm_page_busy_downgrade ,
+.Nm vm_page_busy_sleep ,
+.Nm vm_page_sbusied ,
+.Nm vm_page_sbusy ,
+.Nm vm_page_sleep_if_busy ,
+.Nm vm_page_sunbusy ,
+.Nm vm_page_trysbusy ,
+.Nm vm_page_tryxbusy ,
+.Nm vm_page_xbusied ,
+.Nm vm_page_xbusy ,
+.Nm vm_page_xunbusy ,
+.Nm vm_page_assert_sbusied ,
+.Nm vm_page_assert_unbusied ,
+.Nm vm_page_assert_xbusied
+.Nd protect page identity changes and page content references
+.Sh SYNOPSIS
+.In sys/param.h
+.In vm/vm.h
+.In vm/vm_page.h
+.Ft int
+.Fn vm_page_busied "vm_page_t m"
+.Ft void
+.Fn vm_page_busy_downgrade "vm_page_t m"
+.Ft void
+.Fn vm_page_busy_sleep "vm_page_t m" "const char *msg"
+.Ft int
+.Fn vm_page_sbusied "vm_page_t m"
+.Ft void
+.Fn vm_page_sbusy "vm_page_t m"
+.Ft int
+.Fn vm_page_sleep_if_busy "vm_page_t m" "const char *msg"
+.Ft void
+.Fn vm_page_sunbusy "vm_page_t m"
+.Ft int
+.Fn vm_page_trysbusy "vm_page_t m"
+.Ft int
+.Fn vm_page_tryxbusy "vm_page_t m"
+.Ft int
+.Fn vm_page_xbusied "vm_page_t m"
+.Ft void
+.Fn vm_page_xbusy "vm_page_t m"
+.Ft void
+.Fn vm_page_xunbusy "vm_page_t m"
+.Pp
+.Cd "options INVARIANTS"
+.Cd "options INVARIANT_SUPPORT"
+.Ft void
+.Fn vm_page_assert_sbusied "vm_page_t m"
+.Ft void
+.Fn vm_page_assert_unbusied "vm_page_t m"
+.Ft void
+.Fn vm_page_assert_xbusied "vm_page_t m"
+.Sh DESCRIPTION
+Page identity is usually protected by higher level locks like vm_object
+locks and vm page locks.
+However, sometimes it is not possible to hold such locks for the time
+necessary to complete the identity change.
+In such case the page can be exclusively busied by a thread which needs
+to own the identity for a certain amount of time.
+.Pp
+In other situations, threads do not need to change the identity of the
+page but they want to prevent other threads from changing the identity
+themselves.
+For example, when a thread wants to access or update page contents
+without a lock held the page is shared busied.
+.Pp
+Before busing a page the vm_object lock must be held.
+The same rule applies when a page is unbusied.
+This makes the vm_object lock a real busy interlock.
+.Pp
+The
+.Fn vm_page_busied
+function returns non-zero if the current thread busied
+.Fa m
+in either exclusive or shared mode.
+Returns zero otherwise.
+.Pp
+The
+.Fn vm_page_busy_downgrade
+function must be used to downgrade
+.Fa m
+from an exclusive busy state to a shared busy state.
+.Pp
+The
+.Fn vm_page_busy_sleep
+function puts the invoking thread to sleep using the appropriate
+waitchannels for the busy mechanism.
+The parameter
+.Fa msg
+is a string describing the sleep condition for userland tools.
+.Pp
+The
+.Fn vm_page_busied
+function returns non-zero if the current thread busied
+.Fa m
+in shared mode.
+Returns zero otherwise.
+.Pp
+The
+.Fn vm_page_sbusy
+function shared busies
+.Fa m .
+.Pp
+The
+.Fn vm_page_sleep_if_busy
+function puts the invoking thread to sleep, using the appropriate
+waitchannels for the busy mechanism, if
+.Fa m .
+is busied in either exclusive or shared mode.
+If the invoking thread slept a non-zero value is returned, otherwise
+0 is returned.
+The parameter
+.Fa msg
+is a string describing the sleep condition for userland tools.
+.Pp
+The
+.Fn vm_page_sunbusy
+function shared unbusies
+.Fa m .
+.Pp
+The
+.Fn vm_page_trysbusy
+attempts to shared busy
+.Fa m .
+If the operation cannot immediately succeed
+.Fn vm_page_trysbusy
+returns 0, otherwise a non-zero value is returned.
+.Pp
+The
+.Fn vm_page_tryxbusy
+attempts to exclusive busy
+.Fa m .
+If the operation cannot immediately succeed
+.Fn vm_page_tryxbusy
+returns 0, otherwise a non-zero value is returned.
+.Pp
+The
+.Fn vm_page_xbusied
+function returns non-zero if the current thread busied
+.Fa m
+in exclusive mode.
+Returns zero otherwise.
+.Pp
+The
+.Fn vm_page_xbusy
+function exclusive busies
+.Fa m .
+.Pp
+The
+.Fn vm_page_xunbusy
+function exclusive unbusies
+.Fa m .
+Assertions on the busy state allow kernels compiled with
+.Cd "options INVARIANTS"
+and
+.Cd "options INVARIANT_SUPPORT"
+to panic if they are not respected.
+.Pp
+The
+.Fn vm_page_assert_sbusied
+function panics if
+.Fa m
+is not shared busied.
+.Pp
+The
+.Fn vm_page_assert_unbusied
+function panics if
+.Fa m
+is not unbusied.
+.Pp
+The
+.Fn vm_page_assert_xbusied
+function panics if
+.Fa m
+is not exclusive busied.
+.Sh SEE ALSO
+.Xr VOP_GETPAGES 9 ,
+.Xr vm_page_aflag 9 ,
+.Xr vm_page_alloc 9 ,
+.Xr vm_page_deactivate 9 ,
+.Xr vm_page_free 9 ,
+.Xr vm_page_grab 9 ,
+.Xr vm_page_insert 9 ,
+.Xr vm_page_lookup 9 ,
+.Xr vm_page_rename 9

More information about the svn-src-user mailing list