Document vm_page_aflag_set(9), vm_page_aflag_clear(9) and vm_page_reference(9).

Retire vm_page_flag_set() and vm_page_flag_clear() functions.

Reviewed by:	alc
Approved by:	re (bz)

2 files changed, 53 insertions, 13 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 8fb3305a8ab1..b24be5656a60 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -320,7 +320,7 @@ MAN=	accept_filter.9 \
 	vm_page_cache.9 \
 	vm_page_deactivate.9 \
 	vm_page_dontneed.9 \
-	vm_page_flag.9 \
+	vm_page_aflag.9 \
 	vm_page_free.9 \
 	vm_page_grab.9 \
 	vm_page_hold.9 \
@@ -1372,8 +1372,9 @@ MLINKS+=vm_page_bits.9 vm_page_clear_dirty.9 \
 	vm_page_bits.9 vm_page_test_dirty.9 \
 	vm_page_bits.9 vm_page_undirty.9 \
 	vm_page_bits.9 vm_page_zero_invalid.9
-MLINKS+=vm_page_flag.9 vm_page_flag_clear.9 \
-	vm_page_flag.9 vm_page_flag_set.9
+MLINKS+=vm_page_aflag.9 vm_page_aflag_clear.9 \
+	vm_page_aflag.9 vm_page_aflag_set.9 \
+	vm_page_aflag.9 vm_page_reference.9
 MLINKS+=vm_page_free.9 vm_page_free_toq.9 \
 	vm_page_free.9 vm_page_free_zero.9 \
 	vm_page_free.9 vm_page_try_to_free.9
diff --git a/share/man/man9/vm_page_flag.9 b/share/man/man9/vm_page_aflag.9
index 5a1d75fbd472..8ef5d8703c9f 100644
--- a/share/man/man9/vm_page_flag.9
+++ b/share/man/man9/vm_page_aflag.9
@@ -26,36 +26,75 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 14, 2001
+.Dd August 31, 2011
 .Dt VM_PAGE_FLAG 9
 .Os
 .Sh NAME
-.Nm vm_page_flag_clear , vm_page_flag_set
-.Nd "change page flags"
+.Nm vm_page_aflag_clear , vm_page_aflag_set , vm_page_reference
+.Nd "change page atomic flags"
 .Sh SYNOPSIS
 .In sys/param.h
 .In vm/vm.h
 .In vm/vm_page.h
 .Ft void
-.Fn vm_page_flag_clear "vm_page_t m" "unsigned short bits"
+.Fn vm_page_aflag_clear "vm_page_t m" "uint8_t bits"
 .Ft void
-.Fn vm_page_flag_set "vm_page_t m" "unsigned short bits"
+.Fn vm_page_aflag_set "vm_page_t m" "uint8_t bits"
+.Ft void
+.Fn vm_page_reference "vm_page_t m"
 .Sh DESCRIPTION
 The
-.Fn vm_page_flag_clear
-atomically clears the specified bits on the page's flags.
+.Fn vm_page_aflag_clear
+atomically clears the specified bits on the page's
+.Va aflags .
+.Pp
+The
+.Fn vm_page_aflag_set
+atomically sets the specified bits on the page's
+.Va aflags .
 .Pp
 The
-.Fn vm_page_flag_set
-atomically sets the specified bits on the page's flags.
+.Fn vm_page_reference m
+call is the same as
+.Bd -literal -offset indent
+vm_page_aflag_set(m, PGA_REFERENCED);
+.Ed
+.Lp
+and is the recommended way to mark the page as referenced from
+third-party kernel modules.
+.Pp
+These functions neither block nor require any locks to be held
+around the calls for correctness.
 .Pp
 The functions arguments are:
 .Bl -tag -width ".Fa bits"
 .It Fa m
-The page whose flags are updated.
+The page whose
+.Va aflags
+are updated.
 .It Fa bits
 The bits that are set or cleared on the page's flags.
 .El
+.Pp
+The following
+.Va aflags
+can be set or cleared:
+.Bl -tag -width ".Fa PGA_REFERENCED"
+.It Fa PGA_REFERENCED
+The bit may be set to indicate that the page has been recently accessed.
+For instance,
+.Xr pmap 9
+sets this bit to reflect the accessed attribute of the page mapping
+typically updated by processor's memory management unit on the page access.
+.It Fa PGA_WRITEABLE
+A writeable mapping for the page may exist.
+.El
+.Pp
+Both
+.Dv PGA_REFERENCED
+and
+.Dv PGA_WRITEABLE
+bits are only valid for the managed pages.
 .Sh AUTHORS
 This manual page was written by
 .An Chad David Aq davidc@acns.ab.ca .