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