Index: share/man/man9/pmap_enter.9
===================================================================
--- share/man/man9/pmap_enter.9
+++ share/man/man9/pmap_enter.9
@@ -1,5 +1,6 @@
 .\"
 .\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org>
+.\" Copyright (c) 2014 The FreeBSD Foundation
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -25,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 21, 2003
+.Dd August 13, 2014
 .Dt PMAP_ENTER 9
 .Os
 .Sh NAME
@@ -35,34 +36,101 @@
 .In sys/param.h
 .In vm/vm.h
 .In vm/pmap.h
-.Ft void
+.Ft int
 .Fo pmap_enter
-.Fa "pmap_t pmap" "vm_offset_t va" "vm_page_t p" "vm_prot_t prot"
-.Fa "boolean_t wired"
+.Fa "pmap_t pmap" "vm_offset_t va" "vm_page_t m" "vm_prot_t prot"
+.Fa "u_int flags" "int8_t psind"
 .Fc
 .Sh DESCRIPTION
 The
 .Fn pmap_enter
 function inserts the given physical page
-.Fa p ,
+.Fa m ,
 into the physical map
 .Fa pmap ,
 at the virtual address
 .Fa va ,
 with the protection
 .Fa prot .
-If
-.Fa wired
-is
-.Dv TRUE ,
-then increment the wired count for the page as soon as the mapping
-is inserted into
-.Fa pmap .
-.Sh IMPLEMENTATION NOTES
-This routine MAY NOT lazy-evaluate the entry; it is required by
-specification to make the requested entry at the time it is called.
+.Pp
+The
+.Fa flags
+argument takes the following values:
+.Bl -tag -width ".Dv PMAP_ENTER_NOSLEEP"
+.It Dv VM_PROT_READ
+The page access, which initiated the call, was for read.
+.It Dv VM_PROT_WRITE
+The page access, which initiated the call, was for write.
+.It Dv VM_PROT_EXECUTE
+The page access, which initiated the call, was for execution.
+.It Dv PMAP_ENTER_WIRED
+The pmap implementation should insert the wired entry into the mapping
+structures for the given page.
+.It Dv PMAP_ENTER_NOSLEEP
+The pmap implementation must not sleep during creation of the mapping.
+If the mapping request cannot be satisfied without sleep, an appropriate
+Mach VM error must be returned.
+.El
+If the
+.Dv PMAP_ENTER_NOSLEEP
+flag is not specified, the routine may not lazy-evaluate the entry;
+it is required to make the requested entry at the time it is called.
+The implementation could destroy any other non-wired managed entries
+in the
+.Fa pmap
+to allow the requested mapping to succeed.
+.Pp
+When destroying a mapping during creation of the requested entry,
+including the pre-existing managed mapping for the address
+.Fa va ,
+the
+.Va PGA_REFERENCED
+aflag for the corresponding page should be updated by the information
+from hardware.
+If the hardware indicated that the destroyed mapping was used to write
+to the mapped page, the page
+.Va dirty
+field must be set with
+.Fn vm_page_dirty
+call.
+.Pp
+The
+.Va PGA_WRITEABLE
+aflag must be set for the page
+.Fa m
+if the new mapping is writeable.
+It is advised to clear
+.Va PGA_WRITEABLE
+for destroyed mappings if the implementation can ensure
+that no other writeable managed mappings for the previously
+mapped pages exist.
+.Pp
+If the passed page
+.Fa m
+is managed, the page must be busied by the caller,
+or the owning object must be locked, in which case
+.Dv PMAP_ENTER_NOSLEEP
+have to be specified in
+.Fa flags .
+.Pp
+The
+.Fn pmap_enter
+must handle the multiprocessor TLB consistency for the given address.
+.Sh RETURN VALUES
+If successful, the
+.Fn pmap_enter
+returns
+.Er KERN_SUCCESS.
+If the
+.Dv PMAP_ENTER_NOSLEEP
+flag was specified, and required resources cannot be acquired
+in non-sleeping manner, typical implementation returns
+.Dv KERN_RESOURCE_SHORTAGE
+error.
 .Sh SEE ALSO
 .Xr pmap 9
 .Sh AUTHORS
 This manual page was written by
-.An Bruce M Simpson Aq Mt bms@spc.org .
+.An Bruce M Simpson Aq Mt bms@spc.org
+and
+.An Konstantin Belousov Aq Mt kib@freebsd.org .