[Skiboot] [PATCH] Add man pages for xscom-utils and pflash

Fri Jan 26 20:54:47 AEDT 2018

For the need of Debian/Ubuntu packaging, I infered some initial man
pages from their help output.

Signed-off-by: Frédéric Bonnard <frediz at linux.vnet.ibm.com>
---
 external/pflash/Makefile       |  1 +
 external/pflash/pflash.1       | 96 ++++++++++++++++++++++++++++++++++++++++++
 external/pflash/rules.mk       |  4 +-
 external/xscom-utils/Makefile  |  3 ++
 external/xscom-utils/getscom.1 | 23 ++++++++++
 external/xscom-utils/getsram.1 | 23 ++++++++++
 external/xscom-utils/putscom.1 | 18 ++++++++
 7 files changed, 167 insertions(+), 1 deletion(-)
 create mode 100644 external/pflash/pflash.1
 create mode 100644 external/xscom-utils/getscom.1
 create mode 100644 external/xscom-utils/getsram.1
 create mode 100644 external/xscom-utils/putscom.1

diff --git a/external/pflash/Makefile b/external/pflash/Makefile
index e931f296..5395bdfa 100644
--- a/external/pflash/Makefile
+++ b/external/pflash/Makefile
@@ -20,6 +20,7 @@ check: version.o all
 
 install: all $(INSTALLDEPS)
 	install -D pflash $(DESTDIR)$(sbindir)/pflash
+	install -D -m 0644 pflash.1 $(DESTDIR)$(mandir)/man1/pflash.1
 
 .PHONY: dist
 #File is named $(PFLASH_VERSION).tar because the expectation is that pflash-
diff --git a/external/pflash/pflash.1 b/external/pflash/pflash.1
new file mode 100644
index 00000000..5db8d460
--- /dev/null
+++ b/external/pflash/pflash.1
@@ -0,0 +1,96 @@
+.TH pflash "1" "September 2016"
+.SH NAME
+pflash \- manual page for Open-Power Flash tool
+.SH SYNOPSIS
+\fBpflash\fP [\fI\,options\/\fP] \fI\,commands\/\fP...
+.SH DESCRIPTION
+pflash is a tool to access the flash modules
+on such systems and update the OpenPower firmware.
+.SS Options
+.TP
+\fB\-a\fP \fI\,address\/\fP, \fB\-\-address\fP=\fI\,address\/\fP
+Specify the start address for erasing, reading or flashing
+.TP
+\fB\-s\fP \fI\,size\/\fP, \fB\-\-size\fP=\fI\,size\/\fP
+Specify the size in bytes for erasing, reading or flashing
+.TP
+\fB\-P\fP \fI\,part_name\/\fP, \fB\-\-partition\fP=\fI\,part_name\/\fP
+Specify the partition whose content is to be erased
+programmed or read. This is an alternative to \fB\-a\fP and \fB\-s\fP
+if both \fB\-P\fP and \fB\-s\fP are specified, the smallest of the
+two will be used
+.TP
+\fB\-f\fP, \fB\-\-force\fP
+Don't ask for confirmation before erasing or flashing
+.TP
+\fB\-d\fP, \fB\-\-dummy\fP
+Don't write to flash
+.TP
+\fB\-m\fP, \fB\-\-mtd\fP
+Avoid accessing the flash directly if the BMC supports it.
+This will access the flash through the kernel MTD layer and
+not the flash directly
+.TP
+\fB\-b\fP, \fB\-\-bmc\fP
+Target BMC flash instead of host flash.
+Note: This carries a high chance of bricking your BMC if you
+don't know what you're doing. Consider \fB\-\-mtd\fP to be safe(r)
+.TP
+\fB\-F\fP \fI\,filename\/\fP, \fB\-\-flash\-file\fP \fI\,filename
+Target filename instead of actual flash.
+.TP
+\fB\-S\fP, \fB\-\-side\fP
+Side of the flash on which to operate, 0 (default) or 1
+.TP
+\fB\-T\fP, \fB\-\-toc\fP
+libffs TOC on which to operate, defaults to 0.
+leading 0x is required for interpretation of a hex value
+.SS
+Commands:
+.TP
+\fB\-4\fP, \fB\-\-enable\-4B\fP
+Switch the flash and controller to 4\-bytes address
+mode (no confirmation needed).
+.TP
+\fB\-3\fP, \fB\-\-disable\-4B\fP
+Switch the flash and controller to 3\-bytes address
+mode (no confirmation needed).
+.TP
+\fB\-r\fP \fI\,file\/\fP, \fB\-\-read\fP=\fI\,file\/\fP
+Read flash content from address into file, use \fB\-s\fP
+to specify the size to read (or it will use the source
+file size if used in conjunction with \fB\-p\fP and \fB\-s\fP is not
+specified). When using \fB\-r\fP together with \fB\-e\fP or \fB\-p\fP, the
+read will be performed first
+.TP
+\fB\-E\fP, \fB\-\-erase\-all\fP
+Erase entire flash chip (Not supported on all chips/controllers)
+.TP
+\fB\-e\fP, \fB\-\-erase\fP
+Erase the specified region. If size or address are not
+specified, but '\-\-program' is used, then the file
+size will be used (rounded to an erase block) and the
+address defaults to 0.
+.TP
+\fB\-p\fP \fI\,file\/\fP, \fB\-\-program\fP=\fI\,file\/\fP
+Will program the file to flash. If the address is not
+specified, it will use 0. If the size is not specified
+it will use the file size. Otherwise it will limit to
+the specified size (whatever is smaller). If used in
+conjunction with any erase command, the erase will
+take place first.
+.TP
+\fB\-t\fP, \fB\-\-tune\fP
+Just tune the flash controller & access size
+(Implicit for all other operations)
+.TP
+\fB\-c\fP \fB\-\-clear\fP
+Used to ECC clear a partition of the flash
+Must be used in conjunction with \fB\-P\fP. Will erase the
+partition and then set all the ECC bits as they should be
+.TP
+\fB\-i\fP, \fB\-\-info\fP
+Display some information about the flash.
+.TP
+\fB\-h\fP, \fB\-\-help\fP
+This message.
diff --git a/external/pflash/rules.mk b/external/pflash/rules.mk
index 85484cb2..9dff0026 100644
--- a/external/pflash/rules.mk
+++ b/external/pflash/rules.mk
@@ -10,7 +10,9 @@ CCAN_SRC	:= $(addprefix ccan/list/,$(CCAN_FILES))
 PFLASH_OBJS	:= pflash.o progress.o version.o common-arch_flash.o
 OBJS		:= $(PFLASH_OBJS) $(LIBFLASH_OBJS) $(CCAN_OBJS)
 EXE     	:= pflash
