xref: /freebsd/share/man/man9/vm_page_bits.9 (revision 90aad5d3e44d137ce80d2ec257de07c7c1367bd3)
1.\"
2.\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice(s), this list of conditions and the following disclaimer as
9.\"    the first lines of this file unmodified other than the possible
10.\"    addition of one or more copyright notices.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice(s), this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
16.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
19.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
25.\" DAMAGE.
26.\"
27.Dd December 1, 2001
28.Dt VM_PAGE_BITS 9
29.Os
30.Sh NAME
31.Nm vm_page_bits ,
32.Nm vm_page_set_validclean ,
33.Nm vm_page_clear_dirty ,
34.Nm vm_page_set_invalid ,
35.Nm vm_page_zero_invalid ,
36.Nm vm_page_is_valid ,
37.Nm vm_page_test_dirty ,
38.Nm vm_page_dirty ,
39.Nm vm_page_undirty
40.Nd "manage page clean and dirty bits"
41.Sh SYNOPSIS
42.In sys/param.h
43.In vm/vm.h
44.In vm/vm_page.h
45.Ft int
46.Fn vm_page_bits "int base" "int size"
47.Ft void
48.Fn vm_page_set_validclean "vm_page_t m" "int base" "int size"
49.Ft void
50.Fn vm_page_clear_dirty "vm_page_t m" "int base" "int size"
51.Ft void
52.Fn vm_page_set_invalid "vm_page_t m" "int base" "int size"
53.Ft void
54.Fn vm_page_zero_invalid "vm_page_t m" "boolean_t setvalid"
55.Ft int
56.Fn vm_page_is_valid "vm_page_t m" "int base" "int size"
57.Ft void
58.Fn vm_page_test_dirty "vm_page_t m"
59.Ft void
60.Fn vm_page_dirty "vm_page_t m"
61.Ft void
62.Fn vm_page_undirty "vm_page_t m"
63.Sh DESCRIPTION
64.Fn vm_page_bits
65calculates the bits representing the
66.Dv DEV_BSIZE
67range of bytes between
68.Fa base
69and
70.Fa size .
71The byte range is expected to be within a single page, and if
72.Fa size
73is zero, no bits will be set.
74.Pp
75.Fn vm_page_set_validclean
76flags the byte range between
77.Fa base
78and
79.Fa size
80as valid and clean.
81The range is expected to be
82.Dv DEV_BSIZE
83aligned and no larger than
84.Dv PAGE_SIZE .
85If it is not properly aligned, any unaligned chunks of the
86.Dv DEV_BSIZE
87blocks at the beginning and end of the range will be zeroed.
88.Pp
89If
90.Fa base
91is zero and
92.Fa size
93is one page, the modified bit in the page map is cleared; as well,
94the
95.Dv VPO_NOSYNC
96flag is cleared.
97.Pp
98.Fn vm_page_clear_dirty
99clears the dirty bits within a page in the range between
100.Fa base
101and
102.Fa size .
103The bits representing the range are calculated by calling
104.Fn vm_page_bits .
105.Pp
106.Fn vm_page_set_invalid
107clears the bits in both the valid and dirty flags representing
108the
109.Dv DEV_BSIZE
110blocks between
111.Fa base
112and
113.Fa size
114in the page.
115The bits are calculated by calling
116.Fn vm_page_bits .
117As well as clearing the bits within the page, the generation
118number within the object holding the page is incremented.
119.Pp
120.Fn vm_page_zero_invalid
121zeroes all of the blocks within the page that are currently
122flagged as invalid.
123If
124.Fa setvalid
125is
126.Dv TRUE ,
127all of the valid bits within the page are set.
128.Pp
129In some cases, such as NFS, the valid bits cannot be set
130in order to maintain cache consistency.
131.Pp
132.Fn vm_page_is_valid
133checks to determine if the all of the
134.Dv DEV_BSIZE
135blocks between
136.Fa base
137and
138.Fa size
139of the page are valid.
140If
141.Fa size
142is zero and the page is entirely invalid
143.Fn vm_page_is_valid
144will return
145.Dv TRUE ,
146in all other cases a size of zero will return
147.Dv FALSE .
148.Pp
149.Fn vm_page_test_dirty
150checks if a page has been modified via any of its physical maps,
151and if so, flags the entire page as dirty.
152.Fn vm_page_dirty
153is called to modify the dirty bits.
154.Pp
155.Fn vm_page_dirty
156flags the entire page as dirty.
157It is expected that the page is not currently on the cache queue.
158.Pp
159.Fn vm_page_undirty
160clears all of the dirty bits in a page.
161.Sh NOTES
162None of these functions are allowed to block.
163.Sh AUTHORS
164This manual page was written by
165.An Chad David Aq Mt davidc@acns.ab.ca .
166