Add man pages for the NVRAM area tools

This patch adds man pages for the NVRAM area tools. The man pages are
written in the more readable pod format (plain old documentation; from
perl package) and translated to the troff format using 'pod2man'.

A rule is added to the Makefile.am to generate man pages from more
recent pod files.

v3:
  - Adding text to tpm_nvread/tpm_nvwrite man pages about read and
    write sizes of 0 bytes

v2:
  - adapted man pages to changes in the tools

Signed-off-by: Stefan Berger <stefanb@linux.vnet.ibm.com>

Author: stefanberger

man/man8/Makefile.am

@@ -21,6 +21,16 @@
 #       http://www.opensource.org/licenses/cpl1.0.php.
 #
 
+man8_PODS =
+
+if TSS_LIB_IS_12
+man8_PODS +=	tpm_nvdefine.pod	\
+		tpm_nvinfo.pod		\
+		tpm_nvread.pod		\
+		tpm_nvrelease.pod	\
+		tpm_nvwrite.pod
+endif
+
 man8_MANS =	tpm_changeownerauth.8	\
 		tpm_clear.8		\
 		tpm_createek.8		\
@@ -32,10 +42,17 @@ man8_MANS =	tpm_changeownerauth.8	\
 		tpm_setenable.8		\
 		tpm_setownable.8	\
 		tpm_setpresence.8	\
-		tpm_takeownership.8
+		tpm_takeownership.8	\
+		$(addsuffix .8,$(basename $(man8_PODS)))
 
 if TSS_LIB_IS_12
 man8_MANS+=tpm_revokeek.8 tpm_setoperatorauth.8 tpm_resetdalock.8
 endif
 
 EXTRA_DIST = $(man8_MANS)
+
+%.8 : %.pod
+	@pod2man -r "TPM Management" \
+		-c "" \
+		-n $(basename $@) \
+		--section=8 $< > $@

man/man8/tpm_nvdefine.8

