manual: completed the first edition

Signed-off-by: Josef 'Jeff' Sipek <>
M doc/manual/Makefile +1 -5
@@ 12,10 12,6 @@ pdf: cp-cmd-list.tex cp-directory-sample
-.PHONY: cp-directory-sample.tex
-	(echo "\\begin{verbatim}"; cat ../../sys/; echo "\\end{verbatim}") > $@
-	rm -f *.toc *.aux *.cb *.cb2 *.dvi *.log manual.pdf cp-cmd-list.tex cp-directory-sample.tex
+	rm -f *.toc *.aux *.cb *.cb2 *.dvi *.log manual.pdf cp-cmd-list.tex
 	rm -rf tex/

M doc/manual/abi.tex +79 -1
@@ 1,4 1,5 @@ 
 HVF uses the same ABI (s390x) as Linux on z.  The following sections attempt
 to introduce portions of it.  For more information see the relevant

@@ 35,4 36,81 @@ R15   &   Stack-pointer                 
 \section{ELF Binary File Format}
-FIXME: describe ELF
+This section introduces the ELF binary file format for the s390x ABI.  For
+more detailed description, see the appropriate standard.
+Each ELF file begins with the following header:
+typedef struct {
+	u8       e_ident[16];
+	u16      e_type;
+	u16      e_machine;
+	u32      e_version;
+	u64      e_entry;
+	u64      e_phoff;
+	u64      e_shoff;
+	u32      e_flags;
+	u16      e_ehsize;
+	u16      e_phentsize;
+	u16      e_phnum;
+	u16      e_shentsize;
+	u16      e_shnum;
+	u16      e_shstrndx;
+} Elf64_Ehdr;
+\item[e\_ident] contains several bytes of information:
+	Bytes 0-3 contain the magic ASCII string ``\textbackslash x7FELF'', which is
+	equal to 7F454C46 hex.
+	Byte 4 contains the ELF class which should equal 1 for 31-bit files,
+	and 2 for 64-bit files.
+	Byte 5 contains the byte order information.  A value of 1 indicates
+	little endian format, while value of 2 indicates a big endian
+	format.  In HVF this must always be equal to 2.
+	Byte 6 contains the ELF file format version.  Currently, only one
+	version is defined --- 1.
+	Bytes 7-15 contain other information, however HVF ignores these
+	fields.
+	% FIXME: fill this in later
+\item[e\_type] specifies the type of the payload.  Currently, HVF expects
+	only executables, and therefore this field should be set to 2.
+\item[e\_machine] identifies the target architecture.  It should always
+	equal 16 hex identifying it as ESA/390 or z/Architecture.
+\item[e\_version] contains the ELF header version number.  It should always
+	equal to 1.
+\item[e\_entry] is the address of the entry point.  That is the location of
+	the instruction to transfer control to once loading has completed.
+\item[e\_phoff] contains the offset into the file to the first program
+	header.  HVF ignores this field.
+\item[e\_shoff] contains the offset into the file to the first section
+	header.
+\item[e\_flags] contains processor specific flags.  HVF ignores this field.
+\item[e\_ehsize] is the ELF header size.  HVF ignores this field.
+\item[e\_phentsize] equals the program header entry size.  HVF ignores this
+	field.
+\item[e\_phnum] is the number of program headers.  HVF ignores this field.
+\item[e\_shentsize] equals the section header entry size.
+\item[e\_shnum] is the number of section header.
+\item[e\_shstrndx] contains the section name string table index.  HVF
+	ignores this field.

M doc/manual/cp-commands.tex +1 -0
@@ 1,4 1,5 @@ 
 \chapter{CP Commands}
 This chapter details the CP commands.
 Each command is accompanied by a syntax diagram, authorization level

M doc/manual/cp-directory.tex +7 -2
@@ 1,6 1,8 @@ 
 \chapter{CP Directory}
 The directory contains a list of all valid users on the system.  Currently,
-any changes to the directory require that the nucleus be rebuilt.
+any changes to the directory require that the nucleus be rebuilt, and the
+system re-IPLed.
 \section{Directory Syntax}
 The directory is a simple text file with a declarative syntax used to

@@ 64,9 66,12 @@ long.
 \section{Example Directory}
+Figure~\ref{fig:directory-sample} is the default directory distributed with
+HVF.  It defines several users with nearly identical configurations.
 \caption{\capfont Example directory defining three users.}

M doc/manual/cp-nss.tex +1 -0
@@ 1,4 1,5 @@ 
 \chapter{CP Named Saved Segments}
 XXX: describe NSS file format
 \section{Supplied Named Saved Segments}

M doc/manual/cp-prog.tex +5 -3
@@ 1,5 1,7 @@ 
 \chapter{CP Programming Interfaces}
-FIXME: list all the diags that are supported
-\section{Remote Procedure Call Interface}
-FIXME: describe the rpc
+Currently, there are no DIAGs supported.
+%\section{Remote Procedure Call Interface}
+%FIXME: describe the rpc; currently not supported

M doc/manual/front.tex +1 -1
@@ 24,7 24,7 @@ 
 \hfill HVF-0001-00
-\section*{First Edition (?, 2009)}
+\section*{First Edition (August, 2009)}
 This information in this manual is subject to change without notice.
 Please address any comments to Josef ``Jeff'' Sipek

M doc/manual/license.tex +1 -0
@@ 1,4 1,5 @@ 

M doc/manual/manual.tex +14 -1
@@ 37,6 37,19 @@ 
 \newcommand{\capfont}                   \small
 \newcommand{\captionfont}               {}

@@ 52,7 65,7 @@ 

M doc/manual/preface.tex +20 -1
@@ 1,5 1,24 @@ 
-FIXME: this is where the preface will be
+This document includes information about HVF user and developer interfaces,
+as well as some internal details.
+Chapter~\ref{chap:directory} describes the handling of the directory.
+Including the syntax of the directory file.
+Chapter~\ref{chap:commands} describes each CP command in detail.  Each
+command includes a syntax diagram, as well as other information such as
+purpose, notes, and examples.
+Chapter~\ref{chap:prog} describes the interfaces a developer can use to
+communicate with the hypervisor.
+%Chapter~\ref{chap:nss} describes the design of the Named Saved Segment (NSS)
+%feature.  Additionally, it also describes the NSS supplied with HVF.
+Chapter~\ref{chap:abi} describes HVF's internal ABI.
+Appendix~\ref{chap:license} includes a copy of the GNU General Public
+License (version 2) under which HVF is licensed.
 %\section*{Summary of Changes in Second Edition}