Sat Dec 24 08:05:47 2016 UTC ()
Fix SYNOPSIS. Fix xref. Avoid Xr for itself.


(wiz)
diff -r1.3 -r1.4 src/share/man/man9/uvm_hotplug.9
cvs diff -r1.3 -r1.4 src/share/man/man9/uvm_hotplug.9 (expand / switch to unified diff)

--- src/share/man/man9/uvm_hotplug.9 2016/12/24 07:22:41 1.3
+++ src/share/man/man9/uvm_hotplug.9 2016/12/24 08:05:47 1.4
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: uvm_hotplug.9,v 1.3 2016/12/24 07:22:41 abhinav Exp $ 1.\" $NetBSD: uvm_hotplug.9,v 1.4 2016/12/24 08:05:47 wiz Exp $
2.\" 2.\"
3.\" Copyright (c) 2016 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2016 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Cherry G Mathew and Santhosh N Raju. 7.\" by Cherry G Mathew and Santhosh N Raju.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
@@ -85,46 +85,46 @@ compared to a static array when not. @@ -85,46 +85,46 @@ compared to a static array when not.
85This enables kernel code to add 85This enables kernel code to add
86or remove information about memory segments at any point after boot - 86or remove information about memory segments at any point after boot -
87thus "hotplug". 87thus "hotplug".
88.Pp 88.Pp
89.Fn uvm_page_physload , 89.Fn uvm_page_physload ,
90.Fn uvm_page_physunload , 90.Fn uvm_page_physunload ,
91and 91and
92.Fn uvm_page_physunload_force 92.Fn uvm_page_physunload_force
93are legacy interfaces which may be removed in the future. 93are legacy interfaces which may be removed in the future.
94They must 94They must
95never be used after 95never be used after
96.Xr uvm_init 9 . 96.Xr uvm_init 9 .
97.Pp 97.Pp
98.Em WARNING: 98.Em WARNING :
99This is an experimental feature and should not be used in production 99This is an experimental feature and should not be used in production
100environments. 100environments.
101Furthermore, attempting to "hotplug" without 101Furthermore, attempting to "hotplug" without
102.Cd 'options UVM_HOTPLUG' 102.Cd 'options UVM_HOTPLUG'
103after boot will almost certainly end in a 103after boot will almost certainly end in a
104.Xr panic 9 . 104.Xr panic 9 .
105.Sh USAGE 105.Sh USAGE
106.Ss INITIALIZING HOTPLUG 106.Ss INITIALIZING HOTPLUG
107The function 107The function
108.Fn uvm_physseg_init 108.Fn uvm_physseg_init
109initializes the hotplug subsystem. 109initializes the hotplug subsystem.
110This is expected to happen exactly 110This is expected to happen exactly
111once, at boot time, and from MD code. 111once, at boot time, and from MD code.
112.Ss PLUGGING IN MEMORY 112.Ss PLUGGING IN MEMORY
113.Fn uvm_page_physload 113.Fn uvm_page_physload
114registers 114registers
115.Xr uvm 9 115.Xr uvm 9
116with a memory segment span, and on a specified 116with a memory segment span, and on a specified
117.Fa free_list. 117.Fa free_list .
118It must be called at system boot time as part of setting up memory 118It must be called at system boot time as part of setting up memory
119management. 119management.
120The arguments describe the start and end of the physical addresses of the 120The arguments describe the start and end of the physical addresses of the
121segment, and the available start and end addresses of pages not already in use. 121segment, and the available start and end addresses of pages not already in use.
122If a system has memory banks of different speeds the slower memory should be 122If a system has memory banks of different speeds the slower memory should be
123given a higher 123given a higher
124.Fa free_list 124.Fa free_list
125value. 125value.
126.Bl -tag -offset indent -width "avail_start" 126.Bl -tag -offset indent -width "avail_start"
127.It Fa start 127.It Fa start
128Starting page frame number of the physical memory segments. 128Starting page frame number of the physical memory segments.
129.It Fa end 129.It Fa end
130Ending page frame number of the physical memory segments. 130Ending page frame number of the physical memory segments.
@@ -270,61 +270,61 @@ The arguments are: @@ -270,61 +270,61 @@ The arguments are:
270Starting page frame number of the physical memory segment. 270Starting page frame number of the physical memory segment.
271.It Fa npages 271.It Fa npages
272Total number of pages from the starting page frame number to unplug. 272Total number of pages from the starting page frame number to unplug.
273.El 273.El
274.Pp 274.Pp
275Returns 275Returns
276.Fa true 276.Fa true
277or 277or
278.Fa false 278.Fa false
279depending on success or failure respectively. 279depending on success or failure respectively.
280.Sh UTILITY FUNCTIONS 280.Sh UTILITY FUNCTIONS
281.Bl -ohang 281.Bl -ohang
282.It Ft bool 282.It Ft bool
283.Fn uvm_physseg_valid "uvm_physseg_t upm"; 283.Fn uvm_physseg_valid "uvm_physseg_t upm"
284.It Ft paddr_t 284.It Ft paddr_t
285.Fn uvm_physseg_get_start "uvm_physseg_t upm"; 285.Fn uvm_physseg_get_start "uvm_physseg_t upm"
286.It Ft paddr_t 286.It Ft paddr_t
287.Fn uvm_physseg_get_end "uvm_physseg_t upm"; 287.Fn uvm_physseg_get_end "uvm_physseg_t upm"
288.It Ft paddr_t 288.It Ft paddr_t
289.Fn uvm_physseg_get_avail_start "uvm_physseg_t upm"; 289.Fn uvm_physseg_get_avail_start "uvm_physseg_t upm"
290.It Ft paddr_t 290.It Ft paddr_t
291.Fn uvm_physseg_get_avail_end "uvm_physseg_t upm"; 291.Fn uvm_physseg_get_avail_end "uvm_physseg_t upm"
292.It Ft struct vm_page * 292.It Ft struct vm_page *
293.Fn uvm_physseg_get_pg "uvm_physseg_t upm" "paddr_t index"; 293.Fn uvm_physseg_get_pg "uvm_physseg_t upm" "paddr_t index"
294.It Ft struct pmap_physseg * 294.It Ft struct pmap_physseg *
295.Fn uvm_physseg_get_pmesg "uvm_physseg_t upm"; 295.Fn uvm_physseg_get_pmesg "uvm_physseg_t upm"
296.It Ft int 296.It Ft int
297.Fn uvm_physseg_get_free_list "uvm_physseg_t upm"; 297.Fn uvm_physseg_get_free_list "uvm_physseg_t upm"
298.It Ft u_int 298.It Ft u_int
299.Fn uvm_physseg_get_start_hint "uvm_physseg_t upm"; 299.Fn uvm_physseg_get_start_hint "uvm_physseg_t upm"
300.It Ft bool 300.It Ft bool
301.Fn uvm_physseg_set_start_hint "uvm_physseg_t upm" "u_int start_hint"; 301.Fn uvm_physseg_set_start_hint "uvm_physseg_t upm" "u_int start_hint"
302.It Ft uvm_physseg_t 302.It Ft uvm_physseg_t
303.Fn uvm_physseg_get_next "uvm_physseg_t upm"; 303.Fn uvm_physseg_get_next "uvm_physseg_t upm"
304.It Ft uvm_physseg_t 304.It Ft uvm_physseg_t
305.Fn uvm_physseg_get_prev "uvm_physseg_t upm"; 305.Fn uvm_physseg_get_prev "uvm_physseg_t upm"
306.It Ft uvm_physseg_t 306.It Ft uvm_physseg_t
307.Fn uvm_physseg_get_first "void"; 307.Fn uvm_physseg_get_first "void"
308.It Ft uvm_physseg_t 308.It Ft uvm_physseg_t
309.Fn uvm_physseg_get_last "void"; 309.Fn uvm_physseg_get_last "void"
310.It Ft paddr_t 310.It Ft paddr_t
311.Fn uvm_physseg_get_highest_frame "void"; 311.Fn uvm_physseg_get_highest_frame "void"
312.It Ft paddr_t 312.It Ft paddr_t
313.Fn uvm_physseg_find "paddr pframe" "psize_t *offsetp"; 313.Fn uvm_physseg_find "paddr pframe" "psize_t *offsetp"
314.It Ft void 314.It Ft void
315.Fn uvm_physseg_set_avail_start "uvm_physseg_t upm" "paddr_t avail_start"; 315.Fn uvm_physseg_set_avail_start "uvm_physseg_t upm" "paddr_t avail_start"
316.It Ft void 316.It Ft void
317.Fn uvm_physseg_set_avail_end "uvm_physseg_t upm" "paddr_t avail_end"; 317.Fn uvm_physseg_set_avail_end "uvm_physseg_t upm" "paddr_t avail_end"
318.El 318.El
319.Pp 319.Pp
320.Fn uvm_physseg_valid 320.Fn uvm_physseg_valid
321validates a handle that is passed in, returns 321validates a handle that is passed in, returns
322.Fa true 322.Fa true
323if the given handle is valid, 323if the given handle is valid,
324.Fa false 324.Fa false
325otherwise. 325otherwise.
326.Pp 326.Pp
327.Fn uvm_physseg_get_start 327.Fn uvm_physseg_get_start
328if a valid 328if a valid
329.Fa uvm_physseg_t 329.Fa uvm_physseg_t
330handle is passed in, it returns the starting physical address of 330handle is passed in, it returns the starting physical address of
@@ -489,61 +489,61 @@ segment of type @@ -489,61 +489,61 @@ segment of type
489.Ft paddr_t , 489.Ft paddr_t ,
490the value is set in the segment. 490the value is set in the segment.
491.Sh NOTES 491.Sh NOTES
492.Fn uvm_physseg_plug 492.Fn uvm_physseg_plug
493and 493and
494.Fn uvm_physseg_unplug 494.Fn uvm_physseg_unplug
495must never be used after 495must never be used after
496.Xr uvm_init 9 496.Xr uvm_init 9
497in a kernel build where 497in a kernel build where
498.Cd 'options UVM_HOTPLUG' 498.Cd 'options UVM_HOTPLUG'
499is not enabled. 499is not enabled.
500.Sh DIAGNOSTICS 500.Sh DIAGNOSTICS
501Tests for 501Tests for
502.Xr uvm_hotplug 9 502.Nm
503are in 503are in
504.Pa tests/sys/uvm . 504.Pa tests/sys/uvm .
505.Pp 505.Pp
506Unit / functional tests are in 506Unit / functional tests are in
507.Pa tests/sys/uvm/t_uvm_physseg.c . 507.Pa tests/sys/uvm/t_uvm_physseg.c .
508These tests focus on the expected working of the 508These tests focus on the expected working of the
509.Xr uvm_hotplug 9 509.Nm
510API and its utility functions. 510API and its utility functions.
511.Pp 511.Pp
512Load tests can be found in 512Load tests can be found in
513.Pa tests/sys/uvm/t_uvm_physseg_load.c . 513.Pa tests/sys/uvm/t_uvm_physseg_load.c .
514These tests focus on stressing the 514These tests focus on stressing the
515.Xr uvm_hotplug 9 515.Nm
516implementation in order to make performance comparisons between kernel 516implementation in order to make performance comparisons between kernel
517builds with and without 517builds with and without
518.Cd 'options UVM_HOTPLUG' 518.Cd 'options UVM_HOTPLUG'
519. 519.
520.\" .Sh RETURN VALUES 520.\" .Sh RETURN VALUES
521.\" .Sh EXAMPLES 521.\" .Sh EXAMPLES
522.Sh CODE REFERENCES 522.Sh CODE REFERENCES
523The uvm hotplug feature is implemented in the file 523The uvm hotplug feature is implemented in the file
524.Pa sys/uvm/uvm_physseg.c . 524.Pa sys/uvm/uvm_physseg.c .
525The uvm hotplug API is exported via 525The uvm hotplug API is exported via
526.Pa sys/uvm/uvm_physseg.h . 526.Pa sys/uvm/uvm_physseg.h .
527.Sh SEE ALSO 527.Sh SEE ALSO
528.Xr extent 9 , 528.Xr extent 9 ,
529.Xr free 9 , 529.Xr free 9 ,
530.Xr malloc 9 , 530.Xr malloc 9 ,
531.Xr memoryallocators 9 , 531.Xr memoryallocators 9 ,
532.Xr uvm 9 532.Xr uvm 9
533.Sh HISTORY 533.Sh HISTORY
534This API emerged out of the need to insert new pages at runtime in the 534This API emerged out of the need to insert new pages at runtime in the
535Xen 535Xen
536.Xr balloon 9 536.Xr x86/balloon 4
537driver. 537driver.
538.Sh AUTHORS 538.Sh AUTHORS
539.An -nosplit 539.An -nosplit
540.An Cherry G. Mathew 540.An Cherry G. Mathew
541.Aq Mt cherry@NetBSD.org 541.Aq Mt cherry@NetBSD.org
542designed and integrated the API. 542designed and integrated the API.
543.Pp 543.Pp
544.An Santhosh N. Raju 544.An Santhosh N. Raju
545.Aq Mt santhosh.raju@gmail.com 545.Aq Mt santhosh.raju@gmail.com
546implemented the dynamic segment handling code and all tests for this API. 546implemented the dynamic segment handling code and all tests for this API.
547.Pp 547.Pp
548.An Nick Hudson 548.An Nick Hudson
549.Aq Mt skrll@NetBSD.org 549.Aq Mt skrll@NetBSD.org