chcpu: man page update

Move chcpu man page to section 8 (admin commands) where it belongs.
Also update the contents of the man page.

Signed-off-by: Heiko Carstens <heiko.carstens@de.ibm.com>

1 files changed, 53 insertions, 62 deletions

diff --git a/sys-utils/chcpu.8 b/sys-utils/chcpu.8
index 7cb481c4d..8bafd0d6c 100644
--- a/sys-utils/chcpu.8
+++ b/sys-utils/chcpu.8
@@ -1,85 +1,76 @@
-.TH CHCPU 8 "August 2011" "util-linux" "System Administration"
+.TH CHCPU 8 "August 2011" Linux "User Manuals"
 .SH NAME
-chcpu \- CPU configuration utility
+chcpu \- configure CPUs
 .SH SYNOPSIS
 .B chcpu
-\fB-c\fP|\fB\-d\fP|\fB\-e\fP|\fB\-g\fP
-.IR cpu-list
+.BR \-e | \-d | \-c | \-g " \fIcpu-list\fP"
 .br
-.B
-\fBchcpu \-p\fP \fImode\fP
+.B chcpu
+.BR \-p " \fImode\fP"
+.br
+.B chcpu
+.BR \-r
 .br
 .B chcpu
-.RB [ \-rhV\ ]
+.BR \-h | \-V
 .br
 .SH DESCRIPTION
 .B chcpu
-can modify the logical state of CPUs. It can enable and disable CPUs, scan
-for new CPUs, change the CPU dispatching mode of the underlying hypervisor
-and request (configure) or give logical CPUs back (deconfigure) to the
-the underlying hypervisor.
+can modify the state of CPUs. It can enable or disable CPUs, scan
+for new CPUs, change the CPU dispatching mode of the underlying hypervisor,
+and request CPUs from the hypervisor (configure) or return CPUs to the
+hypervisor (deconfigure).
+
+Some options have a \fIcpu-list\fP argument. Use this argument to specify a
+comma-separated list of CPUs. The list can contain individual CPU addresses or
+ranges of addresses.
+For example,
+.BR 0,5,7,9-11
+makes the command applicable to the CPUs with the addresses 0, 5, 7, 9, 10, and
+11.
 
-Some options have a \fIcpu-list\fP argument. A \fIcpu-list\fP may specify
-multiple CPUs, separated by comma, and ranges.  For example,
-.BR 0,5,7,9-11 .
 .SH OPTIONS
-The --configure, --deconfigure, --disable, --dispatch, --enable and --rescan
-options are mutually exclusive.
 .TP
-.BR \-c , " \-\-configure " <\fIcpu-list\fP>
-Configure all CPUs specified with \fIcpu-list\fP. If
-.BR chcpu
-fails to configure a CPU specified in the \fIcpu-list\fP it will skip that
-CPU and continue with the next one until all specified CPUs have been
-processed.
-.br
-Configuring a CPU means that the underlying hypervisor is informed that
-a logical CPU within a guest should be used. If the hypervisor has enough
-resources the request will succeed.
+.BR \-r , " \-\-rescan"
+Trigger a rescan of CPUs. Use this option on systems that do not automatically
+detect newly attached CPUs. The Linux kernel then recognizes the new CPUs.
 .TP
-.BR \-d , " \-\-disable " <\fIcpu-list\fP>
-Disable all CPUs specified with \fIcpu-list\fP. If
-.BR chcpu
-fails to disable a CPU specified in the \fIcpu-list\fP it will skip that
-CPU and continue with the next one until all specified CPUs have been
-processed.
-.br
-When a CPU has been disabled its state is offline.
+.BR \-c , " \-\-configure " \fIcpu-list\fP
+Configure all specified CPUs. Configuring a CPU means that the hypervisor takes
+a CPU from the CPU pool and assigns it to the virtual hardware on which your
+kernel runs.
 .TP
-.BR \-e , " \-\-enable " <\fIcpu-list\fP>
-Enable all CPUs specified with \fIcpu-list\fP. If
-.BR chcpu
-fails to enable a CPU specified in the \fIcpu-list\fP it will skip that
-CPU and continue with the next one until all specified CPUs have been
-processed.
-.br
-When a CPU has been enabled its state is online.
+.BR \-e , " \-\-enable " \fIcpu-list\fP
+Enable all specified CPUs. Enabling a CPU means that the kernel sets it
+online. A CPU must be configured, see -c,  before it can be enabled.
 .TP
-.BR \-g , " \-\-deconfigure " <\fIcpu-list\fP>
-Deconfigure all CPUs specified with \fIcpu-list\fP. If
-.BR chcpu
-fails to deconfigure a CPU specified in the \fIcpu-list\fP it will skip
-that CPU and continue with the next one until all specified CPUs have been
-processed. Only disabled (offline) CPUs can be deconfigured.
-.br
-Deconfiguring a CPU means that the underlying hypervisor is informed that
-the CPU will not be used anymore and that the hypervisor can add the CPU
-back to its CPU pool.
+.BR \-p , " \-\-dispatch " \fImode\fP
+Set the CPU dispatching mode (polarization). This option has an effect only if
+your hardware architecture and hypervisor support CPU polarization. There are
+two modes:
+.RS
+.TP 12
+.B horizontal
+The workload is spread across all available CPUs.
+.TP 12
+.B vertical
+The workload is concentrated on few CPUs.
+.RE
 .TP
-.BR \-h , " \-\-help"
-Print a help text and exit.
+.BR \-d , " \-\-disable " \fIcpu-list\fP
+Disable all specified CPUs. Disabling a CPU means that the kernel sets it offline.
 .TP
-.BR \-p , " \-\-dispatch " <\fImode\fP>
-Set the CPU dispatching \fImode\fP if the underlying hypervisor supports this.
-\fImode\fP may be horizontal or vertical.
+.BR \-g , " \-\-deconfigure " \fIcpu-list\fP
+Deconfigure all specified CPUs. Deconfiguring a CPU means that the hypervisor
+removes the CPU from the virtual hardware on which the Linux instance runs and
+returns it to the CPU pool. A CPU must be offline, see -d,  before it can be
+deconfigured. 
 .TP
-.BR \-r , " \-\-rescan"
-Trigger a rescan of CPUs. If new CPUs have been attached to the system the
-kernel will detect them. On some systems no event will be generated if a
-CPU gets attached. In that case a CPU rescan must be manually triggered.
+.BR \-h , " \-\-help"
+Display help information and exit.
 .TP
 .BR \-V , " \-\-version"
-Output version information and exit.
+Display version information and exit.
 .SH AUTHOR
 .nf
 Heiko Carstens <heiko.carstens@de.ibm.com>