@@ -0,0 +1,245 @@
+.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "tpm_nvdefine 8"
+.TH tpm_nvdefine 8 "2011-07-07" "TPM Management" ""
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+tpm_nvdefine
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+\&\fBtpm_nvdefine [\s-1OPTIONS\s0]\fR
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBtpm_nvdefine\fR defines a new \s-1NVRAM\s0 area at the given index and of given
+size. The user has to provide the permissions that control access to
+the \s-1NVRAM\s0 area.
+.PP
+Owner authentication is necessary once the \s-1NVRAM\s0 area 0xFFFFFFFF has been
+defined. The owner password may be provided on the command line using
+the owner password option.
+.PP
+The following options are supported:
+.IP "\fB\-h, \-\-help\fR" 4
+.IX Item "-h, --help"
+Display command usage info.
+.IP "\fB\-v, \-\-version\fR" 4
+.IX Item "-v, --version"
+Display command version info.
+.IP "\fB\-l, \-\-log [none|error|info|debug]\fR" 4
+.IX Item "-l, --log [none|error|info|debug]"
+Set logging level.
+.IP "\fB\-u, \-\-unicode\fR" 4
+.IX Item "-u, --unicode"
+Use \s-1TSS\s0 \s-1UNICODE\s0 encoding for passwords to comply with applications
+using \s-1TSS\s0 popup boxes
+.IP "\fB\-y, \-\-owner\-well\-known\fR" 4
+.IX Item "-y, --owner-well-known"
+Use a secret of all zeros (20 bytes of zeros) as the owner's secret.
+.IP "\fB\-z, \-\-area\-well\-known\fR" 4
+.IX Item "-z, --area-well-known"
+Use a secret of all zeros (20 bytes of zeros) as the \s-1NVRAM\s0 area's secret.
+.IP "\fB\-o, \-\-pwdo\fR (optional parameter)" 4
+.IX Item "-o, --pwdo (optional parameter)"
+The owner password.
+.Sp
+A password may be directly provided for example by using '\-\-pwdo=password' or
+\&'\-opassword'. If no password is provided with this option then the program will
+prompt the user for the password.
+.IP "\fB\-a, \-\-pwda\fR (optional parameter)" 4
+.IX Item "-a, --pwda (optional parameter)"
+The \s-1NVRAM\s0 area password.
+.Sp
+A password may be directly provided for example by using '\-\-pwda=password' or
+\&'\-apassword'. If no password is provided with this option then the program will
+prompt the user for the password.
+.IP "\fB\-i, \-\-index\fR" 4
+.IX Item "-i, --index"
+The index of the \s-1NVRAM\s0 area.
+The parameter must either be a decimal number or a hexadecimal number starting with '0x'.
+.Sp
+To select the \s-1NVRAM\s0 area with index 0x100, the command line parameter should be '\-i 0x100' or
+\&'\-\-index 0x100'.
+.IP "\fB\-s, \-\-size\fR" 4
+.IX Item "-s, --size"
+The size of the \s-1NVRAM\s0 area.
+The parameter must either be a decimal number or a hexadecimal number starting with '0x'.
+.IP "\fB\-p, \-\-permissions\fR" 4
+.IX Item "-p, --permissions"
+The access permissions associated with the \s-1NVRAM\s0 area.
+The parameter must either be a decimal number or a hexadecimal number staring with '0x'. It is
+possible to logically 'or' numbers or strings. The following strings are supported:
+.RS 4
+.IP "\fB\s-1AUTHREAD\s0\fR" 4
+.IX Item "AUTHREAD"
+Reading requires \s-1NVRAM\s0 area authorization.
+.IP "\fB\s-1AUTHWRITE\s0\fR" 4
+.IX Item "AUTHWRITE"
+Writing requires \s-1NVRAM\s0 area authorization.
+.IP "\fB\s-1PPREAD\s0\fR" 4
+.IX Item "PPREAD"
+Reading requires physical presence.
+.IP "\fB\s-1PPWRITE\s0\fR" 4
+.IX Item "PPWRITE"
+Writing requires physical presence.
+.IP "\fB\s-1OWNERREAD\s0\fR" 4
+.IX Item "OWNERREAD"
+Reading requires owner authorization.
+.IP "\fB\s-1OWNERWRITE\s0\fR" 4
+.IX Item "OWNERWRITE"
+Writing requires owner authorization.
+.IP "\fB\s-1GLOBALLOCK\s0\fR" 4
+.IX Item "GLOBALLOCK"
+A write to index 0 locks the \s-1NVRAM\s0 area until the next TPM_Startup(\s-1ST_CLEAR\s0)
+.IP "\fB\s-1READ_STCLEAR\s0\fR" 4
+.IX Item "READ_STCLEAR"
+A read with size 0 on the same index prevents further reading until the next TPM_Startup(\s-1ST_CLEAR\s0)
+.IP "\fB\s-1WRITE_STCLEAR\s0\fR" 4
+.IX Item "WRITE_STCLEAR"
+A write with size 0 to the same index prevents further writing until the next TPM_Startup(\s-1ST_CLEAR\s0)
+.IP "\fB\s-1WRITEDEFINE\s0\fR" 4
+.IX Item "WRITEDEFINE"
+A write with size 0 to the same index locks the \s-1NVRAM\s0 area permanently
+.IP "\fB\s-1WRITEALL\s0\fR" 4
+.IX Item "WRITEALL"
+The value must be written in a single operation
+.RE
+.RS 4
+.Sp
+An example of a permission parameter is:
+.Sp
+\&\-\-permissions=\*(L"OWNERREAD|OWNERWRITE\*(R"
+.RE
+.IP "\fB\fR" 4
+.IX Item ""
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBtpm_nvread\fR(8), \fBtpm_nvwrite\fR(8), \fBtpm_nvrelease\fR(8), \fBtpm_nvinfo\fR(8)
+.SH "REPORTING BUGS"
+.IX Header "REPORTING BUGS"
+Report bugs to <trousers\-users@lists.sourceforge.net>