[src/trunk]: src/share/man/man9 Add a manual page that describes the pmap(9) ...

[thorpej <thorpej%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/3c7e5f9f8000
branches:  trunk
changeset: 508995:3c7e5f9f8000
user:      thorpej <thorpej%NetBSD.org@localhost>
date:      Tue Apr 24 02:55:34 2001 +0000

description:
Add a manual page that describes the pmap(9) API and the requirements
of a pmap module.

Many thanks to Bill Sommerfeld for reviewing the document for me.

diffstat:

 share/man/man9/Makefile |     4 +-
 share/man/man9/pmap.9   |  1057 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 1059 insertions(+), 2 deletions(-)

diffs (truncated from 1079 to 300 lines):

diff -r 9986d3f89a79 -r 3c7e5f9f8000 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Tue Apr 24 00:44:23 2001 +0000
+++ b/share/man/man9/Makefile   Tue Apr 24 02:55:34 2001 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.73 2001/04/18 05:56:51 jdolecek Exp $
+#       $NetBSD: Makefile,v 1.74 2001/04/24 02:55:34 thorpej Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -8,7 +8,7 @@
        extent.9 fetch.9 fork1.9 humanize_number.9 inittodr.9 \
        intro.9 ioctl.9 kprintf.9 linedisc.9 lock.9 log.9 malloc.9 mbuf.9 \
        microtime.9 panic.9 pci_configure_bus.9 pci_intr.9 pfil.9 physio.9 \
-       pool.9 powerhook_establish.9 ppsratecheck.9 psignal.9 \
+       pmap.9 pool.9 powerhook_establish.9 ppsratecheck.9 psignal.9 \
        ratecheck.9 resettodr.9 rnd.9 rt_timer.9 \
        shutdownhook_establish.9 sleep.9 softintr.9 \
        spl.9 store.9 time.9 todr.9 uiomove.9 ucom.9 \
diff -r 9986d3f89a79 -r 3c7e5f9f8000 share/man/man9/pmap.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/pmap.9     Tue Apr 24 02:55:34 2001 +0000
@@ -0,0 +1,1057 @@
+.\"    $NetBSD: pmap.9,v 1.1 2001/04/24 02:55:34 thorpej Exp $
+.\"
+.\" Copyright (c) 2000, 2001 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\" 
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Jason R. Thorpe.
+.\" 
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation 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 NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``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 FOUNDATION OR CONTRIBUTORS
+.\" 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 April 16, 2001
+.Dt PMAP 9
+.Os
+.Sh NAME
+.Nm pmap
+.Nd machine-dependent portion of the virtual memory system
+.Sh SYNOPSIS
+.Fd #include <sys/param.h>
+.Fd #include <uvm/uvm_extern.h>
+.Ft void
+.Fn "pmap_init" "void"
+.Ft void
+.Fn "pmap_virtual_space" "vaddr_t *vstartp" "vaddr_t *vendp"
+.Ft void
+.Fn "pmap_steal_memory" "vsize_t size" "vaddr_t *vstartp" "vaddr_t *vendp"
+.Ft pmap_t
+.Fn "pmap_kernel" "void"
+.Ft pmap_t
+.Fn "pmap_create" "void"
+.Ft void
+.Fn "pmap_destroy" "pmap_t pmap"
+.Ft void
+.Fn "pmap_reference" "pmap_t pmap"
+.Ft void
+.Fn "pmap_fork" "pmap_t src_map" "pmap_t dst_map"
+.Ft long
+.Fn "pmap_resident_count" "pmap_t pmap"
+.Ft long
+.Fn "pmap_wired_count" "pmap_t pmap"
+.Ft vaddr_t
+.Fn "pmap_growkernel" "vaddr_t maxkvaddr"
+.Ft int
+.Fn "pmap_enter" "pmap_t pmap" "vaddr_t va" "paddr_t pa" "vm_prot_t prot" \
+    "int flags"
+.Ft void
+.Fn "pmap_remove" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva"
+.Ft void
+.Fn "pmap_protect" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" "vm_prot_t prot"
+.Ft void
+.Fn "pmap_unwire" "pmap_t pmap" "vaddr_t va"
+.Ft boolean_t
+.Fn "pmap_extract" "pmap_t pmap" "vaddr_t va" "paddr_t *pap"
+.Ft void
+.Fn "pmap_kenter_pa" "vaddr_t va" "paddr_t pa" "vm_prot_t prot"
+.Ft void
+.Fn "pmap_kremove" "vaddr_t va" "vsize_t size"
+.Ft void
+.Fn "pmap_copy" "pmap_t dst_map" "pmap_t src_map" "vaddr_t dst_addr" \
+   "vsize_t len" "vaddr_t src_addr"
+.Ft void
+.Fn "pmap_collect" "pmap_t pmap"
+.Ft void
+.Fn "pmap_update" "void"
+.Ft void
+.Fn "pmap_activate" "struct proc *p"
+.Ft void
+.Fn "pmap_deactivate" "struct proc *p"
+.Ft void
+.Fn "pmap_zero_page" "paddr_t pa"
+.Ft void
+.Fn "pmap_copy_page" "paddr_t src" "paddr_t dst"
+.Ft void
+.Fn "pmap_page_protect" "vm_page_t pg" "vm_prot_t prot"
+.Ft boolean_t
+.Fn "pmap_clear_modify" "vm_page_t pg"
+.Ft boolean_t
+.Fn "pmap_clear_reference" "vm_page_t pg"
+.Ft boolean_t
+.Fn "pmap_is_modified" "vm_page_t pg"
+.Ft boolean_t
+.Fn "pmap_is_referenced" "vm_page_t pg"
+.Ft paddr_t
+.Fn "pmap_phys_address" "int cookie"
+.Ft vaddr_t
+.Fn "PMAP_MAP_POOLPAGE" "paddr_t pa"
+.Ft paddr_t
+.Fn "PMAP_UNMAP_POOLPAGE" "vaddr_t va"
+.Sh DESCRIPTION
+The
+.Nm
+module is the machine-dependent portion of the
+.Nx
+virtual memory system
+.Xr uvm 9 .
+The purpose of the
+.Nm
+module is to manage physical address maps, to program the
+memory management hardware on the system, and perform any
+cache operations necessary to ensure correct operation of
+the virtual memory system.  The
+.Nm
+module is also responsible for maintaining certain information
+required by
+.Xr uvm 9 .
+.Pp
+In order to cope with hardware architectures that make the
+invalidation of virtual address mappings expensive (e.g.
+TLB invalidations, TLB shootdown operations for multiple
+processors), the
+.Nm
+module is allowed to delay mapping invalidation or protection
+operations until such time as they are actually necessary.  The
+functions that are allowed to delay such actions are
+.Fn pmap_enter ,
+.Fn pmap_remove ,
+.Fn pmap_protect ,
+.Fn pmap_kenter_pa ,
+and
+.Fn pmap_kremove .
+Callers of these functions must use the
+.Fn pmap_update
+function to notify the
+.Nm
+module that the mappings need to be made correct.  Since the
+.Nm
+module is provided with information as to which processors are
+using a given physical map, the
+.Nm
+module may use whatever optimizations it has available to reduce
+the expense of virtual-to-physical mapping synchronization.
+.Ss HEADER FILES AND DATA STRUCTURES
+Machine-dependent code must provide the header file
+.Pa <machine/pmap.h> .
+This file contains the definition of the
+.Dv pmap
+structure:
+.Bd -literal -offset indent
+struct pmap {
+        /* Contents defined by pmap implementation. */
+};
+typedef struct pmap *pmap_t;
+.Ed
+.Pp
+This header file may also define other data structures that the
+.Nm
+implementation uses.
+.Pp
+Note that all prototypes for
+.Nm
+interface functions are provided by the header file
+.Pa <uvm/uvm_pmap.h> .
+It is possible to override this behavior by defining the
+C pre-processor macro
+.Dq PMAP_EXCLUDE_DECLS .
+This may be used to add a layer of indirection to
+.Nm
+API calls, for handling different MMU types in a single
+.Nm
+module, for example.  If the
+.Dq PMAP_EXCLUDE_DECLS
+macro is defined,
+.Pa <machine/pmap.h>
+.Em must
+provide function prototypes in a block like so:
+.Bd -literal -offset indent
+#ifdef _KERNEL /* not exposed to user namespace */
+__BEGIN_DECLS  /* make safe for C++ */
+/* Prototypes go here. */
+__END_DECLS
+#endif /* _KERNEL */
+.Ed
+.Pp
+The header file
+.Pa <uvm/uvm_pmap.h>
+defines a structure for tracking
+.Nm
+statistics (see below).  This structure is defined as:
+.Bd -literal -offset indent
+struct pmap_statistics {
+        long        resident_count; /* number of mapped pages */
+        long        wired_count;    /* number of wired pages */
+};
+.Ed
+.Ss WIRED MAPPINGS
+The
+.Nm
+module is based on the premise that all information contained
+in the physical maps it manages is redundant.  That is, physical
+map information may be
+.Dq forgotten
+by the
+.Nm
+module in the event that it is necessary to do so; it can be rebuilt
+by
+.Xr uvm 9
+by taking a page fault.  There is one exception to this rule: so-called
+.Dq wired
+mappings may not be forgotten.  Wired mappings are those for which either
+no high-level information exists with which to rebuild the mapping, or
+mappings which are needed by critical sections of code where taking a
+page fault is unacceptable.  Information about which mappings are wired
+is provided to the
+.Nm
+module when a mapping is established.
+.Ss MODIFED/REFERENCED INFORMATION
+The
+.Nm
+module is required to keep track of whether or not a page managed
+by the virtual memory system has been referenced or modified.  This
+information is used by
+.Xr uvm 9
+to determine what happens to the page when scanned by the
+pagedaemon.
+.Pp
+Many CPUs provide hardware support for tracking
+modified/referenced information.  However, many CPUs, particularly
+modern RISC CPUs, do not.  On CPUs which lack hardware support
+for modified/referenced tracking, the
+.Nm
+module must emulate it in software.  There are several strategies
+for doing this, and the best strategy depends on the CPU.
+.Pp
+The
+.Dq referenced
+attribute is used by the pagedaemon to determine if a page is
+.Dq active .
+Active pages are not candidates for re-use in the page replacement
+algorithm.  Accurate referenced information is not required for
+correct operation; if supplying referenced information for a page
+is not feasible, then the
+.Nm
+implementation should always consider the
+.Dq referenced
+attibute to be FALSE.
+.Pp
+The
+.Dq modified
+attribute is used by the pagedaemon to determine if a page needs
+to be cleaned (written to backing store; swap space, a regular file, etc.).
+Accurate modified information
+.Em must
+be provided by the
+.Nm
+module for correct operation of the virtual memory system.
+.Pp
+Note that modified/referenced information is only tracked for
+pages managed by the virtual memory system (i.e. pages for
+which a vm_page structure exists).  In addition, only
+.Dq managed
+mappings of those pages have modified/referenced tracking.  Mappings
+entered with the
+.Fn pmap_enter