-sbindir		?= /usr/sbin
+sbindir		= $(prefix)/sbin
+datadir		= $(prefix)/share
+mandir		= $(datadir)/man
 
 PFLASH_VERSION	?= $(shell ../../make_version.sh $(EXE))
 LINKAGE		?= static
diff --git a/external/xscom-utils/Makefile b/external/xscom-utils/Makefile
index 97c11896..795ce8fb 100644
--- a/external/xscom-utils/Makefile
+++ b/external/xscom-utils/Makefile
@@ -34,6 +34,9 @@ install: all
 	install -D getscom $(DESTDIR)$(sbindir)/getscom
 	install -D putscom $(DESTDIR)$(sbindir)/putscom
 	install -D getsram $(DESTDIR)$(sbindir)/getsram
+	install -D -m 0644 getscom.1 $(DESTDIR)$(mandir)/man1/getscom.1
+	install -D -m 0644 putscom.1 $(DESTDIR)$(mandir)/man1/putscom.1
+	install -D -m 0644 getsram.1 $(DESTDIR)$(mandir)/man1/getsram.1
 
 .PHONY: clean
 clean:
diff --git a/external/xscom-utils/getscom.1 b/external/xscom-utils/getscom.1
new file mode 100644
index 00000000..295b99d5
--- /dev/null
+++ b/external/xscom-utils/getscom.1
@@ -0,0 +1,23 @@
+.TH XSCOM "1" "September 2016"
+.SH NAME
+getscom \- part of xscom utils
+.SH SYNOPIS
+.TP
+\fBgetscom\fP [\-c | \-\-chip \fIchip\-id\fP] \fIaddr\fP
+.TP
+\fBgetscom\fP [\-l | \-\-list\-chips]
+.TP
+\fBgetscom\fP [\-v | \-\-version]
+.SH DESCRIPTION
+\fBgetscom\fP utility provides an interface to query the
+registers of the different chipsets of an OpenPower system.
+.SS Options
+.TP
+\fB\-c|\-\-chip-id\fP \fIchip-id\fP
+Specify chipset where to read register at \fIaddr\fP
+.TP
+\fB\-l|\-\-list\-chips\fP
+List the chipsets found on the system
+.TP
+\fB\-v|\-\-version\fP
+Display version of the tool
diff --git a/external/xscom-utils/getsram.1 b/external/xscom-utils/getsram.1
new file mode 100644
index 00000000..19b29741
--- /dev/null
+++ b/external/xscom-utils/getsram.1
@@ -0,0 +1,23 @@
+.TH XSCOM "1" "January 2018"
+.SH NAME
+getsram \- part of xscom utils
+.SH SYNOPIS
+.TP
+\fBgetsram\fP [\-c | \-\-chip \fIchip\-id\fP] \fIaddr\fP
+.TP
+\fBgetsram\fP [\-n | \-\-occ\-channel \fIchan\fP]
+.TP
+\fBgetsram\fP [\-v | \-\-version]
+.SH DESCRIPTION
+\fBgetsram\fP utility provides an interface to query the
+OCC RAM of an OpenPower system.
+.SS Options
+.TP
+\fB\-c|\-\-chip-id\fP \fIchip-id\fP
+Specify chipset where to read register at \fIaddr\fP
+.TP
+\fB\-n|\-\-occ\-channel\fP
+Specify the channel : 0, 1, 2 or 3
+.TP
+\fB\-v|\-\-version\fP
+Display version of the tool
diff --git a/external/xscom-utils/putscom.1 b/external/xscom-utils/putscom.1
new file mode 100644
index 00000000..9c329fc2
--- /dev/null
+++ b/external/xscom-utils/putscom.1
@@ -0,0 +1,18 @@
+.TH XSCOM "1" "September 2016"
+.SH NAME
+putscom \- part of xscom utils
+.SH SYNOPIS
+.TP
+\fBputscom\fP [\-c | \-\-chip \fIchip\-id\fP] \fIaddr\fP \fIvalue\fP
+.TP
+\fBputscom\fP [\-v | \-\-version]
+.SH DESCRIPTION
+\fBputscom\fP utility provides an interface to modify the
+registers of the different chipsets of an OpenPower system.
+.SS Options
+.TP
+\fB\-c|\-\-chip-id\fP \fIchip\-id\fP
+Specify chipset where to modify register at \fIaddr\fP with \fIvalue\fP
+.TP
+\fB\-v|\-\-version\fP
+Display version of the tool
-- 
2.11.0

