[PATCH 0/6] chcpu und lscpu updates

[PATCH 0/6] chcpu und lscpu updates

[Heiko Carstens]

Hi Karel,

just some more small updates for chcpu and lscpu. The main part are
the man pages updates. Hopefully for the better :)

Thanks,
Heiko

Heiko Carstens (6):
  lscpu: switch Yes/No output to lower case
  lscpu: fix typo in help text
  lscpu: change column names back to mixed case
  lscpu: add s390 kvm test case
  chcpu: man page update
  lscpu: man page update

 sys-utils/Makefile.am                |    2 +-
 sys-utils/chcpu.1                    |   94 -----------------------
 sys-utils/chcpu.8                    |   85 +++++++++++++++++++++
 sys-utils/lscpu.1                    |  136 ++++++++++++++++++++++++----------
 sys-utils/lscpu.c                    |   37 ++++-----
 tests/expected/lscpu/lscpu-s390-kvm  |   21 +++++
 tests/ts/lscpu/dumps/s390-kvm.tar.gz |  Bin 0 -> 2275 bytes
 7 files changed, 221 insertions(+), 154 deletions(-)
 delete mode 100644 sys-utils/chcpu.1
 create mode 100644 sys-utils/chcpu.8
 create mode 100644 tests/expected/lscpu/lscpu-s390-kvm
 create mode 100644 tests/ts/lscpu/dumps/s390-kvm.tar.gz

-- 
1.7.6.3

[PATCH 1/6] lscpu: switch Yes/No output to lower case

[Heiko Carstens]

Some people complained about the first letter of Yes/No as seen in the
online and configured column in the human readabe output being a capital
letter instead of the expected lower case letter.
So let's try to make everbody happy and convert them to lower case.

Signed-off-by: Heiko Carstens <heiko.carstens@de.ibm.com>
---
 sys-utils/lscpu.c |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/sys-utils/lscpu.c b/sys-utils/lscpu.c
index 8637ef1..66fa971 100644
--- a/sys-utils/lscpu.c
+++ b/sys-utils/lscpu.c
@@ -850,7 +850,7 @@ get_cell_data(struct lscpu_desc *desc, int cpu, int col,
 				 desc->configured[cpu] ? _("Y") : _("N"));
 		else
 			snprintf(buf, bufsz,
-				 desc->configured[cpu] ? _("Yes") : _("No"));
+				 desc->configured[cpu] ? _("yes") : _("no"));
 		break;
 	case COL_ONLINE:
 		if (!desc->online)
@@ -860,7 +860,7 @@ get_cell_data(struct lscpu_desc *desc, int cpu, int col,
 				 is_cpu_online(desc, cpu) ? _("Y") : _("N"));
 		else
 			snprintf(buf, bufsz,
-				 is_cpu_online(desc, cpu) ? _("Yes") : _("No"));
+				 is_cpu_online(desc, cpu) ? _("yes") : _("no"));
 		break;
 	}
 	return buf;
-- 
1.7.6.3

[PATCH 2/6] lscpu: fix typo in help text

[Heiko Carstens]

Add missing 'n' in help text for extended output line.

Signed-off-by: Heiko Carstens <heiko.carstens@de.ibm.com>
---
 sys-utils/lscpu.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/sys-utils/lscpu.c b/sys-utils/lscpu.c
