2 .\" Copyright (c) 2013 EMC Corp.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nm vm_page_busy_downgrade ,
33 .Nm vm_page_busy_sleep ,
36 .Nm vm_page_sleep_if_busy ,
38 .Nm vm_page_trysbusy ,
39 .Nm vm_page_tryxbusy ,
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
52 .Fn vm_page_busied "vm_page_t m"
54 .Fn vm_page_busy_downgrade "vm_page_t m"
56 .Fn vm_page_busy_sleep "vm_page_t m" "const char *msg"
58 .Fn vm_page_sbusied "vm_page_t m"
60 .Fn vm_page_sbusy "vm_page_t m"
62 .Fn vm_page_sleep_if_busy "vm_page_t m" "const char *msg"
64 .Fn vm_page_sunbusy "vm_page_t m"
66 .Fn vm_page_trysbusy "vm_page_t m"
68 .Fn vm_page_tryxbusy "vm_page_t m"
70 .Fn vm_page_xbusied "vm_page_t m"
72 .Fn vm_page_xbusy "vm_page_t m"
74 .Fn vm_page_xunbusy "vm_page_t m"
76 .Cd "options INVARIANTS"
77 .Cd "options INVARIANT_SUPPORT"
79 .Fn vm_page_assert_sbusied "vm_page_t m"
81 .Fn vm_page_assert_unbusied "vm_page_t m"
83 .Fn vm_page_assert_xbusied "vm_page_t m"
85 Page identity is usually protected by higher level locks like vm_object
86 locks and vm page locks.
87 However, sometimes it is not possible to hold such locks for the time
88 necessary to complete the identity change.
89 In such case the page can be exclusively busied by a thread which needs
90 to own the identity for a certain amount of time.
92 In other situations, threads do not need to change the identity of the
93 page but they want to prevent other threads from changing the identity
95 For example, when a thread wants to access or update page contents
96 without a lock held the page is shared busied.
98 Before busing a page the vm_object lock must be held.
99 The same rule applies when a page is unbusied.
100 This makes the vm_object lock a real busy interlock.
104 function returns non-zero if the current thread busied
106 in either exclusive or shared mode.
107 Returns zero otherwise.
110 .Fn vm_page_busy_downgrade
111 function must be used to downgrade
113 from an exclusive busy state to a shared busy state.
116 .Fn vm_page_busy_sleep
117 function puts the invoking thread to sleep using the appropriate
118 waitchannels for the busy mechanism.
121 is a string describing the sleep condition for userland tools.
125 function returns non-zero if the current thread busied
128 Returns zero otherwise.
132 function shared busies
136 .Fn vm_page_sleep_if_busy
137 function puts the invoking thread to sleep, using the appropriate
138 waitchannels for the busy mechanism, if
140 is busied in either exclusive or shared mode.
141 If the invoking thread slept a non-zero value is returned, otherwise
145 is a string describing the sleep condition for userland tools.
149 function shared unbusies
154 attempts to shared busy
156 If the operation cannot immediately succeed
158 returns 0, otherwise a non-zero value is returned.
162 attempts to exclusive busy
164 If the operation cannot immediately succeed
166 returns 0, otherwise a non-zero value is returned.
170 function returns non-zero if the current thread busied
173 Returns zero otherwise.
177 function exclusive busies
182 function exclusive unbusies
184 Assertions on the busy state allow kernels compiled with
185 .Cd "options INVARIANTS"
187 .Cd "options INVARIANT_SUPPORT"
188 to panic if they are not respected.
191 .Fn vm_page_assert_sbusied
194 is not shared busied.
197 .Fn vm_page_assert_unbusied
203 .Fn vm_page_assert_xbusied
206 is not exclusive busied.
209 .Xr vm_page_aflag 9 ,
210 .Xr vm_page_alloc 9 ,
211 .Xr vm_page_deactivate 9 ,
214 .Xr vm_page_insert 9 ,
215 .Xr vm_page_lookup 9 ,