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.Dd November 11, 2021 26.Dt VM_PAGE_BUSY 9 27.Os 28.Sh NAME 29.Nm vm_page_busied , 30.Nm vm_page_busy_downgrade , 31.Nm vm_page_busy_sleep , 32.Nm vm_page_sbusied , 33.Nm vm_page_sunbusy , 34.Nm vm_page_trysbusy , 35.Nm vm_page_tryxbusy , 36.Nm vm_page_xbusied , 37.Nm vm_page_xunbusy , 38.Nm vm_page_assert_sbusied , 39.Nm vm_page_assert_unbusied , 40.Nm vm_page_assert_xbusied 41.Nd protect page identity changes and page content references 42.Sh SYNOPSIS 43.In sys/param.h 44.In vm/vm.h 45.In vm/vm_page.h 46.Ft int 47.Fn vm_page_busied "vm_page_t m" 48.Ft void 49.Fn vm_page_busy_downgrade "vm_page_t m" 50.Ft bool 51.Fn vm_page_busy_sleep "vm_page_t m" "const char *msg" "int allocflags" 52.Ft int 53.Fn vm_page_sbusied "vm_page_t m" 54.Ft void 55.Fn vm_page_sunbusy "vm_page_t m" 56.Ft int 57.Fn vm_page_trysbusy "vm_page_t m" 58.Ft int 59.Fn vm_page_tryxbusy "vm_page_t m" 60.Ft int 61.Fn vm_page_xbusied "vm_page_t m" 62.Ft void 63.Fn vm_page_xunbusy "vm_page_t m" 64.Pp 65.Cd "options INVARIANTS" 66.Cd "options INVARIANT_SUPPORT" 67.Ft void 68.Fn vm_page_assert_sbusied "vm_page_t m" 69.Ft void 70.Fn vm_page_assert_unbusied "vm_page_t m" 71.Ft void 72.Fn vm_page_assert_xbusied "vm_page_t m" 73.Sh DESCRIPTION 74Page identity is usually protected by higher level locks like vm_object 75locks and vm page locks. 76However, sometimes it is not possible to hold such locks for the time 77necessary to complete the identity change. 78In such case the page can be exclusively busied by a thread which needs 79to own the identity for a certain amount of time. 80.Pp 81In other situations, threads do not need to change the identity of the 82page but they want to prevent other threads from changing the identity 83themselves. 84For example, when a thread wants to access or update page contents 85without a lock held the page is shared busied. 86.Pp 87Before busying a page the vm_object lock must be held. 88The same rule applies when a page is unbusied. 89This makes the vm_object lock a real busy interlock. 90.Pp 91The 92.Fn vm_page_busied 93function returns non-zero if the current thread busied 94.Fa m 95in either exclusive or shared mode. 96Returns zero otherwise. 97.Pp 98The 99.Fn vm_page_busy_downgrade 100function must be used to downgrade 101.Fa m 102from an exclusive busy state to a shared busy state. 103.Pp 104The 105.Fn vm_page_busy_sleep 106checks the busy state of the page 107.Fa m 108and puts the invoking thread to sleep if the page is busy. 109The VM object for the page must be locked. 110The 111.Fa allocflags 112parameter must be either 113.Dv 0 , 114in which case the function will sleep if the page is busied, 115or 116.Dv VM_ALLOC_IGN_SBUSY , 117in which case the function will sleep only if the page is exclusively 118busied. 119A return value of true indicates that the invoking thread was put to 120sleep and that the object was unlocked. 121A return value of false indicates that the invoking thread did not sleep 122and the object remains locked. 123The parameter 124.Fa msg 125is a string describing the sleep condition for userland tools. 126.Pp 127The 128.Fn vm_page_busied 129function returns non-zero if the current thread busied 130.Fa m 131in shared mode. 132Returns zero otherwise. 133.Pp 134The 135.Fn vm_page_sunbusy 136function shared unbusies 137.Fa m . 138.Pp 139The 140.Fn vm_page_trysbusy 141attempts to shared busy 142.Fa m . 143If the operation cannot immediately succeed 144.Fn vm_page_trysbusy 145returns 0, otherwise a non-zero value is returned. 146.Pp 147The 148.Fn vm_page_tryxbusy 149attempts to exclusive busy 150.Fa m . 151If the operation cannot immediately succeed 152.Fn vm_page_tryxbusy 153returns 0, otherwise a non-zero value is returned. 154.Pp 155The 156.Fn vm_page_xbusied 157function returns non-zero if the current thread busied 158.Fa m 159in exclusive mode. 160Returns zero otherwise. 161.Pp 162The 163.Fn vm_page_xunbusy 164function exclusive unbusies 165.Fa m . 166Assertions on the busy state allow kernels compiled with 167.Cd "options INVARIANTS" 168and 169.Cd "options INVARIANT_SUPPORT" 170to panic if they are not respected. 171.Pp 172The 173.Fn vm_page_assert_sbusied 174function panics if 175.Fa m 176is not shared busied. 177.Pp 178The 179.Fn vm_page_assert_unbusied 180function panics if 181.Fa m 182is not unbusied. 183.Pp 184The 185.Fn vm_page_assert_xbusied 186function panics if 187.Fa m 188is not exclusive busied. 189.Sh SEE ALSO 190.Xr vm_page_aflag 9 , 191.Xr vm_page_alloc 9 , 192.Xr vm_page_deactivate 9 , 193.Xr vm_page_free 9 , 194.Xr vm_page_grab 9 , 195.Xr vm_page_insert 9 , 196.Xr vm_page_lookup 9 , 197.Xr vm_page_rename 9 , 198.Xr VOP_GETPAGES 9 199