Precisely document the synchronization rules for the page's dirty field.

(Saying that the lock on the object that the page belongs to must be held
only represents one aspect of the rules.)

Eliminate the use of the page queues lock for atomically performing read-
modify-write operations on the dirty field when the underlying architecture
supports atomic operations on char and short types.

Document the fact that 32KB pages aren't really supported.

Reviewed by:	attilio, kib

1 files changed, 25 insertions, 8 deletions

diff --git a/sys/vm/vm_page.h b/sys/vm/vm_page.h
index 898857b..e852313 100644
--- a/sys/vm/vm_page.h
+++ b/sys/vm/vm_page.h
@@ -89,10 +89,26 @@
  *	and offset to which this page belongs (for pageout),
  *	and sundry status bits.
  *
- *	Fields in this structure are locked either by the lock on the
- *	object that the page belongs to (O), its corresponding page lock (P),
- *	or by the lock on the page queues (Q).
- *	
+ *	In general, operations on this structure's mutable fields are
+ *	synchronized using either one of or a combination of the lock on the
+ *	object that the page belongs to (O), the pool lock for the page (P),
+ *	or the lock for either the free or paging queues (Q).  If a field is
+ *	annotated below with two of these locks, then holding either lock is
+ *	sufficient for read access, but both locks are required for write 
+ *	access.
+ *
+ *	In contrast, the synchronization of accesses to the page's dirty field
+ *	is machine dependent (M).  In the machine-independent layer, the lock
+ *	on the object that the page belongs to must be held in order to
+ *	operate on the field.  However, the pmap layer is permitted to set
+ *	all bits within the field without holding that lock.  Therefore, if
+ *	the underlying architecture does not support atomic read-modify-write
+ *	operations on the field's type, then the machine-independent layer
+ *	must also hold the page queues lock when performing read-modify-write
+ *	operations and the pmap layer must hold the page queues lock when
+ *	setting the field.  In the machine-independent layer, the
+ *	implementation of read-modify-write operations on the field is
+ *	encapsulated in vm_page_clear_dirty_mask().
  */
 
 TAILQ_HEAD(pglist, vm_page);
@@ -120,18 +136,19 @@ struct vm_page {
 	u_char	busy;			/* page busy count (O) */
 	/* NOTE that these must support one bit per DEV_BSIZE in a page!!! */
 	/* so, on normal X86 kernels, they must be at least 8 bits wide */
+	/* In reality, support for 32KB pages is not fully implemented. */
 #if PAGE_SIZE == 4096
 	u_char	valid;			/* map of valid DEV_BSIZE chunks (O) */
-	u_char	dirty;			/* map of dirty DEV_BSIZE chunks (O) */
+	u_char	dirty;			/* map of dirty DEV_BSIZE chunks (M) */
 #elif PAGE_SIZE == 8192
 	u_short	valid;			/* map of valid DEV_BSIZE chunks (O) */
-	u_short	dirty;			/* map of dirty DEV_BSIZE chunks (O) */
+	u_short	dirty;			/* map of dirty DEV_BSIZE chunks (M) */
 #elif PAGE_SIZE == 16384
 	u_int valid;			/* map of valid DEV_BSIZE chunks (O) */
-	u_int dirty;			/* map of dirty DEV_BSIZE chunks (O) */
+	u_int dirty;			/* map of dirty DEV_BSIZE chunks (M) */
 #elif PAGE_SIZE == 32768
 	u_long valid;			/* map of valid DEV_BSIZE chunks (O) */
-	u_long dirty;			/* map of dirty DEV_BSIZE chunks (O) */
+	u_long dirty;			/* map of dirty DEV_BSIZE chunks (M) */
 #endif
 };