From 6b5007c8934dcfd84b3b6363003c633fafdd76d0 Mon Sep 17 00:00:00 2001
From: Konstantin Belousov <kib@FreeBSD.org>
Date: Sun, 16 Dec 2018 01:51:38 +0000
Subject: [PATCH] Document new required MI behaviour of pmap_enter(9) for CoW.

Reviewed by:	markj
MFC after:	3 days
Sponsored by:	The FreeBSD Foundation
Differential revision:	https://reviews.freebsd.org/D18568
---
 share/man/man9/pmap_enter.9 | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/share/man/man9/pmap_enter.9 b/share/man/man9/pmap_enter.9
index 70b912f99b80..564c91d2f4f0 100644
--- a/share/man/man9/pmap_enter.9
+++ b/share/man/man9/pmap_enter.9
@@ -26,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 16, 2018
+.Dd December 16, 2018
 .Dt PMAP_ENTER 9
 .Os
 .Sh NAME
@@ -120,6 +120,14 @@ for destroyed mappings if the implementation can ensure
 that no other writeable managed mappings for the previously
 mapped pages exist.
 .Pp
+If the request modifies an existing mapping to use a different physical
+page, an implementation of
+.Nm
+must invalidate the previous mapping before installing the new one.
+This ensures that all threads sharing the pmap keep a consistent
+view of the mapping, which is necessary for the correct handling
+of CoW (copy on write) faults.
+.Pp
 If the page
 .Fa m
 is managed, the page must be busied by the caller