Module Name: src
Committed By: wiz
Date: Mon Dec 19 13:45:57 UTC 2016
Modified Files:
src/share/man/man9: uvm_hotplug.9
Log Message:
Various improvements.
New sentence, new line.
Better punctuation.
More appropriate macros.
More markup.
To generate a diff of this commit:
cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/uvm_hotplug.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/uvm_hotplug.9
diff -u src/share/man/man9/uvm_hotplug.9:1.1 src/share/man/man9/uvm_hotplug.9:1.2
--- src/share/man/man9/uvm_hotplug.9:1.1 Mon Dec 19 12:21:29 2016
+++ src/share/man/man9/uvm_hotplug.9 Mon Dec 19 13:45:57 2016
@@ -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 @@ Available starting page frame number of
.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 @@ when the plug fails.
.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 @@ Starting page frame number of the physic
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 @@ The arguments are:
.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 @@ The arguments are:
.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 @@ is returned,
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 @@ or
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 @@ otherwise.
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.
.Pp
.Fn uvm_physseg_get_avail_end
if a valid
.Fa uvm_physseg_t
handle is passed in, it returns the available ending 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.
.Pp
.Fn uvm_physseg_get_pg
if a valid
@@ -372,7 +385,8 @@ if a valid
.Fa uvm_physseg_t
handle is passed in, it returns the
.Fa free_list
-type for which the current segment is associated with. The returned value is of
+type for which the current segment is associated with.
+The returned value is of
type
.Fa int .
.Pp
@@ -381,13 +395,15 @@ if a valid
.Fa uvm_physseg_t
handle is passed in, it returns the
.Fa start_hint
-type for the current segment. The returned value is of type
+type for the current segment.
+The returned value is of type
.Fa u_int .
.Pp
.Fn uvm_physseg_set_start_hint
if a valid handle along with the
.Fa start_hint
-is passed in, the value is set in the segment. And a
+is passed in, the value is set in the segment.
+And a
.Fa true
is returned to indicate a successful value setting.
In case the handle is invalid a
@@ -397,54 +413,60 @@ is returned.
.Fn uvm_physseg_get_next
if a valid handle is passed in, it returns the next valid
.Fa uvm_physseg_t
-handle in the sequence. However if the handle passed is the last segment in the
+handle in the sequence.
+However if the handle passed is the last segment in the
sequence the function returns
.Fa UVM_PHYSSEG_TYPE_INVALID_OVERFLOW .
Passing an invalid handle is not fatal, and returns
-.Fa UVM_PHYSSEG_TYPE_INVALID
+.Fa UVM_PHYSSEG_TYPE_INVALID .
.
.Pp
.Fn uvm_physseg_get_prev
if a valid handle is passed in, it returns the previous validh
.Fa uvm_physseg_t
-handle in the sequence. However if the handle passed is the first segment in
+handle in the sequence.
+However if the handle passed is the first segment in
the sequence the function returns
.Fa UVM_PHYSSEG_TYPE_INVALID_EMPTY .
Passing an invalid handle is not fatal, and returns
-.Fa UVM_PHYSSEG_TYPE_INVALID
+.Fa UVM_PHYSSEG_TYPE_INVALID .
.
.Pp
.Fn uvm_physseg_get_first
returns the first valid
.Fa uvm_physseg_t
-handle in the sequence. However if there are no valid handles in the sequence
+handle in the sequence.
+However if there are no valid handles in the sequence
yet, the function returns
-.Fa UVM_PHYSSEG_TYPE_INVALID_EMPTY
+.Fa UVM_PHYSSEG_TYPE_INVALID_EMPTY .
.Pp
.Fn uvm_physseg_get_last
returns the last valid
.Fa uvm_physseg_t
-handle in the sequence. However if there are no valid handles in the sequence
+handle in the sequence.
+However if there are no valid handles in the sequence
yet, the function returns
-.Fa UVM_PHYSSEG_TYPE_INVALID_EMPTY
+.Fa UVM_PHYSSEG_TYPE_INVALID_EMPTY .
.Pp
.Fn uvm_physseg_get_highest_frame
returns the frame number of the highest registered physical page frame
which is of type
-.Fa paddr_t .
+.Ft paddr_t .
XXX: Searching on empty sequences are not yet processed in the function.
.Pp
.Fn uvm_physseg_find
searches for a given segment containing the page frame
-.Fa ( paddr_t )
-passed in. If a segment that falls between starting and ending addresses is
+.Ft ( paddr_t )
+passed in.
+If a segment that falls between starting and ending addresses is
found, the corresponding
.Fa uvm_physseg_t
handle is returned else a
.Fa UVM_PHYSSEG_TYPE_INVALID
-is returned. The second parameter, if not set to
-.Fa NULL
-, the offset value of the page frame passed in with respect to the
+is returned.
+The second parameter, if not set to
+.Dv NULL ,
+the offset value of the page frame passed in with respect to the
starting address is set to the appropriate
.Fa psize_t
value if the search was successful in finding the segment.
@@ -454,7 +476,7 @@ if a valid
.Fa uvm_physseg_t
handle is passed in along with the available starting physical address of the
segment of type
-.Fa paddr_t ,
+.Ft paddr_t ,
the value is set in the segment.
.Pp
.Fn uvm_physseg_set_avail_end
@@ -462,14 +484,14 @@ if a valid
.Fa uvm_physseg_t
handle is passed in along with the available ending physical address of the
segment of type
-.Fa paddr_t ,
+.Ft paddr_t ,
the value is set in the segment.
.Sh NOTES
.Fn uvm_physseg_plug
and
.Fn uvm_physseg_unplug
must never be used after
-.Pq Xr uvm_init
+.Xr uvm_init 9
in a kernel build where
.Cd 'options UVM_HOTPLUG'
is not enabled.
@@ -498,7 +520,7 @@ builds with and without
.Sh CODE REFERENCES
The uvm hotplug feature is implemented in the file
.Pa sys/uvm/uvm_physseg.c .
-The uvm hotplug api is exported via
+The uvm hotplug API is exported via
.Pa sys/uvm/uvm_physseg.h .
.Sh SEE ALSO
.Xr free 9 ,
@@ -509,13 +531,13 @@ The uvm hotplug api is exported via
.Sh HISTORY
This API emerged out of the need to insert new pages at runtime in the
Xen
-.Pq Xr balloon 9
+.Xr balloon 9
driver.
.Sh AUTHORS
.An -nosplit
.An Cherry G. Mathew
.Aq Mt che...@netbsd.org
-designed and integrated the api.
+designed and integrated the API.
.Pp
.An Santhosh N. Raju
.Aq Mt santhosh.r...@gmail.com
