[src/trunk]: src/share/man/man9 Various improvements.

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

details:   https://anonhg.NetBSD.org/src/rev/907e24cf7dee
branches:  trunk
changeset: 819846:907e24cf7dee
user:      wiz <wiz%NetBSD.org@localhost>
date:      Mon Dec 19 13:45:57 2016 +0000

description:
Various improvements.

New sentence, new line.
Better punctuation.
More appropriate macros.
More markup.

diffstat:

 share/man/man9/uvm_hotplug.9 |  210 +++++++++++++++++++++++-------------------
 1 files changed, 116 insertions(+), 94 deletions(-)

diffs (truncated from 472 to 300 lines):

diff -r 4cd8fae20919 -r 907e24cf7dee share/man/man9/uvm_hotplug.9
--- a/share/man/man9/uvm_hotplug.9      Mon Dec 19 13:02:14 2016 +0000
+++ b/share/man/man9/uvm_hotplug.9      Mon Dec 19 13:45:57 2016 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: uvm_hotplug.9,v 1.1 2016/12/19 12:21:29 cherry Exp $
+.\"    $NetBSD: uvm_hotplug.9,v 1.2 2016/12/19 13:45:57 wiz Exp $
 .\"
 .\" Copyright (c) 2016 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -75,39 +75,44 @@
 .Fn uvm_physseg_unplug "paddr_t pfn" "size_t npages"
 .Sh DESCRIPTION
 These utility routines provide the ability to tell
-.Pq Xr uvm 9
+.Xr uvm 9
 about system memory segments.
 When the kernel is compiled with
-.Cd 'options UVM_HOTPLUG'
-, memory segments are handled in a dynamic data structure
+.Cd 'options UVM_HOTPLUG' ,
+memory segments are handled in a dynamic data structure
 .Pq Xr rbtree 3
-compared to a static array when not. This enables kernel code to add
+compared to a static array when not.
+This enables kernel code to add
 or remove information about memory segments at any point after boot -
 thus "hotplug".
 .Pp
-.Fn uvm_page_physload
-.Fn uvm_page_physunload
+.Fn uvm_page_physload ,
+.Fn uvm_page_physunload ,
 and
 .Fn uvm_page_physunload_force
-are legacy interfaces which may be removed in the future. They must
+are legacy interfaces which may be removed in the future.
+They must
 never be used after
-.Pq Xr uvm_init 9
+.Xr uvm_init 9 .
 .Pp
-WARNING: This is an experimental feature and should not be used in production
-environments. Furthermore, attempting to "hotplug" without
+.Em WARNING:
+This is an experimental feature and should not be used in production
+environments.
+Furthermore, attempting to "hotplug" without
 .Cd 'options UVM_HOTPLUG'
 after boot will almost certainly end in a
-.Pq Xr panic 9
+.Xr panic 9 .
 .Sh USAGE
 .Ss INITIALIZING HOTPLUG
 The function
 .Fn uvm_physseg_init
-initializes the hotplug subsystem. This is expected to happen exactly
+initializes the hotplug subsystem.
+This is expected to happen exactly
 once, at boot time, and from MD code.
 .Ss PLUGGING IN MEMORY
 .Fn uvm_page_physload
 registers
-.Pq Xr uvm 9
+.Xr uvm 9
 with a memory segment span, and on a specified
 .Fa free_list.
 It must be called at system boot time as part of setting up memory
@@ -128,7 +133,7 @@
 .It Fa avail_end
 Available ending page frame number of the physical memory segments.
 .It Fa free_list
-The free list type are defined in the Machine Dependent code.
+The free list types are defined in the Machine Dependent code.
 .El
 .Pp
 This function returns a valid
@@ -139,15 +144,16 @@
 .Pp
 .Fn uvm_physseg_plug
 registers
-.Pq Xr uvm 9
+.Xr uvm 9
 with a memory segment span.
 It can also be called to initiate a hotplug and register a newly
-"hotplugged" physical memory range into the VM. Unlike
+"hotplugged" physical memory range into the VM.
+Unlike
 .Fn uvm_page_physload
 this function can, if
 .Cd 'options UVM_HOTPLUG'
 is enabled at compile time, be used after
-.Pq Xr uvm_init 9
+.Xr uvm_init 9 .
 The arguments describe the start page frame, the number of pages to
 plug starting from the start page frame and an optional return variable, which
 points to a valid
@@ -160,31 +166,31 @@
 Total number of pages from the starting page frame number to plug in.
 .It Fa upmp
 If upmp is not
-.Fa NULL ,
+.Dv NULL ,
 then on a successful plug, a valid pointer to the uvm_physseg_t handle
 for the segment which was plugged is returned.
 .El
 .Pp
 This function returns
 .Fa true
-when a successful plug occurs, 
+when a successful plug occurs,
 .Fa false
 otherwise.
 .Ss UNPLUGGING MEMORY
 The functions
-.Fn uvm_page_physunload
-,
-.Fn uvm_page_physunload_force
+.Fn uvm_page_physunload ,
+.Fn uvm_page_physunload_force ,
 and
 .Fn uvm_physseg_unplug
 make
-.Pq Xr uvm 9
+.Xr uvm 9
 forget about previously registered memory segments or portions of
 such.
 .Pp
 .Fn uvm_page_physunload
 unloads pages from a segment (from the front or from the back)
-depending on its availability. When the last page is removed, the
+depending on its availability.
+When the last page is removed, the
 segment handle is invalidated and supporting metadata is freed.
 .Pp Note: This function can only be used during boot time.
 Pages, once unloaded, are unregistered from uvm and are therefore
@@ -197,7 +203,7 @@
 .It Fa upm
 The handle identifying segment from which we are trying to unload memory.
 .It Fa free_list
