lsmem: new tool

Move the s390 specific lsmem tool to util-linux.

The lsmem tool was originally written in perl and is part of the
s390-tools package which can be found here:
https://www.ibm.com/developerworks/linux/linux390/s390-tools.html

Given that the tool is architecture independent, there is no reason to
keep it in an s390 specific repository. It seems to be useful for
other architectures as well.

This patch converts the tool to C and adds it to util-linux, while the
command line options stay compatible. The only exception is the option
"-v" which used to be the short form of "--version". That got changed
to "-V" so it behaves like most other tools contained within
util-linux.

The lsmem tool inspect the contents of /sys/devices/system/memory and
prints a summary output similar to what lscpu does:

RANGE                                 SIZE STATE   REMOVABLE BLOCK
0x0000000000000000-0x000000005fffffff 1,5G online  yes       0-5
0x0000000060000000-0x000000007fffffff 512M online  no        6-7
0x0000000080000000-0x000000013fffffff   3G online  yes       8-19
0x0000000140000000-0x000000014fffffff 256M offline -         20
0x0000000150000000-0x000000017fffffff 768M online  no        21-23

Memory block size   :     256M
Total online memory :     5,8G
Total offline memory:     256M

In order to keep the output small the tool merges subsequent address
ranges where the attributes are identical. To avoid merging of line
the "-a" option can be used.

The lsmem tool also has "--extendend" and "--parsable" option which
can be used to customize the output, e.g.  limit the output to
specified columns. This is quite similar to what the lscpu tool does.

This is based on a patch from Clemens von Mann.

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

1 files changed, 95 insertions, 0 deletions

diff --git a/sys-utils/lsmem.1 b/sys-utils/lsmem.1
new file mode 100644
index 000000000..bb457dd74
--- /dev/null
+++ b/sys-utils/lsmem.1
@@ -0,0 +1,95 @@
+.TH LSMEM 1 "October 2016" "util-linux" "User Commands"
+.SH NAME
+lsmem \- list the ranges of available memory with their online status
+.SH SYNOPSIS
+.B lsmem
+.RB [ \-h "] [" \-V "] [" \-a "] [" \-s " \fIdirectory\fP] [" \-e [=\fIlist\fP]| \-p [=\fIlist\fP]]
+.br
+.SH DESCRIPTION
+The \fBlsmem\fP command lists the ranges of available memory with their online
+status. The listed memory blocks correspond to the memory block representation
+in sysfs. The command also shows the memory block size and the amount of memory
+in online and offline state.
+.sp
+By default \fBlsmem\fP prints a human readable output table with the RANGE,
+SIZE, STATE, REMOVABLE, and BLOCK columns.
+.sp
+Use the \fB--extended\fP or \fB--parse\fP option to customize the output
+table. You can change the table format and limit, extend, or rearrange the
+table columns.
+.sp
+Not all columns are supported on all systems.  If an unsupported column is
+specified, \fBlsmem\fP prints the column but does not provide any data for it.
+
+.SS COLUMNS
+.TP
+.B RANGE
+Start and end address of the memory range.
+.TP
+.B SIZE
+Size of the memory range.
+.TP
+.B STATE
+Indication of the online status of the memory range. State "on->off" means
+that the address range is in transition from online to offline.
+.TP
+.B REMOVABLE
+"yes" if the memory range can be set offline, "no" if it cannot be set offline.
+A dash ("\-") means that the range is already offline.
+.TP
+.B BLOCK
+Memory block number or numbers that correspond to the memory range.
+.TP
+.B NODE
+Numa node of memory.
+.SH OPTIONS
+.TP
+.BR \-a ", " \-\-all
+List each individual memory block, instead of combining memory blocks with
+similar attributes.
+.TP
+.BR \-e , " \-\-extended" [=\fIlist\fP]
+Display extended memory information in human-readable format.
+
+If the \fIlist\fP argument is omitted, all columns for which data is available
+are included in the command output.
+
+The \fIlist\fP argument is a comma-separated list of column labels that specifies
+the columns to be included in the output table and their sequence in the
+table. See \fBCOLUMNS\fP for valid column labels. Column labels are not case
+sensitive. The specification consisting of option, equal sign (=), and \fIlist\fP
+must not contain any white space.
+
+Examples: '\fB-e=range,size,state\fP' or '\fB--extended=NODE,state,size,RANGE\fP'.
+.TP
+.BR \-h ", " \-\-help
+Display help text and exit.
+.TP
+.BR \-p , " \-\-parse" [=\fIlist\fP]
+Optimize the command output for easy parsing.
+
+If the \fIlist\fP argument is omitted, all columns for which data is available
+are included in the command output.
+
+The \fIlist\fP argument is a comma-separated list of column labels that specifies
+the columns to be included in the output table and their sequence in the
+table. See \fBCOLUMNS\fP for valid column labels. Column labels are not case
+sensitive. The specification consisting of option, equal sign (=), and \fIlist\fP
+must not contain any white space.
+
+Examples: '\fB-p=range,size,state\fP' or '\fB--parse=NODE,state,size,RANGE\fP'.
+.TP
+.BR \-s , " \-\-sysroot " \fIdirectory\fP
+Gather memory data for a Linux instance other than the instance from which the
+\fBlsmem\fP command is issued.  The specified \fIdirectory\fP is the system
+root of the Linux instance to be inspected.
+.TP
+.BR \-V ", " \-\-version
+Display version information and exit.
+.SH SEE ALSO
+.BR chmem (8)
+.SH AVAILABILITY
+The \fBlsmem\fP command is part of the util-linux package and is available from
+.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .