MFC r277793:

Rewrite pmap_enter(9) man page.

1 files changed, 118 insertions, 22 deletions

diff --git a/share/man/man9/pmap_enter.9 b/share/man/man9/pmap_enter.9
index 2e52453..85ab4e8 100644
--- a/share/man/man9/pmap_enter.9
+++ b/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 January 27, 2015
 .Dt PMAP_ENTER 9
 .Os
 .Sh NAME
@@ -35,34 +36,129 @@
 .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 ,
-into the physical map
-.Fa pmap ,
-at the virtual address
-.Fa va ,
+function creates a mapping in the physical map
+.Fa pmap
+from the virtual address
+.Fa va
+to the physical page
+.Fa m
 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.
+Any previous mapping at the virtual address
+.Fa va
+is destroyed.
+.Pp
+The
+.Fa flags
+argument may have the following values:
+.Bl -tag -width ".Dv PMAP_ENTER_NOSLEEP"
+.It Dv VM_PROT_READ
+A read access to the given virtual address triggered the call.
+.It Dv VM_PROT_WRITE
+A write access to the given virtual address triggered the call.
+.It Dv VM_PROT_EXECUTE
+An execute access to the given virtual address triggered the call.
+.It Dv PMAP_ENTER_WIRED
+The mapping should be marked as wired.
+.It Dv PMAP_ENTER_NOSLEEP
+This function may not sleep during creation of the mapping.
+If the mapping cannot be created without sleeping, an appropriate
+Mach VM error is returned.
+.El
+If the
+.Dv PMAP_ENTER_NOSLEEP
+flag is not specified, this function must create the requested mapping
+before returning.
+It may not fail.
+In order to create the requested mapping, this function may destroy
+any non-wired mapping in any pmap.
+.Pp
+The
+.Fa psind
+parameter specifies the page size that should be used by the mapping.
+The supported page sizes are described by the global array
+.Dv pagesizes[] .
+The desired page size is specified by passing the index of the array
+element that equals the desired page size.
+.Pp
+When the
+.Fn pmap_enter
+function destroys or updates a managed mapping, including an existing
+mapping at virtual address
+.Fa va ,
+it updates the
+.Ft vm_page
+structure corresponding to the previously mapped physical page.
+If the physical page was accessed through the managed mapping,
+then the
+.Ft vm_page
+structure's
+.Dv PGA_REFERENCED
+aflag is set.
+If the physical page was modified through the managed mapping, then the
+.Fn vm_page_dirty
+function is called on the
+.Ft vm_page
+structure.
+.Pp
+The
+.Dv PGA_WRITEABLE
+aflag must be set for the page
+.Fa m
+if the new mapping is managed and writeable.
+It is advised to clear
+.Dv 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 page
+.Fa m
+is managed, the page must be busied by the caller
+or the owning object must be locked.
+In the later case, the
+.Dv PMAP_ENTER_NOSLEEP
+must be specified by the caller.
+.Pp
+The
+.Fn pmap_enter
+function must handle the multiprocessor TLB consistency for the
+given address.
+.Sh NOTES
+On amd64, arm and i386 architectures the existing implementation
+of the
+.Nm
+function is incomplete, only value 0 for
+.Fa psind
+is supported.
+Other supported architectures have
+.Dv pagesizes[]
+array of size 1.
+.Sh RETURN VALUES
+If successful, the
+.Fn pmap_enter
+function returns
+.Er KERN_SUCCESS .
+If the
+.Dv PMAP_ENTER_NOSLEEP
+flag was specified and the resources required for the mapping cannot
+be acquired without sleeping,
+.Dv KERN_RESOURCE_SHORTAGE
+is returned.
 .Sh SEE ALSO
 .Xr pmap 9
 .Sh AUTHORS
-This manual page was written by
-.An Bruce M Simpson Aq bms@spc.org .
+This manual page was first written by
+.An Bruce M Simpson Aq Mt bms@spc.org
+and then rewritten by
+.An Alan Cox Aq Mt alc@FreeBSD.org
+and
+.An Konstantin Belousov Aq Mt kib@FreeBSD.org .