1.\" 2.\" Copyright (c) 2013 EMC Corp. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 20.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 21.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 24.\" DAMAGE. 25.\" 26.\" $FreeBSD$ 27.Dd August 07, 2013 28.Dt VM_PAGE_BUSY 9 29.Os 30.Sh NAME 31.Nm vm_page_busied , 32.Nm vm_page_busy_downgrade , 33.Nm vm_page_busy_sleep , 34.Nm vm_page_sbusied , 35.Nm vm_page_sbusy , 36.Nm vm_page_sleep_if_busy , 37.Nm vm_page_sunbusy , 38.Nm vm_page_trysbusy , 39.Nm vm_page_tryxbusy , 40.Nm vm_page_xbusied , 41.Nm vm_page_xbusy , 42.Nm vm_page_xunbusy , 43.Nm vm_page_assert_sbusied , 44.Nm vm_page_assert_unbusied , 45.Nm vm_page_assert_xbusied 46.Nd protect page identity changes and page content references 47.Sh SYNOPSIS 48.In sys/param.h 49.In vm/vm.h 50.In vm/vm_page.h 51.Ft int 52.Fn vm_page_busied "vm_page_t m" 53.Ft void 54.Fn vm_page_busy_downgrade "vm_page_t m" 55.Ft void 56.Fn vm_page_busy_sleep "vm_page_t m" "const char *msg" 57.Ft int 58.Fn vm_page_sbusied "vm_page_t m" 59.Ft void 60.Fn vm_page_sbusy "vm_page_t m" 61.Ft int 62.Fn vm_page_sleep_if_busy "vm_page_t m" "const char *msg" 63.Ft void 64.Fn vm_page_sunbusy "vm_page_t m" 65.Ft int 66.Fn vm_page_trysbusy "vm_page_t m" 67.Ft int 68.Fn vm_page_tryxbusy "vm_page_t m" 69.Ft int 70.Fn vm_page_xbusied "vm_page_t m" 71.Ft void 72.Fn vm_page_xbusy "vm_page_t m" 73.Ft void 74.Fn vm_page_xunbusy "vm_page_t m" 75.Pp 76.Cd "options INVARIANTS" 77.Cd "options INVARIANT_SUPPORT" 78.Ft void 79.Fn vm_page_assert_sbusied "vm_page_t m" 80.Ft void 81.Fn vm_page_assert_unbusied "vm_page_t m" 82.Ft void 83.Fn vm_page_assert_xbusied "vm_page_t m" 84.Sh DESCRIPTION 85Page identity is usually protected by higher level locks like vm_object 86locks and vm page locks. 87However, sometimes it is not possible to hold such locks for the time 88necessary to complete the identity change. 89In such case the page can be exclusively busied by a thread which needs 90to own the identity for a certain amount of time. 91.Pp 92In other situations, threads do not need to change the identity of the 93page but they want to prevent other threads from changing the identity 94themselves. 95For example, when a thread wants to access or update page contents 96without a lock held the page is shared busied. 97.Pp 98Before busing a page the vm_object lock must be held. 99The same rule applies when a page is unbusied. 100This makes the vm_object lock a real busy interlock. 101.Pp 102The 103.Fn vm_page_busied 104function returns non-zero if the current thread busied 105.Fa m 106in either exclusive or shared mode. 107Returns zero otherwise. 108.Pp 109The 110.Fn vm_page_busy_downgrade 111function must be used to downgrade 112.Fa m 113from an exclusive busy state to a shared busy state. 114.Pp 115The 116.Fn vm_page_busy_sleep 117function puts the invoking thread to sleep using the appropriate 118waitchannels for the busy mechanism. 119The parameter 120.Fa msg 121is a string describing the sleep condition for userland tools. 122.Pp 123The 124.Fn vm_page_busied 125function returns non-zero if the current thread busied 126.Fa m 127in shared mode. 128Returns zero otherwise. 129.Pp 130The 131.Fn vm_page_sbusy 132function shared busies 133.Fa m . 134.Pp 135The 136.Fn vm_page_sleep_if_busy 137function puts the invoking thread to sleep, using the appropriate 138waitchannels for the busy mechanism, if 139.Fa m . 140is busied in either exclusive or shared mode. 141If the invoking thread slept a non-zero value is returned, otherwise 1420 is returned. 143The parameter 144.Fa msg 145is a string describing the sleep condition for userland tools. 146.Pp 147The 148.Fn vm_page_sunbusy 149function shared unbusies 150.Fa m . 151.Pp 152The 153.Fn vm_page_trysbusy 154attempts to shared busy 155.Fa m . 156If the operation cannot immediately succeed 157.Fn vm_page_trysbusy 158returns 0, otherwise a non-zero value is returned. 159.Pp 160The 161.Fn vm_page_tryxbusy 162attempts to exclusive busy 163.Fa m . 164If the operation cannot immediately succeed 165.Fn vm_page_tryxbusy 166returns 0, otherwise a non-zero value is returned. 167.Pp 168The 169.Fn vm_page_xbusied 170function returns non-zero if the current thread busied 171.Fa m 172in exclusive mode. 173Returns zero otherwise. 174.Pp 175The 176.Fn vm_page_xbusy 177function exclusive busies 178.Fa m . 179.Pp 180The 181.Fn vm_page_xunbusy 182function exclusive unbusies 183.Fa m . 184Assertions on the busy state allow kernels compiled with 185.Cd "options INVARIANTS" 186and 187.Cd "options INVARIANT_SUPPORT" 188to panic if they are not respected. 189.Pp 190The 191.Fn vm_page_assert_sbusied 192function panics if 193.Fa m 194is not shared busied. 195.Pp 196The 197.Fn vm_page_assert_unbusied 198function panics if 199.Fa m 200is not unbusied. 201.Pp 202The 203.Fn vm_page_assert_xbusied 204function panics if 205.Fa m 206is not exclusive busied. 207.Sh SEE ALSO 208.Xr VOP_GETPAGES 9 , 209.Xr vm_page_aflag 9 , 210.Xr vm_page_alloc 9 , 211.Xr vm_page_deactivate 9 , 212.Xr vm_page_free 9 , 213.Xr vm_page_grab 9 , 214.Xr vm_page_insert 9 , 215.Xr vm_page_lookup 9 , 216.Xr vm_page_rename 9 217