index 66fa971..7c8cb13 100644
--- a/sys-utils/lscpu.c
+++ b/sys-utils/lscpu.c
@@ -1197,7 +1197,7 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 	fputs(_(" -a, --all               print online and offline CPUs (default for -e)\n"
 		" -b, --online            print online CPUs only (default for -p)\n"
 		" -c, --offline           print offline CPUs only\n"
-		" -e, --extended[=<list>] print out a extended readable format\n"
+		" -e, --extended[=<list>] print out an extended readable format\n"
 		" -h, --help              print this help\n"
 		" -p, --parse[=<list>]    print out a parsable format\n"
 		" -s, --sysroot <dir>     use directory DIR as system root\n"
-- 
1.7.6.3

[PATCH 3/6] lscpu: change column names back to mixed case

[Heiko Carstens]

Commit b9d18bc3 "lscpu: add column names to --help" changed all column names
to upper case only and printed the column names for the parsable output in
lower case.
However current behaviour was that for the parsable output the column names
were printed in mixed case. The change might break existing other tools and
breaks also the util-linux internal lscpu tests.
So revert part of the above commit and restore the old behaviour.

Signed-off-by: Heiko Carstens <heiko.carstens@de.ibm.com>
---
 sys-utils/lscpu.c |   31 ++++++++++++++-----------------
 1 files changed, 14 insertions(+), 17 deletions(-)

diff --git a/sys-utils/lscpu.c b/sys-utils/lscpu.c
index 7c8cb13..63facc3 100644
--- a/sys-utils/lscpu.c
+++ b/sys-utils/lscpu.c
@@ -224,15 +224,15 @@ enum {
 static const char *colnames[] =
 {
 	[COL_CPU] = "CPU",
-	[COL_CORE] = "CORE",
-	[COL_SOCKET] = "SOCKET",
-	[COL_NODE] = "NODE",
-	[COL_BOOK] = "BOOK",
-	[COL_CACHE] = "CACHE",
-	[COL_POLARIZATION] = "POLARIZATION",
-	[COL_ADDRESS] = "ADDRESS",
-	[COL_CONFIGURED] = "CONFIGURED",
-	[COL_ONLINE] = "ONLINE",
+	[COL_CORE] = "Core",
+	[COL_SOCKET] = "Socket",
+	[COL_NODE] = "Node",
+	[COL_BOOK] = "Book",
+	[COL_CACHE] = "Cache",
+	[COL_POLARIZATION] = "Polarization",
+	[COL_ADDRESS] = "Address",
+	[COL_CONFIGURED] = "Configured",
+	[COL_ONLINE] = "Online",
 };
 
 
@@ -937,8 +937,6 @@ print_parsable(struct lscpu_desc *desc, int cols[], int ncols,
 
 	fputs("# ", stdout);
 	for (i = 0; i < ncols; i++) {
-		char *p;
-
 		if (cols[i] == COL_CACHE) {
 			if (mod->compat && !desc->ncaches)
 				continue;
@@ -948,11 +946,7 @@ print_parsable(struct lscpu_desc *desc, int cols[], int ncols,
 		if (i > 0)
 			putchar(',');
 
-		p = data = get_cell_header(desc, cols[i],
-					   mod, buf, sizeof(buf));
-		while (p && *p != '\0')
-			*p++ = tolower((unsigned int) *p);
-
+		data = get_cell_header(desc, cols[i], mod, buf, sizeof(buf));
 		fputs(data && *data ? data : "", stdout);
 	}
 	putchar('\n');
@@ -1000,7 +994,10 @@ print_readable(struct lscpu_desc *desc, int cols[], int ncols,
 		 err(EXIT_FAILURE, _("failed to initialize output table"));
 
 	for (i = 0; i < ncols; i++) {
-		data = get_cell_header(desc, cols[i], mod, buf, sizeof(buf));
+		char *p = data = get_cell_header(desc, cols[i],
+						 mod, buf, sizeof(buf));
+		while (p && *p != '\0')
+			*p++ = toupper((unsigned int) *p);
 		tt_define_column(tt, xstrdup(data), 0, 0);
 	}
 
-- 
1.7.6.3

[PATCH 4/6] lscpu: add s390 kvm test case

[Heiko Carstens]

Signed-off-by: Heiko Carstens <heiko.carstens@de.ibm.com>
---
 tests/expected/lscpu/lscpu-s390-kvm  |   21 +++++++++++++++++++++
 tests/ts/lscpu/dumps/s390-kvm.tar.gz |  Bin 0 -> 2275 bytes
 2 files changed, 21 insertions(+), 0 deletions(-)
 create mode 100644 tests/expected/lscpu/lscpu-s390-kvm
 create mode 100644 tests/ts/lscpu/dumps/s390-kvm.tar.gz

diff --git a/tests/expected/lscpu/lscpu-s390-kvm b/tests/expected/lscpu/lscpu-s390-kvm
new file mode 100644
index 0000000..1aa42f9
--- /dev/null
+++ b/tests/expected/lscpu/lscpu-s390-kvm
@@ -0,0 +1,21 @@
+CPU op-mode(s):        32-bit, 64-bit
+CPU(s):                3
+On-line CPU(s) list:   0-2
+Thread(s) per core:    1
+Core(s) per socket:    1
+Socket(s) per book:    1
+Book(s):               3
+Vendor ID:             IBM/S390
+BogoMIPS:              14367.00
+Hypervisor:            KVM/Linux
+Hypervisor vendor:     KVM
+Virtualization type:   full
+Dispatching mode:      horizontal
+
+# The following is the parsable format, which can be fed to other
+# programs. Each different item in every column has an unique ID
+# starting from zero.
+# CPU,Core,Socket,Node
+0,0,0,
+1,1,1,
+2,2,2,
diff --git a/tests/ts/lscpu/dumps/s390-kvm.tar.gz b/tests/ts/lscpu/dumps/s390-kvm.tar.gz
new file mode 100644
index 0000000000000000000000000000000000000000..340f7eabe57b1d9bfcb5f8a959013cd9d7e395f4
GIT binary patch
literal 2275
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
Zl--A}SGuD2%Xyh%nMwSLCEA1~{{VRm2#o*$

literal 0
HcmV?d00001

-- 
1.7.6.3

[PATCH 5/6] chcpu: man page update

[Heiko Carstens]

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>
---
 sys-utils/Makefile.am |    2 +-
 sys-utils/chcpu.1     |   94 -------------------------------------------------
 sys-utils/chcpu.8     |   85 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 86 insertions(+), 95 deletions(-)
 delete mode 100644 sys-utils/chcpu.1
 create mode 100644 sys-utils/chcpu.8

diff --git a/sys-utils/Makefile.am b/sys-utils/Makefile.am
index 8059ee6..1be7eaf 100644
--- a/sys-utils/Makefile.am
+++ b/sys-utils/Makefile.am
@@ -28,7 +28,7 @@ dist_man_MANS += lscpu.1
 sbin_PROGRAMS += chcpu
 chcpu_SOURCES = chcpu.c $(top_srcdir)/lib/cpuset.c \
 			$(top_srcdir)/lib/path.c
-dist_man_MANS += chcpu.1
+dist_man_MANS += chcpu.8
 endif
 
 endif
diff --git a/sys-utils/chcpu.1 b/sys-utils/chcpu.1
deleted file mode 100644
index 9417a72..0000000
--- a/sys-utils/chcpu.1
+++ /dev/null
@@ -1,94 +0,0 @@
-.TH CHCPU 1 "August 2011" Linux "User Manuals"
-.SH NAME
-chcpu \- CPU configuration utility
-.SH SYNOPSIS
-.B chcpu
-\fB-c\fP|\fB\-d\fP|\fB\-e\fP|\fB\-g\fP
-.IR cpu-list
-.br
-.B
-\fBchcpu \-p\fP \fImode\fP
-.br
-.B chcpu
-.RB [ \-rhV\ ]
-.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.
-
-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.
-.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.
-.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.
-.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.
-.TP
-.BR \-h , " \-\-help"
-Print a help text and exit.
-.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.
-.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.
-.TP
-.BR \-V , " \-\-version"
-Output version information and exit.
-.SH AUTHOR
-.nf
-Heiko Carstens <heiko.carstens@de.ibm.com>
-.fi
-.SH COPYRIGHT
-Copyright IBM Corp. 2011
-.br
-.SH "SEE ALSO"
-.BR lscpu (1)
-.SH AVAILABILITY
-The chcpu command is part of the util-linux package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
diff --git a/sys-utils/chcpu.8 b/sys-utils/chcpu.8
new file mode 100644
index 0000000..8bafd0d
--- /dev/null
+++ b/sys-utils/chcpu.8
@@ -0,0 +1,85 @@
+.TH CHCPU 8 "August 2011" Linux "User Manuals"
+.SH NAME
+chcpu \- configure CPUs
+.SH SYNOPSIS
+.B chcpu
+.BR \-e | \-d | \-c | \-g " \fIcpu-list\fP"
+.br
+.B chcpu
+.BR \-p " \fImode\fP"
+.br
+.B chcpu
+.BR \-r
+.br
+.B chcpu
+.BR \-h | \-V
+.br
+.SH DESCRIPTION
+.B chcpu
+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.
+
+.SH OPTIONS
+.TP
+.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 \-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 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 \-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 \-d , " \-\-disable " \fIcpu-list\fP
+Disable all specified CPUs. Disabling a CPU means that the kernel sets it offline.
+.TP
+.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 \-h , " \-\-help"
+Display help information and exit.
+.TP
+.BR \-V , " \-\-version"
+Display version information and exit.
+.SH AUTHOR
+.nf
+Heiko Carstens <heiko.carstens@de.ibm.com>
+.fi
+.SH COPYRIGHT
+Copyright IBM Corp. 2011
+.br
+.SH "SEE ALSO"
+.BR lscpu (1)
+.SH AVAILABILITY
+The chcpu command is part of the util-linux package and is available from
+ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
-- 
1.7.6.3

[PATCH 6/6] lscpu: man page update

[Heiko Carstens]

Rather large man page update which adds more information.

Signed-off-by: Heiko Carstens <heiko.carstens@de.ibm.com>
---
 sys-utils/lscpu.1 |  136 +++++++++++++++++++++++++++++++++++++---------------
 1 files changed, 97 insertions(+), 39 deletions(-)

diff --git a/sys-utils/lscpu.1 b/sys-utils/lscpu.1
index 47c4c31..2df4780 100644
--- a/sys-utils/lscpu.1
+++ b/sys-utils/lscpu.1
@@ -3,86 +3,144 @@
 .\"
 .TH LSCPU 1 "February 2011" "util-linux" "User Commands"
 .SH NAME
-lscpu \- display information on CPU architecture
+lscpu \- display information about the CPU architecture
 .SH SYNOPSIS
 .B lscpu
-.RB [ \-abcehpxV ]
-.RB [ \-s
-.IR directory ]
+.RB [ \-a | \-b | \-c "] [" \-x "] [" \-s " \fIdirectory\fP] [" \-e " [\fI=list\fP]|" \-p " [\fI=list\fP]]"
+.br
+.B lscpu
+.BR \-h | \-V
 .SH DESCRIPTION
 .B lscpu
-gathers CPU architecture information like number of CPUs, threads,
-cores, sockets, NUMA nodes, information about CPU caches, CPU family,
-model, bogoMIPS, byte order and stepping from sysfs and /proc/cpuinfo, and prints it in
-a human-readable format.  It supports both online and offline CPUs.
-It can also print out in a parsable format,
-including how different caches are shared by different CPUs,
-which can be fed to other programs.
+gathers CPU architecture information from sysfs and /proc/cpuinfo. The
+command output can be optimized for parsing or for easy readability by humans.
+.br
+The information includes, for example, the number of CPUs, threads, cores,
+sockets,  and Non-Uniform Memory Access (NUMA) nodes. There is also information
+about the CPU caches and cache sharing, family, model, bogoMIPS, byte order,
+and stepping.
+
+Options that result in an output table have a \fIlist\fP argument. Use this
+argument to customize the command output. Specify a comma-separated list of
+column labels to limit the output table to only the specified columns, arranged
+in the specified order. See \fBCOLUMNS\fP for a list of valid column labels. The
+column labels are not case sensitive.
 
-Some options have a \fIlist\fP argument. The \fIlist\fP argument is a comma
-delimited list of the columns. Currently supported are CPU, Core, Node, Socket,
-Book, Cache, Polarization, Address, Configured and Online columns.
-If the \fIlist\fP argument is given then all requested columns are printed in
-the defined order.
+Not all columns are supported on all architectures. If an unsupported column is
+specified, \fBlscpu\fP prints the column but does not provide any data for it.
 
+.SS COLUMNS
+.TP
+.B CPU
+The logical CPU number of a CPU as used by the Linux kernel.
+.TP
+.B Core
+The logical core number. A core can contain several CPUs.
+.TP
+.B Socket
+The logical socket number. A socket can contain several cores.
+.TP
+.B Book
+The logical book number. A book can contain several sockets.
+.TP
+.B Node
+The logical NUMA node number. A node may contain several books.
+.TP
+.B Cache
+Information about how caches are shared between CPUs.
+.TP
+.B Address
+The physical address of a CPU.
+.TP
+.B Online
+Indicator that shows whether the Linux instance currently makes use of the CPU.
+.TP
+.B Configured
+Indicator that shows if the hypervisor has allocated the CPU to the virtual
+hardware on which the Linux instance runs. CPUs that are configured can be set
+online by the Linux instance.
+This column contains data only if your hardware system and hypervisor support
+dynamic CPU resource allocation.
+.TP
+.B Polarization
+This column contains data for Linux instances that run on virtual hardware with
+a hypervisor that can switch the CPU dispatching mode (polarization). The
+polarization can be:
+.RS
+.TP 12
+.B horizontal\fP
+The workload is spread across all available CPUs.
+.TP 12
+.B vertical
+The workload is concentrated on few CPUs.
+.P
+For vertical polarization, the column also shows the degree of concentration,
+high, medium, or low. This column contains data only if your hardware system
+and hypervisor support CPU polarization.
+.RE
 .SH OPTIONS
 .TP
 .BR \-a , " \-\-all"
-Include online and offline CPUs in output (default for -e).
+Include online and offline CPUs in the output (default for -e).
 .TP
 .BR \-b , " \-\-online"
-Include only online CPUs in output (default for -p).
+Limit the output to online CPUs (default for -p).
 .TP
 .BR \-c , " \-\-offline"
-Include only offline CPUs in output.
+Limit the output to offline CPUs.
 .TP
 .BR \-e , " \-\-extended " \fI[=list]\fP
-Print CPU list out in human-readable format.
+Display the CPU information in human readable format.
 
-If the \fIlist\fP argument is not given then all columns where data is
-available will be printed.
+If the \fIlist\fP argument is omitted, all columns for which data is available
+are included in the command output.
 
-Note that the optional \fIlist\fP argument cannot be separated from the
-option by a space, the correct form is for example '\fB-e=cpu,node\fP' or '\fB--extended=cpu,node\fP'.
+When specifying the \fIlist\fP argument, the string of option, equal sign (=), and
+\fIlist\fP must not contain any blanks or other white space.
+Examples: '\fB-e=cpu,node\fP' or '\fB--extended=cpu,node\fP'.
 .TP
 .BR \-h , " \-\-help"
-Print a help message.
+Display help information and exit.
 .TP
 .BR \-p , " \-\-parse " \fI[=list]\fP
-Print out in parsable format.
+Optimize the command output for easy parsing.
 
-If the \fIlist\fP argument is not given then the default backwardly compatible
-output is printed.  The backwardly compatible format uses two commas to
-separate CPU cache columns. If no CPU caches are identified, then the cache
-columns are not printed at all.
+If the \fIlist\fP argument is omitted, the command output is compatible with earlier
+versions of \fBlscpu\fP. In this compatible format, two commas are used to separate
+CPU cache columns. If no CPU caches are identified the cache column is omitted.
 .br
-If the \fIlist\fP argument is given then the cache columns are separated by ':'.
+If the \fIlist\fP argument is used, cache columns are separated with a colon (:).
 
-Note that the optional \fIlist\fP argument cannot be separated from the
-option by a space, the correct form is for example '\fB-p=cpu,node\fP' or '\fB--parse=cpu,node\fP'.
+When specifying the \fIlist\fP argument, the string of option, equal sign (=), and
+\fIlist\fP must not contain any blanks or other white space.
+Examples: '\fB-p=cpu,node\fP' or '\fB--parse=cpu,node\fP'.
 .TP
 .BR \-s , " \-\-sysroot " \fIdirectory\fP
-Use the specified \fIdirectory\fP as system root.  This allows you to inspect
-a snapshot from a different system.
+Gather CPU data for a Linux instance other than the instance from which the
+\fBlscpu\fP command is issued. The specified \fIdirectory\fP is the system root
+of the Linux instance to be inspected.
 .TP
 .BR \-x , " \-\-hex"
-Use hexadecimal masks for CPU sets (e.g. 0x3).  The default is to print the sets
-in list format (e.g. 0,1).
+Use hexadecimal masks for CPU sets (for example 0x3).  The default is to print
+the sets in list format (for example 0,1).
 .TP
 .BR \-V , " \-\-version"
-Output version information and exit.
+Display version information and exit.
 .SH BUGS
 The basic overview about CPU family, model, etc. is always based on the first
 CPU only.
 
 Sometimes in Xen Dom0 the kernel reports wrong data.
+
+On virtual hardware the number of cores per socket, etc. can be wrong.
 .SH AUTHOR
 .nf
 Cai Qian <qcai@redhat.com>
 Karel Zak <kzak@redhat.com>
+Heiko Carstens <heiko.carstens@de.ibm.com>
 .fi
 .SH "SEE ALSO"
-.BR chcpu (1)
+.BR chcpu (8)
 .SH AVAILABILITY
 The lscpu command is part of the util-linux package and is available from
 ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
-- 
1.7.6.3

Re: [PATCH 3/6] lscpu: change column names back to mixed case

[Karel Zak]

On Mon, Oct 10, 2011 at 10:59:41AM +0200, Heiko Carstens wrote:
> Commit b9d18bc3 "lscpu: add column names to --help" changed all column names
> to upper case only and printed the column names for the parsable output in
> lower case.

This is bug. Sorry.

> However current behaviour was that for the parsable output the column names
> were printed in mixed case. The change might break existing other tools and
> breaks also the util-linux internal lscpu tests.
> So revert part of the above commit and restore the old behaviour.

It would be better to fix the code (upper case for the first letter)
than revert the patch.

I think that we want to use the same concept for column names in all
utils (findmnt, lsblk, ...) where we use upper case in help, man pages
and all outputs. 

The old parsable output is exception, the new -e output should be
compatible with the rest of util-linux.

I will fix it. Thanks.

    Karel

> Signed-off-by: Heiko Carstens <heiko.carstens@de.ibm.com>
> ---
>  sys-utils/lscpu.c |   31 ++++++++++++++-----------------
>  1 files changed, 14 insertions(+), 17 deletions(-)
> 
> diff --git a/sys-utils/lscpu.c b/sys-utils/lscpu.c
> index 7c8cb13..63facc3 100644
> --- a/sys-utils/lscpu.c
> +++ b/sys-utils/lscpu.c
> @@ -224,15 +224,15 @@ enum {
>  static const char *colnames[] =
>  {
>  	[COL_CPU] = "CPU",
> -	[COL_CORE] = "CORE",
> -	[COL_SOCKET] = "SOCKET",
> -	[COL_NODE] = "NODE",
> -	[COL_BOOK] = "BOOK",
> -	[COL_CACHE] = "CACHE",
> -	[COL_POLARIZATION] = "POLARIZATION",
> -	[COL_ADDRESS] = "ADDRESS",
> -	[COL_CONFIGURED] = "CONFIGURED",
> -	[COL_ONLINE] = "ONLINE",
> +	[COL_CORE] = "Core",
> +	[COL_SOCKET] = "Socket",
> +	[COL_NODE] = "Node",
> +	[COL_BOOK] = "Book",
> +	[COL_CACHE] = "Cache",
> +	[COL_POLARIZATION] = "Polarization",
> +	[COL_ADDRESS] = "Address",
> +	[COL_CONFIGURED] = "Configured",
> +	[COL_ONLINE] = "Online",
>  };
>  
>  
> @@ -937,8 +937,6 @@ print_parsable(struct lscpu_desc *desc, int cols[], int ncols,
>  
>  	fputs("# ", stdout);
>  	for (i = 0; i < ncols; i++) {
> -		char *p;
> -
>  		if (cols[i] == COL_CACHE) {
>  			if (mod->compat && !desc->ncaches)
>  				continue;
> @@ -948,11 +946,7 @@ print_parsable(struct lscpu_desc *desc, int cols[], int ncols,
>  		if (i > 0)
>  			putchar(',');
>  
> -		p = data = get_cell_header(desc, cols[i],
> -					   mod, buf, sizeof(buf));
> -		while (p && *p != '\0')
> -			*p++ = tolower((unsigned int) *p);
> -
> +		data = get_cell_header(desc, cols[i], mod, buf, sizeof(buf));
>  		fputs(data && *data ? data : "", stdout);
>  	}
>  	putchar('\n');
> @@ -1000,7 +994,10 @@ print_readable(struct lscpu_desc *desc, int cols[], int ncols,
>  		 err(EXIT_FAILURE, _("failed to initialize output table"));
>  
>  	for (i = 0; i < ncols; i++) {
> -		data = get_cell_header(desc, cols[i], mod, buf, sizeof(buf));
> +		char *p = data = get_cell_header(desc, cols[i],
> +						 mod, buf, sizeof(buf));
> +		while (p && *p != '\0')
> +			*p++ = toupper((unsigned int) *p);
>  		tt_define_column(tt, xstrdup(data), 0, 0);
>  	}
>  
> -- 
> 1.7.6.3
> 
> --
> To unsubscribe from this list: send the line "unsubscribe util-linux" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 3/6] lscpu: change column names back to mixed case

[Heiko Carstens]

On Mon, Oct 10, 2011 at 12:59:45PM +0200, Karel Zak wrote:
> On Mon, Oct 10, 2011 at 10:59:41AM +0200, Heiko Carstens wrote:
> > Commit b9d18bc3 "lscpu: add column names to --help" changed all column names
> > to upper case only and printed the column names for the parsable output in
> > lower case.
> 
> This is bug. Sorry.
> 
> > However current behaviour was that for the parsable output the column names
> > were printed in mixed case. The change might break existing other tools and
> > breaks also the util-linux internal lscpu tests.
> > So revert part of the above commit and restore the old behaviour.
> 
> It would be better to fix the code (upper case for the first letter)
> than revert the patch.

I wanted to... but there is the special case "CPU" which was all upper case
already before :/
And adding special case handling in code sucks a bit, no?

> I think that we want to use the same concept for column names in all
> utils (findmnt, lsblk, ...) where we use upper case in help, man pages
> and all outputs. 
> 
> The old parsable output is exception, the new -e output should be
> compatible with the rest of util-linux.
> 
> I will fix it. Thanks.

Ok, will you update the (new) lscpu man page needs to be changed as well then.
I can send an update if you want.

Thanks,
Heiko

Re: [PATCH 3/6] lscpu: change column names back to mixed case

[Karel Zak]

On Mon, Oct 10, 2011 at 01:13:21PM +0200, Heiko Carstens wrote:
> On Mon, Oct 10, 2011 at 12:59:45PM +0200, Karel Zak wrote:
> > On Mon, Oct 10, 2011 at 10:59:41AM +0200, Heiko Carstens wrote:
> > > Commit b9d18bc3 "lscpu: add column names to --help" changed all column names
> > > to upper case only and printed the column names for the parsable output in
> > > lower case.
> > 
> > This is bug. Sorry.
> > 
> > > However current behaviour was that for the parsable output the column names
> > > were printed in mixed case. The change might break existing other tools and
> > > breaks also the util-linux internal lscpu tests.
> > > So revert part of the above commit and restore the old behaviour.
> > 
> > It would be better to fix the code (upper case for the first letter)
> > than revert the patch.
> 
> I wanted to... but there is the special case "CPU" which was all upper case
> already before :/
> And adding special case handling in code sucks a bit, no?

 Oh, good point :-)

> > I think that we want to use the same concept for column names in all
> > utils (findmnt, lsblk, ...) where we use upper case in help, man pages
> > and all outputs. 
> > 
> > The old parsable output is exception, the new -e output should be
> > compatible with the rest of util-linux.
> > 
> > I will fix it. Thanks.
> 
> Ok, will you update the (new) lscpu man page needs to be changed as well then.
> I can send an update if you want.

 I'll update the man page.

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 0/6] chcpu und lscpu updates

[Karel Zak]

On Mon, Oct 10, 2011 at 10:59:38AM +0200, Heiko Carstens wrote:
> just some more small updates for chcpu and lscpu. The main part are
> the man pages updates. Hopefully for the better :)

 Applied, thanks.

>   lscpu: switch Yes/No output to lower case
>   lscpu: fix typo in help text
>   lscpu: change column names back to mixed case

 Fixed, I have also added columns description to the --help output
 (like we already use for lsblk, findmnt, partx, ...).

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com