Document the pmap interface.

art@ "it's work in progress" ok

1 files changed, 416 insertions, 0 deletions

diff --git a/share/man/man9/pmap.9 b/share/man/man9/pmap.9
new file mode 100644
index 00000000000..5d946ecfc05
--- /dev/null
+++ b/share/man/man9/pmap.9
@@ -0,0 +1,416 @@
+.\"	$OpenBSD: pmap.9,v 1.1 2002/09/02 03:52:38 wcobb Exp $
+.\"
+.\" Copyright (c) 2001, 2002 CubeSoft Communications, Inc.
+.\" <http://www.csoft.org>
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistribution of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Neither the name of CubeSoft Communications, nor the names of its
+.\"    contributors may be used to endorse or promote products derived from
+.\"    this software without specific prior written permission.
+.\" 
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd September 21, 2001
+.Dt PMAP 9
+.Os
+.Sh NAME
+.Nm pmap
+.Nd machine dependent interface to the MMU
+.Sh SYNOPSIS
+.Fd #include <machine/pmap.h>
+.Sh DESCRIPTION
+The architecture-dependent
+.Nm
+module describes how the physical mapping is done between the user-processes
+and kernel virtual addresses and the physical addresses of the main memory,
+providing machine-dependent translation and access tables that are used
+directly or indirectly by the memory-management hardware.
+The
+.Nm
+layer can be viewed as a big array of mapping entries that are indexed by
+virtual address to produce a physical address and flags.
+These flags describe
+the page's protection, whether the page has been referenced or modified and
+other characteristics.
+.Pp
+The
+.Nm
+interface is consistent across all platforms and hides the way page mappings
+are stored.
+.Pp
+.Sh INITIALIZATION
+.nr nS 1
+.Ft void
+.Fn pmap_init "void"
+.nr nS 0
+.Pp
+The
+.Fn pmap_init
+function is called from the machine-independent
+.Xr uvm 9
+initialization code, when the MMU is enabled.
+.Sh PAGE MANAGEMENT
+Modified/referenced information is only tracked for pages managed by
+.Xr uvm 9
+(pages for which a vm_page structure exists).
+Only managed mappings of those pages have modified/referenced tracking.
+The use of unmanaged mappings should be limited to code which may execute
+in interrupt context (such as
+.Xr malloc 9 )
+or to enter mappings for physical addresses which are not managed by
+.Xr uvm 9 .
+This allows
+.Nm
+modules to avoid blocking interrupts when manipulating data structures or
+holding locks.
+Unmanaged mappings may only be entered into the kernel's virtual address space.
+The modified/referenced bits must be tracked on a per-page basis, as they
+are not attributes of a mapping, but attributes of a page.
+Therefore, even after all mappings for a given page have been removed, the
+modified/referenced bits for that page must be preserved.
+The only time the modified/referenced bits may be cleared is when
+.Xr uvm 9
+explicitly calls the
+.Fn pmap_clear_modify
+and
+.Fn pmap_clear_reference
+functions.
+These functions must also change any internal state necessary to detect
+the page being modified or referenced again after the modified/referenced
+state is cleared.
+.Pp
+Mappings entered by
+.Fn pmap_enter
+are managed, mappings entered by
+.Fn pmap_kenter_pa
+are not.
+.Sh MAPPING ALLOCATION
+.nr nS 1
+.Ft int
+.Fn pmap_enter "pmap_t pmap" "vaddr_t va" "paddr_t pa" "vm_prot_t prot" \
+               "int flags"
+.Ft void
+.Fn pmap_kenter_pa "vaddr_t va" "paddr_t pa" "vm_prot_t prot"
+.Ft void
+.Fn pmap_remove "pmap_t pmap" "vaddr_t sva" "paddr_t eva"
+.Ft void
+.Fn pmap_kremove "vaddr_t va" "vsize_t size"
+.nr nS 0
+.Pp
+The
+.Fn pmap_enter
+function creates a managed mapping for physical page
+.Fa pa
+at the specified virtual address
+.Fa va
+in the target physical map
+.Fa pmap
+with protection specified by
+.Fa prot :
+.Bl -tag -width "VM_PROT_EXECUTE  " -indent
+.It VM_PROT_READ
+The mapping must allow reading.
+.It VM_PROT_WRITE
+The mapping must allow writing.
+.It VM_PROT_EXECUTE
+The page mapped contains instructions that will be executed by the
+processor.
+.El
+.Pp
+The
+.Fa flags
+argument contains protection bits (the same bits used in the
+.Fa prot
+argument) indicating the type of access that caused hte mapping to
+be created. This information may be used to seed modified/referenced
+information for the page being mapped, possibly avoiding redundant
+faults on platforms that track modified/referenced information in
+software.
+Other information provided by
+.Fa flags :
+.Bl -tag -width "PMAP_CANFAIL   " -indent
+.It PMAP_WIRED
+The mapping being created is a wired mapping.
+.It PMAP_CANFAIL
+The call to
+.Fn pmap_enter
+is allowed to fail. If this flag is not set, and the
+.Fn pmap_enter
+call is unable to create the mapping, perhaps due to insufficient
+resources, the
+.Nm
+module must panic.
+.El
+.Pp
+The access type provided in the
+.Fa flags
+argument will never exceed the protection specified by
+.Fa prot .
+.Pp
+The
+.Fn pmap_enter
+function is called by the fault routine to establish a mapping for
+the page being faulted in.
+If
+.Fn pmap_enter
+is called to enter a mapping at a virtual address for which a mapping
+already exists, the previous mapping must in invalidated.
+.Fn pmap_enter
+is sometimes called to change the protection for a pre-existing mapping,
+or to change the
+.Dq wired
+attribute for a pre-existing mapping.
+.Pp
+The
+.Fn pmap_kenter_pa
+function creates an unmanaged mapping of physical address
+.Fa pa
+at the specified virtual address
+.Fa va
+with the protection specified by
+.Fa prot .
+.Pp
+The
+.Fn pmap_remove
+function removes the range of virtual addresses
+.Fa sva
+to
+.Fa eva
+from
+.Fa pmap ,
+assuming proper alignment.
+.Fn pmap_remove
+is called during an unmap
+operation to remove low-level machine dependent mappings.
+.Pp
+The
+.Fn pmap_kremove
+function removes an unmanaged mapping at virtual address
+.Fa size .
+.Pp
+A call to
+.Fn pmap_update
+must be made after
+.Fn pmap_kenter_pa
+or
+.Fn pmap_kremove
+to notify the
+.Nm
+layer that the mappings need to be made correct.
+.Sh ACCESS PROTECTION
+.nr nS 1
+.Ft void
+.Fn pmap_unwire "pmap_t pmap" "vaddr_t va"
+.Ft void
+.Fn pmap_protect "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" "vm_prot_t prot"
+.Ft void
+.Fn pmap_page_protect "struct vm_page *pg, vm_prot_t prot"
+.nr nS 0
+.Pp
+The
+.Fn pmap_unwire
+function clears the wired attribute for a map/virtual-address pair.
+The mapping must already exist in
+.Fa pmap .
+.Pp
+The
+.Fn pmap_protect
+function sets the physical protection on range
+.Fa sva
+to
+.Fa eva ,
+in
+.Fa pmap .
+.Pp
+The
+.Fn pmap_protect
+function is called during a copy-on-write operation to write protect
+copy-on-write memory, and when paging out a page to remove all mappings
+of a page.
+The
+.Fn pmap_page_protect
+function sets the permission for all mapping to page
+.Fa pg .
+The
+.Fn pmap_page_protect
+function is called before a pageout operation to ensure that all pmap
+references to a page are removed.
+.Sh PHYSICAL PAGE-USAGE INFORMATION
+.nr nS 1
+.Ft boolean_t
+.Fn pmap_is_modified "struct vm_page *pg"
+.Ft boolean_t
+.Fn pmap_clear_modify "struct vm_page *pg"
+.Ft boolean_t
+.Fn pmap_is_referenced "struct vm_page *pg"
+.Ft boolean_t
+.Fn pmap_clear_reference "struct vm_page *pg"
+.nr nS 0
+.Pp
+The
+.Fn pmap_is_modified
+and
+.Fn pmap_clear_modify
+functions read/set the modify bits on the specified physical page
+.Fa pg .
+The
+.Fn pmap_is_referenced
+and
+.Fn pmap_clear_reference
+functions read/set the reference bits on the specified physical page
+.Fa pg .
+.Pp
+The
+.Fn pmap_is_referenced
+and
+.Fn pmap_is_modified
+functions are called by the pagedaemon when looking for pages to free.
+The
+.Fn pmap_clear_referenced
+and
+.Fn pmap_clear_modify
+functions are called by the pagedaemon to help identification of pages
+that are no longer in demand.
+.Sh PHYSICAL PAGE INITIALIZATION
+.nr nS 1
+.Ft void
+.Fn pmap_copy_page "paddr_t src" "paddr_t dst"
+.Ft void
+.Fn pmap_zero_page "paddr_t phys"
+.nr nS 0
+.Pp
+The
+.Fn pmap_copy_page
+function copies the content of the physical page
+.Fa src
+to physical page
+.Fa dst .
+.Pp
+The
+.Fn pmap_zero_page
+function fills the page at
+.Fa phys
+with zeroes.
+.Sh INTERNAL DATA STRUCTURE MANAGEMENT
+.nr nS 1
+.Ft pmap_t
+.Fn pmap_create "void"
+.Ft void
+.Fn pmap_reference "pmap_t pmap"
+.Ft void
+.Fn pmap_destroy "pmap_t pmap"
+.nr nS 0
+.Pp
+The
+.Fn pmap_create
+function creates an instance of the
+.Em pmap
+structure.
+.Pp
+The
+.Fn pmap_reference
+function increments the reference count on
+.Fa pmap .
+.Pp
+The
+.Fn pmap_destroy
+function decrements the reference count on physical map
+.Fa pmap
+and retire it from service if the count drops to zero, assuming
+it contains no valid mappings.
+.Sh OPTIONAL FUNCTIONS
+.nr nS 1
+.Ft void
+.Fn pmap_steal_memory "vsize_t size" "vaddr_t *vstartp" "vaddr_t *vendp"
+.Ft vaddr_t
+.Fn pmap_growkernel "vaddr_t maxkvaddr"
+.Ft void
+.Fn pmap_update "pmap_t pmap"
+.Ft void
+.Fn pmap_collect "pmap_t pmap"
+.Ft void
+.Fn pmap_virtual_space "vaddr_t *vstartp" "vaddr_t *vendp"
+.Ft void
+.Fn pmap_copy "pmap_t dst_pmap" "pmap_t src_pmap" "vaddr_t dst_addr" \
+              "vsize_t len" "vaddr_t src_addr"
+.nr nS 0
+.Pp
+Wired memory allocation before the virtual memory system is bootstrapped
+is accomplished by the
+.Fn pmap_steal_memory
+function.
+After that point, the kernel memory allocation routines should be used.
+.Pp
+The
+.Fn pmap_growkernel
+function can preallocate kernel page tables to a specified virtual address.
+.Pp
+The
+.Fn pmap_update
+function notifies the
+.Nm
+module to force processing of all delayed actions for all pmaps.
+.Pp
+The
+.Fn pmap_collect
+function informs the
+.Nm
+module that the given
+.Em pmap
+is not expected to be used for some time, giving the
+.Nm
+module a chance to prioritize.
+The initial bounds of the kernel virtual address space are returned by
+.Fn pmap_virtual_space .
+.Pp
+The
+.Fn pmap_copy
+function copies the range specified by
+.Fa src_addr
+and
+.Fa src_len
+from
+.Fa src_pmap
+to the range described by
+.Fa dst_addr
+and
+.Fa dst_len
+in
+.Fa dst_map .
+.Fn pmap_copy
+is called during a
+.Xr fork 2
+operation to give the child process an initial set of low-level
+mappings.
+.Sh SEE ALSO
+.Xr uvm 9 ,
+.Xr fork 2
+.Sh BUGS
+Ifdefs must be documented.
+.Pp
+.Fn pmap_update
+should be mandatory.
+.Sh HISTORY
+The
+.Bx 4.4
+.Nm
+module is based on Mach 3.0.
+The introduction of
+.Xr uvm 9
+left the
+.Nm
+interface unchanged for the most part.