[src/trunk]: src/share/man/man9 Bump date for pmap_remove addition.

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

details:   https://anonhg.NetBSD.org/src/rev/41f60771ff5c
branches:  trunk
changeset: 537137:41f60771ff5c
user:      wiz <wiz%NetBSD.org@localhost>
date:      Fri Sep 27 07:46:37 2002 +0000

description:
Bump date for pmap_remove addition.
Begin new sentences on new lines.
Use .Aq as much as possible instead of \*[Lt]foo\*[Gt].

diffstat:

 share/man/man9/pmap.9 |  345 +++++++++++++++++++++++++++----------------------
 1 files changed, 191 insertions(+), 154 deletions(-)

diffs (truncated from 749 to 300 lines):

diff -r 19dd383c2063 -r 41f60771ff5c share/man/man9/pmap.9
--- a/share/man/man9/pmap.9     Fri Sep 27 07:30:38 2002 +0000
+++ b/share/man/man9/pmap.9     Fri Sep 27 07:46:37 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: pmap.9,v 1.17 2002/09/22 07:22:28 chs Exp $
+.\"    $NetBSD: pmap.9,v 1.18 2002/09/27 07:46:37 wiz Exp $
 .\"
 .\" Copyright (c) 2000, 2001, 2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -34,7 +34,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd August 14, 2002
+.Dd September 27, 2002
 .Dt PMAP 9
 .Os
 .Sh NAME
@@ -125,7 +125,8 @@
 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
+the virtual memory system.
+The
 .Nm
 module is also responsible for maintaining certain information
 required by
@@ -137,8 +138,8 @@
 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
+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 ,
@@ -149,7 +150,8 @@
 .Fn pmap_update
 function to notify the
 .Nm
-module that the mappings need to be made correct.  Since the
+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
@@ -158,7 +160,7 @@
 the expense of virtual-to-physical mapping synchronization.
 .Ss HEADER FILES AND DATA STRUCTURES
 Machine-dependent code must provide the header file
-.Pa \*[Lt]machine/pmap.h\*[Gt] .
+.Aq Pa machine/pmap.h .
 This file contains the definition of the
 .Dv pmap
 structure:
@@ -176,7 +178,7 @@
 Note that all prototypes for
 .Nm
 interface functions are provided by the header file
-.Pa \*[Lt]uvm/uvm_pmap.h\*[Gt] .
+.Aq Pa uvm/uvm_pmap.h .
 It is possible to override this behavior by defining the
 C pre-processor macro
 .Dq PMAP_EXCLUDE_DECLS .
@@ -184,10 +186,11 @@
 .Nm
 API calls, for handling different MMU types in a single
 .Nm
-module, for example.  If the
+module, for example.
+If the
 .Dq PMAP_EXCLUDE_DECLS
 macro is defined,
-.Pa \*[Lt]machine/pmap.h\*[Gt]
+.Aq Pa machine/pmap.h
 .Em must
 provide function prototypes in a block like so:
 .Bd -literal -offset indent
@@ -199,10 +202,11 @@
 .Ed
 .Pp
 The header file
-.Pa \*[Lt]uvm/uvm_pmap.h\*[Gt]
+.Aq Pa uvm/uvm_pmap.h
 defines a structure for tracking
 .Nm
-statistics (see below).  This structure is defined as:
+statistics (see below).
+This structure is defined as:
 .Bd -literal -offset indent
 struct pmap_statistics {
         long        resident_count; /* number of mapped pages */
@@ -213,49 +217,50 @@
 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
+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
+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
+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 MODIFIED/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
+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
+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.
+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
+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
@@ -272,19 +277,22 @@
 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
+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
+mappings of those pages have modified/referenced tracking.
+Mappings entered with the
 .Fn pmap_enter
 function are
 .Dq managed
-mappings.  It is possible for
+mappings.
+It is possible for
 .Dq unmanaged
 mappings of a page to be created, using the
 .Fn pmap_kenter_pa
-function.  The use of
+function.
+The use of
 .Dq unmanaged
 mappings should be limited to code which may execute in interrupt context
 (for example, the kernel memory allocator), or to enter mappings for
@@ -302,17 +310,21 @@
 .Pp
 Also note that the modified/referenced information must be tracked
 on a per-page basis; they are not attributes of a mapping, but attributes
-of a page.  Therefore, even after all mappings for a given page have
+of a page.
+Therefore, even after all mappings for a given page have
 been removed, the modified/referenced information for that page
 .Em must
-be preserved.  The only time the modified/referenced attributes may
+be preserved.
+The only time the modified/referenced attributes may
 be cleared is when the virtual memory system 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 or referenced state is cleared.  (Prior to
+functions.
+These functions must also change any internal state necessary to detect
+the page being modified or referenced again after the modified or
+referenced state is cleared.
+(Prior to
 .Nx 1.6 ,
 .Nm
 implementations could get away without this because UVM (and Mach VM
@@ -333,16 +345,17 @@
 .Pp
 A
 .Dq resident
-page is one for which a mapping exists.  This statistic is used to
-compute the resident size of a process and enforce resource limits.
+page is one for which a mapping exists.
+This statistic is used to compute the resident size of a process and
+enforce resource limits.
 Only pages (whether managed by the virtual memory system or not)
 which are mapped into a physical map should be counted in the resident
 count.
 .Pp
 A
 .Dq wired
-page is one for which a wired mapping exists.  This statistic is used to
-enforce resource limits.
+page is one for which a wired mapping exists.
+This statistic is used to enforce resource limits.
 .Pp
 Note that it is recommended (though not required) that the
 .Nm
@@ -353,8 +366,9 @@
 statistics by placing it inside the
 .Dv pmap
 structure and adjusting the counts when mappings are established, changed,
-or removed.  This avoids potentially expensive data structure traversals
-when the statistics are queried.
+or removed.
+This avoids potentially expensive data structure traversals when the
+statistics are queried.
 .Ss REQUIRED FUNCTIONS
 This section describes functions that a
 .Nm
@@ -363,7 +377,8 @@
 .It void Fn "pmap_init" "void"
 This function initializes the
 .Nm
-module.  It is called by
+module.
+It is called by
 .Fn uvm_init
 to initialize any data structures that the module needs to
 manage physical maps.
@@ -377,8 +392,9 @@
 The
 .Fn pmap_virtual_space
 function is called to determine the initial kernel virtual address
-space beginning and end.  These values are used to create the kernel's
-virtual memory map.  The function must set
+space beginning and end.
+These values are used to create the kernel's virtual memory map.
+The function must set
 .Fa *vstartp
 to the first kernel virtual address that will be managed by
 .Xr uvm 9 ,
@@ -394,7 +410,8 @@
 implementation, then
 .Fa *vendp
 should be set to the maximum kernel virtual address allowed by the
-implementation.  If
+implementation.
+If
 .Fn pmap_growkernel
 is not used, then
 .Fa *vendp
@@ -403,13 +420,14 @@
 the resources currently allocated to map the kernel virtual address
 space.
 .It pmap_t Fn "pmap_create" "void"
-Create a physical map and return it to the caller.  The reference
-count on the new map is 1.
+Create a physical map and return it to the caller.
+The reference count on the new map is 1.
 .It void Fn "pmap_destroy" "pmap_t pmap"
-Drop the reference count on the specified physical map.  If the
-reference count drops to 0, all resources associated with the
-physical map are released and the physical map destroyed.  In the
-case of a drop-to-0, no mappings will exist in the map.  The