-The free list type are defined in the Machine Dependent code.
+The free list types are defined in the Machine Dependent code.
 .It Fa paddrp
 The pointer to the physical address that was unloaded.
 .El
@@ -223,7 +229,7 @@
 .It Fa upm
 The handle identifying segment from which we are trying to unload memory.
 .It Fa free_list
-The free list type are defined in the Machine Dependent code.
+The free list types are defined in the Machine Dependent code.
 .It Fa paddrp
 The pointer to the physical address that was unloaded.
 .El
@@ -235,22 +241,25 @@
 otherwise.
 .Pp
 .Fn uvm_physseg_unplug
-can be called to unplug an existing physical memory segment. Unlike
+can be called to unplug an existing physical memory segment.
+Unlike
 .Fn uvm_page_physunload
 and
-.Fn uvm_page_physunload_force
-, it can be called after
-.Pq Xr uvm_init 9
-, if
+.Fn uvm_page_physunload_force ,
+it can be called after
+.Xr uvm_init 9 ,
+if
 .Cd 'options UVM_HOTPLUG'
 is enabled at compile time.
 .Fn uvm_hotplug 9
 makes no effort to manage the state of the underlying physical
-memory. It is upto the caller to ensure that it is not in use,
+memory.
+It is up to the caller to ensure that it is not in use,
 either by
-.Pq Xr uvm 9
-, or by any other sub-system. Further, any hardware
-quiescing that may be required, is the responsibility of MD code.
+.Xr uvm 9 ,
+or by any other sub-system.
+Further, any hardware
+quiescing that may be required is the responsibility of MD code.
 The arguments
 describe the start page frame and the number of pages to unplug.
 The arguments are:
@@ -268,48 +277,48 @@
 depending on success or failure respectively.
 .Sh UTILITY FUNCTIONS
 .Bl -ohang
-.It bool
+.It Ft bool
 .Fn uvm_physseg_valid "uvm_physseg_t upm";
-.It paddr_t
+.It Ft paddr_t
 .Fn uvm_physseg_get_start "uvm_physseg_t upm";
-.It paddr_t
+.It Ft paddr_t
 .Fn uvm_physseg_get_end "uvm_physseg_t upm";
-.It paddr_t
+.It Ft paddr_t
 .Fn uvm_physseg_get_avail_start "uvm_physseg_t upm";
-.It paddr_t
+.It Ft paddr_t
 .Fn uvm_physseg_get_avail_end "uvm_physseg_t upm";
-.It struct vm_page *
+.It Ft struct vm_page *
 .Fn uvm_physseg_get_pg "uvm_physseg_t upm" "paddr_t index";
-.It struct pmap_physseg *
+.It Ft struct pmap_physseg *
 .Fn uvm_physseg_get_pmesg "uvm_physseg_t upm";
-.It int
+.It Ft int
 .Fn uvm_physseg_get_free_list "uvm_physseg_t upm";
-.It u_int
+.It Ft u_int
 .Fn uvm_physseg_get_start_hint "uvm_physseg_t upm";
-.It bool
+.It Ft bool
 .Fn uvm_physseg_set_start_hint "uvm_physseg_t upm" "u_int start_hint";
-.It uvm_physseg_t
+.It Ft uvm_physseg_t
 .Fn uvm_physseg_get_next "uvm_physseg_t upm";
-.It uvm_physseg_t
+.It Ft uvm_physseg_t
 .Fn uvm_physseg_get_prev "uvm_physseg_t upm";
-.It uvm_physseg_t
+.It Ft uvm_physseg_t
 .Fn uvm_physseg_get_first "void";
-.It uvm_physseg_t
+.It Ft uvm_physseg_t
 .Fn uvm_physseg_get_last "void";
-.It paddr_t
+.It Ft paddr_t
 .Fn uvm_physseg_get_highest_frame "void";
-.It paddr_t
+.It Ft paddr_t
 .Fn uvm_physseg_find "paddr pframe" "psize_t *offsetp";
-.It void
+.It Ft void
 .Fn uvm_physseg_set_avail_start "uvm_physseg_t upm" "paddr_t avail_start";
-.It void
+.It Ft void
 .Fn uvm_physseg_set_avail_end "uvm_physseg_t upm" "paddr_t avail_end";
 .El
 .Pp
 .Fn uvm_physseg_valid
 validates a handle that is passed in, returns
 .Fa true
-if the given handle is valid, 
+if the given handle is valid,
 .Fa false
 otherwise.
 .Pp
@@ -317,41 +326,45 @@
 if a valid
 .Fa uvm_physseg_t
 handle is passed in, it returns the starting physical address of
-the segment. The returned value is of type
-.Fa paddr_t .
+the segment.
+The returned value is of type
+.Ft paddr_t .
 In case the handle is invalid the returned value will match
-.Fa ( paddr_t )
--1.
+.Ft ( paddr_t )
+\-1.
 .Pp
 .Fn uvm_physseg_get_end
 if a valid
 .Fa uvm_physseg_t
 handle is passed in, it returns the ending physical address of the
-segment. The returned value is of type
-.Fa paddr_t .
+segment.
+The returned value is of type
+.Ft paddr_t .
 In case the handle is invalid the returned value will match
-.Fa ( paddr_t )
--1.
+.Ft ( paddr_t )
+\-1.
 .Pp
 .Fn uvm_physseg_get_avail_start
 if a valid
 .Fa uvm_physseg_t
 handle is passed in, it returns the available starting physical
-address of the segment. The returned value is of type
-.Fa paddr_t .
+address of the segment.
+The returned value is of type
+.Ft paddr_t .
 In case the handle is invalid the returned value will match
-.Fa ( paddr_t )
--1.
+.Ft ( paddr_t )
+\-1.